gitnexus 1.6.8-rc.21 → 1.6.8-rc.23

package/dist/core/ingestion/taint/interproc-solver.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Interprocedural taint fixpoint (#2084 M4 U3).
+ *
+ * Composes per-function {@link FunctionSummary} objects over the resolved
+ * `CALLS` graph to find source→sink flows that cross function and file
+ * boundaries. PURE AND DETERMINISTIC (no graph, no I/O, no logger) — the phase
+ * builds the inputs from `ctx.graph` and persists the outputs.
+ *
+ * ## The model — whole-parameter taint reachability
+ *
+ * The unit of taint is `(function, parameter)`. The fixpoint computes the set
+ * of parameters that can hold source-derived data, then fires a finding
+ * whenever a tainted parameter feeds a modelled sink (`paramToSink`).
+ *
+ * - **Seeds** — every `sourceToCallArg` edge: a function generates a source and
+ *   passes it into argument `argIndex` of a call at `callLine`. Resolving that
+ *   call site against the caller's outgoing `CALLS` edges yields the callee;
+ *   the callee's parameter `argIndex` becomes tainted, with the generating
+ *   function recorded as the flow's source.
+ * - **Propagation** — every `paramToCallArg` edge of a function whose parameter
+ *   is ALREADY tainted: `param i → arg j of callee` taints the callee's
+ *   parameter `j` (TITO composition). Iterated to a fixpoint.
+ * - **Findings** — whenever a parameter becomes tainted and the owning
+ *   function's `paramToSink` contains that parameter, a cross-function finding
+ *   is emitted (source function → sink function, with the kind).
+ *
+ * ## Cycle safety (recursion)
+ *
+ * The tainted-parameter set is monotone over a FINITE lattice (`Σ functions ×
+ * params`), so the worklist fixpoint converges: a recursive or mutually
+ * recursive call merely re-proposes an already-tainted parameter, which the
+ * visited-set absorbs — no infinite descent. This is the functional/summary
+ * method's standard termination argument (Sharir-Pnueli; Pysa, Mariana Trench,
+ * and Infer all rely on it). SCC condensation would only refine the PROCESSING
+ * ORDER; correctness and termination do not require it.
+ *
+ * ## Context-insensitivity & the name-join over-approximation
+ *
+ * One summary per function, applied at every call site — return/param merging
+ * is accepted (the security-conservative direction). The call-arg→callee join
+ * is by callee NAME (not line), so when one caller invokes two DISTINCT
+ * same-named callees (`x.handler(src)` and `y.handler(clean)`), a source that
+ * flowed into ONE of them taints BOTH callees' parameter — an extra finding on
+ * the callee the source did not reach. This is sound (over-attribution, never a
+ * missed flow — the conservative direction for a security tool) and is the
+ * documented price of dropping the fragile line-based join; the `explain` tool
+ * surfaces it ("may over-attribute among same-named callees"). Other known
+ * precision losses (call-site conflation, shared dispatch, callbacks) are the
+ * documented M4 trade-offs; refinements are deferred (plan KTD).
+ */
+import type { SinkKind } from './source-sink-config.js';
+import type { FunctionSummary } from './summary-model.js';
+/**
+ * One resolved call edge from the `CALLS` graph. The join to a summary's
+ * call-arg edge is by CALLEE NAME (the callee node's declared name), NOT by
+ * call-site line — line-base parity between the CFG harvest (1-based) and the
+ * reference site is fragile, while the callee identity is exact and the
+ * context-insensitive model tatints the callee's parameter the same way at
+ * every call site to it.
+ */
+export interface InterprocCallEdge {
+    readonly callerId: string;
+    readonly calleeId: string;
+    /** The callee node's declared name (`helper`, `process`) — the join key. */
+    readonly calleeName: string;
+}
+/** One hop of a cross-function flow: the function entered, and how. */
+export interface InterprocHop {
+    readonly fnId: string;
+    /** The call-site line in the PREVIOUS function that entered this one. */
+    readonly callLine?: number;
+    /** Argument position the taint entered through (undefined for the source fn). */
+    readonly argIndex?: number;
+}
+export interface InterprocFinding {
+    readonly sourceFnId: string;
+    readonly sinkFnId: string;
+    readonly sinkKind: SinkKind;
+    /** Ordered source→sink hop chain (functions). A prefix when `truncated`. */
+    readonly hops: readonly InterprocHop[];
+    readonly hopsTruncated: boolean;
+}
+export interface InterprocLimits {
+    /** Max functions in a single flow's hop chain. `undefined`/0 ⇒ default 32. */
+    readonly maxHops?: number;
+    /** Max findings overall (post-dedup). `undefined`/0 ⇒ unlimited. */
+    readonly maxFindings?: number;
+}
+export interface InterprocResult {
+    readonly findings: readonly InterprocFinding[];
+    /** Findings dropped by `maxFindings` (post-dedup). */
+    readonly droppedFindings: number;
+    /** Call edges whose call-site line matched no summary edge (diagnostics). */
+    readonly unmatchedCallSites: number;
+}
+export declare const DEFAULT_MAX_INTERPROC_HOPS = 32;
+/**
+ * Default per-run cap on cross-function findings (#2084 review P1-3). Like the
+ * other pdg caps it is resolved into `RepoMeta.pdg` so `pdgModeMismatch`
+ * stamps it; `0` ⇒ unlimited. 2000 is generous for a real repo — more deduped
+ * `(source, sink, kind)` findings than that is a fixture or a runaway fan-in,
+ * and the overflow is deterministic + counted (`droppedFindings`).
+ */
+export declare const DEFAULT_PDG_MAX_INTERPROC_FINDINGS = 2000;
+/**
+ * Run the interprocedural taint fixpoint. `summaries` is keyed by function node
+ * id; `callEdges` is the resolved `CALLS` graph (caller→callee with call-site
+ * lines). Deterministic: inputs in, sorted findings out.
+ */
+export declare function solveInterprocTaint(summaries: ReadonlyMap<string, FunctionSummary>, callEdges: readonly InterprocCallEdge[], limits?: InterprocLimits): InterprocResult;

package/dist/core/ingestion/taint/interproc-solver.js

@@ -0,0 +1,312 @@
+/**
+ * Interprocedural taint fixpoint (#2084 M4 U3).
+ *
+ * Composes per-function {@link FunctionSummary} objects over the resolved
+ * `CALLS` graph to find source→sink flows that cross function and file
+ * boundaries. PURE AND DETERMINISTIC (no graph, no I/O, no logger) — the phase
+ * builds the inputs from `ctx.graph` and persists the outputs.
+ *
+ * ## The model — whole-parameter taint reachability
+ *
+ * The unit of taint is `(function, parameter)`. The fixpoint computes the set
+ * of parameters that can hold source-derived data, then fires a finding
+ * whenever a tainted parameter feeds a modelled sink (`paramToSink`).
+ *
+ * - **Seeds** — every `sourceToCallArg` edge: a function generates a source and
+ *   passes it into argument `argIndex` of a call at `callLine`. Resolving that
+ *   call site against the caller's outgoing `CALLS` edges yields the callee;
+ *   the callee's parameter `argIndex` becomes tainted, with the generating
+ *   function recorded as the flow's source.
+ * - **Propagation** — every `paramToCallArg` edge of a function whose parameter
+ *   is ALREADY tainted: `param i → arg j of callee` taints the callee's
+ *   parameter `j` (TITO composition). Iterated to a fixpoint.
+ * - **Findings** — whenever a parameter becomes tainted and the owning
+ *   function's `paramToSink` contains that parameter, a cross-function finding
+ *   is emitted (source function → sink function, with the kind).
+ *
+ * ## Cycle safety (recursion)
+ *
+ * The tainted-parameter set is monotone over a FINITE lattice (`Σ functions ×
+ * params`), so the worklist fixpoint converges: a recursive or mutually
+ * recursive call merely re-proposes an already-tainted parameter, which the
+ * visited-set absorbs — no infinite descent. This is the functional/summary
+ * method's standard termination argument (Sharir-Pnueli; Pysa, Mariana Trench,
+ * and Infer all rely on it). SCC condensation would only refine the PROCESSING
+ * ORDER; correctness and termination do not require it.
+ *
+ * ## Context-insensitivity & the name-join over-approximation
+ *
+ * One summary per function, applied at every call site — return/param merging
+ * is accepted (the security-conservative direction). The call-arg→callee join
+ * is by callee NAME (not line), so when one caller invokes two DISTINCT
+ * same-named callees (`x.handler(src)` and `y.handler(clean)`), a source that
+ * flowed into ONE of them taints BOTH callees' parameter — an extra finding on
+ * the callee the source did not reach. This is sound (over-attribution, never a
+ * missed flow — the conservative direction for a security tool) and is the
+ * documented price of dropping the fragile line-based join; the `explain` tool
+ * surfaces it ("may over-attribute among same-named callees"). Other known
+ * precision losses (call-site conflation, shared dispatch, callbacks) are the
+ * documented M4 trade-offs; refinements are deferred (plan KTD).
+ */
+export const DEFAULT_MAX_INTERPROC_HOPS = 32;
+/**
+ * Default per-run cap on cross-function findings (#2084 review P1-3). Like the
+ * other pdg caps it is resolved into `RepoMeta.pdg` so `pdgModeMismatch`
+ * stamps it; `0` ⇒ unlimited. 2000 is generous for a real repo — more deduped
+ * `(source, sink, kind)` findings than that is a fixture or a runaway fan-in,
+ * and the overflow is deterministic + counted (`droppedFindings`).
+ */
+export const DEFAULT_PDG_MAX_INTERPROC_FINDINGS = 2000;
+/**
+ * Taint-state key — `(function, parameter, SOURCE)`. The source discriminator
+ * is load-bearing: without it, a parameter tainted by source A is marked
+ * visited and a later flow from source B to the SAME parameter is dropped
+ * before it can fire that function's sink, silently losing B→sink (the
+ * multi-source collapse — the recurring M3 bug class). Including the source
+ * keeps each origin's flow independent; the lattice stays finite (`fn × param ×
+ * source`), so the monotone worklist still terminates and is cycle-safe.
+ */
+const pkey = (fnId, param, sourceFnId) => `${fnId}#${param}#${sourceFnId}`;
+/**
+ * Run the interprocedural taint fixpoint. `summaries` is keyed by function node
+ * id; `callEdges` is the resolved `CALLS` graph (caller→callee with call-site
+ * lines). Deterministic: inputs in, sorted findings out.
+ */
+export function solveInterprocTaint(summaries, callEdges, limits) {
+    const maxHops = limits?.maxHops && limits.maxHops > 0 ? limits.maxHops : DEFAULT_MAX_INTERPROC_HOPS;
+    // Adjacency built ONCE (#2084 review P3-8): callerId → outgoing edges, AND
+    // callerId → calleeName → edges. The summary's call-arg edges resolve by
+    // callee NAME, so the per-name index turns each resolution into an O(1)
+    // lookup instead of a per-worklist-step `.filter` allocation (the
+    // build-index-once pattern).
+    const callsByCaller = new Map();
+    const callsByCallerName = new Map();
+    for (const e of callEdges) {
+        const list = callsByCaller.get(e.callerId);
+        if (list)
+            list.push(e);
+        else
+            callsByCaller.set(e.callerId, [e]);
+        let byName = callsByCallerName.get(e.callerId);
+        if (!byName) {
+            byName = new Map();
+            callsByCallerName.set(e.callerId, byName);
+        }
+        const named = byName.get(e.calleeName);
+        if (named)
+            named.push(e);
+        else
+            byName.set(e.calleeName, [e]);
+    }
+    let unmatchedCallSites = 0;
+    /** Edges to `name` from `callerId` (O(1)); empty if none — non-counting. */
+    const calleesByName = (callerId, name) => callsByCallerName.get(callerId)?.get(name) ?? [];
+    // Resolve a caller's call-arg edge (by callee name) to concrete callee edges.
+    // An unknown callee name (chain not statically resolvable) conservatively
+    // matches EVERY outgoing call — sound over-approximation (may over-taint).
+    const resolveCallees = (callerId, calleeName) => {
+        const candidates = callsByCaller.get(callerId);
+        if (!candidates || candidates.length === 0) {
+            unmatchedCallSites++;
+            return [];
+        }
+        if (calleeName === undefined)
+            return candidates;
+        const named = calleesByName(callerId, calleeName);
+        if (named.length === 0) {
+            unmatchedCallSites++;
+            return [];
+        }
+        return named;
+    };
+    // ── findings + worklist ───────────────────────────────────────────────────
+    const findingsByKey = new Map();
+    const tainted = new Map();
+    const queue = [];
+    const recordFinding = (sourceFnId, sinkFnId, sinkKind, hops, truncated) => {
+        const key = `${sourceFnId}|${sinkFnId}|${sinkKind}`;
+        if (findingsByKey.has(key))
+            return;
+        findingsByKey.set(key, { sourceFnId, sinkFnId, sinkKind, hops, hopsTruncated: truncated });
+    };
+    /** Fire every `paramToSink` of `tp`'s param, except kinds it neutralised. */
+    const fireSinks = (tp) => {
+        const summary = summaries.get(tp.fnId);
+        if (!summary)
+            return;
+        for (const ps of summary.paramToSink) {
+            if (ps.param !== tp.paramIndex)
+                continue;
+            if (tp.neutralized.has(ps.sinkKind))
+                continue; // sanitised across the boundary (P1-2)
+            // `tp.hops` already terminates at this (tainted) function — it IS the
+            // source→sink chain, no extra hop to append.
+            recordFinding(tp.sourceFnId, tp.fnId, ps.sinkKind, tp.hops, tp.truncated);
+        }
+    };
+    /**
+     * Mark (fnId, paramIndex, source) tainted; enqueue. On a fresh key, taint +
+     * fire sinks. On revisit, INTERSECT the neutralised set (a kind stays
+     * neutralised only if EVERY path neutralises it — the sound direction); if it
+     * shrank, re-enqueue + re-fire so a less-neutralised path's sinks surface
+     * (the shrink-reprocess guard, mirroring `propagate.ts:deriveTaint`). Without
+     * it, a first more-neutralised path would freeze out a real finding (FN).
+     */
+    const taint = (tp) => {
+        const key = pkey(tp.fnId, tp.paramIndex, tp.sourceFnId);
+        const existing = tainted.get(key);
+        if (existing) {
+            const inter = new Set();
+            for (const k of existing.neutralized)
+                if (tp.neutralized.has(k))
+                    inter.add(k);
+            if (inter.size >= existing.neutralized.size)
+                return; // no shrink — cycle-safe
+            const merged = { ...existing, neutralized: inter };
+            tainted.set(key, merged);
+            queue.push(merged);
+            fireSinks(merged);
+            return;
+        }
+        tainted.set(key, tp);
+        queue.push(tp);
+        fireSinks(tp);
+    };
+    // ── seeds: every source→callee-arg, resolved against CALLS ────────────────
+    for (const [callerId, summary] of summaries) {
+        for (const sc of summary.sourceToCallArg) {
+            for (const edge of resolveCallees(callerId, sc.calleeName)) {
+                const callee = summaries.get(edge.calleeId);
+                if (!callee)
+                    continue;
+                if (sc.argIndex >= callee.paramCount)
+                    continue; // arity guard
+                // Build the seed path through the capped append so `maxHops` truncates
+                // the prefix (#2084 review P2-7), not a 2-entry path flagged truncated.
+                const seed = appendHop([{ fnId: callerId }], { fnId: edge.calleeId, callLine: sc.callLine, argIndex: sc.argIndex }, maxHops);
+                taint({
+                    fnId: edge.calleeId,
+                    paramIndex: sc.argIndex,
+                    sourceFnId: callerId,
+                    hops: seed.hops,
+                    truncated: seed.truncated,
+                    neutralized: new Set(sc.neutralized ?? []),
+                });
+            }
+        }
+    }
+    // ── generative return composition (#2084 review P1-1) ─────────────────────
+    // `genReturns` = functions whose RETURN carries a generated source. Seed with
+    // `sourceToReturn`; a caller that returns the result of a generative call is
+    // itself generative (transitive — `wrap(){ return getInput() }`). Small
+    // monotone fixpoint over the name-resolved call graph (`calleesByName`).
+    const genReturns = new Set();
+    for (const [id, s] of summaries)
+        if (s.sourceToReturn.length > 0)
+            genReturns.add(id);
+    let grChanged = true;
+    while (grChanged) {
+        grChanged = false;
+        for (const [callerId, s] of summaries) {
+            if (genReturns.has(callerId))
+                continue;
+            for (const cr of s.callResults) {
+                if (cr.dest.to !== 'return')
+                    continue;
+                if (calleesByName(callerId, cr.calleeName).some((e) => genReturns.has(e.calleeId))) {
+                    genReturns.add(callerId);
+                    grChanged = true;
+                    break;
+                }
+            }
+        }
+    }
+    // Compose: a caller using a generative call's result either FIRES (the result
+    // hits a sink) or SEEDS (the result flows into another call's arg). The
+    // generated source's origin is the generative callee.
+    for (const [callerId, s] of summaries) {
+        for (const cr of s.callResults) {
+            const generative = calleesByName(callerId, cr.calleeName).filter((e) => genReturns.has(e.calleeId));
+            if (generative.length === 0)
+                continue;
+            for (const g of generative) {
+                const d = cr.dest;
+                if (d.to === 'sink') {
+                    recordFinding(g.calleeId, callerId, d.sinkKind, [{ fnId: g.calleeId }, { fnId: callerId }], 2 > maxHops);
+                }
+                else if (d.to === 'callArg') {
+                    for (const tc of d.toCallee === undefined
+                        ? (callsByCaller.get(callerId) ?? [])
+                        : calleesByName(callerId, d.toCallee)) {
+                        const callee = summaries.get(tc.calleeId);
+                        if (!callee || d.argIndex >= callee.paramCount)
+                            continue;
+                        // Capped successive append so `maxHops` truncates the prefix (P2-7).
+                        const h1 = appendHop([{ fnId: g.calleeId }], { fnId: callerId }, maxHops);
+                        const h2 = appendHop(h1.hops, { fnId: tc.calleeId, argIndex: d.argIndex }, maxHops);
+                        taint({
+                            fnId: tc.calleeId,
+                            paramIndex: d.argIndex,
+                            sourceFnId: g.calleeId,
+                            hops: h2.hops,
+                            truncated: h1.truncated || h2.truncated,
+                            neutralized: new Set(),
+                        });
+                    }
+                }
+                // dest:'return' is already folded into `genReturns` above.
+            }
+        }
+    }
+    // ── propagation worklist ──────────────────────────────────────────────────
+    let head = 0;
+    while (head < queue.length) {
+        const tp = queue[head++];
+        const summary = summaries.get(tp.fnId);
+        if (!summary)
+            continue;
+        // This function's tainted param flows into callee args via paramToCallArg.
+        for (const pc of summary.paramToCallArg) {
+            if (pc.param !== tp.paramIndex)
+                continue;
+            for (const edge of resolveCallees(tp.fnId, pc.calleeName)) {
+                const callee = summaries.get(edge.calleeId);
+                if (!callee)
+                    continue;
+                if (pc.argIndex >= callee.paramCount)
+                    continue;
+                const next = appendHop(tp.hops, { fnId: edge.calleeId, callLine: pc.callLine, argIndex: pc.argIndex }, maxHops);
+                // Union the edge's neutralised kinds onto the composed path (a
+                // sanitizer between this param and the callee arg stays neutralised).
+                const neutralized = pc.neutralized && pc.neutralized.length > 0
+                    ? new Set([...tp.neutralized, ...pc.neutralized])
+                    : tp.neutralized;
+                taint({
+                    fnId: edge.calleeId,
+                    paramIndex: pc.argIndex,
+                    sourceFnId: tp.sourceFnId,
+                    hops: next.hops,
+                    truncated: tp.truncated || next.truncated,
+                    neutralized,
+                });
+            }
+        }
+    }
+    // ── deterministic assembly ────────────────────────────────────────────────
+    const all = [...findingsByKey.values()].sort((a, b) => a.sourceFnId.localeCompare(b.sourceFnId) ||
+        a.sinkFnId.localeCompare(b.sinkFnId) ||
+        a.sinkKind.localeCompare(b.sinkKind));
+    const maxFindings = limits?.maxFindings && limits.maxFindings > 0 ? limits.maxFindings : Infinity;
+    const findings = all.length > maxFindings ? all.slice(0, maxFindings) : all;
+    return {
+        findings,
+        droppedFindings: all.length - findings.length,
+        unmatchedCallSites,
+    };
+}
+/** Append a hop, respecting the hop cap (keeps the source-side prefix). */
+function appendHop(hops, hop, maxHops) {
+    if (hops.length >= maxHops)
+        return { hops, truncated: true };
+    return { hops: [...hops, hop], truncated: hops.length + 1 > maxHops };
+}

package/dist/core/ingestion/taint/propagate.d.ts

@@ -98,7 +98,7 @@
 import type { FunctionCfg } from '../cfg/types.js';
 import type { FunctionDefUse, ProgramPoint } from '../cfg/reaching-defs.js';
 import type { FunctionSiteMatches } from './match.js';
-import type { SinkKind, SourceKind } from './source-sink-config.js';
+import { type SinkKind, type SourceKind } from './source-sink-config.js';
 /**
  * Default per-function findings cap (U5 config resolution; cfg/emit.ts
  * DEFAULT_* pattern). Resolved into the RepoMeta `pdg` stamp by

package/dist/core/ingestion/taint/propagate.js

@@ -96,6 +96,7 @@
  * bypassed sanitizer (`exec(x + escape(x))`) killed nothing.
  */
 import { pointKey } from '../cfg/reaching-defs.js';
+import { SINK_KIND_ORDER as KIND_ORDER, sortSinkKinds as sortKinds, } from './source-sink-config.js';
 /**
  * Default per-function findings cap (U5 config resolution; cfg/emit.ts
  * DEFAULT_* pattern). Resolved into the RepoMeta `pdg` stamp by
@@ -113,16 +114,10 @@ export const DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION = 200;
  * `hopsTruncated`, parsed downstream as "path incomplete", never an error.
  */
 export const DEFAULT_PDG_MAX_TAINT_HOPS = 32;
-/** Canonical SinkKind order for deterministic `neutralized` arrays. */
-const KIND_ORDER = [
-    'code-injection',
-    'command-injection',
-    'path-traversal',
-    'sql-injection',
-    'xss',
-];
+// Canonical SinkKind order + sort live in source-sink-config.ts (shared with
+// the M4 summary harvest so the deterministic order never drifts); imported
+// above as KIND_ORDER / sortKinds. `kindRank` is the local comparator index.
 const kindRank = new Map(KIND_ORDER.map((k, i) => [k, i]));
-const sortKinds = (kinds) => [...new Set(kinds)].sort((a, b) => (kindRank.get(a) ?? 99) - (kindRank.get(b) ?? 99));
 const EMPTY_KINDS = new Set();
 const DIRECT_PATH = { kinds: EMPTY_KINDS, viaCall: false, sanitizers: [] };
 /**

package/dist/core/ingestion/taint/source-sink-config.d.ts

@@ -105,3 +105,16 @@ export interface SourceSinkSanitizerSpec {
     readonly sinks: readonly TaintSinkEntry[];
     readonly sanitizers: readonly TaintSanitizerEntry[];
 }
+/**
+ * Canonical deterministic ordering of {@link SinkKind} values. The single
+ * source of this order — the intra-procedural propagation engine
+ * (`propagate.ts`) and the M4 summary harvest (`summary-harvest.ts`) both sort
+ * `neutralized`/exclusion sets by it so their deterministic outputs (and the
+ * summary version stamp) stay stable. Lives here, next to the `SinkKind`
+ * union, so the two consumers never drift.
+ */
+export declare const SINK_KIND_ORDER: readonly SinkKind[];
+/** Dedupe + sort sink kinds by {@link SINK_KIND_ORDER} (deterministic). */
+export declare function sortSinkKinds(kinds: Iterable<SinkKind>): SinkKind[];
+/** Rank of a sink kind in {@link SINK_KIND_ORDER} (for comparator chaining). */
+export declare function sinkKindRank(kind: SinkKind): number;

package/dist/core/ingestion/taint/source-sink-config.js

@@ -13,4 +13,27 @@
  * shadow checks, spread/template position rules) live in the matcher so the
  * spec stays declarative data that can hash into `taintModelVersion`.
  */
-export {};
+/**
+ * Canonical deterministic ordering of {@link SinkKind} values. The single
+ * source of this order — the intra-procedural propagation engine
+ * (`propagate.ts`) and the M4 summary harvest (`summary-harvest.ts`) both sort
+ * `neutralized`/exclusion sets by it so their deterministic outputs (and the
+ * summary version stamp) stay stable. Lives here, next to the `SinkKind`
+ * union, so the two consumers never drift.
+ */
+export const SINK_KIND_ORDER = [
+    'code-injection',
+    'command-injection',
+    'path-traversal',
+    'sql-injection',
+    'xss',
+];
+const SINK_KIND_RANK = new Map(SINK_KIND_ORDER.map((k, i) => [k, i]));
+/** Dedupe + sort sink kinds by {@link SINK_KIND_ORDER} (deterministic). */
+export function sortSinkKinds(kinds) {
+    return [...new Set(kinds)].sort((a, b) => (SINK_KIND_RANK.get(a) ?? 99) - (SINK_KIND_RANK.get(b) ?? 99));
+}
+/** Rank of a sink kind in {@link SINK_KIND_ORDER} (for comparator chaining). */
+export function sinkKindRank(kind) {
+    return SINK_KIND_RANK.get(kind) ?? 99;
+}

package/dist/core/ingestion/taint/summary-harvest-driver.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Summary-harvest driver (#2084 M4 U1) — the in-phase orchestration that turns
+ * per-function CFGs into call-graph-keyed {@link FunctionSummary} objects.
+ *
+ * Runs inside the scope-resolution pdg window (alongside `emitFileTaint`),
+ * where both the live CFG side channel AND the structure-phase `Function` /
+ * `Method` graph nodes are available. For each emit-safe CFG it:
+ *
+ * 1. resolves the CFG's source anchor `(filePath, functionStartLine)` to its
+ *    graph node id, so the summary speaks the call graph's language directly —
+ *    the interprocedural fixpoint then joins summaries to `CALLS` edges by node
+ *    id with no fragile re-derivation;
+ * 2. runs the pure {@link harvestFunctionSummary} over the same RD facts +
+ *    matched sites the M3 taint pass uses;
+ * 3. stamps the own-facts `version` (#2084 review P1-1: callee-version
+ *    composition is RESERVED — the fixpoint does not recompute it today).
+ *
+ * ## The Function↔CFG join (load-bearing)
+ *
+ * `FunctionCfg.functionStartLine` is 1-based (the TS visitor's `row + 1`);
+ * `Function`/`Method` node `startLine` is 0-based (`startPosition.row`). The
+ * join therefore looks up node start line `functionStartLine - 1`
+ * ({@link NODE_TO_CFG_LINE_OFFSET}). Function nodes carry no start column, so a
+ * `(filePath, startLine)` collision — two functions opening on one line,
+ * `{ a: () => x(), b: () => y() }` — is ambiguous: the CFG disambiguates with
+ * `functionStartColumn` but the node does not, so a colliding anchor is DROPPED
+ * (counted as `unresolved`) rather than risk attaching a summary to the wrong
+ * function. Rare in practice; the alternative (cross-wired summaries) is unsound.
+ */
+import type { ParsedImport } from '../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { FunctionCfg } from '../cfg/types.js';
+import type { SourceSinkSanitizerSpec } from './source-sink-config.js';
+import { type FunctionSummary } from './summary-model.js';
+/** `cfg.functionStartLine` (1-based) − this = the node's 0-based `startLine`. */
+export declare const NODE_TO_CFG_LINE_OFFSET = 1;
+/**
+ * Index of functionish graph nodes by `filePath → startLine(0-based) → ids`.
+ * Built ONCE per scope-resolution pass (the graph is whole-repo); reused across
+ * every file's harvest.
+ */
+export type FunctionNodeIndex = ReadonlyMap<string, ReadonlyMap<number, readonly string[]>>;
+export declare function buildFunctionNodeIndex(graph: KnowledgeGraph): FunctionNodeIndex;
+export interface FileSummaryResult {
+    readonly summaries: readonly FunctionSummary[];
+    /** CFGs whose anchor resolved to no unique graph node (collision / missing). */
+    readonly unresolved: number;
+    /** CFGs whose reaching-defs were not `computed` (no summary produced). */
+    readonly gaps: number;
+}
+/**
+ * Harvest summaries for one file's emit-safe CFGs. `cfgs` MUST already be
+ * `isEmitSafeCfg`-filtered (the same `wellFormed` array fed to `emitFileTaint`).
+ * Pure aside from the read-only graph lookup; never throws on valid input.
+ */
+export declare function harvestFileSummaries(fnIndex: FunctionNodeIndex, cfgs: readonly FunctionCfg[], parsedImports: readonly ParsedImport[], spec: SourceSinkSanitizerSpec, maxFacts?: number): FileSummaryResult;