/gitnexus-pdg-query

name: gitnexus-pdg-query
description: "Use when querying or extending GitNexus's PDG control/data-dependence surface (the `pdg_query` MCP tool, CDG/REACHING_DEF edges), or reasoning about \"what controls X\" / \"where does Y flow\" / guard clauses. Examples: \"what guards this statement?\", \"trace this variable within the function\", \"why is the pdg_query result empty?\", \"add a CDG query\"."

PDG query surface with GitNexus

Expert knowledge for the `pdg_query` MCP tool and the control/data-dependence edges it reads — the opt-in `--pdg` program-dependence layers. Read this before touching `gitnexus/src/mcp/local/local-backend.ts` (`_pdgQueryImpl`) or the `pdg_query` tool def, or when explaining a `pdg_query` result.

When to Use

• "Under what condition does this statement run?" (guarding predicates).
• "Where does this variable flow inside the function?" (def→use).
• Guard-clause discovery (early-return guards — subsumes the #559 heuristic).
• Extending or reviewing `pdg_query` / the CDG / REACHING_DEF read path.
• Debugging an empty or surprising `pdg_query` result.

The layered substrate (build order)

`pdg_query` runs **on** the same graph taint runs on. Each layer is opt-in behind `--pdg`; a default `analyze` run records none of them (byte-identical).

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)

All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` table (keyed by the `type` property). There is **no** `Function → BasicBlock` edge.

The two modes

• `pdg_query({ mode: 'controls', target })` — CDG. For the anchored function,

each edge: controlling predicate block → dependent block + branch sense in `reason` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An edge into an early-return/throw block is flagged `guard: true`.

• `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use

edges; `variable` filters to one binding.

`target` is **required** — a file path or a symbol/function name (resolved like `context()`). There is no anchorless mode (see below).

The corrected guard-clause Cypher

The RFC #567 §2 form (`[:CDG {label:'F'}]`) does **not** run as written. Edges are values of the single `CodeRelation` table's `type` property, and the branch sense is in `reason`, NOT a `label` column:

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` is the sense the predicate took to reach the early exit. For `if (!ok) return;` the return rides the predicate's **true** arm (`'T'`) and the protected body rides the **false** arm (`'F'`) — polarity depends on the guard, so don't hard-code one sense.

Gotchas (the load-bearing ones)

• **Always anchored + LIMIT-bounded.** LadybugDB has no rel-property index, so

an unanchored `[:CDG*]`/`[:REACHING_DEF*]` path scan is unbounded. `pdg_query` requires `target` and bounds the page; raw `cypher` callers must anchor on a file id-prefix or symbol span themselves.

• **BasicBlock↔symbol join is reconstructed.** No `Function→BasicBlock` edge:

the block is matched by its id-prefix (`BasicBlock:<file>:<fnStartLine>:…`) plus `startLine` within the symbol's span. BasicBlock `startLine` is **1-based** while the symbol node's `startLine`/`endLine` are **0-based**, so **both** bounds are shifted `+1` (`[symStart+1, symEnd+1]`): the upper `+1` keeps a guard/def/use on the function's **final line**, the lower `+1` excludes an adjacent function's block on the line directly **above**. Same-line / nested functions anchor coarsely.

• **No PDG layer ⇒ a note, not an error.** If the repo wasn't indexed with

`--pdg` the tool returns `{ results: [], note: "no PDG layer …" }` (cheap meta probe on `RepoMeta.pdg.maxCdgEdgesPerFunction` / `maxReachingDefEdgesPerFunction`).

• **CDG labels are binary in M5/M6.** Every `switch`-case arm is `'T'`; per-case

conditions are not yet distinguished.

• **Intra-procedural only.** Cross-function flow is taint's domain (`explain`).

Mirror, don't fork

`_pdgQueryImpl` is the front half of `_explainImpl` (WAL wrapper, meta no-layer probe, limit validation, `resolveSymbolCandidates` anchoring) with CDG/ REACHING_DEF instead of TAINTED — and none of taint's path-codec / interproc `TAINT_PATH` machinery. Reuse those shared helpers; do not re-implement them.