gitnexus-pdg-query

GitNexus による PDG クエリサーフェス

pdg_query MCP ツールと、それが読み取る制御依存/データ依存エッジ — オプトインの --pdg プログラム依存レイヤー — に関する専門知識です。gitnexus/src/mcp/local/local-backend.ts（_pdgQueryImpl）や pdg_query ツール定義に触れる前、または pdg_query の結果を説明する際に、これを読んでください。

使用すべき場面

• 「この文はどのような条件で実行されますか？」（ガード述語）。
• 「この変数は関数内のどこを流れますか？」（def→use）。
• ガード節の発見（早期リターンガード — #559 のヒューリスティックを包含します）。
• pdg_query / CDG / REACHING_DEF の読み取りパスの拡張またはレビュー。
• 空の、または予想外の pdg_query 結果のデバッグ。

階層化された基盤（ビルド順）

pdg_query は、taint が実行されるのと同じグラフ上で実行されます。各レイヤーは --pdg の背後でオプトインです。デフォルトの analyze 実行ではそれらは一切記録されません（バイト単位で同一）。

L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
L5  CDG            Ferrante control dependence (post-dominators)    (M5 #2085)

3 つすべては、単一の CodeRelation テーブル内の BasicBlock → BasicBlock エッジです（type プロパティでキー付けされます）。Function → BasicBlock エッジは存在しません。

2 つのモード

• pdg_query({ mode: 'controls', target }) — CDG。アンカーされた関数について、各エッジは、制御する述語ブロック → 依存ブロック + label 内の分岐の向き（'T' = 述語の true/成立アーム、'F' = false/フォールスルー）です。早期リターン/throw ブロックへのエッジは guard: true とフラグ付けされます。
• pdg_query({ mode: 'flows', target, variable? }) — REACHING_DEF の def→use エッジ。variable は 1 つのバインディングに絞り込みます。

target は必須です — ファイルパス、またはシンボル/関数名（context() と同様に解決されます）。アンカーなしのモードはありません（以下を参照）。

修正されたガード節の Cypher

RFC #567 §2 の形式（[:CDG {label:'F'}]）は、書かれたままでは実行されません。エッジは単一の CodeRelation テーブルの type プロパティの値であり、分岐の向きは reason にあり、label カラムにはありません:

MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock)
WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw'
RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text

r.reason は、述語が早期終了に到達するために取った向きです。if (!ok) return; の場合、return は述語の true アーム（'T'）に乗り、保護された本体は false アーム（'F'）に乗ります — 極性はガードに依存するため、一方の向きをハードコードしないでください。

注意点（特に重要なもの）

• 常にアンカーされ、LIMIT で境界付けられます。 LadybugDB には rel-property インデックスがないため、アンカーされていない [:CDG*]/[:REACHING_DEF*] パススキャンは無制限になります。pdg_query は target を必須とし、ページを境界付けます。生の cypher 呼び出し元は、ファイル id-prefix またはシンボルスパンで自らアンカーする必要があります。
• BasicBlock↔シンボルの結合は再構築されます。 Function→BasicBlock エッジはありません。ブロックはその id-prefix（BasicBlock:<file>:<fnStartLine>:…）と、シンボルのスパン内の startLine によって照合されます。BasicBlock の startLine は 1 始まりである一方、シンボルノードの startLine/endLine は 0 始まりであるため、両方の境界が +1 シフトされます（[symStart+1, symEnd+1]）。上限の +1 は関数の最終行にあるガード/def/use を保持し、下限の +1 は直接上の行にある隣接関数のブロックを除外します。同一行/ネストされた関数は粗くアンカーされます。
• PDG レイヤーがない ⇒ エラーではなく注記。 リポジトリが --pdg でインデックスされていない場合、ツールは { results: [], note: "no PDG layer …" } を返します（RepoMeta.pdg.maxCdgEdgesPerFunction / maxReachingDefEdgesPerFunction に対する低コストのメタプローブ）。
• CDG ラベルは M5/M6 では二値です。 すべての switch-case アームは 'T' です。case ごとの条件はまだ区別されません。
• 手続き内のみ。 関数をまたぐフローは taint の領域です（explain）。

フォークせず、ミラーする

_pdgQueryImpl は _explainImpl の前半部分（WAL ラッパー、メタのレイヤーなしプローブ、limit 検証、resolveSymbolCandidates によるアンカー）を、TAINTED の代わりに CDG/REACHING_DEF で置き換えたものです — そして taint のパスコーデック / 手続き間 TAINT_PATH の仕組みは一切持ちません。それらの共有ヘルパーを再利用してください。再実装しないでください。