gitnexus 1.6.8-rc.8 → 1.6.8

package/dist/core/ingestion/taint/site-safety.js

@@ -0,0 +1,98 @@
+const SITE_KINDS = new Set(['call', 'new', 'member-read']);
+/**
+ * Whether a structurally-valid CFG's M3 `sites` annotations are safe to feed
+ * to the taint matcher/propagator. `true` when no statement carries sites
+ * (pre-M3 channel, or no calls) — absence is the well-formed empty case.
+ */
+export const hasTaintSafeSites = (cfg) => {
+    // Sites carry binding indices — a channel with sites but no binding table
+    // has nothing to range-check them against: reject (checked per statement).
+    const bindingCount = Array.isArray(cfg.bindings) ? cfg.bindings.length : -1;
+    for (const block of cfg.blocks) {
+        const stmts = block.statements;
+        if (stmts === undefined)
+            continue;
+        if (!Array.isArray(stmts))
+            return false;
+        for (const s of stmts) {
+            if (s?.sites === undefined)
+                continue;
+            if (bindingCount < 0)
+                return false;
+            if (!isSafeSiteList(s.sites, bindingCount))
+                return false;
+        }
+    }
+    return true;
+};
+const isSafeSiteList = (sites, bindingCount) => {
+    if (!Array.isArray(sites))
+        return false;
+    const siteCount = sites.length;
+    const bindingInRange = (i) => Number.isInteger(i) && i >= 0 && i < bindingCount;
+    const siteInRange = (i) => Number.isInteger(i) && i >= 0 && i < siteCount;
+    for (const site of sites) {
+        if (site === null || typeof site !== 'object')
+            return false;
+        if (typeof site.kind !== 'string' || !SITE_KINDS.has(site.kind))
+            return false;
+        if (site.callee !== undefined && typeof site.callee !== 'string')
+            return false;
+        if (site.receiver !== undefined && !bindingInRange(site.receiver))
+            return false;
+        if (site.requireArg !== undefined && typeof site.requireArg !== 'string')
+            return false;
+        if (site.template !== undefined && typeof site.template !== 'boolean')
+            return false;
+        if (site.spread !== undefined &&
+            (!Number.isInteger(site.spread) || site.spread < 0)) {
+            return false;
+        }
+        if (site.parent !== undefined) {
+            const p = site.parent;
+            if (!Array.isArray(p) || p.length !== 2)
+                return false;
+            if (!siteInRange(p[0]))
+                return false;
+            if (!Number.isInteger(p[1]) || p[1] < 0)
+                return false;
+        }
+        if (site.resultDefs !== undefined) {
+            if (!Array.isArray(site.resultDefs) || !site.resultDefs.every(bindingInRange))
+                return false;
+        }
+        if (site.args !== undefined) {
+            if (!Array.isArray(site.args))
+                return false;
+            for (const position of site.args) {
+                if (!Array.isArray(position))
+                    return false;
+                for (const entry of position) {
+                    if (typeof entry === 'number') {
+                        if (!bindingInRange(entry))
+                            return false;
+                    }
+                    else if (Array.isArray(entry) && entry.length === 2) {
+                        if (!bindingInRange(entry[0]) || !siteInRange(entry[1]))
+                            return false;
+                    }
+                    else {
+                        return false;
+                    }
+                }
+            }
+        }
+        if (site.kind === 'member-read') {
+            // The matcher dereferences both unconditionally on member reads.
+            if (!bindingInRange(site.object) || typeof site.property !== 'string')
+                return false;
+        }
+        else {
+            if (site.object !== undefined && !bindingInRange(site.object))
+                return false;
+            if (site.property !== undefined && typeof site.property !== 'string')
+                return false;
+        }
+    }
+    return true;
+};

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

@@ -1,36 +1,120 @@
 /**
- * Source/sink/sanitizer config model (issue #2080, taint/PDG substrate M0).
+ * Source/sink/sanitizer config model (issue #2080 M0 seam, extended by #2083
+ * M3 U2).
  *
- * The per-language taint configuration *shape*. M0 ships only the type and an
- * (empty) registry seam — no analysis consumes it yet. M3 (#2083, intra-proc
- * taint) populates per-language specs and reads them when emitting TAINTED /
- * SANITIZES edges.
+ * The per-language taint configuration *shape*. M0 shipped only the bare
+ * `{name, args?}` callable matcher and an empty registry seam; M3 U2 extends
+ * it with the `kind` taxonomy and the resolution-mechanism fields the
+ * import-aware matcher (`taint/match.ts`) needs, and fills the registry with
+ * the built-in TS/JS model (`taint/typescript-model.ts`).
  *
- * Kept deliberately minimal: enough for M3 to express "callable X is a
- * source / sink / sanitizer, optionally for argument position N" without M0
- * committing to matcher semantics it cannot yet validate. The shape is
- * expected to grow (e.g. sanitizer escape conditions, return-position taint)
- * when M3 makes contact with real flows; that is a forward-declared-interface
- * design choice, not a finished contract.
+ * Design rule: entries describe WHAT a callable is (category + how its name
+ * resolves), never HOW matching works — matching semantics (import joins,
+ * shadow checks, spread/template position rules) live in the matcher so the
+ * spec stays declarative data that can hash into `taintModelVersion`.
  */
+/** Categories of taint sources. M3 ships remote HTTP input only. */
+export type SourceKind = 'remote-input';
 /**
- * Identifies a callable that participates in taint flow. `name` is matched
- * against a resolved callable (simple or qualified name — exact matching
- * semantics are M3's call). `args` optionally narrows to specific 0-based
- * argument positions that carry taint (for a source/sink) or clear it (for a
- * sanitizer); omit to mean "unspecified / all".
+ * Vulnerability categories for sinks. Sanitizers reference the SAME taxonomy
+ * via {@link TaintSanitizerEntry.neutralizes}: a sanitizer kill applies only
+ * when it neutralizes the matched sink's kind (`path.basename` strips
+ * directories, not shell metacharacters — a kind-blind kill is a suppressed
+ * live command injection, the forbidden false-negative direction).
  */
-export interface TaintCallableMatcher {
+export type SinkKind = 'command-injection' | 'code-injection' | 'path-traversal' | 'sql-injection' | 'xss';
+/**
+ * Identifies a callable that participates in taint flow. `name` is the
+ * callable's own (unqualified) name — qualification comes from the
+ * resolution-mechanism fields on the extending entry types, not from dotted
+ * `name` strings. `args` optionally narrows to specific 0-based argument
+ * positions that carry taint into a sink (or are cleared by a sanitizer);
+ * omit to mean "all positions".
+ */
+export interface TaintCallableMatcher<K extends string = string> {
+    readonly name: string;
+    readonly args?: readonly number[];
+    /** Category label — drives finding classification and sanitizer kind-compat. */
+    readonly kind: K;
+}
+/**
+ * A sink callable. Exactly one resolution mechanism should be set per entry:
+ *
+ * - `module` — the callable lives in a package/builtin module; the matcher
+ *   resolves call sites against it import-aware (ESM `parsedImports` aliases,
+ *   namespace handles, and the CommonJS `require('<literal>')` join). `name`
+ *   is the exported member (`'exec'` of `'child_process'`); the pseudo-name
+ *   `'default'` denotes invoking the module's default export / the module
+ *   handle itself.
+ * - `global` — a true ECMAScript global (`eval`, `Function`); matched by bare
+ *   name only when the name is not shadowed by an in-function declaration and
+ *   not bound by an import. `newOnly` further restricts to `new` expressions
+ *   (`new Function(body)`).
+ * - `anyReceiver` — a method matched on ANY receiver chain by its final
+ *   segment (`.query(sql)` / `.execute(sql)` on whatever the DB handle is
+ *   named) — deliberately name-conventional, like Semgrep's default rules.
+ * - `receivers` — a method matched only on the listed conventional receiver
+ *   names (`res.send` / `res.write`); exactly `<receiver>.<name>`, name-based.
+ */
+export interface TaintSinkEntry extends TaintCallableMatcher<SinkKind> {
+    readonly module?: string;
+    readonly global?: boolean;
+    /** Only meaningful with `global`: match `new <name>(…)` sites only. */
+    readonly newOnly?: boolean;
+    readonly anyReceiver?: boolean;
+    readonly receivers?: readonly string[];
+}
+/**
+ * A sanitizer callable. Carries the sink kinds it `neutralizes` instead of a
+ * `kind` of its own. STRICTER resolution than sinks by design: only the
+ * `module` (import-aware) and `global` mechanisms exist — never a bare-name
+ * convention — because a sanitizer mis-match is a false KILL (a user's own
+ * `escape` helper must not suppress findings), while a sink mis-match is
+ * merely noise. `args` narrows which argument positions are cleared (omit =
+ * all).
+ */
+export interface TaintSanitizerEntry {
     readonly name: string;
     readonly args?: readonly number[];
+    readonly neutralizes: readonly SinkKind[];
+    readonly module?: string;
+    readonly global?: boolean;
+}
+/**
+ * A member-read taint source: reading `<object>.<property>` where the object
+ * is one of the conventional receiver `objects` names (`req`/`request`) and
+ * the property is one of `properties` (`body`, `query`, …). Matching is
+ * name-based on the harvested `member-read` site (Semgrep-convention, not
+ * type-aware — the accepted M3 FP/FN trade recorded in the plan's risk
+ * table). One entry fans out over the objects × properties product.
+ */
+export interface TaintMemberSourceEntry {
+    readonly kind: SourceKind;
+    readonly objects: readonly string[];
+    readonly properties: readonly string[];
 }
 /**
- * The taint configuration for a single language: which callables introduce
- * taint (sources), which are dangerous to reach with tainted input (sinks),
- * and which clear taint (sanitizers).
+ * The taint configuration for a single language: which member reads introduce
+ * taint (sources), which callables are dangerous to reach with tainted input
+ * (sinks), and which callables clear it (sanitizers). M3 sources are
+ * member-read entries only; call-result sources are a forward extension
+ * (add a union variant), not a missing case.
  */
 export interface SourceSinkSanitizerSpec {
-    readonly sources: readonly TaintCallableMatcher[];
-    readonly sinks: readonly TaintCallableMatcher[];
-    readonly sanitizers: readonly TaintCallableMatcher[];
+    readonly sources: readonly TaintMemberSourceEntry[];
+    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

@@ -1,16 +1,39 @@
 /**
- * Source/sink/sanitizer config model (issue #2080, taint/PDG substrate M0).
+ * Source/sink/sanitizer config model (issue #2080 M0 seam, extended by #2083
+ * M3 U2).
  *
- * The per-language taint configuration *shape*. M0 ships only the type and an
- * (empty) registry seam — no analysis consumes it yet. M3 (#2083, intra-proc
- * taint) populates per-language specs and reads them when emitting TAINTED /
- * SANITIZES edges.
+ * The per-language taint configuration *shape*. M0 shipped only the bare
+ * `{name, args?}` callable matcher and an empty registry seam; M3 U2 extends
+ * it with the `kind` taxonomy and the resolution-mechanism fields the
+ * import-aware matcher (`taint/match.ts`) needs, and fills the registry with
+ * the built-in TS/JS model (`taint/typescript-model.ts`).
  *
- * Kept deliberately minimal: enough for M3 to express "callable X is a
- * source / sink / sanitizer, optionally for argument position N" without M0
- * committing to matcher semantics it cannot yet validate. The shape is
- * expected to grow (e.g. sanitizer escape conditions, return-position taint)
- * when M3 makes contact with real flows; that is a forward-declared-interface
- * design choice, not a finished contract.
+ * Design rule: entries describe WHAT a callable is (category + how its name
+ * resolves), never HOW matching works — matching semantics (import joins,
+ * 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/source-sink-registry.d.ts

@@ -1,10 +1,12 @@
 /**
  * Per-language source/sink/sanitizer registry seam (issue #2080).
  *
- * A keyed registry of {@link SourceSinkSanitizerSpec} by language id. M0 stands
- * up the empty seam — no language is registered and nothing in the pipeline
- * reads it. M3 (#2083) registers per-language specs and queries this registry
- * when emitting taint edges.
+ * A keyed registry of {@link SourceSinkSanitizerSpec} by language id. M0 stood
+ * up the empty seam; M3 U2 (#2083) fills it with the built-in TS/JS model via
+ * the EXPLICIT `registerBuiltinTaintModels()` seam in `typescript-model.ts` —
+ * deliberately not an import side-effect. The U4 taint emit path must call it
+ * once before the pdg window consumes the registry (idempotent; the registry
+ * itself stays empty until then, preserving default-run parity).
  *
  * The store is module-level (matching the codebase's other per-language
  * registries). {@link clearSourceSinkRegistry} resets it for test isolation.

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

@@ -1,10 +1,12 @@
 /**
  * Per-language source/sink/sanitizer registry seam (issue #2080).
  *
- * A keyed registry of {@link SourceSinkSanitizerSpec} by language id. M0 stands
- * up the empty seam — no language is registered and nothing in the pipeline
- * reads it. M3 (#2083) registers per-language specs and queries this registry
- * when emitting taint edges.
+ * A keyed registry of {@link SourceSinkSanitizerSpec} by language id. M0 stood
+ * up the empty seam; M3 U2 (#2083) fills it with the built-in TS/JS model via
+ * the EXPLICIT `registerBuiltinTaintModels()` seam in `typescript-model.ts` —
+ * deliberately not an import side-effect. The U4 taint emit path must call it
+ * once before the pdg window consumes the registry (idempotent; the registry
+ * itself stays empty until then, preserving default-run parity).
  *
  * The store is module-level (matching the codebase's other per-language
  * registries). {@link clearSourceSinkRegistry} resets it for test isolation.

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

@@ -0,0 +1,80 @@
+/**
+ * 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 ReachingDefsSolver } from '../cfg/reaching-defs.js';
+import type { FunctionCfg } from '../cfg/types.js';
+import type { SourceSinkSanitizerSpec } from './source-sink-config.js';
+import { type FunctionSummary } from './summary-model.js';
+import type { CallSummary } from './call-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, solve?: ReachingDefsSolver): FileSummaryResult;
+export interface FileCallSummaryResult {
+    readonly summaries: readonly CallSummary[];
+    /** 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 per-function RETURN-VALUE ASCENT summaries (PDG FU-C, U-C2) for one
+ * file's emit-safe CFGs — the dependence-engine SIBLING of
+ * {@link harvestFileSummaries}. `cfgs` MUST already be `isEmitSafeCfg`-filtered.
+ * Pure aside from the read-only graph lookup; never throws on valid input.
+ *
+ * Unlike the taint harvest, this needs NO source/sink model — return-value
+ * ascent is purely data-dependence over the RD facts — so it runs for every
+ * `--pdg` language (not just those with a registered taint spec). It reuses the
+ * SAME per-function RD facts (recomputed via the same pure solver + cap the RD
+ * emit used; the persisted REACHING_DEF projection is a lossy subset, so the
+ * harvest re-derives in-phase exactly as the taint harvest does — no new
+ * worker/CFG work, no parse-cache bump).
+ */
+export declare function harvestFileCallSummaries(fnIndex: FunctionNodeIndex, cfgs: readonly FunctionCfg[], maxFacts?: number, solve?: ReachingDefsSolver): FileCallSummaryResult;

package/dist/core/ingestion/taint/summary-harvest-driver.js

@@ -0,0 +1,179 @@
+/**
+ * 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 { computeReachingDefs } from '../cfg/reaching-defs.js';
+import { DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION } from '../cfg/emit.js';
+import { buildTaintImportIndex, matchFunctionSites } from './match.js';
+import { harvestFunctionSummary } from './summary-harvest.js';
+import { ownFactsDigest, summaryVersion } from './summary-model.js';
+import { harvestCallSummary } from './call-summary-harvest.js';
+/** `cfg.functionStartLine` (1-based) − this = the node's 0-based `startLine`. */
+export const NODE_TO_CFG_LINE_OFFSET = 1;
+/**
+ * Node labels that can own a CFG / be a `CALLS` endpoint AND receive a
+ * return-value-ascent summary. `Constructor` is INTENTIONALLY excluded: a
+ * constructor's "return" is the freshly-allocated instance, not a user-flowed
+ * value, so a formal→return ascent is not meaningful for it. A Constructor CFG
+ * therefore resolves to no functionish node (counted `unresolved`) and emits no
+ * CALL_SUMMARY edge — a sound recall miss, never a false ascent. The impact
+ * consumer may still DESCEND into a Constructor; it just never learns a
+ * constructor's return-flow. (#2227 tri-review.)
+ */
+const FUNCTIONISH_LABELS = new Set(['Function', 'Method']);
+export function buildFunctionNodeIndex(graph) {
+    const index = new Map();
+    const add = (node) => {
+        if (!FUNCTIONISH_LABELS.has(node.label))
+            return;
+        const filePath = node.properties.filePath;
+        const startLine = node.properties.startLine;
+        if (typeof filePath !== 'string' || typeof startLine !== 'number')
+            return;
+        let byLine = index.get(filePath);
+        if (!byLine) {
+            byLine = new Map();
+            index.set(filePath, byLine);
+        }
+        const ids = byLine.get(startLine);
+        if (ids)
+            ids.push(node.id);
+        else
+            byLine.set(startLine, [node.id]);
+    };
+    for (const node of graph.iterNodes())
+        add(node);
+    return index;
+}
+/** Resolve a CFG anchor to a unique functionish node id, or undefined. */
+function resolveFnId(fnIndex, cfg) {
+    const byLine = fnIndex.get(cfg.filePath);
+    if (!byLine)
+        return undefined;
+    const ids = byLine.get(cfg.functionStartLine - NODE_TO_CFG_LINE_OFFSET);
+    // Unique match only — a same-line collision is unresolvable (no node column).
+    return ids && ids.length === 1 ? ids[0] : undefined;
+}
+/**
+ * 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 function harvestFileSummaries(fnIndex, cfgs, parsedImports, spec, maxFacts = DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION, 
+// U12: shared per-file memoized solver (harvest/taint bucket — no maxBlockVisits).
+solve = computeReachingDefs) {
+    const importIndex = buildTaintImportIndex(parsedImports);
+    const summaries = [];
+    let unresolved = 0;
+    let gaps = 0;
+    for (const cfg of cfgs) {
+        const fnId = resolveFnId(fnIndex, cfg);
+        if (fnId === undefined) {
+            unresolved++;
+            continue;
+        }
+        const defUse = solve(cfg, { maxFacts });
+        const matches = matchFunctionSites(cfg, spec, importIndex);
+        const harvested = harvestFunctionSummary(cfg, defUse, matches);
+        if (harvested.status !== 'computed') {
+            gaps++;
+            continue;
+        }
+        const facts = harvested.facts;
+        // Skip functions with NO taint behaviour at all — they cannot participate
+        // in any flow and would only bloat the fixpoint's working set.
+        if (facts.paramToReturn.length === 0 &&
+            facts.paramToCallArg.length === 0 &&
+            facts.paramToSink.length === 0 &&
+            facts.sourceToReturn.length === 0 &&
+            facts.sourceToCallArg.length === 0 &&
+            facts.callResults.length === 0) {
+            continue;
+        }
+        const digest = ownFactsDigest(facts);
+        summaries.push({
+            fnId,
+            filePath: cfg.filePath,
+            startLine: cfg.functionStartLine,
+            ...facts,
+            // Provisional own-only version; the fixpoint recomputes with callee
+            // versions once the call graph is condensed.
+            version: summaryVersion(digest, []),
+        });
+    }
+    return { summaries, unresolved, gaps };
+}
+/**
+ * Harvest per-function RETURN-VALUE ASCENT summaries (PDG FU-C, U-C2) for one
+ * file's emit-safe CFGs — the dependence-engine SIBLING of
+ * {@link harvestFileSummaries}. `cfgs` MUST already be `isEmitSafeCfg`-filtered.
+ * Pure aside from the read-only graph lookup; never throws on valid input.
+ *
+ * Unlike the taint harvest, this needs NO source/sink model — return-value
+ * ascent is purely data-dependence over the RD facts — so it runs for every
+ * `--pdg` language (not just those with a registered taint spec). It reuses the
+ * SAME per-function RD facts (recomputed via the same pure solver + cap the RD
+ * emit used; the persisted REACHING_DEF projection is a lossy subset, so the
+ * harvest re-derives in-phase exactly as the taint harvest does — no new
+ * worker/CFG work, no parse-cache bump).
+ */
+export function harvestFileCallSummaries(fnIndex, cfgs, maxFacts = DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION, 
+// U12: shared per-file memoized solver (harvest/taint bucket — no maxBlockVisits).
+solve = computeReachingDefs) {
+    const summaries = [];
+    let unresolved = 0;
+    let gaps = 0;
+    for (const cfg of cfgs) {
+        const fnId = resolveFnId(fnIndex, cfg);
+        if (fnId === undefined) {
+            unresolved++;
+            continue;
+        }
+        const defUse = solve(cfg, { maxFacts });
+        const harvested = harvestCallSummary(cfg, defUse);
+        if (harvested.status !== 'computed') {
+            gaps++;
+            continue;
+        }
+        const facts = harvested.facts;
+        // Skip functions with NO return-flow at all — an empty summary records no
+        // ascent fact, so persisting it would only bloat the edge set. (The consumer
+        // treats an absent CALL_SUMMARY as "no known ascent", identical to an empty
+        // one.) A 0-param function or a void function therefore emits no edge.
+        if (facts.returnFlowParams.length === 0)
+            continue;
+        summaries.push({
+            fnId,
+            filePath: cfg.filePath,
+            startLine: cfg.functionStartLine,
+            paramCount: facts.paramCount,
+            returnFlowParams: facts.returnFlowParams,
+        });
+    }
+    return { summaries, unresolved, gaps };
+}