graph-indexer 2.0.0 → 2.1.0

package/mcp/resolver.mjs

@@ -0,0 +1,116 @@
+/**
+ * @file mcp/resolver.mjs
+ * @description Resolver providers (A1): pluggable confidence assignment for the A4 symbol
+ *              graph. The DEFAULT `heuristic` provider preserves today's two-tier confidence
+ *              ({ high, name_only }) exactly. The opt-in `precise` provider lifts the subset of
+ *              edges whose binding is provably UNAMBIGUOUS into a third, stronger tier,
+ *              `resolved` — a reference is `resolved` when there is no question *which*
+ *              definition it binds to:
+ *                • the symbol has a single definition in the repo (no same-named rival), or
+ *                • the receiver's TYPE matches the defining class (typed receiver, the A3
+ *                  inter-procedural fixpoint result, `this.m()` inside the class, or an explicit
+ *                  target class) — type-resolved, so immune to name shadowing.
+ *              `high` then means "ambiguous name, disambiguated by import/proximity" and
+ *              `name_only` means "ambiguous name, no evidence."
+ *
+ *              The provider only changes the `confidence` STRING on edges that already exist —
+ *              it never adds, drops, or reorders edges — so it is parity-free (confidence is
+ *              already serialized) and `findCallers`/`findReferers` set-equivalence is preserved.
+ *              It runs at index time inside buildSymbolGraph and is inert without --symbol-graph.
+ *
+ *              SCOPE (honest): v1 exposes the unambiguous-binding tier the engine can already
+ *              prove from index-time signals. Detecting a LOCAL variable that *shadows* an import
+ *              (and refuting that edge), and cross-file precise resolution via stack-graphs, are
+ *              the documented next layers — both require per-language AST/scope analysis.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+
+/** Total order on confidence — strongest first. Used by the symbol-graph dedupe. */
+export const CONFIDENCE_RANK = { resolved: 3, high: 2, name_only: 1 };
+
+/** The stronger of two confidence strings (ties → `a`). */
+export function strongerConfidence(a, b) {
+    return (CONFIDENCE_RANK[b] || 0) > (CONFIDENCE_RANK[a] || 0) ? b : a;
+}
+
+/**
+ * Default provider: identity. Edge confidence stays exactly { high, name_only } — the index is
+ * byte-identical to a pre-A1 build.
+ */
+const HEURISTIC = {
+    name: 'heuristic',
+    /** @param {string} base 'high' | 'name_only' @param {boolean} _proven */
+    confidenceFor(base /* , proven */) { return base; },
+};
+
+/**
+ * Precise provider: promote a `high` edge to `resolved` when its binding is provably
+ * unambiguous (the `proven` flag set by classifyCallers / findReferences). Never touches
+ * `name_only` (no evidence stays no evidence) and never downgrades.
+ */
+const PRECISE = {
+    name: 'precise',
+    /** @param {string} base @param {boolean} proven */
+    confidenceFor(base, proven) { return base === 'high' && proven ? 'resolved' : base; },
+};
+
+const PROVIDERS = { heuristic: HEURISTIC, precise: PRECISE };
+
+/** Resolve a provider by name; unknown names fall back to the default heuristic. */
+export function getResolver(name) { return PROVIDERS[name] || HEURISTIC; }
+
+/**
+ * SCIP provider (A2): a DATA-BACKED resolver built from a cross-file binding relation
+ * (`bindings: Map<fromChunkId, Set<defChunkId>>`) and the set of defs SCIP actually saw
+ * (`definedChunks`), both produced from a locally-generated SCIP index (see parse/scip.mjs
+ * `buildScipBindings`). Unlike heuristic/precise — which only RELABEL a fixed edge set — the SCIP
+ * provider can also SUPPRESS edges, because SCIP knows the *exact* binding among several same-named
+ * definitions. For a caller `fromId` and the candidate defs `defIds` of one name:
+ *
+ *   • no SCIP target for `fromId` at all, OR none of `defIds` is a target → return null: the
+ *     builder falls through to the heuristic confidence (absence ≠ refutation for this name).
+ *   • SCIP confirms `fromId` binds to ≥1 of `defIds` → `resolved` = those confirmed def(s);
+ *     `suppressed` = the OTHER candidate defs **that SCIP actually saw as definitions**
+ *     (`def ∈ definedChunks`). A candidate def SCIP NEVER recorded — an uncovered file in a
+ *     polyglot / partial run, a stale `.scip`, a missed occurrence — is neither resolved nor
+ *     suppressed: it falls through to heuristic, so a covered caller referencing an *uncovered* def
+ *     is never wrongly dropped. This is the soundness gate the partial-coverage case needs.
+ *
+ * It refines the heuristic's CANDIDATE edges (promote + suppress); it does not synthesize edges the
+ * AST call-extraction missed (a v2 recall concern). The symbol-graph builder applies this to `calls`
+ * edges only — the binding relation is kind-agnostic, so `extends`/`type` edges stay heuristic.
+ * `confidenceFor` is identity, so any edge SCIP does not cover keeps its base confidence.
+ *
+ * @param {Map<string, Set<string>>} bindings  fromChunkId → set of def chunk ids SCIP confirms.
+ * @param {Set<string>} [definedChunks]  every chunk SCIP recorded as a definition (suppression gate).
+ * @returns {{ name:string, confidenceFor:Function, resolveEdges:Function }}
+ */
+export function createScipResolver(bindings, definedChunks) {
+    const rel = bindings instanceof Map ? bindings : new Map();
+    const defined = definedChunks instanceof Set ? definedChunks : new Set();
+    return {
+        name: 'scip',
+        /** Uncovered edges keep their base confidence (no promotion without SCIP evidence). */
+        confidenceFor(base /* , proven */) { return base; },
+        /**
+         * @param {{ fromId:string, defIds:string[] }} q
+         * @returns {{ resolved: Set<string>, suppressed: Set<string> } | null}  null → no SCIP info.
+         */
+        resolveEdges({ fromId, defIds }) {
+            const targets = rel.get(fromId);
+            if (!targets || !targets.size) return null;          // caller uncovered → no opinion
+            const resolved = new Set();
+            for (const id of defIds) if (targets.has(id)) resolved.add(id);
+            if (!resolved.size) return null;                     // binds none of THIS name's defs → fall through
+            const suppressed = new Set();
+            for (const id of defIds) {
+                if (resolved.has(id)) continue;
+                if (defined.has(id)) suppressed.add(id);          // SCIP saw this def but bound elsewhere → wrong-target
+                // else: def uncovered by SCIP → keep heuristic (sound under partial coverage)
+            }
+            return { resolved, suppressed };
+        },
+    };
+}

package/mcp/symbolgraph.mjs

@@ -0,0 +1,137 @@
+/**
+ * @file mcp/symbolgraph.mjs
+ * @description Builds the persistent RESOLVED symbol graph (A4): one edge per resolved
+ *              (referencing-chunk → definition-chunk) pair, tagged with `kind`
+ *              ('calls' | 'extends' | 'type') and `confidence`. Confidence is `high` | `name_only`
+ *              on the default `heuristic` path; the opt-in resolvers add a `resolved` tier — A1
+ *              (`precise`) promotes provably-unambiguous edges, A2 (`scip`) confirms a cross-file
+ *              binding AND suppresses the wrong-target fan-out a same-name ambiguity would emit.
+ *
+ *              It REUSES the query-time resolvers (classifyCallers / findReferences) over
+ *              every defined symbol, so an edge's confidence is identical to what
+ *              get_call_graph / find_references would report — no logic duplication, no
+ *              drift. The result is serialized into the index so both backends expose the
+ *              same graph through getEdges() (deterministically ordered → parity-free), and
+ *              findCallers / findReferers can read it instead of scanning.
+ *
+ *              Opt-in and index-time only (see config.symbolGraph / indexer.mjs). It does
+ *              not touch search ranking. This is the structural foundation for impact_of_edit
+ *              (transitive getEdges), symbol-level PageRank (A5), and precise resolution (A1,
+ *              which upgrades 'high' → 'resolved').
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+import { classifyCallers, findReferences } from './topology.mjs';
+import { getResolver, strongerConfidence } from './resolver.mjs';
+
+/** Deterministic total order on edges — required for memory↔sqlite parity. */
+export function edgeOrder(a, b) {
+    return (a.from_chunk_id < b.from_chunk_id ? -1 : a.from_chunk_id > b.from_chunk_id ? 1 : 0)
+        || (a.to_chunk_id < b.to_chunk_id ? -1 : a.to_chunk_id > b.to_chunk_id ? 1 : 0)
+        || (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0)
+        || (a.confidence < b.confidence ? -1 : a.confidence > b.confidence ? 1 : 0);
+}
+
+const normConfidence = (c) => (c === 'high' ? 'high' : 'name_only');
+
+/**
+ * Build the resolved edge list from a loaded store.
+ *
+ * @param {object} db  A loaded store (iterateChunks, resolveSymbol, findCallers,
+ *                     findReferers, getDependencies — the same contract the resolvers use).
+ * @param {object} [opts]
+ * @param {number} [opts.maxPerName]  Safety cap on edges emitted for one symbol name
+ *                                    (pathological ambiguous names). Excess is logged, not
+ *                                    silently dropped.
+ * @param {object} [opts.resolver]  A1 resolver provider (default `heuristic` → byte-identical
+ *                                  { high, name_only }; `precise` → adds the `resolved` tier).
+ * @returns {{ edges: Array<{from_chunk_id:string,to_chunk_id:string,kind:string,confidence:string}>,
+ *             cappedNames: string[] }}
+ */
+export function buildSymbolGraph(db, { maxPerName = 20000, resolver = getResolver('heuristic') } = {}) {
+    const edges = [];
+    const cappedNames = [];
+
+    const calleeNames = new Set();
+    const refNames = new Set();
+    for (const c of db.iterateChunks()) {
+        for (const n of (c.calls || [])) calleeNames.add(n);
+        for (const t of (c.extends || [])) refNames.add(t);
+        for (const t of (c.type_refs || [])) refNames.add(t);
+    }
+
+    // ── 'calls' edges: every name-match caller → each definition of the callee name,
+    //    bucketed high / name_only exactly as classifyCallers reports. ──────────────
+    for (const name of [...calleeNames].sort()) {
+        const defs = db.resolveSymbol(name);
+        if (!defs.length) continue;            // undefined name → no edge (findCallers falls back to scan)
+        const defIds = defs.map(d => d.id);
+        const { high, nameOnly } = classifyCallers(db, name);
+        let n = 0; let capped = false;
+        const emit = (callers, baseConf) => {
+            for (const { chunk, proven } of callers) {
+                // A2 (calls edges only): a data-backed resolver (scip) may CONFIRM the exact binding
+                // (→ `resolved`) and SUPPRESS the SCIP-known wrong-target siblings. A def SCIP never
+                // saw is neither — it falls through to the heuristic confidence (sound under partial
+                // coverage). No resolveEdges (heuristic/precise) → decision null → byte-identical.
+                const decision = resolver.resolveEdges
+                    ? resolver.resolveEdges({ fromId: chunk.id, defIds })
+                    : null;
+                const fallbackConf = resolver.confidenceFor(baseConf, Boolean(proven));
+                for (const def of defs) {
+                    if (n >= maxPerName) { capped = true; return; }
+                    if (decision && decision.resolved.has(def.id)) {
+                        edges.push({ from_chunk_id: chunk.id, to_chunk_id: def.id, kind: 'calls', confidence: 'resolved' });
+                    } else if (decision && decision.suppressed.has(def.id)) {
+                        continue;                                  // SCIP-confirmed wrong-target → suppress
+                    } else {
+                        edges.push({ from_chunk_id: chunk.id, to_chunk_id: def.id, kind: 'calls', confidence: fallbackConf });
+                    }
+                    n++;
+                }
+            }
+        };
+        emit(high, 'high');
+        if (!capped) emit(nameOnly, 'name_only');
+        if (capped) cappedNames.push(name);
+    }
+
+    // ── 'extends' / 'type' edges: subclasses/implementers and type users → each
+    //    definition, with the per-reference confidence findReferences assigns. ──────
+    for (const name of [...refNames].sort()) {
+        const defs = db.resolveSymbol(name);
+        if (!defs.length) continue;
+        const { inherits, types } = findReferences(db, name);
+        let n = 0; let capped = false;
+        // A2 scopes SCIP resolution to `calls` edges only: the binding relation is kind-agnostic, so
+        // applying it here would let a call-site binding suppress/relabel `extends`/`type` siblings of
+        // a different kind. These edges therefore stay heuristic under every resolver (byte-identical).
+        const emit = (refs, kind) => {
+            for (const r of refs) {
+                const confidence = resolver.confidenceFor(normConfidence(r.confidence), Boolean(r.proven));
+                for (const def of defs) {
+                    if (n >= maxPerName) { capped = true; return; }
+                    edges.push({ from_chunk_id: r.chunk.id, to_chunk_id: def.id, kind, confidence });
+                    n++;
+                }
+            }
+        };
+        emit(inherits, 'extends');
+        if (!capped) emit(types, 'type');
+        if (capped && !cappedNames.includes(name)) cappedNames.push(name);
+    }
+
+    // Dedupe by (from, to, kind) keeping the STRONGEST confidence (resolved > high > name_only),
+    // then return in the deterministic parity order. (On the default `heuristic` path the only
+    // values are high/name_only and high is strongest → identical to the prior keep-first dedupe.)
+    const rep = new Map();
+    for (const e of edges) {
+        const k = `${e.from_chunk_id}|${e.to_chunk_id}|${e.kind}`;
+        const cur = rep.get(k);
+        if (!cur) rep.set(k, { from_chunk_id: e.from_chunk_id, to_chunk_id: e.to_chunk_id, kind: e.kind, confidence: e.confidence });
+        else cur.confidence = strongerConfidence(cur.confidence, e.confidence);
+    }
+    const out = [...rep.values()].sort(edgeOrder);
+    return { edges: out, cappedNames };
+}

package/mcp/taint.mjs

@@ -0,0 +1,225 @@
+/**
+ * @file mcp/taint.mjs
+ * @description Taint analysis (C2): trace untrusted data from SOURCES (request bodies, argv/env,
+ *              stdin, socket/file reads) to dangerous SINKS (eval/exec, SQL, fs/path, HTML, outbound
+ *              requests) across the symbol graph, surfacing injection-class risks (rce/sqli/xss/
+ *              path/ssrf) with a concrete source→sink path.
+ *
+ *              QUERY-TIME and read-only: it scans chunk source with the heuristic catalogs in
+ *              parse/taint-patterns.mjs and walks the call graph (A4 getEdges when present, else
+ *              chunk.calls). No index-time cost, no serialization, no parity surface — the default
+ *              index is byte-identical and the tools cost nothing unless invoked. Air-gapped (pure
+ *              regex + graph traversal; no model, no network).
+ *
+ *              HONESTY: this is a FINDER, not a verifier. It favours precision (direct same-function
+ *              flows are 'high'; cross-function reachability is 'medium'; a sanitizer on the path
+ *              lowers confidence) and will MISS flows through dynamic dispatch, reflection, ORM/
+ *              query-builder indirection, and untyped collections. "0 findings" ≠ "no vulnerabilities."
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+import { SOURCES, SINKS, SANITIZERS, CATEGORY_SEVERITY, langKeyForExt } from '../parse/taint-patterns.mjs';
+
+const extOf = (filePath) => { const i = String(filePath).lastIndexOf('.'); return i >= 0 ? filePath.slice(i) : ''; };
+
+/**
+ * Scan one chunk's source for source / sink / sanitizer hits. Returns null for unsupported
+ * languages or chunks without source text.
+ */
+export function scanChunk(chunk) {
+    const lang = langKeyForExt(extOf(chunk.file_path));
+    if (!lang) return null;
+    const src = chunk.code_snippet || '';
+    if (!src) return null;
+    const lines = src.split('\n');
+    const base = chunk.start_line || 1;
+
+    const sources = [];
+    const sinks = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const s of SOURCES[lang]) if (s.re.test(line)) sources.push({ line: base + i, kind: s.kind, snippet: line.trim().slice(0, 160) });
+        for (const k of SINKS[lang]) if (k.re.test(line)) sinks.push({ line: base + i, category: k.category, label: k.label, snippet: line.trim().slice(0, 160) });
+    }
+    const sanitized = SANITIZERS[lang].some(re => re.test(src));
+    return { lang, sources, sinks, sanitized };
+}
+
+/** Forward callees of a chunk (what it calls): A4 edges when present, else resolved chunk.calls. */
+function forwardCallees(db, chunk) {
+    const out = [];
+    const seen = new Set();
+    const push = (c) => { if (c && !seen.has(c.id)) { seen.add(c.id); out.push(c); } };
+    if (typeof db.hasSymbolGraph === 'function' && db.hasSymbolGraph()) {
+        for (const e of db.getEdges(chunk.id, { direction: 'out', kind: 'calls' })) if (e.chunk) push(e.chunk);
+        return out;
+    }
+    for (const name of (chunk.calls || [])) for (const def of (db.resolveSymbol(name) || [])) push(def);
+    return out;
+}
+
+const confRank = { high: 3, medium: 2, low: 1 };
+const sevRank = Object.fromEntries(CATEGORY_SEVERITY.map((c, i) => [c, CATEGORY_SEVERITY.length - i]));
+
+function flowKey(f) { return `${f.source.chunk_id}|${f.sink.chunk_id}|${f.sink.category}|${f.sink.line}`; }
+
+/** Deterministic order: worst category, then confidence, then source place, then sink place, then id. */
+function flowOrder(a, b) {
+    return (sevRank[b.sink.category] - sevRank[a.sink.category])
+        || (confRank[b.confidence] - confRank[a.confidence])
+        || a.source.file_path.localeCompare(b.source.file_path)
+        || (a.source.line - b.source.line)
+        || a.sink.file_path.localeCompare(b.sink.file_path)
+        || (a.sink.line - b.sink.line)
+        || (a.source.chunk_id < b.source.chunk_id ? -1 : a.source.chunk_id > b.source.chunk_id ? 1 : 0);
+}
+
+/**
+ * Build the taint flow set: every source→sink flow the heuristics can find.
+ *
+ * @param {object} db
+ * @param {object} [opts]
+ * @param {number} [opts.maxDepth]   Cross-function call hops to follow from a source (default 4).
+ * @param {number} [opts.maxFlows]   Cap on flows returned (default 200; truncation is reported).
+ * @param {string} [opts.category]   Restrict to one sink category (rce|sqli|xss|path|ssrf).
+ * @param {boolean}[opts.includeReachable]  Include cross-function reachability flows (default true).
+ * @returns {{ flows: object[], truncated: boolean, scanned: number, sources: number, sinks: number }}
+ */
+export function buildTaintGraph(db, { maxDepth = 4, maxFlows = 200, category = null, includeReachable = true } = {}) {
+    // ── Fast path: serialized flows from an index built with --taint (C2). The cache is the FULL
+    //    flow set computed once at index time (includeReachable, uncapped), so any query within its
+    //    depth envelope is served by filtering — no graph walk, and both backends serve identical
+    //    flows. A direct-only query (includeReachable:false) or a deeper maxDepth than the cache
+    //    falls through to a live recompute (correctness preserved over speed). ───────────────────
+    if (includeReachable && typeof db.hasTaint === 'function' && db.hasTaint()) {
+        const cached = db.getTaintFlows();
+        if (cached && cached.meta && maxDepth <= cached.meta.maxDepth) {
+            let flows = cached.flows || [];
+            if (category) flows = flows.filter(f => f.sink.category === category);
+            if (maxDepth < cached.meta.maxDepth) flows = flows.filter(f => f.depth <= maxDepth);
+            const truncated = flows.length > maxFlows;
+            return {
+                flows: truncated ? flows.slice(0, maxFlows) : flows, truncated, cached: true,
+                scanned: cached.meta.scanned, sources: cached.meta.sources, sinks: cached.meta.sinks,
+            };
+        }
+    }
+
+    // Scan every chunk once (sorted by id for deterministic, backend-stable output).
+    const chunks = [...db.iterateChunks()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const scans = new Map();
+    const sourceChunks = [];
+    const sinkChunkIds = new Set();
+    let sourceCount = 0, sinkCount = 0;
+    for (const c of chunks) {
+        const sc = scanChunk(c);
+        if (!sc) continue;
+        scans.set(c.id, sc);
+        if (sc.sources.length) { sourceChunks.push(c); sourceCount += sc.sources.length; }
+        if (sc.sinks.length) { sinkChunkIds.add(c.id); sinkCount += sc.sinks.length; }
+    }
+
+    const sinkMatches = (sk) => !category || sk.category === category;
+    const card = (chunk) => ({ chunk_id: chunk.id, name: chunk.name, file_path: chunk.file_path });
+
+    const flows = new Map();
+    const addFlow = (srcChunk, srcHit, sinkChunk, sinkHit, path, depth, via, sanitized) => {
+        const confidence = via === 'direct' ? (sanitized ? 'low' : 'high') : (sanitized ? 'low' : 'medium');
+        const f = {
+            source: { ...card(srcChunk), line: srcHit.line, kind: srcHit.kind, snippet: srcHit.snippet },
+            sink: { ...card(sinkChunk), line: sinkHit.line, category: sinkHit.category, label: sinkHit.label, snippet: sinkHit.snippet },
+            path, depth, via, sanitized, confidence,
+        };
+        const k = flowKey(f);
+        const prev = flows.get(k);
+        if (!prev || confRank[f.confidence] > confRank[prev.confidence] || f.depth < prev.depth) flows.set(k, f);
+    };
+
+    // ── Direct: a single function that both takes untrusted input AND performs a dangerous op. ──
+    for (const c of sourceChunks) {
+        const sc = scans.get(c.id);
+        if (!sc.sinks.length) continue;
+        const srcHit = sc.sources[0];                 // representative source
+        for (const sinkHit of sc.sinks) if (sinkMatches(sinkHit)) addFlow(c, srcHit, c, sinkHit, [c.id], 0, 'direct', sc.sanitized);
+    }
+
+    // ── Reachable: a source function transitively calls a sink function. ─────────────────────────
+    if (includeReachable) {
+        for (const start of sourceChunks) {
+            const startScan = scans.get(start.id);
+            const srcHit = startScan.sources[0];
+            const visited = new Set([start.id]);
+            let frontier = [{ chunk: start, path: [start.id], pathSanitized: startScan.sanitized }];
+            for (let depth = 1; depth <= maxDepth; depth++) {
+                const next = [];
+                for (const { chunk, path, pathSanitized } of frontier) {
+                    for (const callee of forwardCallees(db, chunk)) {
+                        if (visited.has(callee.id)) continue;
+                        visited.add(callee.id);
+                        const calleeScan = scans.get(callee.id);
+                        const sanitizedPath = pathSanitized || (calleeScan ? calleeScan.sanitized : false);
+                        if (sinkChunkIds.has(callee.id) && calleeScan) {
+                            for (const sinkHit of calleeScan.sinks) if (sinkMatches(sinkHit)) addFlow(start, srcHit, callee, sinkHit, [...path, callee.id], depth, 'reachable', sanitizedPath);
+                        }
+                        next.push({ chunk: callee, path: [...path, callee.id], pathSanitized: sanitizedPath });
+                    }
+                }
+                if (!next.length) break;
+                frontier = next;
+            }
+        }
+    }
+
+    const all = [...flows.values()].sort(flowOrder);
+    const truncated = all.length > maxFlows;
+    return { flows: truncated ? all.slice(0, maxFlows) : all, truncated, scanned: scans.size, sources: sourceCount, sinks: sinkCount };
+}
+
+/**
+ * Compute the serializable taint cache (C2 --taint) for index-time serialization: the FULL flow set
+ * (uncapped, includeReachable) plus the meta the fast path needs to answer in-envelope queries
+ * (`maxDepth` is the cache's depth — a query asking for ≤ this is served from the cache).
+ */
+export function computeTaintCache(db, { maxDepth = 4 } = {}) {
+    const r = buildTaintGraph(db, { maxDepth, maxFlows: Infinity, includeReachable: true, category: null });
+    return { flows: r.flows, meta: { maxDepth, scanned: r.scanned, sources: r.sources, sinks: r.sinks } };
+}
+
+/** Flows filtered by source kind and/or sink category (a thin filter over buildTaintGraph). */
+export function traceTaint(db, { sourceKind = null, sinkCategory = null, maxDepth = 4, maxFlows = 200 } = {}) {
+    const { flows, truncated, scanned } = buildTaintGraph(db, { maxDepth, maxFlows, category: sinkCategory });
+    const filtered = sourceKind ? flows.filter(f => f.source.kind === sourceKind) : flows;
+    return { flows: filtered, truncated, scanned };
+}
+
+/**
+ * Every dangerous sink, grouped by category, each annotated with whether any untrusted source
+ * reaches it. The orientation tool: "where are my dangerous operations, and which are reachable
+ * from untrusted input?"
+ */
+export function findTaintedSinks(db, { category = null, reachableOnly = false, maxDepth = 4 } = {}) {
+    const { flows, scanned } = buildTaintGraph(db, { maxDepth, maxFlows: 100000, category });
+    const reachedKey = new Set(flows.map(f => `${f.sink.chunk_id}|${f.sink.line}|${f.sink.category}`));
+
+    const chunks = [...db.iterateChunks()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const byCategory = {};
+    for (const c of chunks) {
+        const sc = scanChunk(c);
+        if (!sc || !sc.sinks.length) continue;
+        for (const sk of sc.sinks) {
+            if (category && sk.category !== category) continue;
+            const reached = reachedKey.has(`${c.id}|${sk.line}|${sk.category}`);
+            if (reachableOnly && !reached) continue;
+            (byCategory[sk.category] ||= []).push({
+                chunk_id: c.id, name: c.name, file_path: c.file_path, line: sk.line,
+                label: sk.label, snippet: sk.snippet, reached_by_source: reached,
+            });
+        }
+    }
+    for (const cat of Object.keys(byCategory)) {
+        byCategory[cat].sort((a, b) => (Number(b.reached_by_source) - Number(a.reached_by_source))
+            || a.file_path.localeCompare(b.file_path) || (a.line - b.line));
+    }
+    return { byCategory, scanned, flowCount: flows.length };
+}