understand-diff

/understand-diff

プロジェクトのデータディレクトリにあるナレッジグラフ（.ua/knowledge-graph.json、またはそのディレクトリが存在する場合は従来の .understand-anything/knowledge-graph.json）を基準に、現在のコード変更を分析します。

グラフ構造のリファレンス

ナレッジグラフ JSON の構造は次のとおりです。

• project — {name, description, languages, frameworks, analyzedAt, gitCommitHash}
• nodes[] — 各要素は {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
  • コードノードの種類：file、function、class、module、concept
  • コード以外のノードの種類：config、document、service、table、endpoint、pipeline、schema、resource
  • ドメイン／ナレッジノードの種類：domain、flow、step、article、entity、topic、claim、source
  • ID はノードの種類をプレフィックスとして使用します。例：file:path、function:path:name、config:path、article:path
• edges[] — 各要素は {source, target, type, direction, weight}
  • 主な種類：imports、contains、calls、depends_on、configures、documents、deploys、triggers、contains_flow、flow_step、related、cites
• layers[] — 各要素は {id, name, description, nodeIds[]}
• tour[] — 各要素は {order, title, description, nodeIds[]}

効率的な読み方

1. ファイル全体を読む前に、Grep で JSON 内を検索し、関連する項目を探します
2. 必要なセクションだけを読み、グラフ全体をコンテキストに出力しないでください
3. 内容の理解には、ノード名と概要が最も役立つフィールドです
4. エッジからコンポーネントのつながりを把握できます。依存関係をたどるには、imports と calls を追ってください

手順

1. データディレクトリ $UA_DIR を解決します。 UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) を実行します。既存の .understand-anything/ があればそれを使用し、なければ新しい .ua/ を使用します。$UA_DIR/knowledge-graph.json が存在することを確認します。存在しない場合は、まず /understand を実行するようユーザーに伝えます。

2. 変更されたファイルの一覧を取得します（グラフはまだ読み込まないでください）。

   • 未コミットの変更があるブランチの場合：git diff --name-only
   • フィーチャーブランチの場合：git diff main...HEAD --name-only（またはベースブランチ）
   • ユーザーが PR 番号を指定した場合：その PR の差分を取得します

3. プロジェクトのメタデータを読み込み、グラフの鮮度を確認します — Grep または Read を使い、行数を制限して "project" セクションを抽出します。gitCommitHash も含め、これを GRAPH_COMMIT_RAW として扱います。その後、次の手順を行います。

   • Git の差分に使う前に、値をコミットとして解決します。プロジェクトのルートから、解決したコミットと git rev-parse HEAD を比較し、プロジェクトに関係するコミット済みの変更と作業ツリーの変更を確認します。

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .
     

   • -- . のパス指定は必須です。兄弟関係にあるモノレポ内のプロジェクトのみを変更したコミットによって、このグラフが古いと判定されてはいけません。プロジェクトの差分が空であれば、ハッシュが一致しないだけではグラフが古いとは見なしません。
   • 生成されたグラフ成果物であり、プロジェクトソースの変更ではないため、すべてのコマンドの出力から選択したデータディレクトリ（.ua/ または従来の .understand-anything/）を除外します。
   • コミット済みの差分、またはいずれかの作業ツリー確認コマンドでプロジェクトファイルが報告された場合は、影響分析の前に、グラフにそれらの変更が反映されていない可能性があることを警告します。グラフを更新するには /understand を実行するよう提案します。
   • コミット差分の確認は、GRAPH_COMMIT_RAW を正常に解決できた場合にのみ実行します。グラフのコミットまたは Git メタデータが欠落している、無効である、または利用できない場合は、簡潔なベストエフォートの警告を出し、処理を続行します。

4. 変更されたファイルに対応するノードを検索します — 変更されたファイルパスごとに、Grep を使ってナレッジグラフ内を検索し、次のノードを見つけます。

   • "filePath" の値が一致するノード（例：grep "changed/file/path"）
   • これにより、ファイルレベルのノード（コード以外の種類を含む）と、そのファイル内で定義されている関数／クラスのノードが見つかります。
   • 一致したすべてのノードの id 値を記録します。

5. 接続されたエッジ（1 ホップ）を検索します — 一致した各ノード ID をエッジ内で Grep し、次の項目を確認します。

   • 変更されたノードをインポートまたは依存しているもの（上流の呼び出し元）
   • 変更されたノードがインポートまたは呼び出しているもの（下流の依存先）
   • これらが「影響を受けるコンポーネント」です。破損する可能性があるものや、更新が必要になる可能性があるものを示します。

6. 影響を受けるレイヤーを特定します — 一致したノード ID を "layers" セクションで Grep し、どのアーキテクチャレイヤーに影響するかを特定します。

7. 構造化された分析を提示します。

   • 変更されたコンポーネント：直接変更された内容（一致したノードの要約を含む）
   • 影響を受けるコンポーネント：影響を受ける可能性があるもの（1 ホップのエッジから特定）
   • 影響を受けるレイヤー：影響を受けるアーキテクチャレイヤーと、レイヤー間の懸念事項
   • リスク評価：ノードの complexity 値、レイヤー間のエッジ数、影響範囲（影響を受けるコンポーネント数）に基づく評価
   • 慎重に確認すべき点と、潜在的な問題を提案します。

8. ダッシュボード用の差分オーバーレイを書き込みます — 分析を提示した後、ダッシュボードで変更されたコンポーネントと影響を受けるコンポーネントを可視化できるよう、差分データを $UA_DIR/diff-overlay.json に書き込みます。このファイルの内容は次のとおりです。

   {
     "version": "1.0.0",
     "baseBranch": "<the base branch used>",
     "generatedAt": "<ISO timestamp>",
     "changedFiles": ["<list of changed file paths>"],
     "changedNodeIds": ["<node IDs from step 4>"],
     "affectedNodeIds": ["<node IDs from step 5, excluding changedNodeIds>"]
   }
   

   書き込み後、ユーザーに /understand-anything:understand-dashboard を実行すると、差分オーバーレイを視覚的に確認できることを伝えます。