@oculum/scanner 1.0.14 → 1.0.15

package/src/taint/cfg-builder.ts

@@ -0,0 +1,1127 @@
+/**
+ * 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.
+ */
+
+import type Parser from 'tree-sitter'
+import { walkAST, type ParsedAST } from '../parse/ast'
+import { computeDefUse } from './def-use'
+import type {
+  CFG,
+  CFGNode,
+  CFGNodeKind,
+  CFGEdge,
+  CFGEdgeKind,
+  PendingExit,
+  LoopFrame,
+  SwitchFrame,
+  TryFrame,
+} from './cfg-types'
+
+// ============================================================================
+// 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.
+ */
+export function buildCFG(fnNode: Parser.SyntaxNode, fnName: string): CFG {
+  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>'
+ */
+export function buildFileCFGs(ast: ParsedAST): Map<string, CFG> {
+  const root = ast.tree.rootNode
+  const cfgs = new Map<string, CFG>()
+
+  const fnTypes = [
+    'function_declaration',
+    'generator_function_declaration',
+    'method_definition',
+    'arrow_function',
+    'function_expression',
+    'function_definition',  // Python
+  ]
+
+  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. */
+export function getSuccessors(cfg: CFG, nodeId: number): number[] {
+  const edges = cfg.edges.get(nodeId)
+  if (!edges) return []
+  return edges.map(e => e.to)
+}
+
+/** Get all predecessor node ids for a given node. */
+export function getPredecessors(cfg: CFG, nodeId: number): number[] {
+  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. */
+export function isReachable(cfg: CFG, fromId: number, toId: number): boolean {
+  if (fromId === toId) return true
+  const visited = new Set<number>()
+  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 {
+  private nextId = 2 // 0=entry, 1=exit
+  private nodes = new Map<number, CFGNode>()
+  private edges = new Map<number, CFGEdge[]>()
+  private reverseEdges = new Map<number, CFGEdge[]>()
+
+  private loopStack: LoopFrame[] = []
+  private switchStack: SwitchFrame[] = []
+  private tryStack: TryFrame[] = []
+  private _pendingLabel?: string
+
+  constructor(
+    private fnNode: Parser.SyntaxNode,
+    private fnName: string,
+  ) {}
+
+  build(): CFG {
+    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: PendingExit[] = [{ 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: Parser.SyntaxNode[]): CFG {
+    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: PendingExit[] = [{ 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()
+  }
+
+  private finalize(): CFG {
+    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)
+  // ==========================================================================
+
+  private processStatement(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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
+  // --------------------------------------------------------------------------
+
+  private processPlainStatement(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    const cfgNode = this.createStatementNode(node)
+    this.connectToNode(entries, cfgNode.id)
+    return [{ nodeId: cfgNode.id, edgeKind: 'normal' }]
+  }
+
+  // --------------------------------------------------------------------------
+  // Block
+  // --------------------------------------------------------------------------
+
+  private processBlock(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    let pending = entries
+    for (const stmt of node.namedChildren) {
+      if (pending.length === 0) break
+      pending = this.processStatement(stmt, pending)
+    }
+    return pending
+  }
+
+  // --------------------------------------------------------------------------
+  // If / else
+  // --------------------------------------------------------------------------
+
+  private processIf(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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: PendingExit[] = []
+
+    // 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
+  // --------------------------------------------------------------------------
+
+  private processWhile(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    const condition = node.childForFieldName('condition')
+    const body = node.childForFieldName('body')
+
+    const condNode = this.createConditionNode(condition ?? node)
+    this.connectToNode(entries, condNode.id)
+
+    const frame: LoopFrame = {
+      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' as CFGEdgeKind }]
+
+    // Back-edge
+    this.connectToNode(bodyExits, condNode.id)
+
+    this.loopStack.pop()
+
+    return [
+      { nodeId: condNode.id, edgeKind: 'false' },
+      ...frame.breakExits,
+    ]
+  }
+
+  // --------------------------------------------------------------------------
+  // For
+  // --------------------------------------------------------------------------
+
+  private processFor(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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: CFGNode | null = null
+    if (condition) {
+      condNode = this.createConditionNode(condition)
+      this.connectToNode(pending, condNode.id)
+    }
+
+    // Update node (for continue targeting)
+    let updateNode: CFGNode | null = 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: LoopFrame = {
+      continueTarget,
+      label: this.consumeLabel(),
+      breakExits: [],
+    }
+    this.loopStack.push(frame)
+
+    // Body entries
+    const bodyEntries: PendingExit[] = 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: PendingExit[] = [...frame.breakExits]
+    if (condNode) {
+      exits.push({ nodeId: condNode.id, edgeKind: 'false' })
+    }
+    return exits
+  }
+
+  // --------------------------------------------------------------------------
+  // For-in / For-of
+  // --------------------------------------------------------------------------
+
+  private processForIn(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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 } = computeDefUse(right)
+      for (const u of uses) headerNode.uses.add(u)
+    }
+
+    this.connectToNode(entries, headerNode.id)
+
+    const frame: LoopFrame = {
+      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' as CFGEdgeKind }]
+
+    this.connectToNode(bodyExits, headerNode.id)
+
+    this.loopStack.pop()
+
+    return [
+      { nodeId: headerNode.id, edgeKind: 'false' },
+      ...frame.breakExits,
+    ]
+  }
+
+  // --------------------------------------------------------------------------
+  // Do-while
+  // --------------------------------------------------------------------------
+
+  private processDoWhile(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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: LoopFrame = {
+      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' as CFGEdgeKind }]
+
+    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
+  // --------------------------------------------------------------------------
+
+  private processTry(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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: CFGNode | null = 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 } = 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' as CFGEdgeKind }]
+
+    if (handler || exceptClauses.length > 0) {
+      this.tryStack.pop()
+    }
+
+    let catchExits: PendingExit[] = []
+    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' as CFGEdgeKind }]
+    } else if (exceptClauses.length > 0 && catchEntryNode) {
+      // Python: walk except clause bodies
+      let pending: PendingExit[] = [{ 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
+  // --------------------------------------------------------------------------
+
+  private processSwitch(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    const discriminant = node.childForFieldName('value')
+    const body = node.childForFieldName('body')
+
+    const switchNode = this.createConditionNode(discriminant ?? node)
+    this.connectToNode(entries, switchNode.id)
+
+    const frame: SwitchFrame = { 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: PendingExit[] = []
+
+    for (const caseNode of cases) {
+      const isDefault = caseNode.type === 'switch_default'
+      if (isDefault) hasDefault = true
+
+      const caseEntries: PendingExit[] = [
+        { 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
+  // --------------------------------------------------------------------------
+
+  private processReturn(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    const cfgNode = this.createStatementNode(node)
+    this.connectToNode(entries, cfgNode.id)
+    this.addEdge(cfgNode.id, 1, 'return')
+    return []
+  }
+
+  // --------------------------------------------------------------------------
+  // Throw
+  // --------------------------------------------------------------------------
+
+  private processThrow(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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
+  // --------------------------------------------------------------------------
+
+  private processBreak(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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
+  // --------------------------------------------------------------------------
+
+  private processContinue(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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
+  // --------------------------------------------------------------------------
+
+  private processLabeled(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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)
+  // --------------------------------------------------------------------------
+
+  private processWith(node: Parser.SyntaxNode, entries: PendingExit[]): PendingExit[] {
+    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' }]
+  }
+
+  private consumeLabel(): string | undefined {
+    const label = this._pendingLabel
+    this._pendingLabel = undefined
+    return label
+  }
+
+  // ==========================================================================
+  // Node Creation
+  // ==========================================================================
+
+  private createNode(
+    kind: CFGNodeKind,
+    astNode: Parser.SyntaxNode | null,
+    line: number,
+    label: string,
+  ): CFGNode {
+    const id = kind === 'entry' ? 0 : kind === 'exit' ? 1 : this.nextId++
+    const node: CFGNode = {
+      id,
+      kind,
+      astNode,
+      defs: new Set(),
+      uses: new Set(),
+      line,
+      label,
+    }
+    this.nodes.set(id, node)
+    return node
+  }
+
+  private createStatementNode(astNode: Parser.SyntaxNode): CFGNode {
+    const { defs, uses } = computeDefUse(astNode)
+    const node = this.createNode(
+      'statement',
+      astNode,
+      astNode.startPosition.row + 1,
+      truncate(astNode.text, 40),
+    )
+    node.defs = defs
+    node.uses = uses
+    return node
+  }
+
+  private createConditionNode(astNode: Parser.SyntaxNode): CFGNode {
+    const { defs, uses } = 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
+  // ==========================================================================
+
+  private addEdge(from: number, to: number, kind: CFGEdgeKind): void {
+    const edge: CFGEdge = { 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)
+  }
+
+  private connectToNode(exits: PendingExit[], targetId: number): void {
+    for (const exit of exits) {
+      this.addEdge(exit.nodeId, targetId, exit.edgeKind)
+    }
+  }
+
+  // ==========================================================================
+  // Utility Helpers
+  // ==========================================================================
+
+  private getFunctionBody(): Parser.SyntaxNode | null {
+    if (this.fnNode.type === 'program' || this.fnNode.type === 'module') return null // module-level uses buildFromStatements
+    return this.fnNode.childForFieldName('body')
+  }
+
+  private getStatements(body: Parser.SyntaxNode): Parser.SyntaxNode[] {
+    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. */
+  private getInnermostBreakTarget(breakNode: Parser.SyntaxNode): LoopFrame | SwitchFrame | null {
+    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: Parser.SyntaxNode): string | null {
+  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: Parser.SyntaxNode): string | null {
+  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: Parser.SyntaxNode): Parser.SyntaxNode[] {
+  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: Parser.SyntaxNode): Parser.SyntaxNode[] {
+  // 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: Parser.SyntaxNode, defs: Set<string>): void {
+  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: string, maxLen: number): string {
+  const oneLine = text.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim()
+  if (oneLine.length <= maxLen) return oneLine
+  return oneLine.slice(0, maxLen - 3) + '...'
+}