From 11f2f1845bc05252852a6b49f080fe97368ba5f3 Mon Sep 17 00:00:00 2001 From: Twisted_Arrow Date: Tue, 25 Aug 2026 08:17:44 +0530 Subject: [PATCH 1/3] docs(pdg): bound guard query examples --- gitnexus/skills/gitnexus-pdg-query.md | 33 ++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/gitnexus/skills/gitnexus-pdg-query.md b/gitnexus/skills/gitnexus-pdg-query.md index 58ae04b63..75fb92e0c 100644 --- a/gitnexus/skills/gitnexus-pdg-query.md +++ b/gitnexus/skills/gitnexus-pdg-query.md @@ -44,16 +44,37 @@ All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` tab `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 +## Guard-clause queries -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: +Prefer the dedicated, bounded `pdg_query` surface for guard discovery: + +```text +pdg_query({ mode: 'controls', target: '' }) +``` + +Filter the returned rows for `guard: true` when you only need early-return or +throw guards. The tool requires an explicit target and applies its own bounded +result limit, so it cannot accidentally turn a local guard lookup into a +repository-wide CDG scan. + +If you are debugging the graph and truly need raw Cypher, keep the same two +constraints explicit: anchor the blocks to one known function/file span **and** +add a deterministic `LIMIT`. CDG edges are values of the single `CodeRelation` +table's `type` property, and the branch sense is in `reason`, not a `label` +column. For example, after resolving a function to its file and line span: ```cypher MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock) -WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw' +WHERE pred.filePath = $filePath + AND dep.filePath = $filePath + AND pred.startLine >= $startLine + AND pred.startLine <= $endLine + AND dep.startLine >= $startLine + AND dep.startLine <= $endLine + AND (dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw') RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text +ORDER BY dep.startLine, pred.startLine +LIMIT 100 ``` `r.reason` is the sense the predicate took to reach the early exit. For @@ -66,7 +87,7 @@ so don't hard-code one sense. - **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. + file id-prefix or symbol span themselves and include a deterministic `LIMIT`. - **BasicBlock↔symbol join is reconstructed.** No `Function→BasicBlock` edge: the block is matched by its id-prefix (`BasicBlock:::…`) plus `startLine` within the symbol's span. BasicBlock `startLine` is **1-based** From a9874a7fee15e966bff44116bb109adbfa27c63d Mon Sep 17 00:00:00 2001 From: Twisted_Arrow Date: Tue, 25 Aug 2026 08:18:15 +0530 Subject: [PATCH 2/3] docs(pdg): mirror bounded guard examples --- .../skills/gitnexus-pdg-query/SKILL.md | 33 +++++++++++++++---- 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md b/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md index 58ae04b63..75fb92e0c 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md +++ b/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md @@ -44,16 +44,37 @@ All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` tab `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 +## Guard-clause queries -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: +Prefer the dedicated, bounded `pdg_query` surface for guard discovery: + +```text +pdg_query({ mode: 'controls', target: '' }) +``` + +Filter the returned rows for `guard: true` when you only need early-return or +throw guards. The tool requires an explicit target and applies its own bounded +result limit, so it cannot accidentally turn a local guard lookup into a +repository-wide CDG scan. + +If you are debugging the graph and truly need raw Cypher, keep the same two +constraints explicit: anchor the blocks to one known function/file span **and** +add a deterministic `LIMIT`. CDG edges are values of the single `CodeRelation` +table's `type` property, and the branch sense is in `reason`, not a `label` +column. For example, after resolving a function to its file and line span: ```cypher MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock) -WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw' +WHERE pred.filePath = $filePath + AND dep.filePath = $filePath + AND pred.startLine >= $startLine + AND pred.startLine <= $endLine + AND dep.startLine >= $startLine + AND dep.startLine <= $endLine + AND (dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw') RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text +ORDER BY dep.startLine, pred.startLine +LIMIT 100 ``` `r.reason` is the sense the predicate took to reach the early exit. For @@ -66,7 +87,7 @@ so don't hard-code one sense. - **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. + file id-prefix or symbol span themselves and include a deterministic `LIMIT`. - **BasicBlock↔symbol join is reconstructed.** No `Function→BasicBlock` edge: the block is matched by its id-prefix (`BasicBlock:::…`) plus `startLine` within the symbol's span. BasicBlock `startLine` is **1-based** From 4de4eb7379124a73d60dc1f8a43884332f2682a0 Mon Sep 17 00:00:00 2001 From: Twisted_Arrow Date: Tue, 25 Aug 2026 08:18:36 +0530 Subject: [PATCH 3/3] docs(pdg): sync bounded guard examples --- .../gitnexus/gitnexus-pdg-query/SKILL.md | 35 +++++++++++++++---- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md b/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md index f2fcd7d3b..75fb92e0c 100644 --- a/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md @@ -36,7 +36,7 @@ All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` tab - `pdg_query({ mode: 'controls', target })` — CDG. For the anchored function, each edge: controlling predicate block → dependent block + branch sense in - `label` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An + `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. @@ -44,16 +44,37 @@ All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` tab `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 +## Guard-clause queries -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: +Prefer the dedicated, bounded `pdg_query` surface for guard discovery: + +```text +pdg_query({ mode: 'controls', target: '' }) +``` + +Filter the returned rows for `guard: true` when you only need early-return or +throw guards. The tool requires an explicit target and applies its own bounded +result limit, so it cannot accidentally turn a local guard lookup into a +repository-wide CDG scan. + +If you are debugging the graph and truly need raw Cypher, keep the same two +constraints explicit: anchor the blocks to one known function/file span **and** +add a deterministic `LIMIT`. CDG edges are values of the single `CodeRelation` +table's `type` property, and the branch sense is in `reason`, not a `label` +column. For example, after resolving a function to its file and line span: ```cypher MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock) -WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw' +WHERE pred.filePath = $filePath + AND dep.filePath = $filePath + AND pred.startLine >= $startLine + AND pred.startLine <= $endLine + AND dep.startLine >= $startLine + AND dep.startLine <= $endLine + AND (dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw') RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text +ORDER BY dep.startLine, pred.startLine +LIMIT 100 ``` `r.reason` is the sense the predicate took to reach the early exit. For @@ -66,7 +87,7 @@ so don't hard-code one sense. - **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. + file id-prefix or symbol span themselves and include a deterministic `LIMIT`. - **BasicBlock↔symbol join is reconstructed.** No `Function→BasicBlock` edge: the block is matched by its id-prefix (`BasicBlock:::…`) plus `startLine` within the symbol's span. BasicBlock `startLine` is **1-based**