@holmes-lab/holmes-kit 0.3.11 → 0.4.1

package/dist/holmes/cpg/foundation/cfg.js

@@ -0,0 +1,617 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CFG_LANGUAGES = exports.FUNCTION_TYPES = void 0;
+exports.childrenIndex = childrenIndex;
+exports.functionsIn = functionsIn;
+exports.cfgOf = cfgOf;
+exports.domViolations = domViolations;
+exports.FUNCTION_TYPES = new Set([
+    'function_declaration', 'generator_function_declaration', 'function_expression',
+    'generator_function', 'arrow_function', 'method_definition', 'function',
+    // @implements A-SPEC-510.7 — Python's function node joins the same census.
+    'function_definition', 'lambda',
+]);
+const TS_SIMPLE = new Set([
+    'expression_statement', 'lexical_declaration', 'variable_declaration', 'debugger_statement',
+    'empty_statement', 'function_declaration', 'generator_function_declaration', 'class_declaration',
+    'import_statement', 'export_statement', 'type_alias_declaration', 'interface_declaration',
+    'enum_declaration', 'abstract_class_declaration', 'ambient_declaration',
+]);
+const TS_RULES = {
+    simple: TS_SIMPLE,
+    handled: new Set([
+        ...TS_SIMPLE,
+        'statement_block', 'if_statement', 'while_statement', 'do_statement', 'for_statement',
+        'for_in_statement', 'switch_statement', 'break_statement', 'continue_statement',
+        'return_statement', 'throw_statement', 'try_statement', 'labeled_statement',
+    ]),
+    block: 'statement_block',
+};
+// @implements A-SPEC-510.7 — Python. `pass`/`import`/`global` are straight-line statements;
+// `for`/`while` carry an ELSE clause with distinctive semantics (see the lowering), `match` has
+// no fallthrough, and `with` is a body wrapper whose exceptional edge the try rules cover.
+const PY_SIMPLE = new Set([
+    'expression_statement', 'pass_statement', 'import_statement', 'import_from_statement',
+    'global_statement', 'nonlocal_statement', 'assert_statement', 'delete_statement',
+    'print_statement', 'exec_statement', 'future_import_statement', 'class_definition',
+    'function_definition', 'decorated_definition',
+]);
+const PY_RULES = {
+    simple: PY_SIMPLE,
+    handled: new Set([
+        ...PY_SIMPLE,
+        'block', 'if_statement', 'elif_clause', 'while_statement', 'for_statement', 'match_statement',
+        'with_statement', 'try_statement', 'break_statement', 'continue_statement',
+        'return_statement', 'raise_statement',
+    ]),
+    block: 'block',
+};
+const LANG_RULES = {
+    typescript: TS_RULES, tsx: TS_RULES, python: PY_RULES,
+};
+// @implements A-SPEC-510.6
+/**
+ * The languages this lowering understands — DERIVED from the rule table, so the layer×language
+ * matrix and the guard below can never disagree with what is actually implemented.
+ */
+exports.CFG_LANGUAGES = new Set(Object.keys(LANG_RULES));
+/** Shared child index over the flat pre-order AST — DDG (L3) walks with the same truth. */
+function childrenIndex(ast) {
+    const kids = ast.nodes.map(() => []);
+    ast.nodes.forEach((n, i) => { if (n.parent >= 0)
+        kids[n.parent].push(i); });
+    return { of: (i) => kids[i] };
+}
+/** Every function-like node in the AST, with its body (statement_block or expression body). */
+function functionsIn(ast) {
+    const kids = childrenIndex(ast);
+    const out = [];
+    ast.nodes.forEach((n, i) => {
+        if (!exports.FUNCTION_TYPES.has(n.type))
+            return;
+        const ks = kids.of(i);
+        const block = ks.find((k) => ast.nodes[k].type === 'statement_block' || ast.nodes[k].type === 'block');
+        // Arrow expression bodies: the last named child that is not the parameter list / return type.
+        const body = block ?? ks.filter((k) => ast.nodes[k].named).at(-1);
+        if (body !== undefined)
+            out.push({ nodeIndex: i, bodyIndex: body });
+    });
+    return out;
+}
+class Unsupported {
+    type;
+    constructor(type) {
+        this.type = type;
+    }
+}
+/** Build the CFG of one function, or refuse the whole function honestly. */
+function cfgOf(ast, fn, source) {
+    if (!exports.CFG_LANGUAGES.has(ast.lang)) {
+        return { unsupported: `${ast.lang} (next slice)` };
+    }
+    const rules = LANG_RULES[ast.lang];
+    const isPython = ast.lang === 'python';
+    const kids = childrenIndex(ast);
+    // Points: one per lowered statement (block ids after coalescing). 0=ENTRY, 1=EXIT.
+    const stmtsOf = [[], []];
+    const edges = [];
+    const ENTRY = 0;
+    const EXIT = 1;
+    const newPoint = (astIdx) => { stmtsOf.push([astIdx]); return stmtsOf.length - 1; };
+    const link = (from, to, kind) => { edges.push({ from, to, kind }); };
+    // Label identity is TEXT: the definition and its references sit at different spans, so a
+    // span-keyed name can never match. Without source, labeled flow is honestly unsupported.
+    const labelName = (i) => {
+        if (source === undefined)
+            throw new Unsupported('labeled statement requires source');
+        return source.slice(ast.nodes[i].start, ast.nodes[i].end);
+    };
+    // A `case _:` arm, read from the SOURCE: the pattern's text is exactly `_`.
+    const wildcardText = (caseClause) => {
+        if (source === undefined)
+            return false;
+        const pat = kids.of(caseClause).find((k) => ast.nodes[k].type === 'case_pattern');
+        return pat !== undefined && source.slice(ast.nodes[pat].start, ast.nodes[pat].end).trim() === '_';
+    };
+    try {
+        const lowerSeq = (stmtIdxs, ctx) => {
+            let entry = -1;
+            let exits = [];
+            for (const s of stmtIdxs) {
+                const f = lowerStmt(s, ctx);
+                if (entry === -1)
+                    entry = f.entry;
+                for (const e of exits)
+                    link(e.from, f.entry, e.kind);
+                exits = f.exits;
+            }
+            if (entry === -1) {
+                const p = newPoint(-1);
+                return { entry: p, exits: [{ from: p, kind: 'seq' }] };
+            }
+            return { entry, exits };
+        };
+        const stmtChildren = (i) => kids.of(i).filter((k) => ast.nodes[k].named && ast.nodes[k].type !== 'comment');
+        const wireException = (first, targetProvider) => {
+            // Conservative: every point created inside [first, now) can throw into the handler.
+            const target = targetProvider();
+            for (let p = first; p < stmtsOf.length; p++)
+                link(p, target, 'exception');
+        };
+        const lowerStmt = (i, ctx) => {
+            const t = ast.nodes[i].type;
+            if (!rules.handled.has(t))
+                throw new Unsupported(t);
+            const label = ctx.pendingLabel;
+            ctx.pendingLabel = null;
+            if (rules.simple.has(t)) {
+                const p = newPoint(i);
+                return { entry: p, exits: [{ from: p, kind: 'seq' }] };
+            }
+            switch (t) {
+                case 'statement_block':
+                case 'block':
+                    return lowerSeq(stmtChildren(i), ctx);
+                case 'labeled_statement': {
+                    const [labelNode, inner] = [kids.of(i)[0], stmtChildren(i).at(-1)];
+                    ctx.pendingLabel = labelName(labelNode);
+                    return lowerStmt(inner, ctx);
+                }
+                case 'elif_clause':
+                case 'if_statement': {
+                    const p = newPoint(i);
+                    const named = stmtChildren(i);
+                    // @implements A-SPEC-510.7 — Python spells the arms as fields (`consequence`,
+                    // `alternative` = elif_clause | else_clause), TS as positional children. Reading the
+                    // fields where they exist keeps ONE lowering for both grammars.
+                    const cons = isPython ? (kids.of(i).find((k) => ast.nodes[k].type === 'block') ?? named[1]) : named[1];
+                    let alt;
+                    if (isPython) {
+                        const clause = kids.of(i).find((k) => ['elif_clause', 'else_clause'].includes(ast.nodes[k].type));
+                        if (clause !== undefined) {
+                            alt = ast.nodes[clause].type === 'elif_clause'
+                                ? clause // an elif IS a nested branch
+                                : stmtChildren(clause).find((k) => ast.nodes[k].type === 'block');
+                        }
+                    }
+                    else {
+                        alt = named[2] !== undefined ? stmtChildren(named[2])[0] : undefined;
+                    }
+                    const cf = lowerStmt(cons, ctx);
+                    link(p, cf.entry, 'true');
+                    const exits = [...cf.exits];
+                    if (alt !== undefined) {
+                        const af = lowerStmt(alt, ctx);
+                        link(p, af.entry, 'false');
+                        exits.push(...af.exits);
+                    }
+                    else {
+                        exits.push({ from: p, kind: 'false' });
+                    }
+                    return { entry: p, exits };
+                }
+                case 'while_statement':
+                case 'for_statement':
+                case 'for_in_statement': {
+                    const header = newPoint(i);
+                    // @implements A-SPEC-510.7 — Python's loop `else` runs ONLY when the loop is EXHAUSTED;
+                    // a `break` skips it. Modelling it as a plain successor (the common mistake) would claim
+                    // the else block runs on every exit. Here the false/exhaustion edge enters else, while
+                    // break edges bypass it entirely.
+                    const pyElse = isPython
+                        ? kids.of(i).filter((k) => ast.nodes[k].type === 'else_clause')
+                            .flatMap((k) => stmtChildren(k)).find((k) => ast.nodes[k].type === 'block')
+                        : undefined;
+                    const bodyIdx = isPython
+                        ? kids.of(i).filter((k) => ast.nodes[k].type === 'block').at(0)
+                        : stmtChildren(i).at(-1);
+                    const myBreak = { label, target: -1 }; // ONE owner: labeled and bare breaks share it
+                    ctx.breakT.push({ label, owner: myBreak }, { label: null, owner: myBreak });
+                    ctx.contT.push({ label, target: header }, { label: null, target: header });
+                    const bf = lowerStmt(bodyIdx, ctx);
+                    ctx.breakT.splice(-2);
+                    ctx.contT.splice(-2);
+                    link(header, bf.entry, 'true');
+                    for (const e of bf.exits)
+                        link(e.from, header, 'loop-back');
+                    const exits = [];
+                    if (pyElse !== undefined) {
+                        const ef = lowerStmt(pyElse, ctx);
+                        link(header, ef.entry, 'false'); // exhaustion path enters `else`
+                        exits.push(...ef.exits);
+                    }
+                    else {
+                        exits.push({ from: header, kind: 'false' });
+                    }
+                    // break targets resolved lazily: edges recorded with target -1 fixed by caller — instead
+                    // we collect them via the pendingBreaks list below.
+                    for (const b of claimBreaks(myBreak)) {
+                        exits.push({ from: b.point, kind: 'break' });
+                    }
+                    return { entry: header, exits };
+                }
+                case 'do_statement': {
+                    const header = newPoint(i); // condition point (the `do` node)
+                    const bodyIdx = stmtChildren(i)[0];
+                    const myBreak = { label, target: -1 };
+                    ctx.breakT.push({ label, owner: myBreak }, { label: null, owner: myBreak });
+                    ctx.contT.push({ label, target: header }, { label: null, target: header });
+                    const bf = lowerStmt(bodyIdx, ctx);
+                    ctx.breakT.splice(-2);
+                    ctx.contT.splice(-2);
+                    for (const e of bf.exits)
+                        link(e.from, header, e.kind);
+                    link(header, bf.entry, 'loop-back');
+                    const exits = [{ from: header, kind: 'false' }];
+                    for (const b of claimBreaks(myBreak)) {
+                        exits.push({ from: b.point, kind: 'break' });
+                    }
+                    return { entry: bf.entry, exits };
+                }
+                case 'match_statement': {
+                    // @implements A-SPEC-510.7 — `match` is NOT a switch: the first matching case runs and
+                    // control leaves; there is no fallthrough. Reusing the switch lowering here would invent
+                    // seq edges between cases that Python never takes.
+                    const p = newPoint(i);
+                    const body = kids.of(i).find((k) => ast.nodes[k].type === 'block');
+                    const exits = [];
+                    let sawWildcard = false;
+                    for (const c of body === undefined ? [] : kids.of(body)) {
+                        if (ast.nodes[c].type !== 'case_clause')
+                            continue;
+                        const caseBlock = kids.of(c).find((k) => ast.nodes[k].type === 'block');
+                        if (caseBlock === undefined)
+                            continue;
+                        const cf = lowerStmt(caseBlock, ctx);
+                        link(p, cf.entry, 'case');
+                        exits.push(...cf.exits);
+                        // `case _:` is the catch-all. Detected by NODE TYPE only — reading the type string for
+                        // an underscore matched `case_pattern` itself (measured: every match looked exhaustive).
+                        if (wildcardText(c))
+                            sawWildcard = true;
+                    }
+                    if (!sawWildcard)
+                        exits.push({ from: p, kind: 'default' }); // no arm may match
+                    return { entry: p, exits };
+                }
+                case 'with_statement': {
+                    // @implements A-SPEC-510.7 — a `with` is a body wrapper for control-flow purposes; the
+                    // context manager's exceptional path is covered by the enclosing try rules (conservative).
+                    const body = kids.of(i).find((k) => ast.nodes[k].type === 'block');
+                    if (body === undefined)
+                        throw new Unsupported('with_statement without a block');
+                    return lowerStmt(body, ctx);
+                }
+                case 'raise_statement': {
+                    const p = newPoint(i);
+                    link(p, ctx.catchT.at(-1) ?? EXIT, 'throw');
+                    return { entry: p, exits: [] };
+                }
+                case 'switch_statement': {
+                    const p = newPoint(i);
+                    const body = stmtChildren(i).at(-1); // switch_body
+                    const myBreak = { label, target: -1 };
+                    ctx.breakT.push({ label, owner: myBreak }, { label: null, owner: myBreak });
+                    const cases = kids.of(body).filter((k) => ['switch_case', 'switch_default'].includes(ast.nodes[k].type));
+                    let sawDefault = false;
+                    let prevFall = [];
+                    const exits = [];
+                    for (const c of cases) {
+                        const caseStmts = stmtChildren(c).filter((k) => rules.handled.has(ast.nodes[k].type));
+                        const cf = lowerSeq(caseStmts, ctx);
+                        const kind = ast.nodes[c].type === 'switch_default' ? 'default' : 'case';
+                        if (ast.nodes[c].type === 'switch_default')
+                            sawDefault = true;
+                        link(p, cf.entry, kind);
+                        for (const e of prevFall)
+                            link(e.from, cf.entry, 'seq'); // fallthrough
+                        prevFall = cf.exits;
+                    }
+                    exits.push(...prevFall);
+                    if (!sawDefault)
+                        exits.push({ from: p, kind: 'default' });
+                    ctx.breakT.splice(-2);
+                    for (const b of claimBreaks(myBreak)) {
+                        exits.push({ from: b.point, kind: 'break' });
+                    }
+                    return { entry: p, exits };
+                }
+                case 'break_statement': {
+                    const p = newPoint(i);
+                    const lbl = stmtChildren(i).length ? labelName(stmtChildren(i)[0]) : null;
+                    const bentry = nearestBreak(ctx.breakT, lbl);
+                    if (!bentry)
+                        throw new Unsupported('break outside breakable');
+                    // The owner's OUT is not built yet — park the edge for the construct to claim.
+                    pendingBreaks.push({ point: p, owner: bentry.owner });
+                    return { entry: p, exits: [] };
+                }
+                case 'continue_statement': {
+                    const p = newPoint(i);
+                    const lbl = stmtChildren(i).length ? labelName(stmtChildren(i)[0]) : null;
+                    const centry = nearestCont(ctx.contT, lbl);
+                    if (!centry || centry.target < 0)
+                        throw new Unsupported('continue outside loop');
+                    const target = centry.target;
+                    link(p, target, 'continue');
+                    return { entry: p, exits: [] };
+                }
+                case 'return_statement': {
+                    const p = newPoint(i);
+                    link(p, EXIT, 'return');
+                    return { entry: p, exits: [] };
+                }
+                case 'throw_statement': {
+                    const p = newPoint(i);
+                    link(p, ctx.catchT.at(-1) ?? EXIT, 'throw');
+                    return { entry: p, exits: [] };
+                }
+                case 'try_statement': {
+                    const named = stmtChildren(i);
+                    // @implements A-SPEC-510.7 — Python spells the same shape with `block` / `except_clause`
+                    // / `finally_clause`, PLUS an `else_clause` that runs ONLY when no exception was raised.
+                    const body = isPython
+                        ? kids.of(i).find((k) => ast.nodes[k].type === 'block')
+                        : named.find((k) => ast.nodes[k].type === 'statement_block');
+                    const handler = isPython
+                        ? kids.of(i).find((k) => ast.nodes[k].type === 'except_clause')
+                        : named.find((k) => ast.nodes[k].type === 'catch_clause');
+                    const finalizer = isPython
+                        ? kids.of(i).find((k) => ast.nodes[k].type === 'finally_clause')
+                        : named.find((k) => ast.nodes[k].type === 'finally_clause');
+                    const pyNoExcept = isPython
+                        ? kids.of(i).filter((k) => ast.nodes[k].type === 'else_clause')
+                            .flatMap((k) => kids.of(k)).find((k) => ast.nodes[k].type === 'block')
+                        : undefined;
+                    const exits = [];
+                    // Lower catch/finally FIRST so their entry points exist for exception wiring.
+                    const clauseBody = (clause) => (isPython
+                        ? kids.of(clause).find((k) => ast.nodes[k].type === 'block')
+                        : stmtChildren(clause).at(-1));
+                    let catchFlow;
+                    if (handler !== undefined)
+                        catchFlow = lowerStmt(clauseBody(handler), ctx);
+                    let finallyFlow;
+                    if (finalizer !== undefined)
+                        finallyFlow = lowerStmt(clauseBody(finalizer), ctx);
+                    const excTarget = catchFlow?.entry ?? finallyFlow?.entry ?? (ctx.catchT.at(-1) ?? EXIT);
+                    const firstBodyPoint = stmtsOf.length;
+                    ctx.catchT.push(excTarget);
+                    const bf = lowerStmt(body, ctx);
+                    ctx.catchT.pop();
+                    wireException(firstBodyPoint, () => excTarget); // conservative: any try stmt may throw
+                    const after = [];
+                    if (pyNoExcept !== undefined) {
+                        // Python's try/else: reached ONLY when the body completed without raising.
+                        const ef = lowerStmt(pyNoExcept, ctx);
+                        for (const e of bf.exits)
+                            link(e.from, ef.entry, e.kind);
+                        after.push(...ef.exits);
+                    }
+                    else {
+                        after.push(...bf.exits);
+                    }
+                    if (catchFlow)
+                        after.push(...catchFlow.exits);
+                    if (finallyFlow) {
+                        for (const e of after)
+                            link(e.from, finallyFlow.entry, e.kind);
+                        exits.push(...finallyFlow.exits);
+                        if (!catchFlow) {
+                            // Uncaught exceptional path traverses finally then leaves the function.
+                            for (const e of finallyFlow.exits)
+                                link(e.from, ctx.catchT.at(-1) ?? EXIT, 'throw');
+                        }
+                    }
+                    else {
+                        exits.push(...after);
+                    }
+                    return { entry: bf.entry, exits };
+                }
+                default:
+                    throw new Unsupported(t);
+            }
+        };
+        const pendingBreaks = [];
+        // Claim ONLY this construct's parked breaks: an inner loop draining the whole list would
+        // swallow an outer labeled break (measured: the labeled fixture lost its break edges).
+        const claimBreaks = (owner) => {
+            const mine = [];
+            for (let k = pendingBreaks.length - 1; k >= 0; k--) {
+                if (pendingBreaks[k].owner === owner)
+                    mine.push(...pendingBreaks.splice(k, 1));
+            }
+            return mine;
+        };
+        const nearestBreak = (stack, lbl) => {
+            for (let k = stack.length - 1; k >= 0; k--) {
+                if (lbl === null ? stack[k].label === null : stack[k].label === lbl)
+                    return stack[k];
+            }
+            return undefined;
+        };
+        const nearestCont = (stack, lbl) => {
+            for (let k = stack.length - 1; k >= 0; k--) {
+                if (lbl === null ? stack[k].label === null : stack[k].label === lbl)
+                    return stack[k];
+            }
+            return undefined;
+        };
+        const ctx = { breakT: [], contT: [], catchT: [], pendingLabel: null };
+        const bodyNode = ast.nodes[fn.bodyIndex];
+        const flow = bodyNode.type === rules.block
+            ? lowerSeq(stmtChildren(fn.bodyIndex), ctx)
+            : (() => { const p = newPoint(fn.bodyIndex); return { entry: p, exits: [{ from: p, kind: 'seq' }] }; })();
+        link(ENTRY, flow.entry, 'seq');
+        for (const e of flow.exits)
+            link(e.from, EXIT, e.kind === 'seq' ? 'seq' : e.kind);
+        if (pendingBreaks.length > 0)
+            throw new Unsupported('unresolved break label');
+        return finalize(stmtsOf, edges, ENTRY, EXIT);
+    }
+    catch (e) {
+        if (e instanceof Unsupported)
+            return { unsupported: e.type };
+        throw e;
+    }
+}
+/** Coalesce trivial chains, compute reachability and (post-)dominators, package the Cfg. */
+function finalize(stmtsOf, rawEdges, entry, exit) {
+    const n = stmtsOf.length;
+    // Deduplicate edges (conservative exception wiring can double-insert).
+    const seen = new Set();
+    const edges = rawEdges.filter((e) => {
+        const k = `${e.from}>${e.to}>${e.kind}`;
+        if (seen.has(k) || e.from === e.to && e.kind === 'seq')
+            return false;
+        seen.add(k);
+        return true;
+    });
+    const succ = Array.from({ length: n }, () => []);
+    const pred = Array.from({ length: n }, () => []);
+    for (const e of edges) {
+        succ[e.from].push(e.to);
+        pred[e.to].push(e.from);
+    }
+    // Reachability from entry.
+    const reach = new Uint8Array(n);
+    const stack = [entry];
+    reach[entry] = 1;
+    while (stack.length) {
+        const b = stack.pop();
+        for (const s of succ[b])
+            if (!reach[s]) {
+                reach[s] = 1;
+                stack.push(s);
+            }
+    }
+    const unreachable = [...Array(n).keys()].filter((b) => !reach[b] && b !== entry && b !== exit && stmtsOf[b].length > 0);
+    const idom = dominators(n, entry, succ, pred, reach);
+    // Post-dominators = dominators over the reversed graph rooted at EXIT, restricted to blocks
+    // that actually reach EXIT (an infinite loop legitimately never does).
+    const reachExit = new Uint8Array(n);
+    const st2 = [exit];
+    reachExit[exit] = 1;
+    while (st2.length) {
+        const b = st2.pop();
+        for (const p of pred[b])
+            if (!reachExit[p]) {
+                reachExit[p] = 1;
+                st2.push(p);
+            }
+    }
+    const ipostdom = dominators(n, exit, pred, succ, reachExit);
+    return {
+        blocks: stmtsOf.map((stmts, id) => ({ id, stmts: stmts.filter((s) => s >= 0) })),
+        edges, entry, exit, idom, ipostdom, unreachable,
+    };
+}
+/** Cooper–Harvey–Kennedy iterative dominators over the sub-graph marked in `included`. */
+function dominators(n, root, succ, pred, included) {
+    // Reverse post-order over included nodes.
+    const order = [];
+    const state = new Uint8Array(n);
+    const dfs = (u) => {
+        state[u] = 1;
+        for (const v of succ[u])
+            if (included[v] && !state[v])
+                dfs(v);
+        order.push(u);
+    };
+    if (included[root])
+        dfs(root);
+    order.reverse();
+    const rpo = new Int32Array(n).fill(-1);
+    order.forEach((b, i) => { rpo[b] = i; });
+    const idom = new Int32Array(n).fill(-1);
+    idom[root] = root;
+    const intersect = (a, b) => {
+        while (a !== b) {
+            while (rpo[a] > rpo[b])
+                a = idom[a];
+            while (rpo[b] > rpo[a])
+                b = idom[b];
+        }
+        return a;
+    };
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const b of order) {
+            if (b === root)
+                continue;
+            let newIdom = -1;
+            for (const p of pred[b]) {
+                if (!included[p] || idom[p] === -1)
+                    continue;
+                newIdom = newIdom === -1 ? p : intersect(p, newIdom);
+            }
+            if (newIdom !== -1 && idom[b] !== newIdom) {
+                idom[b] = newIdom;
+                changed = true;
+            }
+        }
+    }
+    idom[root] = -1; // the root has no immediate dominator
+    return idom;
+}
+// @implements A-SPEC-510.3
+/** The invariant verifier — the ONE truth tests and later layers share. [] means the theory holds. */
+function domViolations(cfg) {
+    const out = [];
+    const n = cfg.blocks.length;
+    const inEdges = cfg.edges.filter((e) => e.to === cfg.entry);
+    const outEdges = cfg.edges.filter((e) => e.from === cfg.exit);
+    if (inEdges.length > 0)
+        out.push('ENTRY has predecessors');
+    if (outEdges.length > 0)
+        out.push('EXIT has successors');
+    for (const e of cfg.edges) {
+        if (e.from < 0 || e.from >= n || e.to < 0 || e.to >= n)
+            out.push(`edge escapes the function: ${e.from}->${e.to}`);
+    }
+    // Every reachable block's idom chain terminates at ENTRY (acyclic, rooted).
+    const unreachableSet = new Set(cfg.unreachable);
+    for (let b = 0; b < n; b++) {
+        if (b === cfg.entry || unreachableSet.has(b))
+            continue;
+        if (cfg.idom[b] === -1)
+            continue; // not reachable from entry at all
+        let cur = b;
+        const hop = new Set();
+        while (cur !== cfg.entry) {
+            if (hop.has(cur)) {
+                out.push(`idom cycle at ${b}`);
+                break;
+            }
+            hop.add(cur);
+            const d = cfg.idom[cur];
+            if (d === -1) {
+                out.push(`idom chain of ${b} does not reach ENTRY`);
+                break;
+            }
+            cur = d;
+        }
+    }
+    // Post-dominator chains terminate at EXIT for every block that reaches EXIT.
+    for (let b = 0; b < n; b++) {
+        if (b === cfg.exit || cfg.ipostdom[b] === -1)
+            continue;
+        let cur = b;
+        const hop = new Set();
+        while (cur !== cfg.exit) {
+            if (hop.has(cur)) {
+                out.push(`ipostdom cycle at ${b}`);
+                break;
+            }
+            hop.add(cur);
+            const d = cfg.ipostdom[cur];
+            if (d === -1) {
+                out.push(`ipostdom chain of ${b} does not reach EXIT`);
+                break;
+            }
+            cur = d;
+        }
+    }
+    return out;
+}

package/dist/holmes/cpg/foundation/ddg.d.ts

@@ -0,0 +1,41 @@
+/**
+ * L3-DDG: reaching definitions over the L2 CFG, emitted as Joern-vocabulary REACHING_DEF edges.
+ * Textbook forward may-analysis: per-block gen/kill in statement order, IN = ∪OUT(pred),
+ * worklist to fixpoint. The load-bearing demonstration is the per-branch-sanitize join: when
+ * BOTH branches redefine a name, the tainted definition does not reach the join's use — exactly
+ * the shape behind the two recorded controlFlowAttributable taint false positives.
+ *
+ * HONEST ENVELOPE (sealed): function-level namespace (params + locally defined names) — inner
+ * block shadowing merges (over-approx); imported/global/closure-captured names are NOT tracked;
+ * member/subscript assignment is NOT a def (object mutation is a future axis); nested function
+ * bodies do not participate in the outer function's def/use; destructuring patterns
+ * over-approximate every identifier as a def. Exception-edge reachability is inherited from L2's
+ * conservative model.
+ */
+import type { PersistedAst } from './ast-store';
+import { Cfg, FunctionRef } from './cfg';
+export interface DdgEdge {
+    defStmt: number;
+    useStmt: number;
+    name: string;
+}
+export interface Ddg {
+    edges: DdgEdge[];
+    /** Per-statement definitions/uses (AST node index of the statement → names). */
+    defs: Map<number, Set<string>>;
+    uses: Map<number, Set<string>>;
+    /** Parameter name → the identifier's AST index (its def point lives at ENTRY). */
+    params: Map<string, number>;
+}
+export declare function defUseOf(ast: PersistedAst, cfg: Cfg, fn: FunctionRef, source: string): {
+    defs: Map<number, Set<string>>;
+    uses: Map<number, Set<string>>;
+    params: Map<string, number>;
+};
+export declare function ddgOf(ast: PersistedAst, cfg: Cfg | {
+    unsupported: string;
+}, fn: FunctionRef, source: string): Ddg | {
+    unsupported: string;
+};
+/** The DDG verifier — [] means the reaching-definition THEORY holds on this instance. */
+export declare function ddgViolations(ast: PersistedAst, cfg: Cfg, ddg: Ddg): string[];