gitnexus 1.6.8-rc.8 → 1.6.8

package/dist/core/ingestion/cfg/reaching-defs-graph.js

@@ -0,0 +1,312 @@
+/**
+ * Pure graph sub-stages for the reaching-definitions solvers (#2201 review R4).
+ *
+ * Extracted from reaching-defs.ts to keep that module focused on the
+ * orchestrator, the dense oracle, the statement sweep, and the dispatcher.
+ * Everything here is a pure function of plain arrays — no CFG, no harvest, no
+ * solver state — so this module has NO dependency on reaching-defs.ts (a strict
+ * one-way import) and each stage is independently testable. The SSA pipeline
+ * (dominators → dominance frontiers → Tarjan SCC → reach-set condensation)
+ * implements Cooper-Harvey-Kennedy + Cytron + Tarjan; reverse-post-order, the
+ * loop-reachability check, and the def-set/lattice primitives are shared with
+ * the dense GEN/KILL solver and the dispatcher.
+ *
+ * These are held byte-identical to their former inline form by the differential
+ * equivalence fuzz (test/unit/cfg/reaching-defs-equivalence.test.ts) — any diff
+ * after extraction is an extraction bug, never the oracle.
+ */
+/**
+ * RPO over blocks reachable from `entry`; unreachable blocks appended by index.
+ * Returns the order AND the reachability bitmap the DFS already computed, so a
+ * caller needing "is every block reachable?" reuses this pass instead of a
+ * separate BFS (#2201 review R8 — the SSA path's reachability gate).
+ *
+ * @internal
+ */
+export function reversePostOrder(entry, succs, n) {
+    const visited = new Array(n).fill(false);
+    const post = [];
+    // Iterative DFS with an explicit phase stack (children pushed in reverse so
+    // they pop in sorted order — determinism).
+    const stack = [{ node: entry, childIdx: 0 }];
+    visited[entry] = true;
+    while (stack.length) {
+        const top = stack[stack.length - 1];
+        const children = succs[top.node];
+        if (top.childIdx < children.length) {
+            const next = children[top.childIdx];
+            top.childIdx += 1;
+            if (!visited[next]) {
+                visited[next] = true;
+                stack.push({ node: next, childIdx: 0 });
+            }
+        }
+        else {
+            post.push(top.node);
+            stack.pop();
+        }
+    }
+    const order = post.reverse();
+    for (let b = 0; b < n; b++)
+        if (!visited[b])
+            order.push(b);
+    return { order, visited };
+}
+/**
+ * Immediate dominators (Cooper-Harvey-Kennedy; correct on irreducible CFGs).
+ * `rpo` is the reverse-post-order rooted at the synthetic start `S`, `dPredsX`
+ * the dominator-graph predecessors (incl. S→entry). Returns idom[b] for every
+ * node in [0, nx); idom[S] === S.
+ *
+ * @internal
+ */
+export function buildDominators(rpo, dPredsX, S, nx) {
+    const rpoIdx = new Array(nx);
+    rpo.forEach((b, i) => (rpoIdx[b] = i));
+    const idom = new Array(nx).fill(-1);
+    idom[S] = S;
+    const intersect = (a, b) => {
+        while (a !== b) {
+            while (rpoIdx[a] > rpoIdx[b])
+                a = idom[a];
+            while (rpoIdx[b] > rpoIdx[a])
+                b = idom[b];
+        }
+        return a;
+    };
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const b of rpo) {
+            if (b === S)
+                continue;
+            let nd = -1;
+            for (const p of dPredsX[b])
+                if (idom[p] !== -1)
+                    nd = nd === -1 ? p : intersect(nd, p);
+            if (nd !== -1 && idom[b] !== nd) {
+                idom[b] = nd;
+                changed = true;
+            }
+        }
+    }
+    return idom;
+}
+/**
+ * Dominance frontiers (Cytron). df[b] is the set of nodes where b's dominance
+ * ends — the φ-placement targets for any binding defined in b.
+ *
+ * @internal
+ */
+export function buildDominanceFrontiers(dPredsX, idom, nx) {
+    const df = Array.from({ length: nx }, () => new Set());
+    for (let b = 0; b < nx; b++) {
+        const dp = dPredsX[b];
+        if (dp.length < 2)
+            continue;
+        for (const p of dp) {
+            let runner = p;
+            while (runner !== idom[b] && runner !== -1) {
+                df[runner].add(b);
+                runner = idom[runner];
+            }
+        }
+    }
+    return df;
+}
+/**
+ * Tarjan strongly-connected components over the value-graph operand edges
+ * (`nodeOps[node]` = operand node ids). Iterative (explicit work stack — the
+ * graph can be deep). SCCs are emitted in REVERSE topological order, so an
+ * SCC's operand SCCs are numbered before it — the property
+ * {@link condenseReachingSets} relies on for its single forward pass.
+ *
+ * @internal
+ */
+export function tarjanScc(nodeOps) {
+    const N = nodeOps.length;
+    const sccOf = new Array(N).fill(-1);
+    const sccMembers = [];
+    const index = new Array(N).fill(-1);
+    const low = new Array(N).fill(0);
+    const onStk = new Array(N).fill(false);
+    const tarjanStk = [];
+    let counter = 0;
+    for (let start = 0; start < N; start++) {
+        if (index[start] !== -1)
+            continue;
+        const work = [{ node: start, oi: 0 }];
+        index[start] = low[start] = counter++;
+        tarjanStk.push(start);
+        onStk[start] = true;
+        while (work.length) {
+            const top = work[work.length - 1];
+            const ops = nodeOps[top.node];
+            if (top.oi < ops.length) {
+                const w = ops[top.oi++];
+                if (index[w] === -1) {
+                    index[w] = low[w] = counter++;
+                    tarjanStk.push(w);
+                    onStk[w] = true;
+                    work.push({ node: w, oi: 0 });
+                }
+                else if (onStk[w] && index[w] < low[top.node]) {
+                    low[top.node] = index[w];
+                }
+            }
+            else {
+                if (low[top.node] === index[top.node]) {
+                    const members = [];
+                    let w;
+                    do {
+                        w = tarjanStk.pop();
+                        onStk[w] = false;
+                        sccOf[w] = sccMembers.length;
+                        members.push(w);
+                    } while (w !== top.node);
+                    sccMembers.push(members);
+                }
+                work.pop();
+                if (work.length) {
+                    const par = work[work.length - 1].node;
+                    if (low[top.node] < low[par])
+                        low[par] = low[top.node];
+                }
+            }
+        }
+    }
+    return { sccOf, sccMembers };
+}
+/**
+ * Reaching def-key set per SCC via condensation (cycle-safe union). Tarjan emits
+ * SCCs in reverse topological order, so a single forward pass over SCCs resolves
+ * every union: an SCC's reaching set is its members' own leaf keys plus the
+ * already-computed reaching sets of its cross-SCC operands.
+ *
+ * Alias fast path (#2201 review R2): an SCC with NO own leaf keys whose cross-SCC
+ * operands all resolve to a SINGLE source SCC has exactly that source's reaching
+ * set — share it BY REFERENCE instead of copying element-by-element (the O(defs²)
+ * cost at wide-fan-in φ merges). Safe: the returned sets are read-only after this
+ * pass, and contents are identical (set iteration order is irrelevant — the
+ * sweep sorts each use's keys before emission, KTD6).
+ *
+ * @internal
+ */
+export function condenseReachingSets(sccMembers, sccOf, nodeKeys, nodeOps) {
+    const reachByScc = new Array(sccMembers.length);
+    for (let s = 0; s < sccMembers.length; s++) {
+        const members = sccMembers[s];
+        let aliasTarget = -1; // the unique cross-SCC source SCC, or -1 if none/many
+        let hasOwnKeys = false;
+        let multiSource = false;
+        for (const node of members) {
+            if (nodeKeys[node]) {
+                hasOwnKeys = true;
+                break;
+            }
+            for (const w of nodeOps[node]) {
+                const ws = sccOf[w];
+                if (ws === s)
+                    continue; // intra-SCC operand: same set being built, adds nothing
+                if (aliasTarget === -1)
+                    aliasTarget = ws;
+                else if (aliasTarget !== ws) {
+                    multiSource = true;
+                    break;
+                }
+            }
+            if (multiSource)
+                break;
+        }
+        if (!hasOwnKeys && !multiSource && aliasTarget !== -1) {
+            reachByScc[s] = reachByScc[aliasTarget]; // zero-copy share
+            continue;
+        }
+        // General case: union own leaf keys + every distinct cross-SCC operand set.
+        const set = new Set();
+        for (const node of members) {
+            const keys = nodeKeys[node];
+            if (keys)
+                for (const k of keys)
+                    set.add(k);
+            for (const w of nodeOps[node]) {
+                const ws = sccOf[w];
+                if (ws !== s)
+                    for (const k of reachByScc[ws])
+                        set.add(k);
+            }
+        }
+        reachByScc[s] = set;
+    }
+    return reachByScc;
+}
+/**
+ * True iff a cycle is reachable from `entry` (the CFG has a loop). Iterative DFS
+ * with a gray/black coloring; a gray successor is a back-edge. O(V+E). Used by
+ * the production dispatcher to decide SSA-vs-dense.
+ *
+ * @internal
+ */
+export function hasReachableLoop(entry, succs, n) {
+    const color = new Uint8Array(n); // 0 white, 1 gray, 2 black
+    const stack = [{ node: entry, i: 0 }];
+    color[entry] = 1;
+    while (stack.length) {
+        const top = stack[stack.length - 1];
+        const ss = succs[top.node];
+        if (top.i < ss.length) {
+            const next = ss[top.i++];
+            if (color[next] === 1)
+                return true;
+            if (color[next] === 0) {
+                color[next] = 1;
+                stack.push({ node: next, i: 0 });
+            }
+        }
+        else {
+            color[top.node] = 2;
+            stack.pop();
+        }
+    }
+    return false;
+}
+/**
+ * Order-stable union of two def-sets (shares `a` when `b` adds nothing).
+ *
+ * @internal
+ */
+export function unionSets(a, b) {
+    let target = a;
+    let copied = false;
+    for (const key of b) {
+        if (!target.has(key)) {
+            if (!copied) {
+                target = new Set(a);
+                copied = true;
+            }
+            target.add(key);
+        }
+    }
+    return target;
+}
+/**
+ * Per-binding lattice equality with a reference fast path (sets only ever grow).
+ *
+ * @internal
+ */
+export function latticeEquals(a, b) {
+    if (a === b)
+        return true;
+    if (a.size !== b.size)
+        return false;
+    for (const [k, bSet] of b) {
+        const aSet = a.get(k);
+        if (aSet === bSet)
+            continue;
+        if (!aSet || aSet.size !== bSet.size)
+            return false;
+        for (const v of bSet)
+            if (!aSet.has(v))
+                return false;
+    }
+    return true;
+}

package/dist/core/ingestion/cfg/reaching-defs.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Reaching definitions (#2082 M2 U3, SSA-sparse rewrite #2201) — per-function
+ * intraprocedural may-reaching-definitions, plus the canonical intra-block
+ * statement sweep that recovers statement-granular def→use facts from M1's
+ * coalesced blocks WITHOUT re-splitting the CFG.
+ *
+ * ARCHITECTURE (#2201): the analysis is split into solver-INDEPENDENT stages
+ * (shared by every path, so the byte-identical surface is maximal) and a
+ * swappable IN-set computation:
+ *   - {@link harvestStatementFacts} — per-block GEN/allDefs + def/use telemetry.
+ *   - {@link buildAdjacency} — throw-aware predecessor/successor adjacency.
+ *   - the IN-set computer — answers block-entry reaching-set queries. Two
+ *     implementations: {@link computeInSetsSparse} (SSA — CHK dominators →
+ *     Cytron dominance frontiers + φ-placement → stack renaming over a
+ *     synthetic entry, walked SCC-condensed) and {@link computeInSetsDense}
+ *     (the original GEN/KILL worklist). Production runs {@link
+ *     computeInSetsAuto}, which picks the SSA solver for looping functions large
+ *     enough to amortize construction (where it is asymptotically faster and
+ *     never hits the dense ceiling) and the dense worklist everywhere else; the
+ *     dense path also serves the throw-edge / unreachable-block cases the SSA
+ *     path does not model. The two are held byte-identical by the equivalence
+ *     fuzz — only set CONTENTS must match (the sweep sorts each use's keys
+ *     before the maxFacts cutoff, so iteration order is irrelevant).
+ *   - {@link sweepFacts} — statement sweep + sort + maxFacts truncation.
+ *
+ * PURE AND DETERMINISTIC (load-bearing contract):
+ *  - Pure function of its inputs — no graph, no logger (warnings are the
+ *    caller's job), importable outside the worker. The M3 taint engine calls
+ *    this same function in-phase (facts are recomputed on demand, never
+ *    retained run-wide — the persisted REACHING_DEF edges are a bounded
+ *    projection, never the taint substrate).
+ *  - Deterministic — predecessors merge in sorted block-index order,
+ *    insertion-ordered Maps/Sets throughout, and the output fact array is
+ *    explicitly sorted. Snapshot tests and content-derived edge ids rely on it.
+ *
+ * COMPLEXITY DISCIPLINE: def-sets are SHARED BY REFERENCE, never deep-copied —
+ * a MUST def's kill is total per binding, so a transfer either aliases the
+ * incoming set or replaces it; a MAY def (conditional context — see
+ * StatementFacts.mayDefs) unions WITHOUT killing via a copy-on-extend.
+ *
+ * `limits.maxFacts` bounds materialization: facts are O(defs×uses) BY SPEC in
+ * merge-heavy code (N branch-arm defs × N later uses = N² facts), and a
+ * 2000-line function can spike 100k+ fact objects on the main thread. The
+ * emit path passes DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION (emit.ts);
+ * M3 passes its own large-but-finite limit and treats `status: 'truncated'`
+ * as a per-function taint-coverage gap.
+ */
+import type { BindingEntry, FunctionCfg } from './types.js';
+/** A statement-granular program point within one function's CFG. */
+export interface ProgramPoint {
+    readonly blockIndex: number;
+    /** Statement index within the block's `statements` array. */
+    readonly stmtIndex: number;
+    readonly line: number;
+}
+/**
+ * Canonical `block:stmt` string key for a program point. Colon-separated to
+ * match the codebase's `blockIndex:stmtIndex` id conventions. Shared by the
+ * taint propagation engine (dedup/state keys) and the taint emit path
+ * (persisted edge-id material) so the two never drift.
+ */
+export declare function pointKey(p: ProgramPoint): string;
+/** One def→use fact: the definition at `def` reaches the use at `use`. */
+export interface DefUseFact {
+    /** Index into {@link FunctionDefUse.bindings}. */
+    readonly bindingIdx: number;
+    readonly def: ProgramPoint;
+    readonly use: ProgramPoint;
+}
+export interface ReachingDefsLimits {
+    /**
+     * Maximum number of facts to materialize; the sweep stops early and reports
+     * `status: 'truncated'`. `undefined`/0 ⇒ unlimited.
+     */
+    readonly maxFacts?: number;
+    /**
+     * Adversarial-only safety bound on the DENSE worklist's iteration.
+     *
+     * The dense GEN/KILL solver reads this as a ceiling on total block dequeues:
+     * iterative reaching-defs on a reducible CFG converges in O(loop-nesting-depth)
+     * passes, but a pathologically deep loop nest drives the visit total — and thus
+     * the solver — to O(blocks²), seconds + GB of heap (`maxFacts` does not help:
+     * fact count stays linear). Exceeding the budget means the fixpoint has NOT
+     * converged, so any facts would be unsound — the dense solver bails to a sound
+     * empty `status: 'truncated'` (like the `overflow` guard).
+     *
+     * The SSA solver (#2201) has NO fixpoint iteration — it answers reaching
+     * queries from the def-use graph in one pass — so it always converges and this
+     * budget never trips it. The production dispatcher ({@link computeInSetsAuto})
+     * routes the deep nests that would breach the dense ceiling to the SSA solver,
+     * which computes their full facts: the ceiling that fired on the dense worklist
+     * effectively never fires on real code (#2201 acceptance). The budget is still
+     * honored on the dense fallback path (small / loop-free functions, and the
+     * throw-edge / unreachable-block cases the SSA path does not model).
+     *
+     * `undefined`/0 ⇒ unlimited (the default for direct callers; the emit path sets
+     * a per-function budget).
+     */
+    readonly maxBlockVisits?: number;
+    /**
+     * Memory bound on the SSA-sparse solver's value-graph construction (#2201
+     * review R1). `maxFacts` bounds fact MATERIALIZATION (sweepFacts) but nothing
+     * bounds the φ/value-graph the sparse path builds first; a high-binding-density
+     * deep loop routed to SSA (≥ SSA_MIN_BLOCKS blocks + a reachable loop) builds an
+     * O(blocks×bindings) graph the dense path would have truncated at the
+     * `maxBlockVisits` ceiling (~1.5 GB measured on a 3000-block × 300-binding
+     * function). When the projected node count would exceed this, the sparse solver
+     * falls back to the dense oracle (byte-identical, and bounded — dense honors
+     * `maxBlockVisits`). Honored ONLY by the sparse path; the dense solver ignores
+     * it. `undefined`/0 ⇒ {@link DEFAULT_MAX_SSA_VALUE_GRAPH_NODES}.
+     */
+    readonly maxSsaValueGraphNodes?: number;
+}
+export interface FunctionDefUse {
+    /**
+     * `computed`  — full facts.
+     * `no-facts`  — the CFG carries no statement facts (hand-built or pre-M2
+     *               side channel); empty facts, NOT an error.
+     * `truncated` — `limits.maxFacts` hit; `facts` is a deterministic prefix.
+     * `overflow`  — a block's statement count breaches the def-key stride; no
+     *               facts at all (computing any would risk key aliasing —
+     *               wrong-block facts are strictly worse than none). Distinct
+     *               from `truncated` so the caller's diagnostic doesn't
+     *               misname it as the fact-materialization limit.
+     */
+    readonly status: 'computed' | 'no-facts' | 'truncated' | 'overflow';
+    /** Pass-through of the CFG's binding table (empty for `no-facts`). */
+    readonly bindings: readonly BindingEntry[];
+    /** Sorted by (def block, def stmt, use block, use stmt, binding). */
+    readonly facts: readonly DefUseFact[];
+    /** Total def / use sites seen (telemetry; independent of truncation). */
+    readonly defCount: number;
+    readonly useCount: number;
+}
+/**
+ * Compute reaching definitions for one function. See the module doc for the
+ * purity/determinism/sharing contract.
+ *
+ * This is the production entry point. As of #2201 it auto-dispatches via
+ * {@link computeInSetsAuto} — the SSA-sparse solver ({@link computeInSetsSparse})
+ * for looping functions large enough to amortize construction, the dense
+ * GEN/KILL worklist ({@link computeInSetsDense}) everywhere else (and for the
+ * throw-edge / unreachable-block functions the SSA path does not model). The two
+ * solvers are held byte-identical by the equivalence fuzz (status, bindings,
+ * sorted facts, def/use telemetry), so the dispatch is a pure performance
+ * heuristic; the dense solver doubles as that differential oracle.
+ */
+export declare function computeReachingDefs(cfg: FunctionCfg, limits?: ReachingDefsLimits): FunctionDefUse;
+/** A reaching-defs solver — {@link computeReachingDefs} or a memoized wrapper. */
+export type ReachingDefsSolver = (cfg: FunctionCfg, limits?: ReachingDefsLimits) => FunctionDefUse;
+/**
+ * Per-file memoized reaching-defs solver (#2227 tri-review, U12). Under `--pdg`
+ * the SAME per-function RD fixpoint was solved 3–4× per analyze (RD emit +
+ * call-summary harvest + taint + summary harvest). Cache by (cfg identity,
+ * limits) so each DISTINCT solve runs once: the RD-emit bucket (passes
+ * `maxBlockVisits`) and the harvest/taint bucket (does not) stay byte-identical
+ * to their inline solves because the limits are part of the key. Lazy — solves
+ * on first request, so the taint zero-match fast path still skips its solve.
+ * Create one per FILE and drop it after the file to bound the per-function
+ * `facts` arrays (100k+ objects on a huge function) from going whole-repo.
+ */
+export declare function createMemoizedReachingDefs(): ReachingDefsSolver;