gitnexus-debugging

GitNexus によるデバッグ

使用する場面

• 「この関数が失敗するのはなぜですか？」
• 「このエラーの発生源をたどってください」
• 「このメソッドを呼び出しているのは誰ですか？」
• 「このエンドポイントが 500 を返します」
• バグ、エラー、または予期しない動作を調査するとき

まずリポジトリを指定する

誤ったリポジトリでたどった根本原因は、誤った根本原因です。

確認済みのレジストリ名またはパス、あるいは設定済みの MCP デフォルトを使って、一度指定します。対象がまだ分からない場合は list_repos {} を呼び出し、その指定を以降の呼び出しでも使い続けます。インデックス済みのリポジトリが 1 つなら、以下の例をそのまま使えます。複数ある場合は、呼び出しごとに repo を渡します。repo を省略すると通常はエラーになりますが、MCP ポリシーでデフォルトが設定されている場合は、黙ってそのデフォルトが使われます。どのリポジトリを指しているのか判断できない場合は、作業を止めて確認してください。特に cypher では、ステートメントから実行対象のデータベースを判別するヒントが得られないため、重要です。

list_repos はページネーションされるため、リポジトリが存在しないと結論づける前に、hasMore が false になるまで pagination.nextOffset を使ってページを取得してください。

古いインデックスには、バグ発生前のコードが記述されています。そのため、トレースを信頼する前に更新し、診断にはリポジトリ名とインデックスの鮮度を明記してください。

ワークフロー

0. Bind the repo once (list_repos only if not already known)
1. If the suspect is unknown, query for the error/symptom with small result limits
2. context({name: "<suspect>"})                    → See callers/callees/processes
3. Read a process resource only if its trace resolves an open question
4. cypher({statement: "MATCH path..."})                 → Custom traces if needed

「Index is stale」と表示された場合 → ターミナルで node .gitnexus/run.cjs analyze を実行します。 ホットツールの staleness には、応答に使われたインデックス（branch／lastCommit）とその鮮度（status）が示されます。behind または diverged の場合にのみ再分析します。current は同一性を示し、unknown は測定できないことを示します。

チェックリスト

- [ ] Once per session: bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] context to see callers and callees
- [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
- [ ] State the repository and index freshness with the diagnosis

調査の範囲を絞る

既知のシンボルの context から始めるか、小さな query（limit: 3、max_symbols: 3、include_content: false、chain_depth: 0）でシンボルを 1 つ特定します。サーバーがこれらの単一リポジトリ用フィルターに対応している場合は、必要な情報だけを要求します。

context({uid: "<suspect id>", repo: "my-app", include_content: true,
         response_sections: ["outgoing"], relationTypes: ["CALLS"]})
trace({from_uid: "<suspect id>", to_uid: "<failure id>", repo: "my-app"})

symbol と、完全性／鮮度の診断情報は、フィルターを適用したコンテキストでも維持されます。relationTypes は、返される着信／発信のカテゴリのみをフィルタリングします。既存の範囲が限定されたウィンドウを広げたり、明示的に要求したチェーンをフィルタリングしたりするものではありません。コールバックの登録を調べる場合は USES を含めます。インポートや継承を調べる場合は、それらの関係タイプを要求するか、フィルターを省略します。参照が省略されていても、参照が存在しないとは限りません。仮説の検証に必要な場合は範囲を広げ、UNKNOWN／部分的な情報に関する警告は保持してください。根本原因を断定する前に、ソースとテストを確認してください。2～3 回の呼び出しで調査を終えることは目標ですが、検証や編集前の影響調査を省略する理由にはなりません。

デバッグのパターン

症状	GitNexus の使い方
エラーメッセージ	エラーのテキストを query → throw 箇所で context
戻り値が誤っている	関数で context → データフローを確認するために呼び出し先をたどる
散発的な障害	context → 外部呼び出しや非同期依存関係を探す
パフォーマンスの問題	context → 呼び出し元が多いシンボル（ホットパス）を探す
最近のリグレッション	detect_changes で変更による影響を確認します — リンクされたワークツリーでは worktree を渡します
「A はどのように B に到達しますか？」	2 つのシンボル間で trace を使います — 1 回の呼び出しで最短の呼び出しチェーンを確認できます

ツール

query — エラーに関連するコードを検索します：

query({search_query: "payment validation error", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException

context — 疑わしい箇所のコンテキスト全体を取得します：

context({name: "validatePayment", repo: "my-app"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)

cypher — 独自の呼び出しチェーンをトレースします。Cypher のテキスト自体にはリポジトリ名が含まれないため、結果の出所を特定できるよう、ステートメントと一緒に repo を渡します：

MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chain

trace — 2 つのシンボル間の最短の呼び出しチェーン（「A はどのように B に到達しますか？」）を取得します。context の呼び出しを連鎖させる代わりに、1 回の呼び出しで確認できます：

trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)

パスが存在しない場合、trace は到達可能な最遠のノード、つまりチェーンが途切れる箇所（動的ディスパッチ、リフレクション、または外部境界）を報告します。

例：「決済エンドポイントが断続的に 500 を返す」

0. list_repos {}
   → total: 2 (my-app, billing-api) — bind my-app explicitly on every call

1. query({search_query: "payment error handling", repo: "my-app"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

2. context({name: "validatePayment", repo: "my-app"})
   → Outgoing calls: verifyCard, fetchRates (external API!)

3. READ gitnexus://repo/my-app/process/CheckoutFlow
   → Step 3: validatePayment → calls fetchRates (external)

4. Root cause: fetchRates calls external API without proper timeout
   Repository: my-app  Index: current

インデックス済みのリポジトリが 1 つの場合、ステップ 0 では total: 1 が返され、上記のすべての呼び出しで repo 引数を省略できます。