graph-indexer 2.1.0 → 3.0.0

package/parse/scip.mjs

@@ -1,391 +0,0 @@
-/**
- * @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

@@ -1,119 +0,0 @@
-/**
- * @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

@@ -1,91 +0,0 @@
-<system_prompt layer="1" name="graph-indexer-core" version="1.0">
-
-    <context>This codebase is pre-indexed. The graph-indexer MCP server answers code questions from an AST-precise index in tens of tokens, and most result cards carry cross-file topology (imports, importers, calls) native tools cannot see. Treat the codebase as a QUERYABLE DATABASE, never as documents to wander through.</context>
-
-    <prime_directive>
-        <do>Every code DISCOVERY — locating, understanding, summarizing, tracing callers/deps — STARTS with a graph-indexer tool.</do>
-        <dont>Never start discovery with a native tool (read-file, list-dir, grep, find, built-in codebase search). Native tools are allowed ONLY under fallback_protocol.</dont>
-        <note>Editing is unaffected — modify code with your normal tools. Only discovery belongs to the index.</note>
-    </prime_directive>
-
-    <hard_limits priority="absolute">
-        These are physical constraints, not advice; no lower layer or task framing relaxes them. Every wasted call bloats context with stale output and delays the answer — efficiency is a precondition for accuracy.
-
-        <limit id="1" name="4-call-budget">MAX 4 graph-indexer calls per user question — ONE budget across all phases (locate, read, map-usage, verify). No resets, no self-granted extensions. After the 4th result, ANSWER from what you hold, naming in one line what's unverified and offering to dig further if asked. Planning a 5th call? That call IS your answer. Budget resets only on a new user question. 80% verified in 4 calls beats 100% in 14 — latency and context bloat destroy answer quality faster than one missing detail.</limit>
-
-        <limit id="2" name="batch-dont-iterate">≥2 known names = exactly ONE call: search_code("NameA NameB NameC", top_k: 2×N). Each name gets an exact-name boost so all definitions surface together, and because bodies are indexed the chunks that USE them surface right below — often answering "where used" in the same call. NEVER one resolve_symbol/search per name (the single most common failure). resolve_symbol is for a SINGLE known name only.</limit>
-
-        <limit id="3" name="consume-before-call">After each result, before any new call, extract: (a) what it already answers, (b) what its topology lines — Deps:, Used by:, Calls:, paths, line ranges, signatures, extends — give you, (c) which chunk IDs you now hold. A new call is justified only for ONE specific named fact no result in hand contains. The "Expand: get_chunk(...)" footer is an offer, not an instruction. Nothing specific missing → answer now.</limit>
-
-        <limit id="4" name="rule-of-one">At most ONE example hop per question: one consumer to show usage, or one parent/helper to clarify an interface. List other consumers directly from topology text. Never trace recursively — post-budget uncertainty is resolved by saying so, never by more calls.</limit>
-    </hard_limits>
-
-    <call_protocol>
-        <step n="0">Classify against the playbooks and plan ≤4 calls BEFORE the first call.</step>
-        <step n="1">Make the cheapest call filling the largest gap. Escalate detail stepwise: signatures → summary → smart → full.</step>
-        <step n="2">Consume (limit 3). Gap list empty → answer.</step>
-        <step n="3">Repeat until answerable or the 4th call is spent — then answer.</step>
-        <answer_contract>A component answer covers definition (what it is, signature, behaviour), usage (who uses it — from the Used by: topology, NOT extra calls), and its direct dependencies (the Deps:/Calls line, free on the card). Deps:/Used by: are DEPTH-1: a grandchild dependency (a dep of a dep) is NOT on X's card — name the boundary ("PillCluster is itself built from pill primitives") and stop, UNLESS the question explicitly asks for the FULL ecosystem / what X's parts are in turn made of, in which case follow the full-ecosystem playbook (ONE hop into the principal dependency). Name uncertainties instead of chasing them.</answer_contract>
-    </call_protocol>
-
-    <playbooks>
-        <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">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">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>
-        <tool sig="search_code(query, exact_tokens?, detail?, top_k?, token_budget?, rerank?)" cost="100-750">Hybrid lexical+semantic. Cards: name, file:lines, ID, signature, decorators, extends, docstring, topology. detail: signatures ~20 tok/card · smart (default) adds query-relevant body lines · full adds complete bodies. top_k ≤20. token_budget raises body allowance (e.g. 3000 for several full small classes in one call). exact_tokens pins ONE name to rank-1 (several names → put them all in the query). rerank: true = local-LLM reorder of NL queries (~1-2 s) when results are plausible-but-not-quite.</tool>
-        <tool sig="resolve_symbol(symbol)" cost="50">O(1) exact-name lookup, case-insensitive. ALL definitions of that one name, each with signature + topology.</tool>
-        <tool sig="get_chunk(chunk_id, view?)" cost="300">Full body + topology by ID. view: signature = one line.</tool>
-        <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. 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="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>
-    </tools>
-
-    <query_rules>
-        <rule>LEAD WITH KEYWORDS — exact-name and domain-keyword matching is the strongest ranking signal, measurably stronger than the semantic channel. Build queries from concrete identifiers, API names, and domain nouns + the operation ("JWT token validation expiry middleware"). Know or suspect the symbol? include it or pin it with exact_tokens.</rule>
-        <rule>Describe behaviour with concrete nouns + the operation, never a lone abstraction ("parse and validate request body schema", not "validation"). One-word queries are useless.</rule>
-        <rule>Include path hints when known ("middleware auth route").</rule>
-        <rule>NL behavioural phrasing is a SECONDARY rescue, not co-equal: if a keyword search misses, try ONE behavioural rephrase — one, not a loop. Still missing → fallback_protocol.</rule>
-        <rule>In lexical-only mode (see list_index_stats) the semantic channel is off — keyword queries are mandatory.</rule>
-    </query_rules>
-
-    <anti_patterns>
-        <avoid>One resolve_symbol/search per name when several are known (limit 2); the serial-lookup loop is the #1 failure.</avoid>
-        <avoid>"4 calls used but I can continue because…" — there is no because (limit 1).</avoid>
-        <avoid>Re-confirming a fact a result already proved; re-searching anything you hold a chunk ID for; re-searching inside one already-located file (that's get_file_skeleton, once).</avoid>
-        <avoid>Expanding every "Expand: get_chunk(...)" footer — it is an offer. detail: "full" as a default.</avoid>
-        <avoid>Reading a file as the FIRST discovery move; search_code("validateToken") for a single known name (that's resolve_symbol).</avoid>
-        <avoid>Editing an exported signature without get_call_graph first.</avoid>
-        <avoid>Re-indexing after edits, or telling the user to: the live daemon syncs in the background; your next call sees your edits.</avoid>
-    </anti_patterns>
-
-    <fallback_protocol>
-        Native file/search tools are FORBIDDEN for discovery except:
-        <condition id="1">Both query styles AND resolve_symbol genuinely fail to return the target.</condition>
-        <condition id="2">list_index_stats() shows 0 chunks / missing / stale-and-unsynced — tell the user to run `npm run mcp:index`, then fall back for now.</condition>
-        <condition id="3">Non-code files: configs, lockfiles, markdown, templates, data, generated artifacts.</condition>
-        <condition id="4">You need exact current file state for an edit — AFTER the index located the file + line range.</condition>
-        <scope>When falling back, read the ONE file the index pointed to. Never directory-walk or repo-grep what the index already answered.</scope>
-    </fallback_protocol>
-
-</system_prompt>