gitnexus 1.6.8-rc.20 → 1.6.8-rc.21

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

@@ -27,8 +27,22 @@ import { getExactScanLimit, isVectorExtensionSupportedByPlatform, } from '../../
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
 import { logger } from '../../core/logger.js';
-import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT } from '../tools.js';
+import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT, EXPLAIN_DEFAULT_LIMIT, EXPLAIN_MAX_LIMIT, } from '../tools.js';
 import { findImportCycles } from '../../core/graph/import-cycles.js';
+import { decodeTaintPath } from '../../core/ingestion/taint/path-codec.js';
+import { EXTENSIONS } from '../../core/ingestion/import-resolvers/utils.js';
+/** Real source-file extensions (`.ts`, `.py`, …) from the resolver's list,
+ *  excluding the empty entry and the `/index.*` forms — used to decide whether
+ *  an `explain` target is a file path vs a (possibly dotted) symbol name. */
+const SOURCE_FILE_EXTENSIONS = EXTENSIONS.filter((e) => e.startsWith('.') && !e.includes('/'));
+/** A target is path-ish if it has a path separator or ends in a known source
+ *  extension. A bare dotted symbol (`UserController.create`) is NOT path-ish. */
+function looksLikeFilePath(target) {
+    if (/[\\/]/.test(target))
+        return true;
+    const lower = target.toLowerCase();
+    return SOURCE_FILE_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -1034,6 +1048,8 @@ export class LocalBackend {
             }
             case 'context':
                 return this.context(repo, params);
+            case 'explain':
+                return this.explain(repo, params);
             case 'impact':
                 return this.impact(repo, params);
             case 'detect_changes':
@@ -2247,6 +2263,230 @@ export class LocalBackend {
             })),
         };
     }
+    /**
+     * Explain tool (#2083 M3 U6) — persisted taint-finding explanation.
+     * WAL-aware wrapper mirroring `context`.
+     */
+    async explain(repo, params) {
+        try {
+            return await this._explainImpl(repo, params);
+        }
+        catch (err) {
+            const msg = (err instanceof Error ? err.message : String(err)) || 'Explain query failed';
+            if (isWalCorruptionError(err)) {
+                return {
+                    error: msg,
+                    recoverySuggestion: WAL_RECOVERY_SUGGESTION,
+                };
+            }
+            throw err;
+        }
+    }
+    /**
+     * Taint findings are persisted as `TAINTED` rows in CodeRelation whose
+     * endpoints are BOTH BasicBlock nodes — the label anchor restricts every
+     * query here to the BasicBlock→BasicBlock partition of the rel table
+     * (which holds only the sparse, per-function-capped pdg layers), never a
+     * global symbol-space scan (the S1 verdict; LadybugDB has no rel-property
+     * index, so the label anchor IS the bound).
+     *
+     * Anchoring granularity:
+     * - file target → BasicBlock id prefix (`BasicBlock:<filePath>:` — the
+     *   shared `basicBlockId` template) with an exact-or-suffix path match so
+     *   `vuln.ts` finds `src/vuln.ts`.
+     * - symbol target → resolved via `resolveSymbolCandidates` (the context()
+     *   path: ambiguous ⇒ ranked candidates, unknown ⇒ not-found), then the
+     *   file id-prefix PLUS source-block startLine within the symbol's
+     *   [startLine, endLine] span. Findings are intra-procedural, so filtering
+     *   the SOURCE endpoint is sufficient — both endpoints share the function.
+     *   Symbols without a line span degrade to the file-level filter.
+     *
+     * The per-finding `sinkKind` and hop path decode from the persisted
+     * `reason` via the SHARED `taint/path-codec.ts` (the U4 write path encodes
+     * with the same module — `;<kind>` header + ordered `variable:line` hops).
+     */
+    async _explainImpl(repo, params) {
+        await this.ensureInitialized(repo);
+        const rawLimit = params.limit ?? EXPLAIN_DEFAULT_LIMIT;
+        if (!Number.isInteger(rawLimit) || rawLimit < 1 || rawLimit > EXPLAIN_MAX_LIMIT) {
+            return {
+                error: `Invalid "limit": expected an integer in [1, ${EXPLAIN_MAX_LIMIT}], got ${JSON.stringify(params.limit)}.`,
+            };
+        }
+        const limit = rawLimit;
+        const NO_TAINT_NOTE = 'no taint layer — run gitnexus analyze --pdg to record taint findings for this repo';
+        // Cheap meta probe: the TAINT layer exists iff the pdg stamp carries a
+        // `taintModelVersion` (the field M3 added). An M1/M2-era `--pdg` index has
+        // `meta.pdg` defined but no taintModelVersion — BasicBlock/REACHING_DEF
+        // exist, zero TAINTED rows do — so it must surface the no-taint-layer hint,
+        // not the generic "analyzed, nothing found" note. An unreadable meta (e.g.
+        // a seeded test DB) falls through to the row-existence probe below.
+        let pdgStamped;
+        try {
+            const meta = await loadMeta(path.dirname(repo.lbugPath));
+            if (meta)
+                pdgStamped = meta.pdg?.taintModelVersion !== undefined;
+        }
+        catch {
+            /* meta unreadable — decide from the DB below */
+        }
+        if (pdgStamped === false) {
+            return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
+        }
+        // Resolve the optional anchor into a WHERE clause on the SOURCE block.
+        const target = typeof params.target === 'string' ? params.target.trim() : '';
+        let anchorClause = '';
+        const queryParams = {};
+        let anchor;
+        // Build the anchor as a file filter (used only when `target` is path-ish).
+        const buildFileAnchor = () => {
+            // Exact path via the BasicBlock id-prefix template, OR a
+            // path-separator-aligned suffix so partial paths work like context()'s
+            // file_path hint ("vuln.ts" ⇒ "src/vuln.ts", never "devuln.ts").
+            anchorClause =
+                'AND (a.id STARTS WITH $idPrefix OR a.filePath = $targetPath OR a.filePath ENDS WITH $targetSuffix)';
+            queryParams.idPrefix = `BasicBlock:${target}:`;
+            queryParams.targetPath = target;
+            queryParams.targetSuffix = `/${target}`;
+            anchor = { file: target };
+        };
+        // Resolve `target` as a symbol into the anchor. Returns an early-return
+        // payload (not_found / ambiguous) or undefined on success.
+        const resolveSymbolAnchor = async () => {
+            const outcome = await this.resolveSymbolCandidates(repo, { name: target }, {});
+            if (outcome.kind === 'not_found') {
+                return { error: `Symbol '${target}' not found` };
+            }
+            if (outcome.kind === 'ambiguous') {
+                return {
+                    status: 'ambiguous',
+                    message: `Found ${outcome.candidates.length} symbols matching '${target}'. Re-call explain with the file path, or disambiguate via context() first.`,
+                    candidates: outcome.candidates.map((c) => ({
+                        uid: c.id,
+                        name: c.name,
+                        kind: c.type,
+                        filePath: c.filePath,
+                        line: c.startLine,
+                        score: Number(c.score.toFixed(2)),
+                    })),
+                };
+            }
+            const sym = outcome.symbol;
+            queryParams.idPrefix = `BasicBlock:${sym.filePath}:`;
+            anchor = { file: sym.filePath, symbol: sym.name };
+            if (typeof sym.startLine === 'number' &&
+                typeof sym.endLine === 'number' &&
+                sym.endLine >= sym.startLine) {
+                anchorClause =
+                    'AND a.id STARTS WITH $idPrefix AND a.startLine >= $symStart AND a.startLine <= $symEnd';
+                queryParams.symStart = sym.startLine;
+                queryParams.symEnd = sym.endLine;
+                anchor.startLine = sym.startLine;
+                anchor.endLine = sym.endLine;
+            }
+            else {
+                // No usable span — degrade to the file-level filter (documented).
+                anchorClause = 'AND a.id STARTS WITH $idPrefix';
+            }
+            return undefined;
+        };
+        // Bounded by construction: the BasicBlock→BasicBlock partition holds only
+        // the sparse pdg layers, TAINTED rows are per-function-capped at analyze
+        // time, and the page is LIMIT-bounded (the limit is a validated integer —
+        // interpolated because LadybugDB does not parameterize LIMIT).
+        const runAnchoredQuery = async () => {
+            const matchClause = `
+      MATCH (a:BasicBlock)-[r:CodeRelation]->(b:BasicBlock)
+      WHERE r.type = 'TAINTED' ${anchorClause}`;
+            const [qRows, countRows] = await Promise.all([
+                executeParameterized(repo.lbugPath, `${matchClause}
+      RETURN a.id AS sourceBlockId, a.filePath AS file, a.startLine AS sourceStart,
+             b.startLine AS sinkStart, r.reason AS reason, b.id AS sinkBlockId
+      ORDER BY sourceBlockId, sinkBlockId, reason
+      LIMIT ${limit}`, queryParams),
+                executeParameterized(repo.lbugPath, `${matchClause}
+      RETURN COUNT(*) AS total`, queryParams),
+            ]);
+            return {
+                rows: qRows,
+                totalFindings: Number(countRows[0]?.total ?? countRows[0]?.[0] ?? 0),
+            };
+        };
+        if (target) {
+            if (looksLikeFilePath(target)) {
+                buildFileAnchor();
+            }
+            else {
+                // A bare or dotted symbol name (`UserController.create`) — resolve as a
+                // symbol rather than silently file-anchoring to an empty result.
+                const early = await resolveSymbolAnchor();
+                if (early)
+                    return early;
+            }
+        }
+        const { rows, totalFindings } = await runAnchoredQuery();
+        if (totalFindings === 0 && pdgStamped === undefined && !target) {
+            // Meta was unreadable and the repo-wide enumerate found nothing — the
+            // count above WAS the existence probe; surface the layer hint.
+            return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
+        }
+        if (totalFindings === 0 && pdgStamped === undefined && target) {
+            // Anchored miss with unreadable meta: one extra bounded probe decides
+            // "no findings for this anchor" vs "no taint layer at all".
+            const probe = await executeParameterized(repo.lbugPath, `MATCH (a:BasicBlock)-[r:CodeRelation]->(b:BasicBlock) WHERE r.type = 'TAINTED' RETURN r.reason AS reason LIMIT 1`, {});
+            if (probe.length === 0) {
+                return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
+            }
+        }
+        const findings = rows.map((r) => {
+            const sourceBlockId = String(r.sourceBlockId ?? r[0] ?? '');
+            const file = String(r.file ?? r[1] ?? '');
+            const sourceStart = (r.sourceStart ?? r[2]);
+            const sinkStart = (r.sinkStart ?? r[3]);
+            const reason = r.reason ?? r[4];
+            // basicBlockId = `BasicBlock:<filePath>:<fnLine>:<fnCol>:<blockIdx>` —
+            // split from the RIGHT (the filePath may itself contain ':').
+            const idParts = sourceBlockId.split(':');
+            const fnLine = Number(idParts[idParts.length - 3]);
+            const decoded = decodeTaintPath(reason);
+            if (!decoded.ok) {
+                // Unreadable reason (foreign/corrupt row): surface the finding's
+                // existence with its block anchors, never throw.
+                return {
+                    file,
+                    ...(Number.isInteger(fnLine) ? { functionLine: fnLine } : {}),
+                    sinkKind: 'unknown',
+                    source: { line: sourceStart },
+                    sink: { line: sinkStart },
+                    hops: [],
+                    pathIncomplete: true,
+                };
+            }
+            const hops = decoded.hops.map((h) => ({
+                variable: h.variable,
+                line: h.line,
+                ...(h.viaCall ? { viaCall: true } : {}),
+            }));
+            const first = hops[0];
+            const last = hops[hops.length - 1];
+            return {
+                file,
+                ...(Number.isInteger(fnLine) ? { functionLine: fnLine } : {}),
+                sinkKind: decoded.kind ?? 'unknown',
+                source: first ? { variable: first.variable, line: first.line } : { line: sourceStart },
+                sink: { line: last?.line ?? sinkStart },
+                hops,
+                ...(decoded.truncated ? { pathIncomplete: true } : {}),
+            };
+        });
+        return {
+            ...(anchor ? { anchor } : {}),
+            findings,
+            totalFindings,
+            ...(totalFindings > findings.length ? { truncated: true } : {}),
+            note: 'Intra-procedural findings only — cross-function, closure/callback, property/field, and implicit flows are not modeled; absence of a finding is not proof of safety. SANITIZES (kill) edges are queryable via cypher.',
+        };
+    }
     /**
      * Legacy explore — kept for backwards compatibility with resources.ts.
      * Routes cluster/process types to direct graph queries.

package/dist/mcp/resources.js

@@ -270,6 +270,7 @@ async function getContextResource(backend, repoName) {
     lines.push('  - query: Process-grouped code intelligence (execution flows related to a concept)');
     lines.push('  - context: 360-degree symbol view (categorized refs, process participation)');
     lines.push('  - impact: Blast radius analysis (what breaks if you change a symbol)');
+    lines.push('  - explain: Persisted taint findings — source→sink data flows with per-hop variables (requires analyze --pdg)');
     lines.push('  - detect_changes: Git-diff impact analysis (what do your changes affect)');
     lines.push('  - rename: Multi-file coordinated rename with confidence tags');
     lines.push('  - cypher: Raw graph queries');

package/dist/mcp/tools.d.ts

@@ -36,4 +36,13 @@ export interface ToolDefinition {
  */
 export declare const LIST_REPOS_DEFAULT_LIMIT = 50;
 export declare const LIST_REPOS_MAX_LIMIT = 200;
+/**
+ * Pagination bounds for the `explain` tool (#2083 M3 U6). Findings are sparse
+ * and capped per function at analyze time, but a large repo can still
+ * accumulate enough TAINTED rows to blow MCP/LLM token limits — the response
+ * is page-bounded like `list_repos`. Exported so the backend clamp
+ * (`local-backend.ts`) and the schema stay a single source of truth.
+ */
+export declare const EXPLAIN_DEFAULT_LIMIT = 50;
+export declare const EXPLAIN_MAX_LIMIT = 200;
 export declare const GITNEXUS_TOOLS: ToolDefinition[];

package/dist/mcp/tools.js

@@ -32,6 +32,15 @@ const DESTRUCTIVE_TOOL_ANNOTATIONS = {
  */
 export const LIST_REPOS_DEFAULT_LIMIT = 50;
 export const LIST_REPOS_MAX_LIMIT = 200;
+/**
+ * Pagination bounds for the `explain` tool (#2083 M3 U6). Findings are sparse
+ * and capped per function at analyze time, but a large repo can still
+ * accumulate enough TAINTED rows to blow MCP/LLM token limits — the response
+ * is page-bounded like `list_repos`. Exported so the backend clamp
+ * (`local-backend.ts`) and the schema stay a single source of truth.
+ */
+export const EXPLAIN_DEFAULT_LIMIT = 50;
+export const EXPLAIN_MAX_LIMIT = 200;
 export const GITNEXUS_TOOLS = [
     {
         name: 'list_repos',
@@ -462,6 +471,49 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
             required: ['target', 'direction'],
         },
     },
+    {
+        name: 'explain',
+        description: `Explain persisted taint findings: intra-procedural source→sink data flows (TAINTED edges) recorded by \`gitnexus analyze --pdg\`.
+
+Each finding carries the sink category (command-injection, code-injection, path-traversal, sql-injection, xss), the source/sink lines, and the ordered hop path with the variable carried on each hop (decoded from the persisted path encoding).
+
+WHEN TO USE: Security review — "what taint findings exist in this repo / file / function?". Requires the repo to be indexed with \`gitnexus analyze --pdg\`; without that layer the tool returns a clear "no taint layer" note, not an error.
+
+ANCHORLESS (no "target"): enumerates all persisted findings for the repo — bounded ("limit", deterministic order), with "totalFindings" and a "truncated" flag.
+ANCHORED ("target" = file path or symbol/function name): full hop detail for that anchor. A file-ish target (contains "/" or an extension) filters by file; a symbol name resolves like context() — ambiguous names return ranked candidates, unknown names return not-found. Symbol anchoring is line-range granular (findings whose source block starts inside the symbol's span).
+
+CONTRACT CAVEATS (intra-procedural M3 scope — absent flows are NOT proof of safety):
+- Cross-function flows are not modeled (a flow through a helper function is invisible).
+- Closure/callback flows are invisible in both directions (e.g. arr.forEach(() => sink(y))).
+- Property/field flows are not tracked (obj.x = taint; sink(obj.y) has no chain).
+- Guard-style sanitizers (if (isValid(x))) and implicit/control-dependence flows are not modeled.
+- CommonJS aliasing is partially modeled (require('<literal>') joins resolve; dynamic requires do not).
+- Exception-path over-approximation can produce false-positive noise.
+
+Findings are deliberately NOT part of impact()'s traversal or the web schema — explain is the dedicated taint consumer. SANITIZES (kill) edges are queryable via cypher.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: {
+                    type: 'string',
+                    description: 'Optional anchor: a file path (e.g. "src/handlers/run.ts" — suffix match accepted) or a symbol/function name (resolved like context()). Omit to enumerate all findings for the repo.',
+                },
+                limit: {
+                    type: 'integer',
+                    description: `Max findings returned (default: ${EXPLAIN_DEFAULT_LIMIT}, max: ${EXPLAIN_MAX_LIMIT}). "totalFindings" reports the full matched count; "truncated" is set when the page is smaller.`,
+                    default: EXPLAIN_DEFAULT_LIMIT,
+                    minimum: 1,
+                    maximum: EXPLAIN_MAX_LIMIT,
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+            },
+            required: [],
+        },
+    },
     {
         name: 'route_map',
         description: `Show API route mappings: which components/hooks fetch which API endpoints, and which handler files serve them.
@@ -595,6 +647,7 @@ const BRANCH_SCOPED_TOOLS = new Set([
     'cypher',
     'context',
     'detect_changes',
+    'explain',
     'check',
     'impact',
     'rename',

package/dist/storage/parse-cache.js

@@ -111,7 +111,16 @@ export const computeChunkHash = (entries, pdg = false) => {
     // option-blind-key trap. `def` marks an unset (default) value so two
     // default-cap runs share a key. The emit-time edge cap is deliberately
     // absent — see the PdgCacheKey doc comment.
-    const ns = `pdg:1;maxFn=${opts.maxFunctionLines ?? 'def'}`;
+    //
+    // NAMESPACE VERSION (`pdg:2`): bumped when the worker-emitted
+    // `cfgSideChannel` SHAPE changes for pdg-mode runs only — pdg:1→2 in #2083
+    // M3 U1 (TsHarvester emits taint `sites` on StatementFacts). Invalidates
+    // pdg-mode chunks and their durable parsedfile-cache entries; flag-off
+    // chunk keys never reach this line and stay byte-identical, so non-pdg
+    // users pay nothing. Deliberately NOT a SCHEMA_BUMP — that gates the whole
+    // cache version and would force a full cold re-parse on EVERY user (the M1
+    // bump comment above records that cost).
+    const ns = `pdg:2;maxFn=${opts.maxFunctionLines ?? 'def'}`;
     return sha256Hex(`${ns}\n${joined}`);
 };
 /**

package/dist/storage/repo-manager.d.ts

@@ -134,6 +134,24 @@ export interface RepoMeta {
          * type for that reason; resolved (always present) on every M2+ write.
          */
         maxReachingDefEdgesPerFunction?: number;
+        /**
+         * Per-function taint findings cap, resolved (0 = unlimited; #2083 M3).
+         * ABSENT on an M1/M2-era stamp — like `maxReachingDefEdgesPerFunction`,
+         * that absence is what trips `pdgModeMismatch` on the first M3 run and
+         * forces the full writeback that populates TAINTED/SANITIZES rows.
+         */
+        maxTaintFindingsPerFunction?: number;
+        /** Per-finding taint hop cap, resolved (0 = unlimited; #2083 M3 KTD6 —
+         *  bounds the persisted hop-encoded `reason`). Optional for the same
+         *  M2-era-stamp upgrade reason as the findings cap. */
+        maxTaintHops?: number;
+        /**
+         * Digest of the built-in taint model the persisted findings were
+         * produced under (#2083 M3 KTD7/R7). Any model-content change ships a
+         * new digest → mismatch → full writeback repopulates taint edges
+         * without `--force`. Optional: absent on pre-M3 stamps.
+         */
+        taintModelVersion?: string;
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.20",
+  "version": "1.6.8-rc.21",
   "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",

package/skills/gitnexus-guide.md

@@ -38,6 +38,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | `detect_changes` | Git-diff impact — what do your current changes affect                    |
 | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
 | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `explain`        | Persisted taint findings — source→sink data flows (needs `analyze --pdg`) |
 | `list_repos`     | Discover indexed repos (paginated — `limit`/`offset`)                    |
 
 ### Paginating `list_repos`
@@ -71,6 +72,16 @@ list_repos { offset: 400 }  → repos 401–437,                 hasMore false
 
 Notes: `offset` ≥ `total` returns an empty page (with `total` still reported). Out-of-range or malformed `limit`/`offset` (non-integer, `limit` outside `[1, 200]`, `offset < 0`) are rejected with a clear error — `limit` above the max is rejected, not silently capped. The order is deterministic (lower-cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged.
 
+### Taint findings (`explain`)
+
+`explain` returns intra-procedural taint findings (`TAINTED` edges) recorded by `gitnexus analyze --pdg` — each with a sink category (command-injection, code-injection, path-traversal, sql-injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop.
+
+- `explain {}` — enumerate all findings for the repo (bounded by `limit`, deterministic order)
+- `explain { target: "src/vuln.ts" }` — findings in a file (suffix path match accepted)
+- `explain { target: "runUserCommand" }` — findings in a function (resolved like `context`; ambiguous names return ranked candidates)
+
+A repo indexed without `--pdg` returns a clear "no taint layer" note. Caveats: findings are intra-procedural only — cross-function, closure/callback, property/field, and implicit flows are not modeled, so the absence of a finding is **not** proof of safety. `SANITIZES` (sanitizer-kill) edges are queryable via `cypher`.
+
 ## Resources Reference
 
 Lightweight reads (~100-500 tokens) for navigation: