gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

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

@@ -0,0 +1,204 @@
+/**
+ * In-phase taint emission (#2083 M3 U4, plan KTD1/KTD6).
+ *
+ * Per-file driver for the M3 taint pass: gate → match → solve → propagate →
+ * persist sparse `TAINTED` + `SANITIZES` edges. Invoked from the pdg window in
+ * scope-resolution (`pipeline/run.ts`), immediately after `emitFileReachingDefs`
+ * inside the SAME per-file try — per-file isolation for free (KTD1). Mirrors
+ * `emitFileReachingDefs` (cfg/emit.ts) for the budget/dedup/warn discipline and
+ * the telemetry-result shape.
+ *
+ * ## Per-function pipeline (ordering is load-bearing)
+ *
+ * 1. `hasTaintSafeSites` — a corrupted-store site annotation degrades to
+ *    SKIP-TAINT-KEEP-RD for this function (counted + warned), never a crash
+ *    (KTD2; the matcher/propagator dereference indices unvalidated).
+ * 2. `matchFunctionSites` against the language spec (the import index is
+ *    built ONCE per file — imports are a file-level fact).
+ * 3. ZERO-MATCH FAST PATH: the solver runs only when the function has at
+ *    least one matched source AND one matched sink. In a typical repo almost
+ *    no function has both; an unconditional second `computeReachingDefs` per
+ *    function would ship a near-2× solve cost to every `--pdg` user.
+ * 4. `computeReachingDefs` with the taint `maxFacts` — by DEFAULT the M2
+ *    derived `DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION` (deliberate
+ *    reuse, not a new constant: the fact-materialization envelope is a
+ *    memory question, O(defs×uses), orthogonal to the findings cap, and M2
+ *    already validated exactly this envelope on the same solver in the same
+ *    window). The run.ts caller derives `limits.maxFacts` from the SAME
+ *    RD-edge-cap formula `emitFileReachingDefs` uses, so taint coverage and
+ *    RD coverage truncate together — a function is never `truncated` for one
+ *    layer and `computed` for the other.
+ * 5. `computeTaintFlows` — a non-`computed` status is a per-function
+ *    COVERAGE GAP (R4: counted by `gapReason`, function skipped entirely,
+ *    never partially analyzed).
+ * 6. Emit one `TAINTED` edge per finding and one `SANITIZES` edge per kill.
+ *    Kills are emitted even when findings are zero — a fully-sanitized
+ *    function's kills are exactly its evidence of safety.
+ *
+ * ## Identity, dedup, budget (KTD6)
+ *
+ * Findings carry STATEMENT-LEVEL identity — function anchor + sink kind +
+ * source occurrence (point/site/object-binding/property) + sink occurrence
+ * (point/site/arg/binding) — NOT the REACHING_DEF block-level key (block-pair
+ * conflation would drop `exec(req.body, req.query)`'s second finding). The
+ * propagation engine dedups by this exact key BEFORE its deterministic cap
+ * (`maxFindingsPerFunction`) and counts the overflow; this module templates
+ * the same coordinates into the edge id (binding identity via the shared
+ * `bindingKey`; the free-text `property` rides LAST so it can never collide
+ * into another component) and warns with the drop count on truncation.
+ *
+ * `reason` carries the versioned hop encoding (`taint/path-codec.ts` — U6's
+ * `explain` decodes the same module) for `TAINTED`, and the killed binding's
+ * plain name for `SANITIZES` (M0/S1 queryability verdict, like REACHING_DEF).
+ *
+ * ## Warn split (R4 vs noise)
+ *
+ * Unsafe-site skips and cap drops warn PER FUNCTION here (rare, actionable —
+ * mirrors `emitFileReachingDefs`' malformed/cap warns). Solver coverage gaps
+ * (`truncated`/`overflow`) do NOT re-warn per function: the RD layer already
+ * warned for the same function with the same solver status (same `maxFacts`
+ * derivation — see step 4), and a duplicate `[taint]` line per mega-function
+ * would be pure spam. They are counted (+ exampled) in the result and the
+ * run.ts caller aggregates them into ONE unconditional `logger.warn` per
+ * language (R4) — never dropped on the floor (the M2 lesson).
+ */
+import { generateId } from '../../../lib/utils.js';
+import { basicBlockId, bindingKey, DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION, } from '../cfg/emit.js';
+import { computeReachingDefs, pointKey } from '../cfg/reaching-defs.js';
+import { hasTaintSafeSites } from './site-safety.js';
+import { buildTaintImportIndex, matchFunctionSites } from './match.js';
+import { computeTaintFlows, DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './propagate.js';
+// Re-exported so the pipeline (run.ts) sources the taint default caps through
+// this orchestration module rather than reaching into propagate.ts directly.
+export { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './propagate.js';
+import { encodeTaintPath } from './path-codec.js';
+/** Cap on example anchors carried per result (aggregate-warn material, R4). */
+const MAX_EXAMPLES = 5;
+const pushExample = (list, anchor) => {
+    if (list.length < MAX_EXAMPLES)
+        list.push(anchor);
+};
+/**
+ * Run the taint pass over one file's emit-safe CFGs and persist TAINTED +
+ * SANITIZES edges. `cfgs` MUST already be `isEmitSafeCfg`-filtered (the same
+ * `wellFormed` array the caller fed `emitFileCfgs`/`emitFileReachingDefs`) —
+ * block/edge anchors are trusted here; only the M3 `sites` layer is
+ * re-validated (`hasTaintSafeSites`). Never throws on well-formed input;
+ * the caller's per-file try isolates the rest.
+ */
+export function emitFileTaint(graph, cfgs, parsedImports, spec, limits, onWarn) {
+    const result = {
+        functionsAnalyzed: 0,
+        functionsSkippedNoMatch: 0,
+        functionsSkippedUnsafeSites: 0,
+        functionsCoverageGap: { truncated: 0, overflow: 0, 'no-facts': 0 },
+        findingsEmitted: 0,
+        killsEmitted: 0,
+        findingsDropped: 0,
+        hopsTruncatedFindings: 0,
+        coverageGapExamples: [],
+        droppedExamples: [],
+    };
+    // Imports are a FILE-level fact — build the index once, not per function.
+    const importIndex = buildTaintImportIndex(parsedImports);
+    const maxFindingsPerFunction = limits?.maxFindingsPerFunction ?? DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION;
+    const maxHops = limits?.maxHops ?? DEFAULT_PDG_MAX_TAINT_HOPS;
+    const maxFacts = limits?.maxFacts ?? DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION;
+    // Defensive cross-CFG id guard: finding identity is unique WITHIN a
+    // function by construction (the propagation engine dedups), so a repeat can
+    // only mean two CFGs sharing an anchor — skip, never double-insert.
+    const seenEdgeIds = new Set();
+    for (const cfg of cfgs) {
+        const { filePath, functionStartLine, functionStartColumn } = cfg;
+        const anchor = `${filePath}:${functionStartLine}`;
+        if (!hasTaintSafeSites(cfg)) {
+            result.functionsSkippedUnsafeSites++;
+            pushExample(result.coverageGapExamples, anchor);
+            onWarn?.(`[taint] ${anchor}: malformed site annotations (out-of-range binding/site ` +
+                `indices) — taint skipped for this function; its CFG and REACHING_DEF ` +
+                `layers are unaffected`);
+            continue;
+        }
+        const matches = matchFunctionSites(cfg, spec, importIndex);
+        if (!matches.hasSource || !matches.hasSink) {
+            // Zero-match fast path: no solver call (see module doc step 3).
+            result.functionsSkippedNoMatch++;
+            continue;
+        }
+        const defUse = computeReachingDefs(cfg, { maxFacts });
+        const flows = computeTaintFlows(cfg, defUse, matches, { maxFindingsPerFunction, maxHops });
+        if (flows.status === 'coverage-gap') {
+            // R4: skipped entirely, counted by reason; aggregate-warned by the
+            // caller (the RD layer already per-function-warned this solver status).
+            result.functionsCoverageGap[flows.gapReason ?? 'no-facts']++;
+            pushExample(result.coverageGapExamples, anchor);
+            continue;
+        }
+        result.functionsAnalyzed++;
+        const bindings = cfg.bindings ?? [];
+        const fnAnchor = `${filePath}:${functionStartLine}:${functionStartColumn}`;
+        const blockId = (p) => basicBlockId(filePath, functionStartLine, functionStartColumn, p.blockIndex);
+        const bKey = (idx) => {
+            const b = bindings[idx];
+            return b === undefined ? `#${idx}` : bindingKey(b);
+        };
+        // SANITIZES — one edge per kill, REGARDLESS of findings (kills can and do
+        // exist with zero findings: a fully-sanitized flow IS the kill evidence).
+        for (const kill of flows.kills) {
+            const id = generateId('SANITIZES', `${fnAnchor}:${pointKey(kill.sanitizer)}->${pointKey(kill.killedDef)}:` +
+                bKey(kill.bindingIdx));
+            if (seenEdgeIds.has(id))
+                continue;
+            seenEdgeIds.add(id);
+            graph.addRelationship({
+                id,
+                type: 'SANITIZES',
+                sourceId: blockId(kill.sanitizer),
+                targetId: blockId(kill.killedDef),
+                confidence: 1.0,
+                reason: bindings[kill.bindingIdx]?.name ?? `#${kill.bindingIdx}`,
+            });
+            result.killsEmitted++;
+        }
+        // TAINTED — one edge per finding (already deduped + capped upstream).
+        for (const finding of flows.findings) {
+            const { source, sink } = finding;
+            // KTD6 statement-level identity: function anchor + kind + source
+            // occurrence + sink occurrence + binding keys. The rule-(b) occurrence
+            // coordinates (site index / arg index) distinguish
+            // `exec(req.body, req.query)`'s two findings; `property` is free-text
+            // (string-literal subscripts) and rides LAST so it cannot collide into
+            // another component.
+            const id = generateId('TAINTED', `${fnAnchor}:${finding.sinkKind}:` +
+                `${pointKey(source.point)}.${source.siteIndex}:${bKey(source.objectBindingIdx)}:` +
+                `${pointKey(sink.point)}.${sink.siteIndex}.${sink.argIndex}:${bKey(sink.bindingIdx)}:` +
+                `${sink.entryName}:${source.property}`);
+            if (seenEdgeIds.has(id))
+                continue;
+            seenEdgeIds.add(id);
+            // `kind` rides the reason's `;<kind>` header — the only persisted
+            // channel for the finding's category (the edge id embedding it is not a
+            // stored column; `step` is INT32). U6's `explain` decodes it back.
+            const encoded = encodeTaintPath(finding.hops.map((h) => ({ name: h.name, line: h.point.line, viaCall: h.viaCall })), { truncated: finding.hopsTruncated === true, kind: finding.sinkKind });
+            if (encoded.truncated)
+                result.hopsTruncatedFindings++;
+            graph.addRelationship({
+                id,
+                type: 'TAINTED',
+                sourceId: blockId(source.point),
+                targetId: blockId(sink.point),
+                confidence: 1.0,
+                reason: encoded.reason,
+            });
+            result.findingsEmitted++;
+        }
+        if (flows.droppedFindings > 0) {
+            result.findingsDropped += flows.droppedFindings;
+            pushExample(result.droppedExamples, anchor);
+            onWarn?.(`[taint] ${anchor}: per-function taint findings cap ` +
+                `(${maxFindingsPerFunction}) reached — dropped ${flows.droppedFindings} of ` +
+                `${flows.findings.length + flows.droppedFindings} deduped findings`);
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Import-aware taint-site matcher (#2083 M3 U2, plan KTD7).
+ *
+ * Classifies a function's harvested {@link SiteRecord}s against a registered
+ * {@link SourceSinkSanitizerSpec}: which member reads are SOURCES, which
+ * call/new sites are SINKS (and at which argument positions), and which are
+ * SANITIZERS. Pure main-thread data work — sites + bindings come from the U1
+ * worker harvest, imports from `ParsedFile.parsedImports`; no AST, no I/O.
+ *
+ * PRECONDITION: the caller must gate the CFG through `hasTaintSafeSites`
+ * (taint/site-safety.ts) first — this module dereferences binding/site
+ * indices without re-validating them.
+ *
+ * ## Callee resolution precedence (bare and member-rooted calls)
+ *
+ * 1. ESM import join — the callee root's local name is resolved through the
+ *    {@link TaintImportIndex} built from `parsedImports` (`named`/`alias`
+ *    members, `namespace`/default-import module handles); `import { exec as
+ *    run } from 'child_process'` makes `run(c)` resolve to
+ *    `child_process.exec`, and `import * as cp …` makes `cp.exec(c)` resolve
+ *    the same way.
+ * 2. require-literal join — a binding whose in-function defining site carries
+ *    `requireArg` resolves like a namespace handle (`const cp =
+ *    require('child_process'); cp.exec(c)`). A BARE call of a require-joined
+ *    binding is matched under BOTH interpretations, `<module>.default` (the
+ *    module/default export invoked directly) and `<module>.<localName>`
+ *    (non-renamed destructured require — the harvest attaches `resultDefs`
+ *    to destructured bindings without recording the property path, and the
+ *    binding name IS the member name in the non-renamed case).
+ * 3. Bare-name fallback — TRUE GLOBALS only (`global: true` entries: `eval`,
+ *    `new Function`, `encodeURIComponent`), and only when the name is neither
+ *    import-bound nor shadowed. Conventional receiver names (`req`/`request`
+ *    member-read sources, `res.send`, `.query`/`.execute`) are matched
+ *    name-based by their own mechanisms, never via the global fallback.
+ *
+ * ## Shadowing rule (exact)
+ *
+ * A name is treated as function-local — blocking import/global resolution —
+ * iff the function's binding table contains a NON-`synthetic` entry with that
+ * name (an in-function `function exec(){}` / `const exec = …`). Synthetic
+ * bindings (kind `module`, `synthetic: true`) are imports, true globals, or
+ * enclosing-scope captures and do not shadow. Member-call roots use the
+ * harvested `receiver` binding index directly (no name scan).
+ *
+ * ## Documented resolution gaps (direction stated, per plan KTD10)
+ *
+ * - MODULE-LEVEL `const cp = require('child_process')`: the binding is
+ *   synthetic inside the function, produces no `ParsedImport`, and its
+ *   defining site lives outside the function's harvested sites — the
+ *   require join cannot see it. Module-mechanism sinks miss (FN) and
+ *   sanitizers don't kill (FP noise — never a false kill, the safe
+ *   direction). Only in-function requires resolve.
+ * - RENAMED destructured require (`const { exec: run } = require(…)`):
+ *   the dual interpretation resolves `run` to `child_process.run` — no
+ *   match (FN). Non-renamed destructures resolve exactly.
+ * - CONSERVATIVE shadow scan for bare calls: ANY non-synthetic binding of
+ *   the callee name anywhere in the function blocks import/global
+ *   resolution, even when the shadow is block-scoped elsewhere and the call
+ *   site actually sees the import (FN; rare; safe for sanitizers).
+ * - MODULE-LEVEL user declarations are indistinguishable from imports in
+ *   the binding table (both synthetic). ESM forbids a module-level
+ *   declaration colliding with an import name, so the import join is
+ *   authoritative when an import exists; a module-level user function
+ *   shadowing a TRUE GLOBAL (e.g. a local `encodeURIComponent`) is not
+ *   detectable and would still match (pathological; accepted).
+ * - Handle COPIES (`const c2 = cp; c2.exec(…)`) are not followed — joins
+ *   are one level deep (binding → import/require), never through
+ *   assignments (FN).
+ * - `this.`/`super.`-rooted and call-rooted callee chains have no
+ *   resolvable root: only the syntactic `anyReceiver`/`receivers`
+ *   mechanisms can match them.
+ * - `reexport`/`wildcard`/`dynamic-*`/`side-effect` imports introduce no
+ *   matcher-visible local binding and are skipped by the index.
+ */
+import type { ParsedImport } from '../../../_shared/index.js';
+import type { FunctionCfg } from '../cfg/types.js';
+import type { SourceSinkSanitizerSpec, TaintMemberSourceEntry, TaintSanitizerEntry, TaintSinkEntry } from './source-sink-config.js';
+/** What a local name imported into the file denotes. */
+export interface TaintImportBinding {
+    /** Normalized module specifier (`node:` scheme stripped). */
+    readonly module: string;
+    /**
+     * Exported member bound by a named/aliased import; `undefined` when the
+     * local name is a MODULE HANDLE (namespace import, or a default import —
+     * CJS interop makes the default export ≈ the module object).
+     */
+    readonly member?: string;
+}
+/** Local name → import provenance for one file. Build once per file (U4). */
+export type TaintImportIndex = ReadonlyMap<string, TaintImportBinding>;
+/** A member-read site matched as a taint source. */
+export interface MatchedSourceRead {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintMemberSourceEntry;
+}
+/** A call/new site matched as a sink. */
+export interface MatchedSinkCall {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintSinkEntry;
+    /**
+     * Positions (indices into `site.args`) that are registered sink positions
+     * AND carry at least one recorded binding occurrence, after the spread
+     * rule (a recorded position ≥ `site.spread` matches when any registered
+     * position ≥ the spread index exists — runtime positions after a spread
+     * are unknowable) and the template rule (`template: true` aggregates all
+     * substitutions at position 0 and matches any-position). Never empty — a
+     * sink whose dangerous positions carry no occurrences cannot produce a
+     * finding and is not reported.
+     */
+    readonly argPositions: readonly number[];
+}
+/** A call site matched as a sanitizer (import-aware/global only — see module doc). */
+export interface MatchedSanitizerCall {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintSanitizerEntry;
+    /**
+     * Bindings the sanitizer's result defines directly (`const b = escape(t)`
+     * ⇒ `b`) — U3's kill targets (KTD4b). Empty for value-position sanitizer
+     * calls (`exec(escape(x))`), whose effect is occurrence INTERPOSITION via
+     * the site's `parent`/via-tag chain, not a def kill.
+     */
+    readonly resultDefs: readonly number[];
+}
+/** All matches within one statement. Emitted only when at least one list is non-empty. */
+export interface StatementMatches {
+    readonly blockIndex: number;
+    readonly statementIndex: number;
+    readonly line: number;
+    readonly sources: readonly MatchedSourceRead[];
+    readonly sinks: readonly MatchedSinkCall[];
+    readonly sanitizers: readonly MatchedSanitizerCall[];
+}
+/** Classified sites for one function, in (block, statement, site, entry) order. */
+export interface FunctionSiteMatches {
+    readonly statements: readonly StatementMatches[];
+    /** Fast-path gates for U4: the solver runs only when both are true. */
+    readonly hasSource: boolean;
+    readonly hasSink: boolean;
+}
+/**
+ * Build the local-name → module/member index from a file's `parsedImports`.
+ * Only `named`/`alias`/`namespace` kinds bind matcher-visible local names;
+ * `importedName === 'default'` collapses to a module handle.
+ */
+export declare function buildTaintImportIndex(imports: readonly ParsedImport[]): TaintImportIndex;
+/**
+ * Classify a function's harvested sites against a language spec. See the
+ * module doc for resolution precedence, the shadowing rule, and gaps.
+ */
+export declare function matchFunctionSites(cfg: FunctionCfg, spec: SourceSinkSanitizerSpec, imports: TaintImportIndex): FunctionSiteMatches;

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

@@ -0,0 +1,278 @@
+/**
+ * Import-aware taint-site matcher (#2083 M3 U2, plan KTD7).
+ *
+ * Classifies a function's harvested {@link SiteRecord}s against a registered
+ * {@link SourceSinkSanitizerSpec}: which member reads are SOURCES, which
+ * call/new sites are SINKS (and at which argument positions), and which are
+ * SANITIZERS. Pure main-thread data work — sites + bindings come from the U1
+ * worker harvest, imports from `ParsedFile.parsedImports`; no AST, no I/O.
+ *
+ * PRECONDITION: the caller must gate the CFG through `hasTaintSafeSites`
+ * (taint/site-safety.ts) first — this module dereferences binding/site
+ * indices without re-validating them.
+ *
+ * ## Callee resolution precedence (bare and member-rooted calls)
+ *
+ * 1. ESM import join — the callee root's local name is resolved through the
+ *    {@link TaintImportIndex} built from `parsedImports` (`named`/`alias`
+ *    members, `namespace`/default-import module handles); `import { exec as
+ *    run } from 'child_process'` makes `run(c)` resolve to
+ *    `child_process.exec`, and `import * as cp …` makes `cp.exec(c)` resolve
+ *    the same way.
+ * 2. require-literal join — a binding whose in-function defining site carries
+ *    `requireArg` resolves like a namespace handle (`const cp =
+ *    require('child_process'); cp.exec(c)`). A BARE call of a require-joined
+ *    binding is matched under BOTH interpretations, `<module>.default` (the
+ *    module/default export invoked directly) and `<module>.<localName>`
+ *    (non-renamed destructured require — the harvest attaches `resultDefs`
+ *    to destructured bindings without recording the property path, and the
+ *    binding name IS the member name in the non-renamed case).
+ * 3. Bare-name fallback — TRUE GLOBALS only (`global: true` entries: `eval`,
+ *    `new Function`, `encodeURIComponent`), and only when the name is neither
+ *    import-bound nor shadowed. Conventional receiver names (`req`/`request`
+ *    member-read sources, `res.send`, `.query`/`.execute`) are matched
+ *    name-based by their own mechanisms, never via the global fallback.
+ *
+ * ## Shadowing rule (exact)
+ *
+ * A name is treated as function-local — blocking import/global resolution —
+ * iff the function's binding table contains a NON-`synthetic` entry with that
+ * name (an in-function `function exec(){}` / `const exec = …`). Synthetic
+ * bindings (kind `module`, `synthetic: true`) are imports, true globals, or
+ * enclosing-scope captures and do not shadow. Member-call roots use the
+ * harvested `receiver` binding index directly (no name scan).
+ *
+ * ## Documented resolution gaps (direction stated, per plan KTD10)
+ *
+ * - MODULE-LEVEL `const cp = require('child_process')`: the binding is
+ *   synthetic inside the function, produces no `ParsedImport`, and its
+ *   defining site lives outside the function's harvested sites — the
+ *   require join cannot see it. Module-mechanism sinks miss (FN) and
+ *   sanitizers don't kill (FP noise — never a false kill, the safe
+ *   direction). Only in-function requires resolve.
+ * - RENAMED destructured require (`const { exec: run } = require(…)`):
+ *   the dual interpretation resolves `run` to `child_process.run` — no
+ *   match (FN). Non-renamed destructures resolve exactly.
+ * - CONSERVATIVE shadow scan for bare calls: ANY non-synthetic binding of
+ *   the callee name anywhere in the function blocks import/global
+ *   resolution, even when the shadow is block-scoped elsewhere and the call
+ *   site actually sees the import (FN; rare; safe for sanitizers).
+ * - MODULE-LEVEL user declarations are indistinguishable from imports in
+ *   the binding table (both synthetic). ESM forbids a module-level
+ *   declaration colliding with an import name, so the import join is
+ *   authoritative when an import exists; a module-level user function
+ *   shadowing a TRUE GLOBAL (e.g. a local `encodeURIComponent`) is not
+ *   detectable and would still match (pathological; accepted).
+ * - Handle COPIES (`const c2 = cp; c2.exec(…)`) are not followed — joins
+ *   are one level deep (binding → import/require), never through
+ *   assignments (FN).
+ * - `this.`/`super.`-rooted and call-rooted callee chains have no
+ *   resolvable root: only the syntactic `anyReceiver`/`receivers`
+ *   mechanisms can match them.
+ * - `reexport`/`wildcard`/`dynamic-*`/`side-effect` imports introduce no
+ *   matcher-visible local binding and are skipped by the index.
+ */
+const stripNodeScheme = (specifier) => specifier.startsWith('node:') ? specifier.slice('node:'.length) : specifier;
+/**
+ * Build the local-name → module/member index from a file's `parsedImports`.
+ * Only `named`/`alias`/`namespace` kinds bind matcher-visible local names;
+ * `importedName === 'default'` collapses to a module handle.
+ */
+export function buildTaintImportIndex(imports) {
+    const index = new Map();
+    for (const imp of imports) {
+        if (imp.kind === 'named' || imp.kind === 'alias') {
+            const module = stripNodeScheme(imp.targetRaw);
+            index.set(imp.localName, imp.importedName === 'default' ? { module } : { module, member: imp.importedName });
+        }
+        else if (imp.kind === 'namespace') {
+            index.set(imp.localName, { module: stripNodeScheme(imp.targetRaw) });
+        }
+    }
+    return index;
+}
+/**
+ * Classify a function's harvested sites against a language spec. See the
+ * module doc for resolution precedence, the shadowing rule, and gaps.
+ */
+export function matchFunctionSites(cfg, spec, imports) {
+    const bindings = cfg.bindings ?? [];
+    // Non-synthetic (in-function-declared) binding indices by name — the
+    // shadow scan + bare-call require-join lookup.
+    const nonSyntheticByName = new Map();
+    bindings.forEach((b, i) => {
+        if (b.synthetic === true)
+            return;
+        const list = nonSyntheticByName.get(b.name);
+        if (list)
+            list.push(i);
+        else
+            nonSyntheticByName.set(b.name, [i]);
+    });
+    // require-literal join: binding index → module specifier. A binding def'd
+    // by two DIFFERENT require literals is conflicted → dropped (resolving it
+    // either way could fabricate a sanitizer kill).
+    const requireByBinding = new Map();
+    const conflicted = new Set();
+    for (const block of cfg.blocks) {
+        for (const stmt of block.statements ?? []) {
+            for (const site of stmt.sites ?? []) {
+                if (site.requireArg === undefined || site.resultDefs === undefined)
+                    continue;
+                const module = stripNodeScheme(site.requireArg);
+                for (const def of site.resultDefs) {
+                    if (conflicted.has(def))
+                        continue;
+                    const prior = requireByBinding.get(def);
+                    if (prior === undefined)
+                        requireByBinding.set(def, module);
+                    else if (prior !== module) {
+                        requireByBinding.delete(def);
+                        conflicted.add(def);
+                    }
+                }
+            }
+        }
+    }
+    const resolveCallee = (site) => {
+        if (site.callee === undefined)
+            return undefined;
+        const path = site.callee.split('.');
+        const root = path[0];
+        const rest = path.slice(1);
+        const canonical = [];
+        let globalRoot = false;
+        if (site.receiver !== undefined) {
+            // Member chain with an identifier root — origin known by binding index.
+            const rb = bindings[site.receiver];
+            if (rb.synthetic === true) {
+                const imp = imports.get(rb.name);
+                if (imp !== undefined) {
+                    const base = imp.member === undefined ? [imp.module] : [imp.module, imp.member];
+                    canonical.push([...base, ...rest].join('.'));
+                }
+            }
+            else {
+                const module = requireByBinding.get(site.receiver);
+                if (module !== undefined)
+                    canonical.push([module, ...rest].join('.'));
+            }
+        }
+        else if (path.length === 1) {
+            // Bare call. `this`/`super`/call-rooted chains never get here (those
+            // are dotted-without-receiver or callee-less).
+            const locals = nonSyntheticByName.get(root);
+            if (locals !== undefined) {
+                // Shadowed by an in-function declaration — only the require join
+                // applies, under the dual interpretation (module doc).
+                for (const idx of locals) {
+                    const module = requireByBinding.get(idx);
+                    if (module !== undefined)
+                        canonical.push(`${module}.default`, `${module}.${root}`);
+                }
+            }
+            else {
+                const imp = imports.get(root);
+                if (imp !== undefined) {
+                    canonical.push(imp.member === undefined ? `${imp.module}.default` : `${imp.module}.${imp.member}`);
+                }
+                else {
+                    globalRoot = true;
+                }
+            }
+        }
+        return { path, canonical, globalRoot };
+    };
+    /** The spread/template/registered-position rule (see MatchedSinkCall doc). */
+    const positionMatches = (entry, site, p) => {
+        if (site.template === true)
+            return true;
+        if (entry.args === undefined)
+            return true;
+        if (site.spread !== undefined && p >= site.spread) {
+            const spread = site.spread;
+            return entry.args.some((q) => q >= spread);
+        }
+        return entry.args.includes(p);
+    };
+    const sinkMechanismHit = (entry, site, r) => {
+        if (entry.module !== undefined)
+            return r.canonical.includes(`${entry.module}.${entry.name}`);
+        if (entry.global === true) {
+            return (r.globalRoot &&
+                r.path.length === 1 &&
+                r.path[0] === entry.name &&
+                (entry.newOnly !== true || site.kind === 'new'));
+        }
+        if (entry.anyReceiver === true) {
+            return r.path.length >= 2 && r.path[r.path.length - 1] === entry.name;
+        }
+        if (entry.receivers !== undefined) {
+            return r.path.length === 2 && entry.receivers.includes(r.path[0]) && r.path[1] === entry.name;
+        }
+        return false;
+    };
+    // Sanitizers: module + global mechanisms ONLY — never receiver-conventional,
+    // never bare-name for non-globals (a false kill is the forbidden direction).
+    const sanitizerMechanismHit = (entry, r) => {
+        if (entry.module !== undefined)
+            return r.canonical.includes(`${entry.module}.${entry.name}`);
+        if (entry.global === true) {
+            return r.globalRoot && r.path.length === 1 && r.path[0] === entry.name;
+        }
+        return false;
+    };
+    const statements = [];
+    let hasSource = false;
+    let hasSink = false;
+    cfg.blocks.forEach((block, blockIndex) => {
+        block.statements?.forEach((stmt, statementIndex) => {
+            const sites = stmt.sites;
+            if (sites === undefined || sites.length === 0)
+                return;
+            const sources = [];
+            const sinks = [];
+            const sanitizers = [];
+            sites.forEach((site, siteIndex) => {
+                if (site.kind === 'member-read') {
+                    if (site.object === undefined || site.property === undefined)
+                        return;
+                    const objectName = bindings[site.object].name;
+                    const property = site.property;
+                    for (const entry of spec.sources) {
+                        if (entry.objects.includes(objectName) && entry.properties.includes(property)) {
+                            sources.push({ siteIndex, entry });
+                        }
+                    }
+                    return;
+                }
+                // call / new
+                const resolved = resolveCallee(site);
+                if (resolved === undefined)
+                    return;
+                for (const entry of spec.sinks) {
+                    if (!sinkMechanismHit(entry, site, resolved))
+                        continue;
+                    const argPositions = [];
+                    site.args?.forEach((occurrences, p) => {
+                        if (occurrences.length > 0 && positionMatches(entry, site, p))
+                            argPositions.push(p);
+                    });
+                    if (argPositions.length > 0)
+                        sinks.push({ siteIndex, entry, argPositions });
+                }
+                for (const entry of spec.sanitizers) {
+                    if (!sanitizerMechanismHit(entry, resolved))
+                        continue;
+                    sanitizers.push({ siteIndex, entry, resultDefs: site.resultDefs ?? [] });
+                }
+            });
+            if (sources.length === 0 && sinks.length === 0 && sanitizers.length === 0)
+                return;
+            hasSource ||= sources.length > 0;
+            hasSink ||= sinks.length > 0;
+            statements.push({ blockIndex, statementIndex, line: stmt.line, sources, sinks, sanitizers });
+        });
+    });
+    return { statements, hasSource, hasSink };
+}