From 11f2f1845bc05252852a6b49f080fe97368ba5f3 Mon Sep 17 00:00:00 2001 From: Twisted_Arrow Date: Tue, 25 Aug 2026 08:17:44 +0530 Subject: [PATCH 1/7] 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/7] 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/7] 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** From 9522780fe203d612b1b8df829eb25a21b1a76912 Mon Sep 17 00:00:00 2001 From: Twisted_Arrow Date: Sat, 17 Oct 2026 08:05:27 +0530 Subject: [PATCH 4/7] docs(pdg): clarify guard control-transfer semantics --- .claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md b/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md index 75fb92e0c..36ed924fa 100644 --- a/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md @@ -37,7 +37,8 @@ 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 `reason` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An - edge into an early-return/throw block is flagged `guard: true`. + edge into a `return`, `throw`, `continue`, or `break` block is flagged + `guard: true` (early control transfer, not just a function exit). - `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use edges; `variable` filters to one binding. @@ -52,10 +53,12 @@ Prefer the dedicated, bounded `pdg_query` surface for guard discovery: 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. +Filter the returned rows for `guard: true` to find early control-transfer +guards (`return`, `throw`, `continue`, or `break`). If you only need function +exits, also filter `dependent.text` for a leading `return` or `throw`; the +`guard` flag alone includes loop `continue`/`break` statements. 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** From ddfc2a772242f56933990ae77cadf2aff4f03213 Mon Sep 17 00:00:00 2001 From: Twisted_Arrow Date: Sat, 17 Oct 2026 08:05:30 +0530 Subject: [PATCH 5/7] docs(pdg): clarify guard control-transfer semantics --- .../skills/gitnexus-pdg-query/SKILL.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md b/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md index 75fb92e0c..36ed924fa 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md +++ b/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md @@ -37,7 +37,8 @@ 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 `reason` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An - edge into an early-return/throw block is flagged `guard: true`. + edge into a `return`, `throw`, `continue`, or `break` block is flagged + `guard: true` (early control transfer, not just a function exit). - `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use edges; `variable` filters to one binding. @@ -52,10 +53,12 @@ Prefer the dedicated, bounded `pdg_query` surface for guard discovery: 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. +Filter the returned rows for `guard: true` to find early control-transfer +guards (`return`, `throw`, `continue`, or `break`). If you only need function +exits, also filter `dependent.text` for a leading `return` or `throw`; the +`guard` flag alone includes loop `continue`/`break` statements. 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** From e897ad61dc95deba2550f3f8aac3a6313077628c Mon Sep 17 00:00:00 2001 From: Twisted_Arrow Date: Sun, 18 Oct 2026 08:02:16 +0530 Subject: [PATCH 6/7] docs(pdg): clarify control-transfer guard semantics in remaining mirror --- gitnexus/skills/gitnexus-pdg-query.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/gitnexus/skills/gitnexus-pdg-query.md b/gitnexus/skills/gitnexus-pdg-query.md index 75fb92e0c..36ed924fa 100644 --- a/gitnexus/skills/gitnexus-pdg-query.md +++ b/gitnexus/skills/gitnexus-pdg-query.md @@ -37,7 +37,8 @@ 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 `reason` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An - edge into an early-return/throw block is flagged `guard: true`. + edge into a `return`, `throw`, `continue`, or `break` block is flagged + `guard: true` (early control transfer, not just a function exit). - `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use edges; `variable` filters to one binding. @@ -52,10 +53,12 @@ Prefer the dedicated, bounded `pdg_query` surface for guard discovery: 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. +Filter the returned rows for `guard: true` to find early control-transfer +guards (`return`, `throw`, `continue`, or `break`). If you only need function +exits, also filter `dependent.text` for a leading `return` or `throw`; the +`guard` flag alone includes loop `continue`/`break` statements. 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** From c71a803c7c59b86b19bcf7adb52c0c0caff91a26 Mon Sep 17 00:00:00 2001 From: Twisted_Arrow Date: Tue, 27 Oct 2026 07:59:43 +0530 Subject: [PATCH 7/7] docs(pdg): distinguish MCP label from raw edge reason --- .claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md | 8 +++++--- gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md | 8 +++++--- gitnexus/skills/gitnexus-pdg-query.md | 8 +++++--- 3 files changed, 15 insertions(+), 9 deletions(-) diff --git a/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md b/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md index 36ed924fa..565d167f3 100644 --- a/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-pdg-query/SKILL.md @@ -36,7 +36,8 @@ 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 - `reason` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An + `label` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). + The tool maps the stored edge's `reason` to this response field. An edge into a `return`, `throw`, `continue`, or `break` block is flagged `guard: true` (early control transfer, not just a function exit). - `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use @@ -63,8 +64,9 @@ 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: +table's `type` property. Raw Cypher reads the branch sense from `r.reason` +(not a `label` column); `pdg_query` exposes the same value as `label`. +For example, after resolving a function to its file and line span: ```cypher MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock) diff --git a/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md b/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md index 36ed924fa..565d167f3 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md +++ b/gitnexus-claude-plugin/skills/gitnexus-pdg-query/SKILL.md @@ -36,7 +36,8 @@ 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 - `reason` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An + `label` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). + The tool maps the stored edge's `reason` to this response field. An edge into a `return`, `throw`, `continue`, or `break` block is flagged `guard: true` (early control transfer, not just a function exit). - `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use @@ -63,8 +64,9 @@ 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: +table's `type` property. Raw Cypher reads the branch sense from `r.reason` +(not a `label` column); `pdg_query` exposes the same value as `label`. +For example, after resolving a function to its file and line span: ```cypher MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock) diff --git a/gitnexus/skills/gitnexus-pdg-query.md b/gitnexus/skills/gitnexus-pdg-query.md index 36ed924fa..565d167f3 100644 --- a/gitnexus/skills/gitnexus-pdg-query.md +++ b/gitnexus/skills/gitnexus-pdg-query.md @@ -36,7 +36,8 @@ 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 - `reason` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An + `label` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). + The tool maps the stored edge's `reason` to this response field. An edge into a `return`, `throw`, `continue`, or `break` block is flagged `guard: true` (early control transfer, not just a function exit). - `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use @@ -63,8 +64,9 @@ 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: +table's `type` property. Raw Cypher reads the branch sense from `r.reason` +(not a `label` column); `pdg_query` exposes the same value as `label`. +For example, after resolving a function to its file and line span: ```cypher MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock)