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