@optave/codegraph 3.3.0 → 3.4.0

package/src/ast-analysis/visitors/{cfg-visitor.js → cfg-visitor.ts}

@@ -1,45 +1,92 @@
-/**
- * Visitor: Build intraprocedural Control Flow Graphs (CFGs) from tree-sitter AST.
- *
- * Replaces the statement-level traversal in cfg.js (buildFunctionCFG) with a
- * node-level visitor that plugs into the unified walkWithVisitors framework.
- * This eliminates the last redundant tree traversal (Mode B) in engine.js,
- * unifying all 4 analyses into a single DFS walk.
- *
- * The visitor builds basic blocks and edges incrementally via enterNode/exitNode
- * hooks, using a control-flow frame stack to track branch/loop/switch context.
- */
-
-// ── Node-type predicates ────────────────────────────────────────────────
-
-function isIfNode(type, cfgRules) {
+import type { TreeSitterNode, Visitor, VisitorContext } from '../../types.js';
+
+// biome-ignore lint/suspicious/noExplicitAny: CFG rules are opaque language-specific objects
+type AnyRules = any;
+
+function nn(node: TreeSitterNode | null, context?: string): TreeSitterNode {
+  if (node === null) {
+    throw new Error(`Unexpected null tree-sitter node${context ? ` (${context})` : ''}`);
+  }
+  return node;
+}
+
+interface CfgBlockInternal {
+  index: number;
+  type: string;
+  startLine: number | null;
+  endLine: number | null;
+  label: string | null;
+}
+
+interface CfgEdgeInternal {
+  sourceIndex: number;
+  targetIndex: number;
+  kind: string;
+}
+
+interface LabelCtx {
+  headerBlock: CfgBlockInternal | null;
+  exitBlock: CfgBlockInternal | null;
+}
+
+interface LoopCtx {
+  headerBlock: CfgBlockInternal;
+  exitBlock: CfgBlockInternal;
+}
+
+interface FuncState {
+  blocks: CfgBlockInternal[];
+  edges: CfgEdgeInternal[];
+  makeBlock(
+    type: string,
+    startLine?: number | null,
+    endLine?: number | null,
+    label?: string | null,
+  ): CfgBlockInternal;
+  addEdge(source: CfgBlockInternal, target: CfgBlockInternal, kind: string): void;
+  entryBlock: CfgBlockInternal;
+  exitBlock: CfgBlockInternal;
+  currentBlock: CfgBlockInternal | null;
+  loopStack: LoopCtx[];
+  labelMap: Map<string, LabelCtx>;
+  cfgStack: FuncState[];
+  funcNode: TreeSitterNode | null;
+}
+
+interface CFGResultInternal {
+  funcNode: TreeSitterNode;
+  blocks: CfgBlockInternal[];
+  edges: CfgEdgeInternal[];
+  cyclomatic: number;
+}
+
+function isIfNode(type: string, cfgRules: AnyRules): boolean {
   return type === cfgRules.ifNode || cfgRules.ifNodes?.has(type);
 }
 
-function isForNode(type, cfgRules) {
+function isForNode(type: string, cfgRules: AnyRules): boolean {
   return cfgRules.forNodes.has(type);
 }
 
-function isWhileNode(type, cfgRules) {
+function isWhileNode(type: string, cfgRules: AnyRules): boolean {
   return type === cfgRules.whileNode || cfgRules.whileNodes?.has(type);
 }
 
-function isSwitchNode(type, cfgRules) {
+function isSwitchNode(type: string, cfgRules: AnyRules): boolean {
   return type === cfgRules.switchNode || cfgRules.switchNodes?.has(type);
 }
 
-function isCaseNode(type, cfgRules) {
+function isCaseNode(type: string, cfgRules: AnyRules): boolean {
   return (
     type === cfgRules.caseNode || type === cfgRules.defaultNode || cfgRules.caseNodes?.has(type)
   );
 }
 
-function isBlockNode(type, cfgRules) {
+function isBlockNode(type: string, cfgRules: AnyRules): boolean {
   return type === 'statement_list' || type === cfgRules.blockNode || cfgRules.blockNodes?.has(type);
 }
 
-/** Check if a node is a control-flow statement that we handle specially */
-function isControlFlow(type, cfgRules) {
+function isControlFlow(type: string, cfgRules: AnyRules): boolean {
   return (
     isIfNode(type, cfgRules) ||
     (cfgRules.unlessNode && type === cfgRules.unlessNode) ||
@@ -58,24 +105,20 @@ function isControlFlow(type, cfgRules) {
   );
 }
 
-// ── Utility functions ───────────────────────────────────────────────────
-
-/**
- * Get the actual control-flow node (unwrapping expression_statement if needed).
- */
-function effectiveNode(node, cfgRules) {
+function effectiveNode(node: TreeSitterNode, cfgRules: AnyRules): TreeSitterNode {
   if (node.type === 'expression_statement' && node.namedChildCount === 1) {
-    const inner = node.namedChild(0);
+    const inner = nn(node.namedChild(0));
     if (isControlFlow(inner.type, cfgRules)) return inner;
   }
   return node;
 }
 
-/**
- * Register a loop/switch in label map for labeled break/continue.
- */
-function registerLabelCtx(S, headerBlock, exitBlock) {
-  for (const [, ctx] of S.labelMap) {
+function registerLabelCtx(
+  S: FuncState,
+  headerBlock: CfgBlockInternal,
+  exitBlock: CfgBlockInternal,
+): void {
+  for (const [, ctx] of Array.from(S.labelMap)) {
     if (!ctx.headerBlock) {
       ctx.headerBlock = headerBlock;
       ctx.exitBlock = exitBlock;
@@ -83,19 +126,15 @@ function registerLabelCtx(S, headerBlock, exitBlock) {
   }
 }
 
-/**
- * Get statements from a body node (block or single statement).
- * Returns effective (unwrapped) nodes.
- */
-function getBodyStatements(bodyNode, cfgRules) {
+function getBodyStatements(bodyNode: TreeSitterNode | null, cfgRules: AnyRules): TreeSitterNode[] {
   if (!bodyNode) return [];
   if (isBlockNode(bodyNode.type, cfgRules)) {
-    const stmts = [];
+    const stmts: TreeSitterNode[] = [];
     for (let i = 0; i < bodyNode.namedChildCount; i++) {
-      const child = bodyNode.namedChild(i);
+      const child = nn(bodyNode.namedChild(i));
       if (child.type === 'statement_list') {
         for (let j = 0; j < child.namedChildCount; j++) {
-          stmts.push(child.namedChild(j));
+          stmts.push(nn(child.namedChild(j)));
         }
       } else {
         stmts.push(child);
@@ -106,18 +145,23 @@ function getBodyStatements(bodyNode, cfgRules) {
   return [bodyNode];
 }
 
-function makeFuncState() {
-  const blocks = [];
-  const edges = [];
+function makeFuncState(): FuncState {
+  const blocks: CfgBlockInternal[] = [];
+  const edges: CfgEdgeInternal[] = [];
   let nextIndex = 0;
 
-  function makeBlock(type, startLine = null, endLine = null, label = null) {
-    const block = { index: nextIndex++, type, startLine, endLine, label };
+  function makeBlock(
+    type: string,
+    startLine: number | null = null,
+    endLine: number | null = null,
+    label: string | null = null,
+  ): CfgBlockInternal {
+    const block: CfgBlockInternal = { index: nextIndex++, type, startLine, endLine, label };
     blocks.push(block);
     return block;
   }
 
-  function addEdge(source, target, kind) {
+  function addEdge(source: CfgBlockInternal, target: CfgBlockInternal, kind: string): void {
     edges.push({ sourceIndex: source.index, targetIndex: target.index, kind });
   }
 
@@ -141,10 +185,13 @@ function makeFuncState() {
   };
 }
 
-// ── Statement processors ────────────────────────────────────────────────
-
-function processStatements(stmts, currentBlock, S, cfgRules) {
-  let cur = currentBlock;
+function processStatements(
+  stmts: TreeSitterNode[],
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal | null {
+  let cur: CfgBlockInternal | null = currentBlock;
   for (const stmt of stmts) {
     if (!cur) break;
     cur = processStatement(stmt, cur, S, cfgRules);
@@ -152,7 +199,12 @@ function processStatements(stmts, currentBlock, S, cfgRules) {
   return cur;
 }
 
-function processStatement(stmt, currentBlock, S, cfgRules) {
+function processStatement(
+  stmt: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal | null {
   if (!stmt || !currentBlock) return currentBlock;
 
   const effNode = effectiveNode(stmt, cfgRules);
@@ -199,7 +251,6 @@ function processStatement(stmt, currentBlock, S, cfgRules) {
     return processContinue(effNode, currentBlock, S);
   }
 
-  // Regular statement — extend current block
   if (!currentBlock.startLine) {
     currentBlock.startLine = stmt.startPosition.row + 1;
   }
@@ -207,14 +258,17 @@ function processStatement(stmt, currentBlock, S, cfgRules) {
   return currentBlock;
 }
 
-// ── Labeled / break / continue ──────────────────────────────────────────
-
-function processLabeled(node, currentBlock, S, cfgRules) {
+function processLabeled(
+  node: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal | null {
   const labelNode = node.childForFieldName('label');
   const labelName = labelNode ? labelNode.text : null;
   const body = node.childForFieldName('body');
   if (body && labelName) {
-    const labelCtx = { headerBlock: null, exitBlock: null };
+    const labelCtx: LabelCtx = { headerBlock: null, exitBlock: null };
     S.labelMap.set(labelName, labelCtx);
     const result = processStatement(body, currentBlock, S, cfgRules);
     S.labelMap.delete(labelName);
@@ -223,15 +277,19 @@ function processLabeled(node, currentBlock, S, cfgRules) {
   return currentBlock;
 }
 
-function processBreak(node, currentBlock, S) {
+function processBreak(
+  node: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+): CfgBlockInternal | null {
   const labelNode = node.childForFieldName('label');
   const labelName = labelNode ? labelNode.text : null;
 
-  let target = null;
+  let target: CfgBlockInternal | null = null;
   if (labelName && S.labelMap.has(labelName)) {
-    target = S.labelMap.get(labelName).exitBlock;
+    target = (S.labelMap.get(labelName) as LabelCtx).exitBlock;
   } else if (S.loopStack.length > 0) {
-    target = S.loopStack[S.loopStack.length - 1].exitBlock;
+    target = S.loopStack[S.loopStack.length - 1]!.exitBlock;
   }
 
   if (target) {
@@ -242,15 +300,19 @@ function processBreak(node, currentBlock, S) {
   return currentBlock;
 }
 
-function processContinue(node, currentBlock, S) {
+function processContinue(
+  node: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+): CfgBlockInternal | null {
   const labelNode = node.childForFieldName('label');
   const labelName = labelNode ? labelNode.text : null;
 
-  let target = null;
+  let target: CfgBlockInternal | null = null;
   if (labelName && S.labelMap.has(labelName)) {
-    target = S.labelMap.get(labelName).headerBlock;
+    target = (S.labelMap.get(labelName) as LabelCtx).headerBlock;
   } else if (S.loopStack.length > 0) {
-    target = S.loopStack[S.loopStack.length - 1].headerBlock;
+    target = S.loopStack[S.loopStack.length - 1]!.headerBlock;
   }
 
   if (target) {
@@ -261,9 +323,12 @@ function processContinue(node, currentBlock, S) {
   return currentBlock;
 }
 
-// ── If / else-if / else ─────────────────────────────────────────────────
-
-function processIf(ifStmt, currentBlock, S, cfgRules) {
+function processIf(
+  ifStmt: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal {
   currentBlock.endLine = ifStmt.startPosition.row + 1;
 
   const condBlock = S.makeBlock(
@@ -276,7 +341,6 @@ function processIf(ifStmt, currentBlock, S, cfgRules) {
 
   const joinBlock = S.makeBlock('body');
 
-  // True branch
   const consequentField = cfgRules.ifConsequentField || 'consequence';
   const consequent = ifStmt.childForFieldName(consequentField);
   const trueBlock = S.makeBlock('branch_true', null, null, 'then');
@@ -287,7 +351,6 @@ function processIf(ifStmt, currentBlock, S, cfgRules) {
     S.addEdge(trueEnd, joinBlock, 'fallthrough');
   }
 
-  // False branch
   if (cfgRules.elifNode) {
     processElifSiblings(ifStmt, condBlock, joinBlock, S, cfgRules);
   } else {
@@ -297,7 +360,13 @@ function processIf(ifStmt, currentBlock, S, cfgRules) {
   return joinBlock;
 }
 
-function processAlternative(ifStmt, condBlock, joinBlock, S, cfgRules) {
+function processAlternative(
+  ifStmt: TreeSitterNode,
+  condBlock: CfgBlockInternal,
+  joinBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): void {
   const alternative = ifStmt.childForFieldName('alternative');
   if (!alternative) {
     S.addEdge(condBlock, joinBlock, 'branch_false');
@@ -305,7 +374,6 @@ function processAlternative(ifStmt, condBlock, joinBlock, S, cfgRules) {
   }
 
   if (cfgRules.elseViaAlternative && alternative.type !== cfgRules.elseClause) {
-    // Pattern C: direct alternative (Go, Java, C#)
     if (isIfNode(alternative.type, cfgRules)) {
       const falseBlock = S.makeBlock('branch_false', null, null, 'else-if');
       S.addEdge(condBlock, falseBlock, 'branch_false');
@@ -319,15 +387,14 @@ function processAlternative(ifStmt, condBlock, joinBlock, S, cfgRules) {
       if (falseEnd) S.addEdge(falseEnd, joinBlock, 'fallthrough');
     }
   } else if (alternative.type === cfgRules.elseClause) {
-    // Pattern A: else_clause wrapper (JS/TS, Rust)
-    const elseChildren = [];
+    const elseChildren: TreeSitterNode[] = [];
     for (let i = 0; i < alternative.namedChildCount; i++) {
-      elseChildren.push(alternative.namedChild(i));
+      elseChildren.push(nn(alternative.namedChild(i)));
     }
-    if (elseChildren.length === 1 && isIfNode(elseChildren[0].type, cfgRules)) {
+    if (elseChildren.length === 1 && isIfNode(elseChildren[0]!.type, cfgRules)) {
       const falseBlock = S.makeBlock('branch_false', null, null, 'else-if');
       S.addEdge(condBlock, falseBlock, 'branch_false');
-      const elseIfEnd = processIf(elseChildren[0], falseBlock, S, cfgRules);
+      const elseIfEnd = processIf(elseChildren[0]!, falseBlock, S, cfgRules);
       if (elseIfEnd) S.addEdge(elseIfEnd, joinBlock, 'fallthrough');
     } else {
       const falseBlock = S.makeBlock('branch_false', null, null, 'else');
@@ -338,12 +405,18 @@ function processAlternative(ifStmt, condBlock, joinBlock, S, cfgRules) {
   }
 }
 
-function processElifSiblings(ifStmt, firstCondBlock, joinBlock, S, cfgRules) {
+function processElifSiblings(
+  ifStmt: TreeSitterNode,
+  firstCondBlock: CfgBlockInternal,
+  joinBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): void {
   let lastCondBlock = firstCondBlock;
   let foundElse = false;
 
   for (let i = 0; i < ifStmt.namedChildCount; i++) {
-    const child = ifStmt.namedChild(i);
+    const child = nn(ifStmt.namedChild(i));
 
     if (child.type === cfgRules.elifNode) {
       const elifCondBlock = S.makeBlock(
@@ -368,13 +441,13 @@ function processElifSiblings(ifStmt, firstCondBlock, joinBlock, S, cfgRules) {
       S.addEdge(lastCondBlock, elseBlock, 'branch_false');
 
       const elseBody = child.childForFieldName('body');
-      let elseStmts;
+      let elseStmts: TreeSitterNode[];
       if (elseBody) {
         elseStmts = getBodyStatements(elseBody, cfgRules);
       } else {
         elseStmts = [];
         for (let j = 0; j < child.namedChildCount; j++) {
-          elseStmts.push(child.namedChild(j));
+          elseStmts.push(nn(child.namedChild(j)));
         }
       }
       const elseEnd = processStatements(elseStmts, elseBlock, S, cfgRules);
@@ -389,9 +462,12 @@ function processElifSiblings(ifStmt, firstCondBlock, joinBlock, S, cfgRules) {
   }
 }
 
-// ── Loops ───────────────────────────────────────────────────────────────
-
-function processForLoop(forStmt, currentBlock, S, cfgRules) {
+function processForLoop(
+  forStmt: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal {
   const headerBlock = S.makeBlock(
     'loop_header',
     forStmt.startPosition.row + 1,
@@ -401,7 +477,7 @@ function processForLoop(forStmt, currentBlock, S, cfgRules) {
   S.addEdge(currentBlock, headerBlock, 'fallthrough');
 
   const loopExitBlock = S.makeBlock('body');
-  const loopCtx = { headerBlock, exitBlock: loopExitBlock };
+  const loopCtx: LoopCtx = { headerBlock, exitBlock: loopExitBlock };
   S.loopStack.push(loopCtx);
   registerLabelCtx(S, headerBlock, loopExitBlock);
 
@@ -418,7 +494,12 @@ function processForLoop(forStmt, currentBlock, S, cfgRules) {
   return loopExitBlock;
 }
 
-function processWhileLoop(whileStmt, currentBlock, S, cfgRules) {
+function processWhileLoop(
+  whileStmt: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal {
   const headerBlock = S.makeBlock(
     'loop_header',
     whileStmt.startPosition.row + 1,
@@ -428,7 +509,7 @@ function processWhileLoop(whileStmt, currentBlock, S, cfgRules) {
   S.addEdge(currentBlock, headerBlock, 'fallthrough');
 
   const loopExitBlock = S.makeBlock('body');
-  const loopCtx = { headerBlock, exitBlock: loopExitBlock };
+  const loopCtx: LoopCtx = { headerBlock, exitBlock: loopExitBlock };
   S.loopStack.push(loopCtx);
   registerLabelCtx(S, headerBlock, loopExitBlock);
 
@@ -445,14 +526,19 @@ function processWhileLoop(whileStmt, currentBlock, S, cfgRules) {
   return loopExitBlock;
 }
 
-function processDoWhileLoop(doStmt, currentBlock, S, cfgRules) {
+function processDoWhileLoop(
+  doStmt: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal {
   const bodyBlock = S.makeBlock('loop_body', doStmt.startPosition.row + 1, null, 'do');
   S.addEdge(currentBlock, bodyBlock, 'fallthrough');
 
   const condBlock = S.makeBlock('loop_header', null, null, 'do-while');
   const loopExitBlock = S.makeBlock('body');
 
-  const loopCtx = { headerBlock: condBlock, exitBlock: loopExitBlock };
+  const loopCtx: LoopCtx = { headerBlock: condBlock, exitBlock: loopExitBlock };
   S.loopStack.push(loopCtx);
   registerLabelCtx(S, condBlock, loopExitBlock);
 
@@ -468,7 +554,12 @@ function processDoWhileLoop(doStmt, currentBlock, S, cfgRules) {
   return loopExitBlock;
 }
 
-function processInfiniteLoop(loopStmt, currentBlock, S, cfgRules) {
+function processInfiniteLoop(
+  loopStmt: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal {
   const headerBlock = S.makeBlock(
     'loop_header',
     loopStmt.startPosition.row + 1,
@@ -478,7 +569,7 @@ function processInfiniteLoop(loopStmt, currentBlock, S, cfgRules) {
   S.addEdge(currentBlock, headerBlock, 'fallthrough');
 
   const loopExitBlock = S.makeBlock('body');
-  const loopCtx = { headerBlock, exitBlock: loopExitBlock };
+  const loopCtx: LoopCtx = { headerBlock, exitBlock: loopExitBlock };
   S.loopStack.push(loopCtx);
   registerLabelCtx(S, headerBlock, loopExitBlock);
 
@@ -490,14 +581,16 @@ function processInfiniteLoop(loopStmt, currentBlock, S, cfgRules) {
   const bodyEnd = processStatements(bodyStmts, bodyBlock, S, cfgRules);
   if (bodyEnd) S.addEdge(bodyEnd, headerBlock, 'loop_back');
 
-  // No loop_exit from header — only via break
   S.loopStack.pop();
   return loopExitBlock;
 }
 
-// ── Switch / match ──────────────────────────────────────────────────────
-
-function processSwitch(switchStmt, currentBlock, S, cfgRules) {
+function processSwitch(
+  switchStmt: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal {
   currentBlock.endLine = switchStmt.startPosition.row + 1;
 
   const switchHeader = S.makeBlock(
@@ -509,7 +602,7 @@ function processSwitch(switchStmt, currentBlock, S, cfgRules) {
   S.addEdge(currentBlock, switchHeader, 'fallthrough');
 
   const joinBlock = S.makeBlock('body');
-  const switchCtx = { headerBlock: switchHeader, exitBlock: joinBlock };
+  const switchCtx: LoopCtx = { headerBlock: switchHeader, exitBlock: joinBlock };
   S.loopStack.push(switchCtx);
 
   const switchBody = switchStmt.childForFieldName('body');
@@ -517,7 +610,7 @@ function processSwitch(switchStmt, currentBlock, S, cfgRules) {
 
   let hasDefault = false;
   for (let i = 0; i < container.namedChildCount; i++) {
-    const caseClause = container.namedChild(i);
+    const caseClause = nn(container.namedChild(i));
 
     const isDefault = caseClause.type === cfgRules.defaultNode;
     const isCase = isDefault || isCaseNode(caseClause.type, cfgRules);
@@ -541,22 +634,22 @@ function processSwitch(switchStmt, currentBlock, S, cfgRules) {
   return joinBlock;
 }
 
-function extractCaseBody(caseClause, cfgRules) {
+function extractCaseBody(caseClause: TreeSitterNode, cfgRules: AnyRules): TreeSitterNode[] {
   const caseBodyNode =
     caseClause.childForFieldName('body') || caseClause.childForFieldName('consequence');
   if (caseBodyNode) {
     return getBodyStatements(caseBodyNode, cfgRules);
   }
 
-  const stmts = [];
+  const stmts: TreeSitterNode[] = [];
   const valueNode = caseClause.childForFieldName('value');
   const patternNode = caseClause.childForFieldName('pattern');
   for (let j = 0; j < caseClause.namedChildCount; j++) {
-    const child = caseClause.namedChild(j);
+    const child = nn(caseClause.namedChild(j));
     if (child !== valueNode && child !== patternNode && child.type !== 'switch_label') {
       if (child.type === 'statement_list') {
         for (let k = 0; k < child.namedChildCount; k++) {
-          stmts.push(child.namedChild(k));
+          stmts.push(nn(child.namedChild(k)));
         }
       } else {
         stmts.push(child);
@@ -566,17 +659,19 @@ function extractCaseBody(caseClause, cfgRules) {
   return stmts;
 }
 
-// ── Try / catch / finally ───────────────────────────────────────────────
-
-function processTryCatch(tryStmt, currentBlock, S, cfgRules) {
+function processTryCatch(
+  tryStmt: TreeSitterNode,
+  currentBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): CfgBlockInternal {
   currentBlock.endLine = tryStmt.startPosition.row + 1;
 
   const joinBlock = S.makeBlock('body');
 
-  // Try body
   const tryBody = tryStmt.childForFieldName('body');
-  let tryBodyStart;
-  let tryStmts;
+  let tryBodyStart: number;
+  let tryStmts: TreeSitterNode[];
   if (tryBody) {
     tryBodyStart = tryBody.startPosition.row + 1;
     tryStmts = getBodyStatements(tryBody, cfgRules);
@@ -584,7 +679,7 @@ function processTryCatch(tryStmt, currentBlock, S, cfgRules) {
     tryBodyStart = tryStmt.startPosition.row + 1;
     tryStmts = [];
     for (let i = 0; i < tryStmt.namedChildCount; i++) {
-      const child = tryStmt.namedChild(i);
+      const child = nn(tryStmt.namedChild(i));
       if (cfgRules.catchNode && child.type === cfgRules.catchNode) continue;
       if (cfgRules.finallyNode && child.type === cfgRules.finallyNode) continue;
       tryStmts.push(child);
@@ -595,7 +690,6 @@ function processTryCatch(tryStmt, currentBlock, S, cfgRules) {
   S.addEdge(currentBlock, tryBlock, 'fallthrough');
   const tryEnd = processStatements(tryStmts, tryBlock, S, cfgRules);
 
-  // Find catch and finally handlers
   const { catchHandler, finallyHandler } = findTryHandlers(tryStmt, cfgRules);
 
   if (catchHandler) {
@@ -609,11 +703,14 @@ function processTryCatch(tryStmt, currentBlock, S, cfgRules) {
   return joinBlock;
 }
 
-function findTryHandlers(tryStmt, cfgRules) {
-  let catchHandler = null;
-  let finallyHandler = null;
+function findTryHandlers(
+  tryStmt: TreeSitterNode,
+  cfgRules: AnyRules,
+): { catchHandler: TreeSitterNode | null; finallyHandler: TreeSitterNode | null } {
+  let catchHandler: TreeSitterNode | null = null;
+  let finallyHandler: TreeSitterNode | null = null;
   for (let i = 0; i < tryStmt.namedChildCount; i++) {
-    const child = tryStmt.namedChild(i);
+    const child = nn(tryStmt.namedChild(i));
     if (cfgRules.catchNode && child.type === cfgRules.catchNode) catchHandler = child;
     if (cfgRules.finallyNode && child.type === cfgRules.finallyNode) finallyHandler = child;
   }
@@ -621,25 +718,25 @@ function findTryHandlers(tryStmt, cfgRules) {
 }
 
 function processCatchHandler(
-  catchHandler,
-  tryBlock,
-  tryEnd,
-  finallyHandler,
-  joinBlock,
-  S,
-  cfgRules,
-) {
+  catchHandler: TreeSitterNode,
+  tryBlock: CfgBlockInternal,
+  tryEnd: CfgBlockInternal | null,
+  finallyHandler: TreeSitterNode | null,
+  joinBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): void {
   const catchBlock = S.makeBlock('catch', catchHandler.startPosition.row + 1, null, 'catch');
   S.addEdge(tryBlock, catchBlock, 'exception');
 
   const catchBodyNode = catchHandler.childForFieldName('body');
-  let catchStmts;
+  let catchStmts: TreeSitterNode[];
   if (catchBodyNode) {
     catchStmts = getBodyStatements(catchBodyNode, cfgRules);
   } else {
     catchStmts = [];
     for (let i = 0; i < catchHandler.namedChildCount; i++) {
-      catchStmts.push(catchHandler.namedChild(i));
+      catchStmts.push(nn(catchHandler.namedChild(i)));
     }
   }
   const catchEnd = processStatements(catchStmts, catchBlock, S, cfgRules);
@@ -666,7 +763,13 @@ function processCatchHandler(
   }
 }
 
-function processFinallyOnly(finallyHandler, tryEnd, joinBlock, S, cfgRules) {
+function processFinallyOnly(
+  finallyHandler: TreeSitterNode,
+  tryEnd: CfgBlockInternal | null,
+  joinBlock: CfgBlockInternal,
+  S: FuncState,
+  cfgRules: AnyRules,
+): void {
   const finallyBlock = S.makeBlock(
     'finally',
     finallyHandler.startPosition.row + 1,
@@ -683,12 +786,9 @@ function processFinallyOnly(finallyHandler, tryEnd, joinBlock, S, cfgRules) {
   if (finallyEnd) S.addEdge(finallyEnd, joinBlock, 'fallthrough');
 }
 
-// ── Enter-function body processing ──────────────────────────────────────
-
-function processFunctionBody(funcNode, S, cfgRules) {
+function processFunctionBody(funcNode: TreeSitterNode, S: FuncState, cfgRules: AnyRules): void {
   const body = funcNode.childForFieldName('body');
   if (!body) {
-    // No body — entry → exit
     S.blocks.length = 2;
     S.edges.length = 0;
     S.addEdge(S.entryBlock, S.exitBlock, 'fallthrough');
@@ -697,8 +797,7 @@ function processFunctionBody(funcNode, S, cfgRules) {
   }
 
   if (!isBlockNode(body.type, cfgRules)) {
-    // Expression body (e.g., arrow function `(x) => x + 1`)
-    const bodyBlock = S.blocks[2];
+    const bodyBlock = S.blocks[2]!;
     bodyBlock.startLine = body.startPosition.row + 1;
     bodyBlock.endLine = body.endPosition.row + 1;
     S.addEdge(bodyBlock, S.exitBlock, 'fallthrough');
@@ -706,7 +805,6 @@ function processFunctionBody(funcNode, S, cfgRules) {
     return;
   }
 
-  // Block body — process statements
   const stmts = getBodyStatements(body, cfgRules);
   if (stmts.length === 0) {
     S.blocks.length = 2;
@@ -716,7 +814,7 @@ function processFunctionBody(funcNode, S, cfgRules) {
     return;
   }
 
-  const firstBody = S.blocks[2];
+  const firstBody = S.blocks[2]!;
   const lastBlock = processStatements(stmts, firstBody, S, cfgRules);
   if (lastBlock) {
     S.addEdge(lastBlock, S.exitBlock, 'fallthrough');
@@ -724,54 +822,52 @@ function processFunctionBody(funcNode, S, cfgRules) {
   S.currentBlock = null;
 }
 
-// ── Visitor factory ─────────────────────────────────────────────────────
-
-/**
- * Create a CFG visitor for use with walkWithVisitors.
- *
- * @param {object} cfgRules - CFG_RULES for the language
- * @returns {Visitor}
- */
-export function createCfgVisitor(cfgRules) {
-  const funcStateStack = [];
-  let S = null;
-  const results = [];
+export function createCfgVisitor(cfgRules: AnyRules): Visitor {
+  const funcStateStack: FuncState[] = [];
+  let S: FuncState | null = null;
+  const results: CFGResultInternal[] = [];
 
   return {
     name: 'cfg',
     functionNodeTypes: cfgRules.functionNodes,
 
-    enterFunction(funcNode, _funcName, _context) {
+    enterFunction(
+      funcNode: TreeSitterNode,
+      _funcName: string | null,
+      _context: VisitorContext,
+    ): void {
       if (S) funcStateStack.push(S);
       S = makeFuncState();
       S.funcNode = funcNode;
       processFunctionBody(funcNode, S, cfgRules);
     },
 
-    exitFunction(funcNode, _funcName, _context) {
+    exitFunction(
+      funcNode: TreeSitterNode,
+      _funcName: string | null,
+      _context: VisitorContext,
+    ): void {
       if (S && S.funcNode === funcNode) {
         const cyclomatic = S.edges.length - S.blocks.length + 2;
         results.push({
-          funcNode: S.funcNode,
+          funcNode: S.funcNode as TreeSitterNode,
           blocks: S.blocks,
           edges: S.edges,
           cyclomatic: Math.max(cyclomatic, 1),
         });
       }
-      S = funcStateStack.length > 0 ? funcStateStack.pop() : null;
+      S = funcStateStack.length > 0 ? (funcStateStack.pop() as FuncState) : null;
     },
 
-    enterNode(_node, _context) {
-      // No-op — all CFG construction is done in enterFunction via processStatements.
-      // We intentionally do NOT return skipChildren so the walker recurses into
-      // children, allowing nested functions to trigger enterFunction/exitFunction.
+    enterNode(_node: TreeSitterNode, _context: VisitorContext): undefined {
+      // No-op
     },
 
-    exitNode(_node, _context) {
+    exitNode(_node: TreeSitterNode, _context: VisitorContext): void {
       // No-op
     },
 
-    finish() {
+    finish(): CFGResultInternal[] {
       return results;
     },
   };