| 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.
