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

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

@@ -0,0 +1,118 @@
+/**
+ * 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';
+/** `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. */
+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) {
+    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 = computeReachingDefs(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 };
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Per-function taint SUMMARY harvest (#2084 M4 U1).
+ *
+ * Pure, deterministic derivation of one function's {@link FunctionSummary}
+ * facts from the SAME substrate the M3 intra-procedural pass consumes — the M2
+ * reaching-definition facts (`computeReachingDefs`) and the matched taint sites
+ * (`matchFunctionSites`). No graph, no I/O, no logger; mirrors the
+ * `computeReachingDefs` / `computeTaintFlows` contract (insertion-ordered
+ * worklist, explicitly sorted outputs) so snapshot tests and the version stamp
+ * stay stable. Runs IN-PHASE inside the scope-resolution pdg window where the
+ * CFG side channel is live (plan KTD1); the cross-function fixpoint that
+ * COMPOSES these summaries runs afterward over the complete call graph.
+ *
+ * ## What a summary captures (whole-parameter granularity)
+ *
+ * Seeding each formal parameter as taint and running forward reachability over
+ * the def→use facts yields four edge categories:
+ *
+ * - **param→return** — a param's value reaches a `return <expr>`. Return
+ *   statements are identified structurally: the SOURCE block of every CFG edge
+ *   of kind `return` terminates in the return jump (the M2 edge-kind
+ *   invariant), so its last statement's `uses` are the returned bindings.
+ * - **param→callee-arg** — a param occurrence lands in argument position
+ *   `argIndex` of a call at `callLine`. The fixpoint resolves `callLine` to a
+ *   callee via the caller's `CALLS` edges and applies the callee's summary
+ *   (TITO composition).
+ * - **param→sink** — a param reaches a modelled sink position (the partial
+ *   flow that a cross-function source completes).
+ * - **source→return** — a modelled source read (`req.body`) reaches the return
+ *   (a generative summary: calling the function yields tainted data).
+ *
+ * ## Soundness model (context-insensitive first cut)
+ *
+ * Onward propagation uses the M3 STATEMENT-LEVEL precision floor: a statement
+ * that uses a tainted binding taints all of its defs (and `mayDefs`). This is
+ * the same sound over-approximation M3 documents — it may over-taint
+ * (multi-declarator conflation) but never drops a real flow. Sanitizer
+ * `resultDefs` narrow the EXCLUSION set (a def produced by a matched sanitizer
+ * carries that sanitizer's neutralised `SinkKind`s), so a sanitised value does
+ * not trigger a downstream sink of the neutralised kind — the kind-set
+ * exclusion model, simplified to the result-def channel (occurrence
+ * interposition, field paths, and callbacks are deferred — plan KTD).
+ *
+ * The summary edges themselves (return / call-arg / sink) are recorded from
+ * ACTUAL binding occurrences (a tainted binding present in a return's uses, a
+ * call's arg list, or a matched sink position), never the floor — the floor
+ * governs only onward def-tainting, keeping the recorded edges precise.
+ *
+ * ## Known limitation — destructured / rest params (documented FN)
+ *
+ * Param indices are assigned by ORDINAL over the flattened param-binding list,
+ * which equals the FORMAL parameter position only when every param is a simple
+ * identifier. A destructured or rest param contributes several bindings (or
+ * shifts the count), so a simple param positioned AFTER one
+ * (`function f([a, b], x) { sink(x) }`) gets a summary port index that does not
+ * match the formal argument position the interprocedural solver joins against
+ * — a cross-function false negative for that function. The precise fix needs a
+ * formal-param index threaded from the worker harvest (`BindingEntry`), a
+ * cache-namespace-affecting change deferred with the other documented FN
+ * classes (closures, fields — see the taint skill). Functions with all-simple
+ * params (the common case) are unaffected.
+ */
+import type { FunctionCfg } from '../cfg/types.js';
+import { type FunctionDefUse } from '../cfg/reaching-defs.js';
+import type { FunctionSiteMatches } from './match.js';
+import type { CallResult, ParamToCallArg, ParamToReturn, ParamToSink, SourceToCallArg, SourceToReturn } from './summary-model.js';
+/** The own-facts portion of a summary (fnId/version are added by the caller). */
+export interface HarvestedSummaryFacts {
+    readonly paramCount: number;
+    readonly paramToReturn: readonly ParamToReturn[];
+    readonly paramToCallArg: readonly ParamToCallArg[];
+    readonly paramToSink: readonly ParamToSink[];
+    readonly sourceToReturn: readonly SourceToReturn[];
+    readonly sourceToCallArg: readonly SourceToCallArg[];
+    readonly callResults: readonly CallResult[];
+}
+export interface HarvestResult {
+    /** `computed` — facts derived; `coverage-gap` — the RD solver was not
+     *  `computed`, so no summary is produced (consistent with M3 R4). */
+    readonly status: 'computed' | 'coverage-gap';
+    readonly gapReason?: FunctionDefUse['status'];
+    readonly facts: HarvestedSummaryFacts;
+}
+/**
+ * Harvest the summary facts for one function. PRECONDITION: `cfg` is
+ * `isEmitSafeCfg`-filtered and `defUse` was computed from it; sites are assumed
+ * `hasTaintSafeSites`-valid (the caller gates exactly as the M3 emit path does).
+ */
+export declare function harvestFunctionSummary(cfg: FunctionCfg, defUse: FunctionDefUse, matches: FunctionSiteMatches): HarvestResult;