graph-indexer 2.0.0 → 2.1.1

package/parse/scip.mjs

@@ -0,0 +1,391 @@
+/**
+ * @file parse/scip.mjs
+ * @description A2 — SCIP ingestion for the precise resolver provider. Reads a LOCALLY-generated
+ *              SCIP index (Sourcegraph's protocol; produced out-of-band by the user's own
+ *              air-gapped toolchain — `scip-typescript`, `scip-python`, `scip-java`,
+ *              `rust-analyzer --scip`) and aligns its symbol OCCURRENCES to our AST chunks by
+ *              (file, line), yielding a genuinely cross-file binding relation:
+ *
+ *                  bindings: Map<fromChunkId, Set<defChunkId>>
+ *
+ *              i.e. "chunk F references a symbol whose definition lives in chunk D." The `scip`
+ *              resolver (mcp/resolver.mjs) consumes this to (a) PROMOTE a heuristic edge to the
+ *              `resolved` tier when SCIP confirms it, and (b) SUPPRESS the wrong-target edges a
+ *              name-only fan-out would otherwise emit — the precision A1's heuristic cannot reach.
+ *
+ *              ZERO new runtime dependency: the `.scip` protobuf is decoded by a minimal,
+ *              hand-rolled wire reader (only the four fields A2 needs — Index.documents,
+ *              Document.relative_path / .occurrences, Occurrence.range / .symbol / .symbol_roles).
+ *              A SCIP-shaped JSON file is also accepted (handy for hand-authored fixtures and for
+ *              `scip print`-style dumps). Fully offline; pure parsing + graph alignment.
+ *
+ *              HONEST SCOPE: SCIP coverage is only as good as the indexer that produced the file
+ *              and the (file, range) alignment to our chunks. Suppression is SOUND under partial
+ *              coverage — a candidate def is dropped only if SCIP actually recorded it as a
+ *              definition (`definedChunks`); a def SCIP never saw falls through to heuristic. v1
+ *              applies SCIP resolution to `calls` edges only (the binding relation is kind-agnostic,
+ *              so `extends`/`type` edges stay heuristic to avoid cross-kind contamination).
+ *
+ *              A2 v2 ADDS a second, kind-agnostic consumer that the same binding relation serves
+ *              soundly precisely BECAUSE it is kind-agnostic: `buildScipReferers` inverts the
+ *              bindings into a precise cross-file "referenced-by" map for find_references — no edge
+ *              suppression, no cross-kind risk, just the binding-precise reference set serialized as
+ *              an isolated index artifact (like centrality/taint), so it cannot perturb A4 edges or
+ *              A5 centrality.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+import fs from 'node:fs';
+
+// ── SCIP schema field numbers (scip.proto) — only what A2 reads ─────────────────────────────
+//   Index.documents          = 2  (repeated Document)
+//   Document.relative_path    = 1  (string)
+//   Document.occurrences      = 2  (repeated Occurrence)
+//   Occurrence.range          = 1  (repeated int32, packed)
+//   Occurrence.symbol         = 2  (string)
+//   Occurrence.symbol_roles   = 3  (int32 bitset; Definition = 0x1)
+const F_INDEX_DOCUMENTS = 2;
+const F_DOC_RELATIVE_PATH = 1;
+const F_DOC_OCCURRENCES = 2;
+const F_OCC_RANGE = 1;
+const F_OCC_SYMBOL = 2;
+const F_OCC_SYMBOL_ROLES = 3;
+const ROLE_DEFINITION = 0x1;
+
+// ── Minimal protobuf wire-format reader (zero deps) ─────────────────────────────────────────
+
+/**
+ * Read a base-128 varint as a JS Number. Uses multiplication (not bit-shift) so values up to
+ * 2^53 decode correctly — proto lengths / line numbers never exceed that in practice.
+ * @returns {[number, number]} [value, nextPos]
+ */
+function readVarint(buf, pos) {
+    let result = 0;
+    let mul = 1;
+    let p = pos;
+    for (;;) {
+        if (p >= buf.length) throw new Error('SCIP: truncated varint');
+        const b = buf[p++];
+        result += (b & 0x7f) * mul;
+        if ((b & 0x80) === 0) break;
+        mul *= 128;
+    }
+    return [result, p];
+}
+
+/**
+ * Iterate the fields of one protobuf message region [start, end). Yields, per field, either a
+ * scalar `{ field, wire, value }` (varint / fixed) or a length-delimited `{ field, wire, start,
+ * end }` slice. Unknown fields are yielded too (callers skip what they don't recognise).
+ */
+function* iterFields(buf, start, end) {
+    let p = start;
+    while (p < end) {
+        let tag;
+        [tag, p] = readVarint(buf, p);
+        const field = Math.floor(tag / 8);
+        const wire = tag % 8;
+        if (wire === 0) {
+            let value;
+            [value, p] = readVarint(buf, p);
+            yield { field, wire, value };
+        } else if (wire === 2) {
+            let len;
+            [len, p] = readVarint(buf, p);
+            const s = p;
+            p += len;
+            if (p > end) throw new Error('SCIP: length-delimited field overruns message');
+            yield { field, wire, start: s, end: p };
+        } else if (wire === 5) {
+            if (p + 4 > end) throw new Error('SCIP: fixed32 field overruns message');
+            const value = buf.readUInt32LE(p);
+            p += 4;
+            yield { field, wire, value };
+        } else if (wire === 1) {
+            if (p + 8 > end) throw new Error('SCIP: fixed64 field overruns message');
+            const lo = buf.readUInt32LE(p);
+            const hi = buf.readUInt32LE(p + 4);
+            p += 8;
+            yield { field, wire, value: hi * 4294967296 + lo };
+        } else {
+            throw new Error(`SCIP: unsupported wire type ${wire}`);
+        }
+    }
+}
+
+/** Read all packed varints in [start, end) into an array (Occurrence.range is packed int32). */
+function readPackedVarints(buf, start, end) {
+    const out = [];
+    let p = start;
+    while (p < end) {
+        let v;
+        [v, p] = readVarint(buf, p);
+        out.push(v);
+    }
+    return out;
+}
+
+/**
+ * SCIP `range` → 0-based start line. Length-3 ranges are [startLine, startChar, endChar]
+ * (single line); length-4 are [startLine, startChar, endLine, endChar]. We key alignment on the
+ * start line only.
+ */
+function rangeStartLine(range) {
+    return Array.isArray(range) && range.length >= 1 ? range[0] : null;
+}
+
+function parseOccurrence(buf, start, end) {
+    let range = [];
+    let symbol = '';
+    let roles = 0;
+    for (const f of iterFields(buf, start, end)) {
+        if (f.field === F_OCC_RANGE) {
+            if (f.wire === 2) range = range.concat(readPackedVarints(buf, f.start, f.end)); // packed
+            else if (f.wire === 0) range.push(f.value); // unpacked fallback
+        } else if (f.field === F_OCC_SYMBOL && f.wire === 2) {
+            symbol = buf.toString('utf8', f.start, f.end);
+        } else if (f.field === F_OCC_SYMBOL_ROLES && f.wire === 0) {
+            roles = f.value;
+        }
+    }
+    const startLine = rangeStartLine(range);
+    if (startLine === null || !symbol) return null;
+    return { startLine, symbol, isDefinition: (roles & ROLE_DEFINITION) === ROLE_DEFINITION };
+}
+
+function parseDocument(buf, start, end) {
+    let relativePath = '';
+    const occurrences = [];
+    for (const f of iterFields(buf, start, end)) {
+        if (f.field === F_DOC_RELATIVE_PATH && f.wire === 2) {
+            relativePath = buf.toString('utf8', f.start, f.end);
+        } else if (f.field === F_DOC_OCCURRENCES && f.wire === 2) {
+            const occ = parseOccurrence(buf, f.start, f.end);
+            if (occ) occurrences.push(occ);
+        }
+    }
+    return { relativePath, occurrences };
+}
+
+/** Decode a `.scip` protobuf buffer into `{ documents: [{ relativePath, occurrences }] }`. */
+function decodeScipProtobuf(buf) {
+    const documents = [];
+    for (const f of iterFields(buf, 0, buf.length)) {
+        if (f.field === F_INDEX_DOCUMENTS && f.wire === 2) {
+            documents.push(parseDocument(buf, f.start, f.end));
+        }
+    }
+    return { documents };
+}
+
+// ── JSON-shaped SCIP (convenience: hand-authored fixtures, `scip print` dumps) ──────────────
+
+function normalizeJsonScip(obj) {
+    const rawDocs = obj.documents || obj.Documents || [];
+    const documents = [];
+    for (const d of rawDocs) {
+        const relativePath = d.relative_path || d.relativePath || d.path || '';
+        const occurrences = [];
+        for (const o of (d.occurrences || d.Occurrences || [])) {
+            const range = o.range || o.Range || [];
+            const symbol = o.symbol || o.Symbol || '';
+            const roles = o.symbol_roles || o.symbolRoles || o.roles || 0;
+            const startLine = rangeStartLine(range);
+            if (startLine === null || !symbol) continue;
+            occurrences.push({ startLine, symbol, isDefinition: (roles & ROLE_DEFINITION) === ROLE_DEFINITION });
+        }
+        documents.push({ relativePath, occurrences });
+    }
+    return { documents };
+}
+
+/**
+ * Load a SCIP index from disk. Accepts the `.scip` protobuf OR a SCIP-shaped JSON file
+ * (auto-detected: a leading `{` / `.json` extension → JSON). Returns the decoded documents and a
+ * loud-on-failure shape (throws with an actionable message; the caller decides whether a missing
+ * file is fatal or a warning).
+ *
+ * @param {string} filePath
+ * @returns {{ documents: Array<{ relativePath: string, occurrences: Array<{ startLine:number, symbol:string, isDefinition:boolean }> }> }}
+ */
+export function loadScip(filePath) {
+    let buf;
+    try {
+        buf = fs.readFileSync(filePath);
+    } catch (e) {
+        throw new Error(`SCIP index not readable at ${filePath}: ${e.message}`);
+    }
+    const looksJson = filePath.endsWith('.json') || (buf.length > 0 && (buf[0] === 0x7b /* { */ || buf[0] === 0x5b /* [ */));
+    if (looksJson) {
+        try {
+            return normalizeJsonScip(JSON.parse(buf.toString('utf8')));
+        } catch (e) {
+            throw new Error(`SCIP JSON parse failed at ${filePath}: ${e.message}`);
+        }
+    }
+    try {
+        return decodeScipProtobuf(buf);
+    } catch (e) {
+        throw new Error(`SCIP protobuf decode failed at ${filePath}: ${e.message}`);
+    }
+}
+
+// ── Alignment: SCIP occurrences → our chunk ids ─────────────────────────────────────────────
+
+/** Normalize a SCIP document path to our chunk `file_path` form: repo-root-relative, POSIX, no `./`. */
+export function normalizeScipPath(p) {
+    if (!p) return '';
+    let s = String(p).replace(/\\/g, '/');
+    s = s.replace(/^file:\/\//, '');     // tolerate a file:// URI prefix
+    s = s.replace(/^\.?\//, '');          // strip a leading './' or '/'
+    return s;
+}
+
+function addToSetMap(map, key, value) {
+    let s = map.get(key);
+    if (!s) { s = new Set(); map.set(key, s); }
+    s.add(value);
+}
+
+/**
+ * Find the MOST SPECIFIC chunk (smallest line span) whose 1-based [start_line, end_line] range
+ * contains `line1`. Deterministic tie-break: larger start_line (innermost), then smaller id.
+ * `arr` is the file's chunk list (any order — we scan it fully; files have few chunks).
+ */
+function chunkContaining(arr, line1) {
+    let best = null;
+    let bestSpan = Infinity;
+    for (const c of arr) {
+        if (c.start_line <= line1 && line1 <= c.end_line) {
+            const span = c.end_line - c.start_line;
+            if (span < bestSpan
+                || (span === bestSpan && best && (c.start_line > best.start_line
+                    || (c.start_line === best.start_line && c.id < best.id)))) {
+                best = c;
+                bestSpan = span;
+            }
+        }
+    }
+    return best;
+}
+
+/**
+ * Align a decoded SCIP index to a loaded store's chunks and derive the cross-file binding
+ * relation the `scip` resolver consumes:
+ *
+ *     bindings: Map<fromChunkId, Set<defChunkId>>   // "chunk F references a symbol defined in D"
+ *
+ * Built by: (1) bucket chunks by file; (2) for each SCIP occurrence, locate its containing chunk
+ * by 1-based line range (SCIP lines are 0-based → +1); (3) split occurrences into per-symbol
+ * DEFINITIONS (symbol_roles & Definition) and per-chunk REFERENCES; (4) join references to the
+ * chunk(s) that define each referenced symbol. Self-references are dropped (a def referencing
+ * itself is not an inbound edge). Fully deterministic; pure graph alignment, no network.
+ *
+ * Also returns `definedChunks` — every chunk SCIP recorded a DEFINITION occurrence for. This is the
+ * SOUNDNESS gate for suppression: a candidate def may be dropped as a wrong-target only if SCIP
+ * actually *saw* it as a definition (`def ∈ definedChunks`). A def SCIP never covered (an uncovered
+ * file in a polyglot / partial run, a stale `.scip`, a missed occurrence) is NEVER suppressed — it
+ * falls through to heuristic confidence, honouring "files the SCIP index does not cover are never
+ * worse" even when the *caller* is covered but the *def* is not.
+ *
+ * @param {object} db  A loaded store exposing iterateChunks() (chunks carry file_path/start_line/end_line/id).
+ * @param {{documents: Array}} scip  The result of loadScip().
+ * @returns {{ bindings: Map<string, Set<string>>, definedChunks: Set<string>, stats: object }}
+ */
+export function buildScipBindings(db, scip) {
+    const documents = (scip && scip.documents) || [];
+
+    // (1) one pass over chunks → Map<file_path, chunk[]>
+    const byFile = new Map();
+    for (const c of db.iterateChunks()) {
+        let arr = byFile.get(c.file_path);
+        if (!arr) { arr = []; byFile.set(c.file_path, arr); }
+        arr.push(c);
+    }
+
+    const defChunkBySymbol = new Map(); // symbol → Set<chunkId> (definition occurrences)
+    const refSymbolsByChunk = new Map(); // chunkId → Set<symbol> (reference occurrences)
+    let matchedDocs = 0;
+    let placedOcc = 0;
+    let totalOcc = 0;
+
+    // (2)+(3) place occurrences into chunks
+    for (const doc of documents) {
+        const fp = normalizeScipPath(doc.relativePath);
+        const arr = byFile.get(fp);
+        if (!arr) continue;               // SCIP doc not in our index (path mismatch or uncovered)
+        matchedDocs++;
+        for (const occ of (doc.occurrences || [])) {
+            totalOcc++;
+            const line1 = occ.startLine + 1; // SCIP 0-based → our 1-based
+            const c = chunkContaining(arr, line1);
+            if (!c) continue;
+            placedOcc++;
+            if (occ.isDefinition) addToSetMap(defChunkBySymbol, occ.symbol, c.id);
+            else addToSetMap(refSymbolsByChunk, c.id, occ.symbol);
+        }
+    }
+
+    // (4) derive fromChunk → Set<defChunk>
+    const bindings = new Map();
+    let pairCount = 0;
+    for (const [fromId, symbols] of refSymbolsByChunk) {
+        for (const sym of symbols) {
+            const defChunks = defChunkBySymbol.get(sym);
+            if (!defChunks) continue;
+            for (const defId of defChunks) {
+                if (defId === fromId) continue; // self-reference is not an inbound edge
+                const before = bindings.get(fromId)?.size || 0;
+                addToSetMap(bindings, fromId, defId);
+                if ((bindings.get(fromId)?.size || 0) > before) pairCount++;
+            }
+        }
+    }
+
+    // The set of chunks SCIP recorded as a definition — the suppression soundness gate.
+    const definedChunks = new Set();
+    for (const ids of defChunkBySymbol.values()) for (const id of ids) definedChunks.add(id);
+
+    const stats = {
+        docs: documents.length,
+        matchedDocs,
+        occurrences: totalOcc,
+        placedOccurrences: placedOcc,
+        definedSymbols: defChunkBySymbol.size,
+        definedChunks: definedChunks.size,
+        boundChunks: bindings.size,
+        bindingPairs: pairCount,
+    };
+    return { bindings, definedChunks, stats };
+}
+
+/**
+ * A2 v2 — invert the cross-file binding relation into the precise "referenced-by" map that
+ * find_references consumes:
+ *
+ *     scipRefs: { defChunkId: [refererChunkId, ...] }   // "this definition is referenced by …"
+ *
+ * SCIP occurrences are kind-AGNOSTIC — a Reference occurrence is "symbol X is used here," with no
+ * call/type-use/inheritance distinction — which is exactly the question find_references answers
+ * ("what references this symbol?"). So the inverse of `bindings` is a genuinely cross-file,
+ * binding-precise reference set: it (a) DISAMBIGUATES same-named symbols (a referer is attached to
+ * the one definition SCIP bound it to, not every same-named def the name heuristic would match), and
+ * (b) RECOVERS references the AST/name heuristic misses entirely (the v1 "recall concern"), e.g.
+ * type usages in languages whose `type_refs` channel is empty. Serialized deterministically (sorted
+ * def ids, sorted referer ids) so both backends round-trip byte-identically. Self-references were
+ * already dropped upstream in buildScipBindings.
+ *
+ * @param {Map<string, Set<string>>} bindings  fromChunkId → set of def chunk ids (buildScipBindings).
+ * @returns {Record<string, string[]>}  defChunkId → sorted referer chunk ids (empty object when none).
+ */
+export function buildScipReferers(bindings) {
+    const rel = bindings instanceof Map ? bindings : new Map();
+    const inv = new Map();                       // defChunkId → Set<refererChunkId>
+    for (const [refererId, defIds] of rel) {
+        for (const defId of defIds) addToSetMap(inv, defId, refererId);
+    }
+    const out = {};
+    for (const defId of [...inv.keys()].sort()) out[defId] = [...inv.get(defId)].sort();
+    return out;
+}

package/parse/taint-patterns.mjs

@@ -0,0 +1,119 @@
+/**
+ * @file parse/taint-patterns.mjs
+ * @description Source / sink / sanitizer catalogs for taint analysis (C2). Heuristic, line-scannable
+ *              regexes per language family — the basis for a *finder*, not a verifier (see
+ *              mcp/taint.mjs and docs/internals/PHASE3_TAINT_ANALYSIS.md for the honesty caveats).
+ *
+ *              SOURCES = untrusted input (request bodies, argv/env, stdin, file/socket reads).
+ *              SINKS   = dangerous operations, grouped by category (rce | sqli | xss | path | ssrf).
+ *              SANITIZERS = constructs that neutralise taint (escape/encode/parameterise/validate).
+ *
+ *              Covers the JS/TS family ('js'), Python ('py'), Java ('java'), and Go ('go'); other
+ *              languages return no patterns (the analysis simply finds nothing for them).
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+
+/** Normalise a file extension to a pattern-catalog key, or null if unsupported. */
+export function langKeyForExt(ext) {
+    if (['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx'].includes(ext)) return 'js';
+    if (ext === '.py') return 'py';
+    if (ext === '.java') return 'java';
+    if (ext === '.go') return 'go';
+    return null;
+}
+
+/** Untrusted-input sources: { re, kind }. */
+export const SOURCES = {
+    js: [
+        { re: /\breq(uest)?\.(body|query|params|cookies|headers|url|originalUrl)\b/, kind: 'http-request' },
+        { re: /\bctx\.(request|query|params|body)\b/, kind: 'http-request' },          // Koa
+        { re: /\bprocess\.(argv|env)\b/, kind: 'process-input' },
+        { re: /\.on\s*\(\s*['"]data['"]/, kind: 'socket-data' },
+        { re: /\b(location\.(search|hash|href)|document\.(URL|cookie|referrer))\b/, kind: 'dom-input' },
+    ],
+    py: [
+        { re: /\brequest\.(GET|POST|data|args|form|json|values|cookies|files|headers)\b/, kind: 'http-request' },
+        { re: /\b(sys\.argv|os\.environ)\b/, kind: 'process-input' },
+        { re: /\binput\s*\(/, kind: 'stdin' },
+        { re: /\bflask\.request\b|\bself\.get_argument\s*\(/, kind: 'http-request' },
+    ],
+    java: [
+        { re: /\b(request|req)\.(getParameter|getParameterValues|getParameterMap|getHeader|getHeaders|getQueryString|getInputStream|getReader|getCookies)\s*\(/, kind: 'http-request' },
+        { re: /@(RequestParam|PathVariable|RequestBody|RequestHeader|CookieValue|MatrixVariable|ModelAttribute)\b/, kind: 'http-request' },
+        { re: /\bSystem\.(getenv|getProperty)\s*\(/, kind: 'process-input' },
+        { re: /\bnew\s+Scanner\s*\(\s*System\.in\b/, kind: 'stdin' },
+    ],
+    go: [
+        { re: /\br\.(URL\.Query\s*\(\s*\)|FormValue|PostFormValue|Form\b|PostForm\b|MultipartForm)|\br\.Header\.Get\s*\(|\br\.Cookie\s*\(/, kind: 'http-request' },
+        { re: /\b(mux\.Vars|c\.(Param|Query|PostForm|DefaultQuery)|ctx\.(Query|Param))\s*\(/, kind: 'http-request' },
+        { re: /\b(os\.Args|os\.Getenv\s*\(|flag\.(String|Int|Bool|Parse)\s*\()/, kind: 'process-input' },
+        { re: /\bbufio\.NewReader\s*\(\s*os\.Stdin\b|\bfmt\.Scan\w*\s*\(/, kind: 'stdin' },
+    ],
+};
+
+/** Dangerous sinks: { re, category, label }. Categories: rce | sqli | xss | path | ssrf. */
+export const SINKS = {
+    js: [
+        { re: /\beval\s*\(/, category: 'rce', label: 'eval()' },
+        { re: /\bnew\s+Function\s*\(/, category: 'rce', label: 'new Function()' },
+        { re: /\b(child_process\b|\bexecSync\b|\bexecFile\b|\bexec\s*\(|\bspawn\s*\()/, category: 'rce', label: 'child_process exec/spawn' },
+        { re: /\.(query|execute|raw)\s*\(/, category: 'sqli', label: 'db query/execute' },
+        { re: /(\.innerHTML\s*=|dangerouslySetInnerHTML|\bres\.(send|write|end)\s*\()/, category: 'xss', label: 'html sink' },
+        { re: /\b(fs\.(readFile|writeFile|unlink|createReadStream|createWriteStream|appendFile)(Sync)?|path\.join|res\.sendFile)\s*\(/, category: 'path', label: 'fs/path sink' },
+        { re: /\b(fetch|axios|got|superagent)\s*\(|\bhttps?\.request\s*\(/, category: 'ssrf', label: 'outbound request' },
+    ],
+    py: [
+        { re: /\b(eval|exec)\s*\(/, category: 'rce', label: 'eval/exec' },
+        { re: /\bos\.system\s*\(|\bsubprocess\.(call|run|Popen|check_output)\s*\(|\bos\.popen\s*\(/, category: 'rce', label: 'os.system/subprocess' },
+        { re: /\.execute(many)?\s*\(|\bcursor\.execute\s*\(|\.raw\s*\(/, category: 'sqli', label: 'cursor.execute' },
+        { re: /\b(mark_safe|render_template_string|HttpResponse)\s*\(/, category: 'xss', label: 'html sink' },
+        { re: /\b(open|send_file|os\.path\.join)\s*\(/, category: 'path', label: 'open/send_file' },
+        { re: /\brequests\.(get|post|put|delete|request)\s*\(|\burllib\.|\burlopen\s*\(/, category: 'ssrf', label: 'outbound request' },
+    ],
+    java: [
+        { re: /\bRuntime\.getRuntime\s*\(\s*\)\s*\.exec\s*\(|\bnew\s+ProcessBuilder\s*\(|\bProcessBuilder\s*\(/, category: 'rce', label: 'Runtime.exec/ProcessBuilder' },
+        { re: /\.(executeQuery|executeUpdate|execute|createQuery|createNativeQuery|createStatement)\s*\(/, category: 'sqli', label: 'jdbc/jpa statement' },
+        { re: /\b(getWriter\s*\(\s*\)\s*\.(print|println|write)|out\.(print|println)\s*\(|\.appendChild\s*\()/, category: 'xss', label: 'servlet/JSP writer' },
+        { re: /\bnew\s+(File|FileInputStream|FileReader|FileOutputStream|FileWriter)\s*\(|\bPaths\.get\s*\(|\bFiles\.(read|write|newInputStream|copy)\w*\s*\(/, category: 'path', label: 'file/path sink' },
+        { re: /\bnew\s+URL\s*\(|\.openConnection\s*\(|\b(RestTemplate|WebClient|HttpClient)\b|\bHttpRequest\.newBuilder\s*\(/, category: 'ssrf', label: 'outbound request' },
+    ],
+    go: [
+        { re: /\bexec\.Command(Context)?\s*\(/, category: 'rce', label: 'exec.Command' },
+        // The `.URL`-scoped lookbehind excludes only `x.URL.Query()` (net/url's parser) — a db handle
+        // like `dbURL.Query()` is still matched. Exec* needs no guard (url.URL has no Exec method).
+        { re: /(?<!\.URL)\.(Query|QueryRow|QueryContext|QueryRowContext)\s*\(/, category: 'sqli', label: 'db query' },
+        { re: /\.(Exec|ExecContext)\s*\(/, category: 'sqli', label: 'db exec' },
+        { re: /\bw\.Write\s*\(|\bio\.WriteString\s*\(\s*w|\bfmt\.Fprint\w*\s*\(\s*w|\btemplate\.HTML\s*\(/, category: 'xss', label: 'response writer / template.HTML' },
+        { re: /\b(os\.Open|os\.OpenFile|os\.ReadFile|ioutil\.ReadFile|os\.Create|filepath\.Join|http\.ServeFile)\s*\(/, category: 'path', label: 'file/path sink' },
+        { re: /\bhttp\.(Get|Post|Head|PostForm|NewRequest|NewRequestWithContext)\s*\(|\b\w*[Cc]lient\.Do\s*\(/, category: 'ssrf', label: 'outbound request' },
+    ],
+};
+
+/** Taint-clearing constructs: any match in/around the flow lowers a finding's confidence. */
+export const SANITIZERS = {
+    js: [
+        /\b(escape|encodeURI|encodeURIComponent|sanitize|DOMPurify|validator|xss)\b/i,
+        /\b(parameteriz|prepared|placeholder)\b/i,
+        /\b(Number|parseInt|parseFloat)\s*\(/,
+    ],
+    py: [
+        /\b(shlex\.quote|escape|bleach|markupsafe|secure_filename|quote)\b/i,
+        /\b(parameteriz|placeholder)\b/i,
+        /\bint\s*\(|\bfloat\s*\(/,
+    ],
+    java: [
+        /\b(PreparedStatement|setString|setInt|setLong|NamedParameter)\b|@Param\b/,
+        /\b(URLEncoder\.encode|StringEscapeUtils|HtmlUtils\.htmlEscape|ESAPI|encodeForHTML|Encode\.forHtml|Jsoup\.clean)\b/,
+        /\b(Integer\.parseInt|Long\.parseLong|Double\.parseDouble|UUID\.fromString)\s*\(/,
+    ],
+    go: [
+        /\bstrconv\.(Atoi|ParseInt|ParseFloat|ParseUint|ParseBool)\s*\(/,
+        /\b(template\.HTMLEscapeString|template\.JSEscapeString|html\.EscapeString|url\.QueryEscape|url\.PathEscape)\s*\(/,
+        /\bfilepath\.(Clean|Base)\s*\(|\bsql\.Named\b|\$\d+/,
+    ],
+};
+
+/** Human-readable severity order for sink categories (worst first). */
+export const CATEGORY_SEVERITY = ['rce', 'sqli', 'ssrf', 'path', 'xss'];

package/prompts/CORE.md

@@ -32,12 +32,12 @@
         <playbook name="one-known-symbol" calls="1-2">resolve_symbol("Name") → answer. get_chunk(id) only when the body is the question. Miss → ONE search_code(query: "what it does", exact_tokens: "Name"), then accept the outcome.</playbook>
         <playbook name="several-known-symbols" calls="1-2">ONE search_code(query: "A B C D", detail: "smart", top_k: 2×N): top cards = definitions with query-relevant body lines + topology; lower cards = consumers whose bodies mention the names. Spend a 2nd call only to escalate ONE result to full body. The serial resolve_symbol(A)→(B)→(C)→(D) loop burns the budget with nothing read — limit 2 forbids it.</playbook>
         <playbook name="concept-or-behaviour" calls="2-3">search_code(behavioural query, detail: "signatures", top_k: 5) → get_chunk_summary(best id) or one re-search with detail: "smart" → answer. LOW-CONFIDENCE HANDOFF: a "⚠️ Low confidence — Candidate files" line (json: low_confidence + candidate_files[]) means the right FILE is in that short list but wasn't ranked #1 — get_file_skeleton ONE candidate (or re-search with a symbol name / exact_tokens), never read whole files blindly. It never appears on confident symbol lookups, so its presence is itself the signal to switch tactics.</playbook>
-        <playbook name="where-used-or-impact" calls="1-2">Blast radius, by node type (check the card): FUNCTION/METHOD → get_call_graph("name"); CLASS/TYPE/INTERFACE/ENUM → find_references("Name"); thin result → ONE search_code(exact_tokens: "Name", detail: "signatures", top_k: 8). Never read files to hunt usage. "No callers/refs" ≠ unused (may be framework-invoked). A STALE index footer (json: index.stale) means a "safe to modify" verdict may be wrong — trust it only after `npm run mcp:index`.</playbook>
+        <playbook name="where-used-or-impact" calls="1-2">Editing X next? ONE impact_of_edit("X") gives the precise transitive radius + routes + tests; unfamiliar symbol → explain_symbol("X"). Just listing usage, by node type (check the card): FUNCTION/METHOD → get_call_graph("name"); CLASS/TYPE/INTERFACE/ENUM → find_references("Name"); thin result → ONE search_code(exact_tokens: "Name", detail: "signatures", top_k: 8). Never read files to hunt usage. "No callers/refs" ≠ unused (may be framework-invoked). A STALE index footer (json: index.stale) means a "safe to modify" verdict may be wrong — trust it only after `npm run mcp:index`.</playbook>
         <playbook name="one-file" calls="1">get_file_skeleton(path): every definition + line ranges, nested methods included. Cost ∝ file (small ~80 tok, god-class 1.5–2.5k). Already resolved the symbol? get_chunk_summary(id, expand_calls) is cheaper. Never skeleton a big file to find call sites — that is get_call_graph.</playbook>
         <playbook name="orientation" calls="1">get_repo_map(path_filter: "subsystem") once. Never twice with overlapping filters.</playbook>
         <playbook name="trace-a-flow" calls="1-2">"How does X flow through the system / how do these connect" → get_subgraph("seed", depth: 2) ONCE: connected callees + high-confidence callers + type users in a budget, instead of stitching search_code + get_call_graph + find_references yourself. Widen max_nodes/token_budget only on ⚠️ truncated.</playbook>
         <playbook name="full-ecosystem" calls="2-3">"What is X built from / its full ecosystem / what its parts are in turn made of" is a DEPTH-2 question — the single most common miss is stopping at depth-1. (1) resolve_symbol("X") (or get_chunk) and read the Deps:/Calls/Type refs line = X's DIRECT (depth-1) collaborators. (2) REQUIRED second move: resolve_symbol the PRINCIPAL depth-1 dependency (the one the question centres on) and read ITS Deps:/Calls to name the grandchild (depth-2) deps — the dep-of-a-dep is NOT on X's card, so a one-card answer misses it. List the other depth-1 deps directly from X's topology (rule-of-one: hop into only the principal child). get_subgraph is the WRONG tool for import/type/JSX composition — it walks the CALL graph, never imports/JSX children — so for "what is X built from" resolve the dependency's card, do NOT get_subgraph. (Exception: where composition IS calls — e.g. a Ruby/Python service that *calls* its collaborators — get_subgraph(depth:2) reaches depth-2 directly.)</playbook>
-        <playbook name="modify-a-signature" calls="2-4">get_call_graph("target") FIRST → optionally ONE caller chunk as the edit template → edit. For a refactor where completeness is the point, spend the budget CLOSING the full caller set (high-confidence callers + the name-only bucket + the git "changes with" line), not on body reads — an incomplete caller set is the costly miss here, not a missing body. Exact pre-edit file state = fallback condition 4, not an index call.</playbook>
+        <playbook name="modify-a-signature" calls="2-4">impact_of_edit("target") FIRST (precise transitive callers + tests + git "changes with" in ONE call; get_call_graph only when scoping a single hop) → optionally ONE caller chunk as the edit template → edit. For a refactor where completeness is the point, spend the budget CLOSING the full caller set, not on body reads — an incomplete caller set is the costly miss here, not a missing body. Exact pre-edit file state = fallback condition 4, not an index call.</playbook>
     </playbooks>
 
     <tools>
@@ -47,10 +47,15 @@
         <tool sig="get_chunk_summary(chunk_id, expand_calls?)" cost="50-150">Signature, doc, calls — no body. expand_calls inlines ≤6 callee signatures. Where a whole class is ONE chunk (Java/C#/PHP, often Python/Kotlin), callees may not resolve → get_file_skeleton or get_chunk answers more.</tool>
         <tool sig="get_file_skeleton(file_path)" cost="80-2.5k ∝ size">Every definition in one file + line ranges, nested methods included. Parses the LIVE file — precise even for whole-class chunks. Don't reach for it when get_chunk_summary/get_call_graph answers the question.</tool>
         <tool sig="get_call_graph(target_function, target_class?)" cost="15-100">Repo-wide callers of a FUNCTION/METHOD, high-confidence vs name-only. A class/type/interface returns "no callers" (construction and type-use aren't call edges) → use find_references. target_class scopes an ambiguous name. "No callers" ≠ unused. With git history indexed, appends "🔄 Historically changes with" — fold those files into a refactor's blast radius.</tool>
-        <tool sig="find_references(symbol, target_class?)" cost="15-120">Broader than get_call_graph: callers + subclasses/implementers (extends) + type-annotation users, each high-confidence vs name-only. THE move for a CLASS/TYPE/INTERFACE; for a plain function get_call_graph is the cheaper subset. Per-language coverage of the heritage/type channels is in your language layer.</tool>
+        <tool sig="find_references(symbol, target_class?)" cost="15-120">Broader than get_call_graph: callers + subclasses/implementers (extends) + type-annotation users, each high-confidence vs name-only. THE move for a CLASS/TYPE/INTERFACE; for a plain function get_call_graph is the cheaper subset. Per-language coverage of the heritage/type channels is in your language layer. On a `--resolver scip` index it also returns a precise cross-file "🎯 SCIP-resolved" reference set — trust it over name-only matches: it disambiguates same-named symbols and catches uses the heuristics miss.</tool>
         <tool sig="get_subgraph(symbol, depth?, max_nodes?, token_budget?)" cost="100-600">ONE bounded connected subgraph around a seed: callees + high-confidence callers + type/inheritance users, depth 1–3 (default 2). THE "trace a flow across files" move; replaces chaining. Edges are CALLS + refs/inheritance, NOT imports — a module merely imported (or a JSX child, which is not a call) is NOT reached; for "what is X built from" read the Deps: line, not this. ⚠️ truncated = raise the budget. Not for one body (get_chunk) or a flat caller list (get_call_graph).</tool>
         <tool sig="find_routes(method?, path?)" cost="15-80">HTTP routes → handler chunk_id for Express/Koa, NestJS, FastAPI/Flask, Spring (controller prefix already joined onto the method path). Feed the chunk_id straight into get_chunk/get_call_graph. method case-insensitive; path "/"=prefix else substring. NOT populated for attribute-routed C#/ASP.NET, PHP (Laravel/Symfony), Rails, or Django URLconf — search the path string there.</tool>
-        <tool sig="get_repo_map(path_filter?, max_files?, sort_by?)" cost="300-1500">Symbol map grouped by file, most-imported first.</tool>
+        <tool sig="explain_symbol(symbol, target_class?)" cost="80-400">ONE-call overview before editing an unfamiliar symbol: signature(s) + callees + callers (blast radius) + subclasses/type users + routes it handles + the tests that exercise it + git recency/co-change + (on a --symbol-graph index) its centrality rank (how central it is to the program). Replaces the resolve_symbol→find_references→find_routes→tests_for chain; reach for it when the question is "what is this and what would I break". target_class scopes an ambiguous name.</tool>
+        <tool sig="tests_for(symbol)" cost="15-80">The test/spec chunks that call or reference a symbol → which tests to run or update before changing it, and worked examples of intended behaviour. "No tests" ≠ untested (the test may hit a wrapper, not the symbol directly). Feed a returned id into get_chunk for the test body.</tool>
+        <tool sig="impact_of_edit(symbols?, files?, max_depth?, precision?)" cost="50-400">Precise blast radius BEFORE editing: pass the symbol(s)/file(s) you're about to change → transitively-affected code (high-confidence callers/subclasses/type users, by depth), the routes that reach them, the tests to run, ambiguous same-named referrers to verify, and git "changes with". THE pre-refactor move for "what breaks if I change X" — one call instead of recursive get_call_graph. Chunk-precise on a `--symbol-graph` index, query-time resolution otherwise. precision='strict' follows only provably-unambiguous (resolved) edges for a false-positive-free radius (best on a --resolver precise or --resolver scip index); 'standard' (default) is the wider resolved+high closure.</tool>
+        <tool sig="trace_taint(source_kind?, category?, max_depth?)" cost="80-500">SECURITY: trace untrusted data (req.body/query/params, argv/env, stdin) → a dangerous sink (eval/exec, SQL, fs/path, HTML, outbound request) across the call graph, with the source→sink path. Categories rce|sqli|xss|path|ssrf. Same-function flows=high confidence, cross-function reachability=medium, a sanitizer on the path lowers it. JS/TS, Python, Java, Go. HEURISTIC FINDER, not a verifier — "no flows" ≠ "safe"; triage each path. Reach for it on "is this input reachable to a dangerous call".</tool>
+        <tool sig="find_tainted_sinks(category?, reachable_only?)" cost="80-500">SECURITY orientation: every dangerous sink grouped by category, each flagged whether an untrusted source reaches it. Use FIRST to map the attack surface, then trace_taint one. Same finder caveats.</tool>
+        <tool sig="get_repo_map(path_filter?, max_files?, sort_by?)" cost="300-1500">Symbol map grouped by file, most-imported first. On a --symbol-graph index the unfiltered view also lists the most-central symbols (PageRank) — the program's hubs.</tool>
         <tool sig="list_index_stats()" cost="100">Index health: chunk count, search mode, daemon, freshness.</tool>
         <tool sig="resource graph://dependencies/{file_path}" cost="100">Bidirectional import topology of one file.</tool>
         <note>Topology reliability is LANGUAGE-DEPENDENT — your language layer states whether Deps:/Used by: are RELIABLE or WEAK. Where weak, map usage by name search; never read an empty Used by: as "unused". A re_export node = symbol re-exported from an external dependency; its implementation is outside this repo — don't hunt for it.</note>

package/prompts/frameworks/FASTAPI_DJANGO.md

@@ -12,6 +12,7 @@
         <rule name="schema-models">Pydantic models, serializers, forms are declarative — the class definition IS the validation. resolve_symbol("UserCreate") answers "what is validated"; imperative validation code doesn't exist, don't search for it.</rule>
         <rule name="signals-and-tasks">Signals connect by the signal OBJECT and tasks by name/registration — no call edges. ONE exact_tokens search on the signal/task name finds both ends. Middleware lists and settings are config files — fallback condition 3 once the consuming code is located.</rule>
         <rule name="query-style">URL fragments and signal names beat function names. For "where is this field validated/transformed", name the FIELD and behaviour ("normalize email before saving user") — model, serializer, or signal handler, one behavioural search covers all three.</rule>
+        <rule name="request-input-to-sink">SECURITY ("can user input reach SQL/RCE/template here"): find_tainted_sinks(category) to map the surface, then trace_taint one — request.json/POST/GET + path/query params → raw()/extra()/.execute() (sqli), os.system/subprocess (rce), template/HTML (xss). Finder, not proof: "no flows" ≠ safe.</rule>
     </rules>
 
     <playbook question="what happens on POST /orders" calls="3-4">find_routes("POST", "/orders") (FastAPI/Flask; for Django URLconf fall back to search_code(exact_tokens: "/orders")) → get_chunk(handler/view) — decorators + signature reveal deps and models → resolve_symbol(the ONE model/service it delegates to) → answer; ONE dependency/parent hop only if the question demands it.</playbook>

package/prompts/frameworks/NODE_EXPRESS_NESTJS.md

@@ -11,6 +11,7 @@
         <rule name="container-wiring">WHICH implementation backs an injected token is container wiring, not a call: constructor injection creates no edge. Find the binding with ONE search of the module/provider registration (exact_tokens: "UserService") — never via the constructor's call graph.</rule>
         <rule name="lifecycle-hooks">onModuleInit-style hooks, error handlers, scheduled/cron methods, event/queue consumers have no inbound edges — the decorator in the summary says WHO invokes them; don't hunt for callers.</rule>
         <rule name="query-style">Path strings beat handler names (routes rename rarely, handlers often). Cross-cutting behaviour ("where do we attach the request ID") lives in middleware whose name you can't guess — search behaviourally.</rule>
+        <rule name="request-taint">SECURITY: req.body/query/params is the untrusted source. "Is this endpoint injectable" → find_tainted_sinks(category) to map the surface, then trace_taint one source→sink path (sqli|rce|xss|path|ssrf). Finder, not proof — "no flows" ≠ safe.</rule>
     </rules>
 
     <playbook question="what happens on POST /orders" calls="3-4">find_routes("POST", "/orders") → get_chunk(handler chunk_id) → get_chunk_summary(the service it calls, expand_calls: true) → answer; ONE middleware/guard chunk only if the question is about it.</playbook>

package/prompts/frameworks/REACT.md

@@ -13,7 +13,7 @@
         <rule name="query-style">Component names are PascalCase and unique — exact_tokens with the component name is the highest-precision query here. For visual/behavioural questions ("the dropdown that closes on outside click"), use a behavioural sentence — handler names vary too much.</rule>
     </rules>
 
-    <playbook question="explain component X and where it renders" calls="2-3">resolve_symbol("X") → get_chunk(id) — a component's body IS its behaviour (hooks + JSX), so the full chunk replaces two summary calls → answer citing Used by: as the render sites; ≤1 consumer chunk as a render example. Do NOT resolve every child component in its JSX.</playbook>
+    <playbook question="explain component X and where it renders" calls="2-3">resolve_symbol("X") → get_chunk(id) — a component's body IS its behaviour (hooks + JSX), so the full chunk replaces two summary calls → answer citing Used by: as the render sites; ≤1 consumer chunk as a render example. Do NOT resolve every child component in its JSX. BEFORE a prop/signature change use explain_symbol("X") instead — render sites (Used by:), tests, and git recency in ONE call, since get_call_graph is blind to JSX.</playbook>
 
     <playbook question="explain component X and its full ecosystem / what it's built from" calls="2-3">The child components X renders are IMPORTS, not calls — get_call_graph AND get_subgraph are BLIND to them (both walk the call graph, returning X's hooks/util calls, never its JSX children). The composition tree is the Deps: line on the resolve_symbol/get_chunk card (depth-1); render sites are Used by:. (1) resolve_symbol("X") → read Deps: for the direct child components. (2) For the FULL ecosystem / "what it's built from", the depth-2 grandchild is REQUIRED, not optional: resolve_symbol the PRINCIPAL child to read ITS Deps: — e.g. Modal's Deps: lists Fade; resolving Fade surfaces TransitionWrapper, which is NOT on Modal's card. A depth-1-only answer (Modal's children, stop) is INCOMPLETE for this question. Rule-of-one: hop into only the principal child; list the rest of X's children straight from its Deps:. NEVER get_subgraph to enumerate composition — it returns animation/hook plumbing, not the component tree.</playbook>
 

package/prompts/frameworks/SPRING_BOOT.md

@@ -12,6 +12,7 @@
         <rule name="deep-inheritance">If a resolved class looks too thin, the behaviour lives in an abstract base — resolve ONE parent, guided by the extends list on the card.</rule>
         <rule name="events-and-config">Event publishers and @EventListener handlers connect by the EVENT CLASS — ONE exact_tokens search on the event class finds both ends. @Value/configuration-properties bind to yml/properties — fallback condition 3 once the consuming class is located.</rule>
         <rule name="query-style">Annotation names are high-precision tokens (exact_tokens: "@Scheduled"). Cross-cutting behaviour ("where do we audit changes") lives in an aspect/listener you can't name — search behaviourally.</rule>
+        <rule name="request-input-taint">SECURITY: controller request data (@RequestBody/@RequestParam/@PathVariable) is the untrusted source. For "can request input reach SQL/exec/path" use find_tainted_sinks(category) then trace_taint — Java-supported. Finder, not proof: "no flows" ≠ safe.</rule>
     </rules>
 
     <playbook question="what happens on POST /orders" calls="3-4">find_routes("POST", "/orders") → get_chunk_summary(handler chunk_id, expand_calls: true) — annotations + called services in one shot → get_chunk_summary(the ONE service method doing the work) → answer; ONE impl/parent/aspect hop only if the question demands it.</playbook>

package/prompts/languages/GO.md

@@ -15,6 +15,7 @@
         <rule name="embedded-promotion">A call to a method the outer type doesn't define lives in an EMBEDDED type — check the type-declaration chunk for embedded fields before distrusting the index.</rule>
         <rule name="implicit-execution">init() and `_` blank imports run with no inbound edges — absence of callers is not dead code. `go fn()` and `defer fn()` ARE edges; channel flow is not — trace channels by searching the channel field name.</rule>
         <rule name="first-class-functions">Functions passed as values (http.HandlerFunc(handle), middleware constructors) create no edge to the passed function — find sites with exact_tokens.</rule>
+        <rule name="input-reachability">SECURITY — "can request/CLI input reach a dangerous call" (exec, SQL, fs/path) → trace_taint (Go is supported); find_tainted_sinks first to map the surface. Finder, not proof — "no flows" ≠ safe.</rule>
         <rule name="query-style">Always include package/domain words ("auth middleware token refresh", never bare "Refresh"). To find where an error originates, search its message string literal — the most unique token in the flow.</rule>
     </rules>
 

package/prompts/languages/JAVA.md

@@ -18,6 +18,6 @@
         <rule name="accessor-noise">Never read a POJO/bean body: detail: "signatures" or get_file_skeleton tells you everything a data class can. Exception flow: ONE exact_tokens search on the exception class finds throw sites and handlers together.</rule>
     </rules>
 
-    <playbook question="explain service X / change a method safely" calls="2-4">resolve_symbol("X") (annotations visible) → get_chunk_summary(id, expand_calls: true) → answer with Used by:. Signature change: get_call_graph("method") → filter callers by class via paths → ONE caller chunk as template → edit.</playbook>
+    <playbook question="explain service X / change a method safely" calls="2-4">resolve_symbol("X") (annotations visible) → get_chunk_summary(id, expand_calls: true) → answer with Used by:. Signature change: impact_of_edit(symbols:["method"]) — transitive callers+overrides+tests in ONE call, no recursive get_call_graph (class-granular chunks make that painful) → ONE caller chunk as template → edit.</playbook>
 
 </environment_prompt>

package/prompts/languages/PYTHON.md

@@ -10,7 +10,7 @@
     </index_facts>
 
     <rules>
-        <rule name="name-overmatch">Dispatch binds by NAME and Python is duck-typed: get_call_graph("save") mixes every save repo-wide, and resolve_symbol may return several — pick by file path + class context from the cards, no extra reads.</rule>
+        <rule name="name-overmatch">Dispatch binds by NAME and Python is duck-typed: get_call_graph("save") mixes every save repo-wide, and resolve_symbol may return several — pick by file path + class context from the cards, no extra reads. If your index was built --resolver scip (scip-python), find_references returns a 🎯 SCIP-resolved set that disambiguates the right one — trust it over name-only.</rule>
         <rule name="dunder-magic">Implicit protocol calls have no edges: `obj()`↛__call__, `a+b`↛__add__, attr access↛__getattr__, `with`↛__enter__/__exit__. An empty call graph on a dunder means nothing.</rule>
         <rule name="package-barrels">`__init__.py` re-export hubs produce re_export nodes: internal origin → ONE hop; external dependency → stop.</rule>
         <rule name="decorators-wrap">Call sites point at the DECORATED name even when a decorator wraps it. If runtime behaviour is the question, read the decorator's chunk ONCE — never trace every wrapped function.</rule>