gitnexus-debugging

GitNexus を使ったデバッグ

使用する場面

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

ワークフロー

1. query({search_query: "<error or symptom>"})            → Find related execution flows
2. context({name: "<suspect>"})                    → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
4. cypher({statement: "MATCH path..."})                 → Custom traces if needed

「Index is stale」と表示された場合 → ターミナルで node .gitnexus/run.cjs analyze を実行します。

チェックリスト

- [ ] 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

デバッグパターン

症状	GitNexus のアプローチ
エラーメッセージ	エラー文字列を query → throw 箇所で context を実行
戻り値が誤っている	関数で context を実行 → データフローを把握するために呼び出し先を追跡
断続的な失敗	context → 外部呼び出しや非同期依存関係を探す
パフォーマンスの問題	context → 呼び出し元が多いシンボル（ホットパス）を見つける
最近のリグレッション	detect_changes で変更による影響を確認
「A から B へはどのように到達しますか？」	2 つのシンボル間で trace を実行 — 1 回の呼び出しで最短の呼び出しチェーンを確認

ツール

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

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

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

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

cypher — カスタムの呼び出しチェーンをトレースします：

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" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)

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

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

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

2. context({name: "validatePayment"})
   → 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