From 5ba811c9f0327f2e6c4713c4ec50daf893389cad Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Tue, 23 Jun 2026 18:42:02 +0000 Subject: [PATCH] docs(mcp): fix impact `line` description contradiction for whole-symbol pdg (#2283) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new `line` schema description said "mode:'pdg' requires a positive line", which contradicted the top-level impact description ("Without 'line', pdg returns whole-symbol inter-procedural reach plus local whole-symbol PDG diagnostics"). A pdg call without a line is a valid (degraded whole-symbol) call, not an error — the old wording could push an agent to avoid valid no-line pdg calls or synthesize line:0 (which then hard-errors). Reword to: omit line for whole-symbol pdg; a positive line anchors a statement slice; literal 0 is tolerated only as an omitted-line compatibility sentinel on the callgraph path and is rejected for mode:'pdg'. Update the schema test to pin the new, non-contradictory wording and assert "requires a positive line" is gone. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/tools.ts | 2 +- gitnexus/test/unit/tools.test.ts | 9 +++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/gitnexus/src/mcp/tools.ts b/gitnexus/src/mcp/tools.ts index 5db37438e..9591213c6 100644 --- a/gitnexus/src/mcp/tools.ts +++ b/gitnexus/src/mcp/tools.ts @@ -476,7 +476,7 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep // statement anchor" and is tolerated on the callgraph path. minimum: 0, description: - "1-based source line — PDG statement anchor (mode:'pdg'). Seeds affectedStatements on the statement at this line; inter-procedural symbols are still returned in interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket. 0 (or omitted) means no statement anchor; mode:'pdg' requires a positive line.", + "1-based source line — PDG statement anchor (mode:'pdg'). Seeds affectedStatements on the statement at this line; inter-procedural symbols are still returned in interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket. Omit line for whole-symbol pdg (whole-symbol reach + diagnostics); a positive line anchors a statement slice. Literal 0 is tolerated only as an omitted-line compatibility sentinel on the callgraph path and is rejected for mode:'pdg'.", }, file_path: { type: 'string', diff --git a/gitnexus/test/unit/tools.test.ts b/gitnexus/test/unit/tools.test.ts index 0b90061a8..076c4dae2 100644 --- a/gitnexus/test/unit/tools.test.ts +++ b/gitnexus/test/unit/tools.test.ts @@ -146,10 +146,15 @@ describe('GITNEXUS_TOOLS', () => { // Statement-anchored slice is optional — never required. expect(impactTool.inputSchema.required).not.toContain('line'); // The description names the mode:'pdg' statement-anchor semantics and the - // 0/omitted = no-anchor compatibility convention. + // literal-0 compatibility convention — without contradicting the top-level + // "omit line for whole-symbol pdg" contract (#2283). expect(line.description).toMatch(/statement anchor/i); expect(line.description).toMatch(/pdg/i); - expect(line.description).toMatch(/0 \(or omitted\) means no statement anchor/i); + expect(line.description).toMatch(/literal 0 is tolerated only .* on the callgraph path/i); + expect(line.description).toMatch(/omit line for whole-symbol pdg/i); + // Must NOT claim pdg "requires a positive line" — that contradicts the valid + // no-line whole-symbol pdg call documented in the top-level description. + expect(line.description).not.toMatch(/requires a positive line/i); // The top-level description mentions the statement-anchored slice and result shape. expect(impactTool.description).toMatch(/statement-anchored|STATEMENT-ANCHORED/); expect(impactTool.description).toContain('affectedStatements');