gitnexus-impact-analysis

GitNexus による影響分析

使用する場面

• 「この関数を変更しても安全ですか？」
• 「X を変更すると何が壊れますか？」
• 「影響範囲を見せてください」
• 「このコードを使っているのは誰ですか？」
• 自明でないコード変更を行う前
• コミットする前 — 変更が何に影響するかを把握するため

まずリポジトリをバインドする

影響分析は編集を承認するゲートであるため、これから編集しようとしているリポジトリに対して回答する必要があります。

最初のツール呼び出しの前に list_repos {} を呼び出してください。インデックス化されたリポジトリが 1 つなら、以下の例をそのまま使用します。複数ある場合は、すべての呼び出しで repo を渡してください。repo を省略すると通常はエラーになりますが、デフォルトが設定された MCP ポリシー下では、そのデフォルトに暗黙的に解決されます。どのリポジトリを指しているか判別できない場合は、立ち止まって確認してください。曖昧な識別情報の下にあるすべての結果は、その曖昧さを引き継ぎます。list_repos はページネーションされるため、リポジトリが存在しないと結論付ける前に、hasMore が false になるまで offset: pagination.nextOffset でページを進めてください。

detect_changes は、変更が MCP サーバーの起動元ではないリンクされたワークツリーにある場合に worktree を受け取ります。サーバーがワークツリーを自動検出するのは、その内部から起動された場合のみです。それ以外の場合、git diff は誤ったチェックアウトで実行され、変更されたシンボルをゼロと報告します — これは以下に説明する劣化フラグを一切伴わない、偽のクリーンチェックです。CLI フォールバックでは、--repo . は現在のチェックアウトを意味します。意図したリポジトリ内にいない場合は、代わりにそのリポジトリのパスを渡してください。

リスクレポートとともに、バインドされた識別情報を明示してください:

Repository: <name> (<path>)   Worktree: <path>   Index: <commit>, <n> behind HEAD

ワークフロー

0. list_repos {}                                           → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) or `node .gitnexus/run.cjs impact "X" --direction upstream --repo .`
2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
3. detect_changes({scope: "all"}) or `node .gitnexus/run.cjs detect-changes --scope all --repo .`
4. Assess risk and report to user, echoing repo/worktree/index identity

「Index is stale」の場合 → ターミナルで node .gitnexus/run.cjs analyze を実行します。 ホットツールの staleness は、どのインデックスが回答したか（branch/lastCommit）と、その鮮度（status）を示します。再分析が必要なのは behind または diverged の場合のみです — current は同一性、unknown は測定不能です。 .gitnexus/run.cjs が存在しない場合は、フォールバックコマンド内の node .gitnexus/run.cjs を npx gitnexus に置き換えてください。

チェックリスト

- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] impact({target, direction: "upstream"}) or CLI fallback to find dependents
- [ ] Review d=1 items first (these WILL BREAK)
- [ ] Check high-confidence (>0.8) dependencies
- [ ] READ processes to check affected execution flows
- [ ] detect_changes({scope: "all"}) or CLI fallback for pre-commit check
- [ ] Confirm the checkout you edited is the checkout that was diffed
- [ ] Assess risk level and report, stating repo/worktree/index identity

出力の理解

深さ	リスクレベル	意味
d=1	WILL BREAK	直接の呼び出し元/インポーター
d=2	LIKELY AFFECTED	間接的な依存関係
d=3	MAY NEED TESTING	推移的な影響

リスク評価

影響範囲	リスク
シンボル 5 未満、プロセス少数	LOW
シンボル 5〜15、プロセス 2〜5	MEDIUM
シンボル 15 超、またはプロセス多数	HIGH
クリティカルパス（認証、決済）	CRITICAL
呼び出し元がゼロ	UNKNOWN

UNKNOWN はこの尺度の低い段階ではありません — 走査が回答できなかったことを意味します。呼び出し元の集合が空であることは、「本当に未使用」と「呼び出し元がインデックスで解決できない」（プレーンオブジェクトのプロパティアクセス、動的ディスパッチ、言語をまたぐ呼び出し）のどちらとも同じように整合するため、呼び出し元が少ない ⇒ LOW は適用されません。結果にはその旨を示す riskNote が付きます。シンボルを変更または削除しても安全と扱う前に、テキスト検索で確認してください。

risk は編集ゲートです。HIGH/CRITICAL では警告し、UNKNOWN では不確実性が解消されるまで停止します。単一リポジトリモードでは、File とシンボルのターゲットをローカルの riskSharedAxes（direct/total のみ）で比較します。グループモードでは、グループの結果のみを比較します。その riskSharedAxes は、解決されたリポジトリ間の交差をそのローカル値に重ね合わせます。どちらのフィールドも、編集ゲートを免除するために使用しないでください。種類を比較する前に riskScale.unusedAxes を確認してください。MCP の File 走査は process/module 軸を省略しますが、Web の Graph-RAG はエンリッチメントの前に File ターゲットをファイル内のシンボルに展開します。

ツール

impact — シンボルの影響範囲を調べるための主要ツールです。MCP が利用できない場合は、代わりに node .gitnexus/run.cjs impact <symbol> --direction upstream --repo . を使用してください:

impact({
  target: "validateUser",
  repo: "my-app",          // required once >1 repository is indexed
  direction: "upstream",
  minConfidence: 0.8,
  maxDepth: 3
})

→ d=1 (WILL BREAK):
  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]

→ d=2 (LIKELY AFFECTED):
  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]

detect_changes — git diff に基づく影響分析です。MCP が利用できない場合は、代わりに node .gitnexus/run.cjs detect-changes --scope all --repo . を使用してください:

detect_changes({scope: "all"})

→ Changed: 5 symbols in 3 files
→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
→ Risk: MEDIUM

複数のリポジトリがインデックスされている場合は repo を追加し、変更がサーバーの起動元ではないリンクされたワークツリー内にある場合は worktree: "<abs path>" を追加してください。

partial: true（グラフクエリが失敗した）または truncated: true（変更されたシンボルの一覧が上限に達した）は、結果が真実に及んでいないことを意味し、上記の UNKNOWN と同様に読み取れます。そこでのゼロは、影響を受けていないのではなく、未確認であることを意味します。pre-commit チェックにチェックを入れるのではなく、再実行してください。

誤ったワークツリーによるゼロにはどちらのフラグも付かず、真にクリーンな結果と形が同一であるため、空の変更セットを合格したチェックとして扱う前に、編集したチェックアウトが実際に diff されたものであることを確認してください。

例:「validateUser を変更すると何が壊れるか？」

0. list_repos {}
   → total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly

1. impact({target: "validateUser", repo: "my-app", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
   → d=1: loginHandler, apiMiddleware (WILL BREAK)
   → d=2: authRouter, sessionManager (LIKELY AFFECTED)

2. READ gitnexus://repo/my-app/processes
   → LoginFlow and TokenRefresh touch validateUser

3. Risk: 2 direct callers, 2 processes = MEDIUM
   Repository: my-app (/abs/path/my-app)  Worktree: same  Index: current

インデックスされたリポジトリが 1 つだけの場合、ステップ 0 は total: 1 を返し、上記のすべての呼び出しから repo 引数が不要になります。