gitnexus 1.6.11-rc.3 → 1.6.11-rc.4

package/dist/mcp/local/local-backend.js

@@ -3000,7 +3000,22 @@ export class LocalBackend {
         else if (isQualified) {
             // Parenthesised because the kind filter below is appended with AND, which
             // binds tighter than OR.
-            whereClause = `WHERE (n.id = $symName OR n.name = $symName)`;
+            // #3074: a repo-relative file path (e.g. "supabase/functions/_shared/crypto.ts")
+            // is the most natural way to name a File and is exactly what `target.filePath`
+            // reports, but the old clause only matched `n.id` (= "File:<path>") or basename
+            // `n.name`, so the same path the graph stores never resolved. Also match the
+            // repo-relative `n.filePath` exactly and via an anchored suffix (segment-boundary
+            // "ENDS WITH $suffix" where suffix is "/"+path) so "a.ts" does not spuriously
+            // match "mylib/a.ts" — same anchoring used in detect_changes (#2915).
+            const suffix = pathSuffixOf(name);
+            // File-path terms must be scoped to File nodes — n.filePath is shared by
+            // every symbol in the file, so an unlabeled predicate would turn
+            // "src/actions.ts" into every symbol in that file (bot review #3084 P1).
+            // LadybugDB does not allow label tests in WHERE (n:File), so scope via
+            // id prefix — File nodes are `File:<path>`.
+            whereClause = `WHERE (n.id = $symName OR n.name = $symName OR (n.id STARTS WITH $filePrefix AND (n.filePath = $symName OR n.filePath ENDS WITH $suffix)))`;
+            queryParams.suffix = suffix;
+            queryParams.filePrefix = 'File:';
         }
         else {
             whereClause = `WHERE n.name = $symName`;
@@ -3079,7 +3094,7 @@ export class LocalBackend {
         if (rows.length === 0)
             return { kind: 'not_found' };
         // Normalise row shape across object / tuple returns from LadybugDB.
-        const normalized = rows.map((r) => ({
+        let normalized = rows.map((r) => ({
             id: (r.id ?? r[0]),
             name: (r.name ?? r[1]),
             type: (r.type ?? r[2] ?? ''),
@@ -3088,6 +3103,14 @@ export class LocalBackend {
             endLine: (r.endLine ?? r[5]),
             ...(include_content ? { content: (r.content ?? r[6]) } : {}),
         }));
+        // An exact File path wins over anchored suffix candidates. Without this,
+        // `lib/a.ts` and `src/lib/a.ts` both score as File candidates and turn an
+        // otherwise unambiguous exact target into `ambiguous` (#3084 review P2).
+        if (isQualified) {
+            const exactFiles = normalized.filter((candidate) => candidate.id.startsWith('File:') && candidate.filePath === name);
+            if (exactFiles.length > 0)
+                normalized = exactFiles;
+        }
         // The COUNT can never legitimately be below the page it accompanies, so a
         // value under `normalized.length` means the count leg failed or returned an
         // unreadable shape. Keep the window size as the floor — reporting zero would
@@ -4942,6 +4965,7 @@ export class LocalBackend {
                     direction: params.direction,
                     suggestion,
                     recoverySuggestion,
+                    undetermined: true,
                 });
                 return pdgErr;
             }
@@ -4949,7 +4973,7 @@ export class LocalBackend {
                 error: message,
                 target: { name: params.target },
                 direction: params.direction,
-                impactedCount: 0,
+                impactedCount: null,
                 risk: 'UNKNOWN',
                 suggestion,
                 ...(recoverySuggestion ? { recoverySuggestion } : {}),
@@ -5036,6 +5060,7 @@ export class LocalBackend {
                         `(single-repo PDG impact). Remove them or use mode:'callgraph' for cross-repo fan-out.`,
                     target: crossDepthTarget,
                     direction,
+                    undetermined: true,
                 });
                 return pdgErr;
             }
@@ -5091,12 +5116,17 @@ export class LocalBackend {
                     error: `Target '${missing}' not found`,
                     target: notFoundTarget,
                     direction,
+                    undetermined: true,
                 })
                 : {
                     error: `Target '${missing}' not found`,
                     target: { name: target },
                     direction,
-                    impactedCount: 0,
+                    // #3074 follow-up: do not ship a normal-shaped 0/UNKNOWN blast radius
+                    // alongside the error — it reads as a real "nothing depends on this"
+                    // answer. Null marks UNDETERMINED (same as the ambiguous path) so a
+                    // consumer testing `impactedCount === 0` cannot misread a miss as safe.
+                    impactedCount: null,
                     risk: 'UNKNOWN',
                 };
         }

package/dist/mcp/local/pdg-impact.d.ts

@@ -31,8 +31,10 @@ export declare function splitCalleeIds(raw: unknown): string[];
  * Bump on any breaking change to the PDG result fields.
  * v2: `startLine` in the result is now 1-based display (#2380), matching the
  * context/query/impact tools (was 0-based).
+ * v3: error envelopes use `impactedCount: null` when a target cannot be resolved
+ * (#3074), so consumers cannot read a miss as a measured zero.
  */
-export declare const PDG_RESULT_VERSION: 2;
+export declare const PDG_RESULT_VERSION: 3;
 /** A reachable dependence block resolved to its source statement. */
 export interface PdgStatement {
     /** 1-based source line where the statement's block starts. */
@@ -229,7 +231,7 @@ export interface PdgInterproceduralImpact {
 export interface PdgImpactBaseResult extends PdgImpactParityFields {
     mode: 'pdg';
     /** Contract version of the mode:'pdg' impact result shape; bump on any breaking change to the PDG result fields. */
-    pdgResultVersion: 2;
+    pdgResultVersion: 3;
     target: PdgImpactTarget;
     direction: 'upstream' | 'downstream';
     impactedCount: number;
@@ -296,11 +298,11 @@ export interface PdgImpactDegradedResult extends PdgImpactBaseResult {
 export interface PdgImpactErrorResult {
     mode?: 'pdg';
     /** Contract version of the mode:'pdg' impact result shape; bump on any breaking change to the PDG result fields. */
-    pdgResultVersion: 2;
+    pdgResultVersion: 3;
     error: string;
     target: PdgImpactTarget;
     direction: 'upstream' | 'downstream';
-    impactedCount: 0;
+    impactedCount: number | null;
     risk: 'UNKNOWN';
     suggestion?: string;
     recoverySuggestion?: string;
@@ -313,6 +315,8 @@ export declare function makePdgImpactErrorResult(input: {
     mode?: 'pdg';
     suggestion?: string;
     recoverySuggestion?: string;
+    /** True when analysis did not obtain a measured impact count. */
+    undetermined?: boolean;
 }): PdgImpactErrorResult;
 export declare function isPdgDegradedLayerStatus(layer: PdgLayerStatus): layer is PdgDegradedLayerStatus;
 export declare function makePdgLayerDegradedResult(input: {

package/dist/mcp/local/pdg-impact.js

@@ -109,8 +109,10 @@ export function splitCalleeIds(raw) {
  * Bump on any breaking change to the PDG result fields.
  * v2: `startLine` in the result is now 1-based display (#2380), matching the
  * context/query/impact tools (was 0-based).
+ * v3: error envelopes use `impactedCount: null` when a target cannot be resolved
+ * (#3074), so consumers cannot read a miss as a measured zero.
  */
-export const PDG_RESULT_VERSION = 2;
+export const PDG_RESULT_VERSION = 3;
 /**
  * FU-B-2 intra-block def→use line walk. Given a block's self REACHING_DEF
  * def→use line PAIRS (every `defLine → useLine` step decoded from the edge
@@ -469,7 +471,10 @@ export function makePdgImpactErrorResult(input) {
         error: input.error,
         target: input.target,
         direction: input.direction,
-        impactedCount: 0,
+        // #3074 follow-up + P2 review: an unmeasured PDG result must not ship a
+        // confident-looking 0 blast radius. null marks UNDETERMINED, so a consumer
+        // testing === 0 cannot misread a miss or failed query as safe.
+        impactedCount: input.undetermined ? null : 0,
         risk: 'UNKNOWN',
         ...(input.suggestion ? { suggestion: input.suggestion } : {}),
         ...(input.recoverySuggestion ? { recoverySuggestion: input.recoverySuggestion } : {}),

package/dist/mcp/tools.js

@@ -425,7 +425,7 @@ MODE (opt-in): "callgraph" (default) walks symbol→symbol edges (CALLS/IMPORTS/
 
 STATEMENT-ANCHORED PDG SLICE: with mode:'pdg', pass "line" (1-based source line within the target symbol) to seed the dependence slice on the statement at that line and return what depends on it in affectedStatements (line + text). Inter-procedural symbols are still reported through interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket. Without "line", pdg returns whole-symbol inter-procedural reach plus local whole-symbol PDG diagnostics.
 
-PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:2 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:2, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar. Return-value-ascent coverage is published structurally at pdgEvidence.ascent — present iff the inter-procedural descent ran, including on an empty slice — with referencesScanned (DISTINCT callees scanned for a CALL_SUMMARY: a distinct-id tally, not a call-site count — two call sites to the same callee count once), returnFlowFound (whether the ascent fired anywhere in the slice), undecodableSummaryCount, examinedComplete (whether that scan covered every callee the index recorded a resolved id for on the visited blocks), incompleteReasons ('traversal-truncated' | 'callee-list-capped' | 'callee-ids-unrecorded'), and callSummaryLayerPresent. Read callSummaryLayerPresent FIRST: false ⇒ a pre-CALL_SUMMARY index, so {referencesScanned:N>0, returnFlowFound:false} is self-consistent and says nothing about the callees — the scan ran, but no layer existed in which a return-flow could be recorded (remedy: re-run gitnexus analyze --pdg). Branch on those fields; the note narrates the same facts in prose for humans and is not a stable contract.
+PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:3 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:3, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar. Return-value-ascent coverage is published structurally at pdgEvidence.ascent — present iff the inter-procedural descent ran, including on an empty slice — with referencesScanned (DISTINCT callees scanned for a CALL_SUMMARY: a distinct-id tally, not a call-site count — two call sites to the same callee count once), returnFlowFound (whether the ascent fired anywhere in the slice), undecodableSummaryCount, examinedComplete (whether that scan covered every callee the index recorded a resolved id for on the visited blocks), incompleteReasons ('traversal-truncated' | 'callee-list-capped' | 'callee-ids-unrecorded'), and callSummaryLayerPresent. Read callSummaryLayerPresent FIRST: false ⇒ a pre-CALL_SUMMARY index, so {referencesScanned:N>0, returnFlowFound:false} is self-consistent and says nothing about the callees — the scan ran, but no layer existed in which a return-flow could be recorded (remedy: re-run gitnexus analyze --pdg). Branch on those fields; the note narrates the same facts in prose for humans and is not a stable contract.
 
 WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
 AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.11-rc.3",
+  "version": "1.6.11-rc.4",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",