@oculum/scanner 1.0.14 → 1.0.15

package/dist/taint/cfg-builder.js

@@ -0,0 +1,980 @@
+"use strict";
+/**
+ * Control Flow Graph Builder
+ *
+ * Builds an intra-procedural CFG for each function in a parsed AST.
+ * Uses the "pending-exits" pattern: each processStatement() call receives
+ * a list of nodes needing an outgoing edge and returns a new list of exits.
+ *
+ * Statement-level granularity. Expression-level flow (sub-expressions, short-circuit)
+ * is handled by the taint propagator within each CFGNode.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCFG = buildCFG;
+exports.buildFileCFGs = buildFileCFGs;
+exports.getSuccessors = getSuccessors;
+exports.getPredecessors = getPredecessors;
+exports.isReachable = isReachable;
+const ast_1 = require("../parse/ast");
+const def_use_1 = require("./def-use");
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Build a CFG for a single function AST node.
+ * The function node should be one of: function_declaration, arrow_function,
+ * function_expression, method_definition, generator_function_declaration.
+ */
+function buildCFG(fnNode, fnName) {
+    const builder = new CFGBuilder(fnNode, fnName);
+    return builder.build();
+}
+/**
+ * Build CFGs for all functions in a file. Returns a map keyed by function name,
+ * using the same naming conventions as call-graph.ts:
+ * - function_declaration → name
+ * - method_definition → ClassName.methodName
+ * - arrow/function_expression in variable_declarator → variable name
+ * - module-level code → '<module>'
+ */
+function buildFileCFGs(ast) {
+    const root = ast.tree.rootNode;
+    const cfgs = new Map();
+    const fnTypes = [
+        'function_declaration',
+        'generator_function_declaration',
+        'method_definition',
+        'arrow_function',
+        'function_expression',
+        'function_definition', // Python
+    ];
+    (0, ast_1.walkAST)(root, (node) => {
+        // Python: decorated_definition wraps the function_definition
+        if (node.type === 'decorated_definition') {
+            const def = node.namedChildren.find(c => fnTypes.includes(c.type));
+            if (def) {
+                const name = getFunctionName(def);
+                if (name) {
+                    cfgs.set(name, buildCFG(def, name));
+                }
+            }
+            return true; // skip children — we already processed the inner definition
+        }
+        if (!fnTypes.includes(node.type))
+            return false;
+        const name = getFunctionName(node);
+        if (name) {
+            cfgs.set(name, buildCFG(node, name));
+        }
+        return false;
+    });
+    // Module-level code: gather top-level statements NOT inside a function/class
+    const moduleStatements = getModuleLevelStatements(root);
+    if (moduleStatements.length > 0) {
+        const builder = new CFGBuilder(root, '<module>');
+        cfgs.set('<module>', builder.buildFromStatements(moduleStatements));
+    }
+    return cfgs;
+}
+// ============================================================================
+// Query Helpers
+// ============================================================================
+/** Get all successor node ids from a given node. */
+function getSuccessors(cfg, nodeId) {
+    const edges = cfg.edges.get(nodeId);
+    if (!edges)
+        return [];
+    return edges.map(e => e.to);
+}
+/** Get all predecessor node ids for a given node. */
+function getPredecessors(cfg, nodeId) {
+    const edges = cfg.reverseEdges.get(nodeId);
+    if (!edges)
+        return [];
+    return edges.map(e => e.from);
+}
+/** Check if there's a path from `fromId` to `toId` in the CFG using BFS. */
+function isReachable(cfg, fromId, toId) {
+    if (fromId === toId)
+        return true;
+    const visited = new Set();
+    const queue = [fromId];
+    visited.add(fromId);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const edges = cfg.edges.get(current);
+        if (!edges)
+            continue;
+        for (const edge of edges) {
+            if (edge.to === toId)
+                return true;
+            if (!visited.has(edge.to)) {
+                visited.add(edge.to);
+                queue.push(edge.to);
+            }
+        }
+    }
+    return false;
+}
+// ============================================================================
+// CFG Builder Class
+// ============================================================================
+class CFGBuilder {
+    constructor(fnNode, fnName) {
+        this.fnNode = fnNode;
+        this.fnName = fnName;
+        this.nextId = 2; // 0=entry, 1=exit
+        this.nodes = new Map();
+        this.edges = new Map();
+        this.reverseEdges = new Map();
+        this.loopStack = [];
+        this.switchStack = [];
+        this.tryStack = [];
+    }
+    build() {
+        const entry = this.createNode('entry', null, -1, 'ENTRY');
+        const exit = this.createNode('exit', null, -1, 'EXIT');
+        const body = this.getFunctionBody();
+        if (!body || body.namedChildren.length === 0) {
+            this.addEdge(entry.id, exit.id, 'normal');
+        }
+        else {
+            let pending = [{ nodeId: entry.id, edgeKind: 'normal' }];
+            const statements = this.getStatements(body);
+            for (const stmt of statements) {
+                if (pending.length === 0)
+                    break;
+                pending = this.processStatement(stmt, pending);
+            }
+            this.connectToNode(pending, exit.id);
+        }
+        return this.finalize();
+    }
+    /** Build a CFG from an explicit list of statements (for module-level code). */
+    buildFromStatements(statements) {
+        const entry = this.createNode('entry', null, -1, 'ENTRY');
+        const exit = this.createNode('exit', null, -1, 'EXIT');
+        if (statements.length === 0) {
+            this.addEdge(entry.id, exit.id, 'normal');
+        }
+        else {
+            let pending = [{ nodeId: entry.id, edgeKind: 'normal' }];
+            for (const stmt of statements) {
+                if (pending.length === 0)
+                    break;
+                pending = this.processStatement(stmt, pending);
+            }
+            this.connectToNode(pending, exit.id);
+        }
+        return this.finalize();
+    }
+    finalize() {
+        return {
+            nodes: this.nodes,
+            edges: this.edges,
+            reverseEdges: this.reverseEdges,
+            entryId: 0,
+            exitId: 1,
+            functionNode: this.fnNode,
+            functionName: this.fnName,
+        };
+    }
+    // ==========================================================================
+    // Statement Processing (returns new pending exits)
+    // ==========================================================================
+    processStatement(node, entries) {
+        switch (node.type) {
+            case 'if_statement':
+            case 'elif_clause': // Python: elif has same fields (condition/consequence) as if_statement
+                return this.processIf(node, entries);
+            case 'while_statement':
+                return this.processWhile(node, entries);
+            case 'for_statement':
+                // Python for_statement uses left/right fields (like for-in), not initializer/condition/increment
+                if (node.childForFieldName('left') && node.childForFieldName('right')) {
+                    return this.processForIn(node, entries);
+                }
+                return this.processFor(node, entries);
+            case 'for_in_statement':
+                return this.processForIn(node, entries);
+            case 'do_statement':
+                return this.processDoWhile(node, entries);
+            case 'try_statement':
+                return this.processTry(node, entries);
+            case 'switch_statement':
+                return this.processSwitch(node, entries);
+            case 'return_statement':
+                return this.processReturn(node, entries);
+            case 'throw_statement':
+            case 'raise_statement':
+                return this.processThrow(node, entries);
+            case 'break_statement':
+                return this.processBreak(node, entries);
+            case 'continue_statement':
+                return this.processContinue(node, entries);
+            case 'labeled_statement':
+                return this.processLabeled(node, entries);
+            case 'statement_block':
+            case 'block':
+                return this.processBlock(node, entries);
+            case 'empty_statement':
+            case 'pass_statement':
+                return entries;
+            case 'with_statement':
+                return this.processWith(node, entries);
+            default:
+                return this.processPlainStatement(node, entries);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Plain statement
+    // --------------------------------------------------------------------------
+    processPlainStatement(node, entries) {
+        const cfgNode = this.createStatementNode(node);
+        this.connectToNode(entries, cfgNode.id);
+        return [{ nodeId: cfgNode.id, edgeKind: 'normal' }];
+    }
+    // --------------------------------------------------------------------------
+    // Block
+    // --------------------------------------------------------------------------
+    processBlock(node, entries) {
+        let pending = entries;
+        for (const stmt of node.namedChildren) {
+            if (pending.length === 0)
+                break;
+            pending = this.processStatement(stmt, pending);
+        }
+        return pending;
+    }
+    // --------------------------------------------------------------------------
+    // If / else
+    // --------------------------------------------------------------------------
+    processIf(node, entries) {
+        const condition = node.childForFieldName('condition');
+        const consequence = node.childForFieldName('consequence');
+        const alternative = node.childForFieldName('alternative');
+        const condNode = this.createConditionNode(condition ?? node);
+        this.connectToNode(entries, condNode.id);
+        const allExits = [];
+        // True branch
+        if (consequence) {
+            const trueExits = this.processStatement(consequence, [{ nodeId: condNode.id, edgeKind: 'true' }]);
+            allExits.push(...trueExits);
+        }
+        else {
+            allExits.push({ nodeId: condNode.id, edgeKind: 'true' });
+        }
+        // False branch
+        if (alternative) {
+            const altBody = alternative.type === 'else_clause'
+                ? (alternative.namedChildren.find(c => c.type === 'block') ?? alternative.namedChildren[0] ?? alternative)
+                : alternative;
+            const falseExits = this.processStatement(altBody, [{ nodeId: condNode.id, edgeKind: 'false' }]);
+            allExits.push(...falseExits);
+        }
+        else {
+            allExits.push({ nodeId: condNode.id, edgeKind: 'false' });
+        }
+        // Python if/elif/else: when alternative is elif_clause, the else_clause is a
+        // separate sibling child (not reachable via childForFieldName('alternative')).
+        // We need to find and process it from the last elif's false exit.
+        if (alternative?.type === 'elif_clause') {
+            const elseClause = node.namedChildren.find(c => c.type === 'else_clause');
+            if (elseClause) {
+                // The else body is reachable when all elif conditions are false.
+                // Since elif_clause is processed recursively via processIf, the last elif's
+                // false exit is already in allExits. We need to replace the "no alternative"
+                // false exit from the deepest elif with the else body.
+                // However, since elif recursion already added its false exit to our allExits
+                // via processStatement, we process the else body from the elif chain's exits.
+                // For simplicity and correctness, we find the else body and note that the
+                // elif's false exits already flow into it via processIf recursion — but only
+                // if the elif_clause itself has no alternative. The deepest elif will have
+                // added a condNode false exit. We need to intercept that.
+                //
+                // Simpler approach: the else_clause attaches to the LAST condition's false exit.
+                // Since we recursed into elif_clause, its false exits are already in allExits.
+                // We replace the last condition's false exit with the else body exits.
+                const elseBody = elseClause.namedChildren.find(c => c.type === 'block')
+                    ?? elseClause.namedChildren[0];
+                if (elseBody) {
+                    // Find exits that came from condition false edges (from deepest elif)
+                    // These are the exits where the condition was false and no else was found
+                    const condFalseExits = allExits.filter(e => e.edgeKind === 'false');
+                    if (condFalseExits.length > 0) {
+                        // Remove the condition false exits from allExits
+                        for (const cfe of condFalseExits) {
+                            const idx = allExits.indexOf(cfe);
+                            if (idx >= 0)
+                                allExits.splice(idx, 1);
+                        }
+                        // Process else body with those exits as entries
+                        const elseExits = this.processStatement(elseBody, condFalseExits);
+                        allExits.push(...elseExits);
+                    }
+                }
+            }
+        }
+        return allExits;
+    }
+    // --------------------------------------------------------------------------
+    // While
+    // --------------------------------------------------------------------------
+    processWhile(node, entries) {
+        const condition = node.childForFieldName('condition');
+        const body = node.childForFieldName('body');
+        const condNode = this.createConditionNode(condition ?? node);
+        this.connectToNode(entries, condNode.id);
+        const frame = {
+            continueTarget: condNode.id,
+            label: this.consumeLabel(),
+            breakExits: [],
+        };
+        this.loopStack.push(frame);
+        const bodyExits = body
+            ? this.processStatement(body, [{ nodeId: condNode.id, edgeKind: 'true' }])
+            : [{ nodeId: condNode.id, edgeKind: 'true' }];
+        // Back-edge
+        this.connectToNode(bodyExits, condNode.id);
+        this.loopStack.pop();
+        return [
+            { nodeId: condNode.id, edgeKind: 'false' },
+            ...frame.breakExits,
+        ];
+    }
+    // --------------------------------------------------------------------------
+    // For
+    // --------------------------------------------------------------------------
+    processFor(node, entries) {
+        const init = node.childForFieldName('initializer');
+        const condition = node.childForFieldName('condition');
+        const increment = node.childForFieldName('increment');
+        const body = node.childForFieldName('body');
+        // Init
+        let pending = entries;
+        if (init) {
+            const initNode = this.createStatementNode(init);
+            this.connectToNode(pending, initNode.id);
+            pending = [{ nodeId: initNode.id, edgeKind: 'normal' }];
+        }
+        // Condition
+        let condNode = null;
+        if (condition) {
+            condNode = this.createConditionNode(condition);
+            this.connectToNode(pending, condNode.id);
+        }
+        // Update node (for continue targeting)
+        let updateNode = null;
+        if (increment) {
+            updateNode = this.createStatementNode(increment);
+        }
+        // Continue target: update → condition → init (fallback)
+        const continueTarget = updateNode?.id ?? condNode?.id ?? pending[0]?.nodeId ?? 0;
+        const frame = {
+            continueTarget,
+            label: this.consumeLabel(),
+            breakExits: [],
+        };
+        this.loopStack.push(frame);
+        // Body entries
+        const bodyEntries = condNode
+            ? [{ nodeId: condNode.id, edgeKind: 'true' }]
+            : pending; // for(;;) — no condition, enter body from init/entry
+        const bodyExits = body
+            ? this.processStatement(body, bodyEntries)
+            : bodyEntries;
+        // Back-edge: body → update → condition
+        if (updateNode) {
+            this.connectToNode(bodyExits, updateNode.id);
+            if (condNode) {
+                this.addEdge(updateNode.id, condNode.id, 'normal');
+            }
+            else {
+                // No condition — update loops directly to body entry
+                // For for(;; i++), connect update back to first body node
+                if (bodyEntries.length > 0) {
+                    // The body was entered from `pending`. After update, re-enter the same way.
+                    // For simplicity, loop update → itself (the first body statement will be reached)
+                    for (const be of bodyEntries) {
+                        this.addEdge(updateNode.id, be.nodeId, 'normal');
+                    }
+                }
+            }
+        }
+        else if (condNode) {
+            this.connectToNode(bodyExits, condNode.id);
+        }
+        else {
+            // for(;;) — no condition, no update, body loops back
+            for (const be of bodyEntries) {
+                this.connectToNode(bodyExits, be.nodeId);
+            }
+        }
+        this.loopStack.pop();
+        const exits = [...frame.breakExits];
+        if (condNode) {
+            exits.push({ nodeId: condNode.id, edgeKind: 'false' });
+        }
+        return exits;
+    }
+    // --------------------------------------------------------------------------
+    // For-in / For-of
+    // --------------------------------------------------------------------------
+    processForIn(node, entries) {
+        const left = node.childForFieldName('left');
+        const right = node.childForFieldName('right');
+        const body = node.childForFieldName('body');
+        const headerNode = this.createNode('condition', node, node.startPosition.row + 1, `for-${node.text.includes(' of ') ? 'of' : 'in'}`);
+        // Left side is always a def (identifier or destructuring pattern).
+        // tree-sitter strips the `const/let/var` keyword from the left field.
+        if (left) {
+            extractPatternDefs(left, headerNode.defs);
+        }
+        if (right) {
+            const { uses } = (0, def_use_1.computeDefUse)(right);
+            for (const u of uses)
+                headerNode.uses.add(u);
+        }
+        this.connectToNode(entries, headerNode.id);
+        const frame = {
+            continueTarget: headerNode.id,
+            label: this.consumeLabel(),
+            breakExits: [],
+        };
+        this.loopStack.push(frame);
+        const bodyExits = body
+            ? this.processStatement(body, [{ nodeId: headerNode.id, edgeKind: 'true' }])
+            : [{ nodeId: headerNode.id, edgeKind: 'true' }];
+        this.connectToNode(bodyExits, headerNode.id);
+        this.loopStack.pop();
+        return [
+            { nodeId: headerNode.id, edgeKind: 'false' },
+            ...frame.breakExits,
+        ];
+    }
+    // --------------------------------------------------------------------------
+    // Do-while
+    // --------------------------------------------------------------------------
+    processDoWhile(node, entries) {
+        const body = node.childForFieldName('body');
+        const condition = node.childForFieldName('condition');
+        // We need a merge point for the body entry (initial entry + back-edge from condition).
+        // Create a synthetic merge node.
+        const mergeNode = this.createNode('statement', null, node.startPosition.row + 1, 'do-merge');
+        this.connectToNode(entries, mergeNode.id);
+        const condNode = this.createConditionNode(condition ?? node);
+        const frame = {
+            continueTarget: condNode.id,
+            label: this.consumeLabel(),
+            breakExits: [],
+        };
+        this.loopStack.push(frame);
+        const bodyExits = body
+            ? this.processStatement(body, [{ nodeId: mergeNode.id, edgeKind: 'normal' }])
+            : [{ nodeId: mergeNode.id, edgeKind: 'normal' }];
+        this.connectToNode(bodyExits, condNode.id);
+        // true → back to merge (re-enter body)
+        this.addEdge(condNode.id, mergeNode.id, 'true');
+        this.loopStack.pop();
+        return [
+            { nodeId: condNode.id, edgeKind: 'false' },
+            ...frame.breakExits,
+        ];
+    }
+    // --------------------------------------------------------------------------
+    // Try / catch / finally
+    // --------------------------------------------------------------------------
+    processTry(node, entries) {
+        const tryBody = node.childForFieldName('body');
+        const handler = node.childForFieldName('handler');
+        // JS: 'finalizer' field. Python: finally_clause is a named child (no field name).
+        const finalizer = node.childForFieldName('finalizer')
+            ?? node.namedChildren.find(c => c.type === 'finally_clause')?.namedChildren.find(c => c.type === 'block');
+        // Python: except_clause children instead of handler field
+        const exceptClauses = node.namedChildren.filter(c => c.type === 'except_clause' || c.type === 'except_group_clause');
+        const tryEntry = this.createNode('statement', node, node.startPosition.row + 1, 'try-entry');
+        this.connectToNode(entries, tryEntry.id);
+        let catchEntryNode = null;
+        if (handler) {
+            // JS: catch_clause
+            const param = handler.childForFieldName('parameter');
+            catchEntryNode = this.createNode('statement', handler, handler.startPosition.row + 1, 'catch-entry');
+            if (param) {
+                if (param.type === 'identifier') {
+                    catchEntryNode.defs.add(param.text);
+                }
+                else {
+                    const { defs } = (0, def_use_1.computeDefUse)(param);
+                    for (const d of defs)
+                        catchEntryNode.defs.add(d);
+                }
+            }
+            this.addEdge(tryEntry.id, catchEntryNode.id, 'exception');
+            this.tryStack.push({ catchEntry: catchEntryNode.id });
+        }
+        else if (exceptClauses.length > 0) {
+            // Python: use first except clause as catch entry
+            const firstExcept = exceptClauses[0];
+            catchEntryNode = this.createNode('statement', firstExcept, firstExcept.startPosition.row + 1, 'except-entry');
+            // Extract the exception variable from as_pattern (e.g., except ValueError as e)
+            const asPattern = firstExcept.descendantsOfType('as_pattern')[0];
+            if (asPattern) {
+                const target = asPattern.namedChildren.find(c => c.type === 'as_pattern_target');
+                const ident = target?.namedChildren.find(c => c.type === 'identifier');
+                if (ident)
+                    catchEntryNode.defs.add(ident.text);
+            }
+            this.addEdge(tryEntry.id, catchEntryNode.id, 'exception');
+            this.tryStack.push({ catchEntry: catchEntryNode.id });
+        }
+        const tryExits = tryBody
+            ? this.processStatement(tryBody, [{ nodeId: tryEntry.id, edgeKind: 'normal' }])
+            : [{ nodeId: tryEntry.id, edgeKind: 'normal' }];
+        if (handler || exceptClauses.length > 0) {
+            this.tryStack.pop();
+        }
+        let catchExits = [];
+        if (handler && catchEntryNode) {
+            // JS: catch_clause body
+            const catchBody = handler.childForFieldName('body');
+            catchExits = catchBody
+                ? this.processStatement(catchBody, [{ nodeId: catchEntryNode.id, edgeKind: 'normal' }])
+                : [{ nodeId: catchEntryNode.id, edgeKind: 'normal' }];
+        }
+        else if (exceptClauses.length > 0 && catchEntryNode) {
+            // Python: walk except clause bodies
+            let pending = [{ nodeId: catchEntryNode.id, edgeKind: 'normal' }];
+            for (const ec of exceptClauses) {
+                const exceptBody = ec.namedChildren.find(c => c.type === 'block');
+                if (exceptBody) {
+                    pending = this.processStatement(exceptBody, pending);
+                }
+            }
+            catchExits = pending;
+        }
+        // Python: else clause (runs if no exception raised)
+        const elseClause = node.childForFieldName('alternative')
+            ?? node.namedChildren.find(c => c.type === 'else_clause');
+        if (elseClause) {
+            const elseBody = elseClause.type === 'else_clause'
+                ? (elseClause.namedChildren.find(c => c.type === 'block') ?? elseClause.namedChildren[0])
+                : elseClause;
+            if (elseBody) {
+                const elseExits = this.processStatement(elseBody, tryExits);
+                // try exits are replaced by else exits
+                if (finalizer) {
+                    const allBeforeFinally = [...elseExits, ...catchExits];
+                    return this.processStatement(finalizer, allBeforeFinally);
+                }
+                return [...elseExits, ...catchExits];
+            }
+        }
+        if (finalizer) {
+            const allBeforeFinally = [...tryExits, ...catchExits];
+            return this.processStatement(finalizer, allBeforeFinally);
+        }
+        return [...tryExits, ...catchExits];
+    }
+    // --------------------------------------------------------------------------
+    // Switch
+    // --------------------------------------------------------------------------
+    processSwitch(node, entries) {
+        const discriminant = node.childForFieldName('value');
+        const body = node.childForFieldName('body');
+        const switchNode = this.createConditionNode(discriminant ?? node);
+        this.connectToNode(entries, switchNode.id);
+        const frame = { label: this.consumeLabel(), breakExits: [] };
+        this.switchStack.push(frame);
+        const cases = body
+            ? body.namedChildren.filter(c => c.type === 'switch_case' || c.type === 'switch_default')
+            : [];
+        let hasDefault = false;
+        let prevCaseExits = [];
+        for (const caseNode of cases) {
+            const isDefault = caseNode.type === 'switch_default';
+            if (isDefault)
+                hasDefault = true;
+            const caseEntries = [
+                { nodeId: switchNode.id, edgeKind: isDefault ? 'normal' : 'true' },
+            ];
+            // Fallthrough from previous case
+            if (prevCaseExits.length > 0) {
+                for (const e of prevCaseExits) {
+                    caseEntries.push({ nodeId: e.nodeId, edgeKind: 'fallthrough' });
+                }
+            }
+            // Case body: skip the case value expression nodes
+            const caseStatements = getCaseBodyStatements(caseNode);
+            let caseExits = caseEntries;
+            for (const stmt of caseStatements) {
+                if (caseExits.length === 0)
+                    break;
+                caseExits = this.processStatement(stmt, caseExits);
+            }
+            prevCaseExits = caseExits;
+        }
+        this.switchStack.pop();
+        const exits = [...frame.breakExits, ...prevCaseExits];
+        if (!hasDefault) {
+            exits.push({ nodeId: switchNode.id, edgeKind: 'false' });
+        }
+        return exits;
+    }
+    // --------------------------------------------------------------------------
+    // Return
+    // --------------------------------------------------------------------------
+    processReturn(node, entries) {
+        const cfgNode = this.createStatementNode(node);
+        this.connectToNode(entries, cfgNode.id);
+        this.addEdge(cfgNode.id, 1, 'return');
+        return [];
+    }
+    // --------------------------------------------------------------------------
+    // Throw
+    // --------------------------------------------------------------------------
+    processThrow(node, entries) {
+        const cfgNode = this.createStatementNode(node);
+        this.connectToNode(entries, cfgNode.id);
+        if (this.tryStack.length > 0) {
+            const frame = this.tryStack[this.tryStack.length - 1];
+            this.addEdge(cfgNode.id, frame.catchEntry, 'throw');
+        }
+        else {
+            this.addEdge(cfgNode.id, 1, 'throw');
+        }
+        return [];
+    }
+    // --------------------------------------------------------------------------
+    // Break
+    // --------------------------------------------------------------------------
+    processBreak(node, entries) {
+        const cfgNode = this.createStatementNode(node);
+        this.connectToNode(entries, cfgNode.id);
+        const label = node.childForFieldName('label')?.text;
+        if (label) {
+            for (let i = this.loopStack.length - 1; i >= 0; i--) {
+                if (this.loopStack[i].label === label) {
+                    this.loopStack[i].breakExits.push({ nodeId: cfgNode.id, edgeKind: 'break' });
+                    return [];
+                }
+            }
+            for (let i = this.switchStack.length - 1; i >= 0; i--) {
+                if (this.switchStack[i].label === label) {
+                    this.switchStack[i].breakExits.push({ nodeId: cfgNode.id, edgeKind: 'break' });
+                    return [];
+                }
+            }
+        }
+        // Unlabeled: target innermost loop or switch
+        const target = this.getInnermostBreakTarget(node);
+        if (target) {
+            target.breakExits.push({ nodeId: cfgNode.id, edgeKind: 'break' });
+        }
+        return [];
+    }
+    // --------------------------------------------------------------------------
+    // Continue
+    // --------------------------------------------------------------------------
+    processContinue(node, entries) {
+        const cfgNode = this.createStatementNode(node);
+        this.connectToNode(entries, cfgNode.id);
+        const label = node.childForFieldName('label')?.text;
+        if (label) {
+            for (let i = this.loopStack.length - 1; i >= 0; i--) {
+                if (this.loopStack[i].label === label) {
+                    this.addEdge(cfgNode.id, this.loopStack[i].continueTarget, 'continue');
+                    return [];
+                }
+            }
+        }
+        if (this.loopStack.length > 0) {
+            const frame = this.loopStack[this.loopStack.length - 1];
+            this.addEdge(cfgNode.id, frame.continueTarget, 'continue');
+        }
+        return [];
+    }
+    // --------------------------------------------------------------------------
+    // Labeled statement
+    // --------------------------------------------------------------------------
+    processLabeled(node, entries) {
+        const label = node.childForFieldName('label')?.text;
+        const body = node.namedChildren.find(c => c !== node.childForFieldName('label'));
+        if (!body)
+            return entries;
+        // Set label BEFORE processing — loop/switch processors will consume it
+        if (label) {
+            this._pendingLabel = label;
+        }
+        return this.processStatement(body, entries);
+    }
+    // --------------------------------------------------------------------------
+    // With statement (Python)
+    // --------------------------------------------------------------------------
+    processWith(node, entries) {
+        const cfgNode = this.createStatementNode(node);
+        this.connectToNode(entries, cfgNode.id);
+        const body = node.childForFieldName('body');
+        if (body) {
+            return this.processStatement(body, [{ nodeId: cfgNode.id, edgeKind: 'normal' }]);
+        }
+        return [{ nodeId: cfgNode.id, edgeKind: 'normal' }];
+    }
+    consumeLabel() {
+        const label = this._pendingLabel;
+        this._pendingLabel = undefined;
+        return label;
+    }
+    // ==========================================================================
+    // Node Creation
+    // ==========================================================================
+    createNode(kind, astNode, line, label) {
+        const id = kind === 'entry' ? 0 : kind === 'exit' ? 1 : this.nextId++;
+        const node = {
+            id,
+            kind,
+            astNode,
+            defs: new Set(),
+            uses: new Set(),
+            line,
+            label,
+        };
+        this.nodes.set(id, node);
+        return node;
+    }
+    createStatementNode(astNode) {
+        const { defs, uses } = (0, def_use_1.computeDefUse)(astNode);
+        const node = this.createNode('statement', astNode, astNode.startPosition.row + 1, truncate(astNode.text, 40));
+        node.defs = defs;
+        node.uses = uses;
+        return node;
+    }
+    createConditionNode(astNode) {
+        const { defs, uses } = (0, def_use_1.computeDefUse)(astNode);
+        const node = this.createNode('condition', astNode, astNode.startPosition.row + 1, `cond: ${truncate(astNode.text, 30)}`);
+        node.defs = defs;
+        node.uses = uses;
+        return node;
+    }
+    // ==========================================================================
+    // Edge Helpers
+    // ==========================================================================
+    addEdge(from, to, kind) {
+        const edge = { from, to, kind };
+        if (!this.edges.has(from))
+            this.edges.set(from, []);
+        this.edges.get(from).push(edge);
+        if (!this.reverseEdges.has(to))
+            this.reverseEdges.set(to, []);
+        this.reverseEdges.get(to).push(edge);
+    }
+    connectToNode(exits, targetId) {
+        for (const exit of exits) {
+            this.addEdge(exit.nodeId, targetId, exit.edgeKind);
+        }
+    }
+    // ==========================================================================
+    // Utility Helpers
+    // ==========================================================================
+    getFunctionBody() {
+        if (this.fnNode.type === 'program' || this.fnNode.type === 'module')
+            return null; // module-level uses buildFromStatements
+        return this.fnNode.childForFieldName('body');
+    }
+    getStatements(body) {
+        if (body.type === 'statement_block' || body.type === 'block') {
+            return body.namedChildren;
+        }
+        return [body];
+    }
+    /** Determine the innermost break-target (loop or switch) by walking up the AST. */
+    getInnermostBreakTarget(breakNode) {
+        const loopTypes = new Set([
+            'while_statement', 'for_statement', 'for_in_statement', 'do_statement',
+        ]);
+        // Python for_statement is already in the set — its name matches
+        let current = breakNode.parent;
+        while (current) {
+            if (current.type === 'switch_statement' && this.switchStack.length > 0) {
+                return this.switchStack[this.switchStack.length - 1];
+            }
+            if (loopTypes.has(current.type) && this.loopStack.length > 0) {
+                return this.loopStack[this.loopStack.length - 1];
+            }
+            current = current.parent;
+        }
+        // Fallback
+        if (this.switchStack.length > 0)
+            return this.switchStack[this.switchStack.length - 1];
+        if (this.loopStack.length > 0)
+            return this.loopStack[this.loopStack.length - 1];
+        return null;
+    }
+}
+// ============================================================================
+// Function Name Resolution (matches call-graph conventions)
+// ============================================================================
+function getFunctionName(node) {
+    switch (node.type) {
+        case 'function_declaration':
+        case 'generator_function_declaration':
+            return node.childForFieldName('name')?.text ?? null;
+        case 'method_definition': {
+            const methodName = node.childForFieldName('name')?.text;
+            if (!methodName)
+                return null;
+            const className = getEnclosingClassName(node);
+            return className ? `${className}.${methodName}` : methodName;
+        }
+        case 'function_definition': {
+            const name = node.childForFieldName('name')?.text;
+            if (!name)
+                return null;
+            const className = getEnclosingClassName(node);
+            return className ? `${className}.${name}` : name;
+        }
+        case 'arrow_function':
+        case 'function_expression': {
+            const parent = node.parent;
+            if (parent?.type === 'variable_declarator') {
+                const nameNode = parent.childForFieldName('name');
+                if (nameNode?.type === 'identifier')
+                    return nameNode.text;
+            }
+            if (parent?.type === 'assignment_expression') {
+                const left = parent.childForFieldName('left');
+                if (left?.type === 'identifier')
+                    return left.text;
+            }
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+function getEnclosingClassName(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === 'class_declaration' || current.type === 'class' || current.type === 'class_definition') {
+            return current.childForFieldName('name')?.text ?? null;
+        }
+        // Python: decorated_definition wraps the class, check its definition child
+        if (current.type === 'decorated_definition') {
+            const def = current.childForFieldName('definition');
+            if (def?.type === 'class_definition') {
+                return def.childForFieldName('name')?.text ?? null;
+            }
+        }
+        current = current.parent;
+    }
+    return null;
+}
+function getModuleLevelStatements(root) {
+    const fnTypes = new Set([
+        'function_declaration', 'generator_function_declaration', 'class_declaration',
+        'function_definition', 'class_definition', 'decorated_definition', // Python
+    ]);
+    return root.namedChildren.filter(child => {
+        if (fnTypes.has(child.type))
+            return false;
+        if (child.type === 'import_statement')
+            return false;
+        if (child.type === 'import_from_statement')
+            return false; // Python
+        if (child.type === 'export_statement') {
+            const decl = child.namedChildren[0];
+            if (decl && fnTypes.has(decl.type))
+                return false;
+        }
+        return true;
+    });
+}
+/** Get the body statements from a switch case, skipping the case value expression. */
+function getCaseBodyStatements(caseNode) {
+    // switch_case children: value expression(s) + ":" + body statements
+    // switch_default children: ":" + body statements
+    // The "value" field contains the case expression, everything else is body
+    if (caseNode.type === 'switch_default') {
+        return caseNode.namedChildren;
+    }
+    // For switch_case, the first named child is the value, rest are body
+    const value = caseNode.childForFieldName('value');
+    return caseNode.namedChildren.filter(c => c !== value);
+}
+// ============================================================================
+// Pattern Def Extraction (for for-of/for-in left side)
+// ============================================================================
+/** Extract defined variable names from a pattern (identifier, array/object destructuring). */
+function extractPatternDefs(node, defs) {
+    switch (node.type) {
+        case 'identifier':
+            defs.add(node.text);
+            return;
+        case 'array_pattern':
+            for (const child of node.namedChildren) {
+                extractPatternDefs(child, defs);
+            }
+            return;
+        case 'object_pattern':
+            for (const prop of node.namedChildren) {
+                if (prop.type === 'shorthand_property_identifier_pattern') {
+                    defs.add(prop.text);
+                }
+                else if (prop.type === 'pair_pattern') {
+                    const value = prop.childForFieldName('value');
+                    if (value)
+                        extractPatternDefs(value, defs);
+                }
+                else if (prop.type === 'rest_pattern' && prop.namedChildren[0]) {
+                    extractPatternDefs(prop.namedChildren[0], defs);
+                }
+            }
+            return;
+        case 'rest_pattern':
+            if (node.namedChildren[0])
+                extractPatternDefs(node.namedChildren[0], defs);
+            return;
+        case 'assignment_pattern': {
+            const left = node.childForFieldName('left');
+            if (left)
+                extractPatternDefs(left, defs);
+            return;
+        }
+        // Python tuple/list unpacking: for a, b in items / for [a, b] in items
+        case 'pattern_list':
+        case 'tuple_pattern':
+        case 'list_pattern':
+        case 'expression_list':
+        case 'tuple':
+            for (const child of node.namedChildren) {
+                extractPatternDefs(child, defs);
+            }
+            return;
+        // Python: let/const declarations wrapping for-of
+        case 'lexical_declaration':
+        case 'variable_declaration':
+            for (const child of node.namedChildren) {
+                if (child.type === 'variable_declarator') {
+                    const nameNode = child.childForFieldName('name');
+                    if (nameNode)
+                        extractPatternDefs(nameNode, defs);
+                }
+            }
+            return;
+        case 'list_splat_pattern':
+            if (node.namedChildren[0])
+                extractPatternDefs(node.namedChildren[0], defs);
+            return;
+        default:
+            return;
+    }
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+function truncate(text, maxLen) {
+    const oneLine = text.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= maxLen)
+        return oneLine;
+    return oneLine.slice(0, maxLen - 3) + '...';
+}
+//# sourceMappingURL=cfg-builder.js.map