@optave/codegraph 3.8.0 → 3.9.0

package/src/ast-analysis/engine.ts

@@ -21,6 +21,7 @@ import { performance } from 'node:perf_hooks';
 import { bulkNodeIdsByFile } from '../db/index.js';
 import { debug } from '../infrastructure/logger.js';
 import { loadNative } from '../infrastructure/native.js';
+import { toErrorMessage } from '../shared/errors.js';
 import type {
   AnalysisOpts,
   AnalysisTiming,
@@ -102,12 +103,83 @@ async function getParserModule(): Promise<typeof import('../domain/parser.js')>
 
 // ─── Native standalone analysis ─────────────────────────────────────────
 
+interface NativeAnalysisNeeds {
+  complexity: boolean;
+  cfg: boolean;
+  dataflow: boolean;
+}
+
 /**
  * Try native Rust analysis for files missing complexity/CFG/dataflow data.
  * Reads source from disk, calls the native standalone functions, and stores
- * results directly on definitions/symbols. Returns the set of files that
- * were fully handled (no remaining gaps except possibly AST store).
+ * results directly on definitions/symbols.
  */
+
+/** Determine which native analyses a file still needs. */
+function detectNativeNeeds(
+  symbols: ExtractorOutput,
+  ext: string,
+  langId: string,
+  opts: { doComplexity: boolean; doCfg: boolean; doDataflow: boolean },
+): NativeAnalysisNeeds {
+  const defs = symbols.definitions || [];
+  const langSupportsComplexity = COMPLEXITY_EXTENSIONS.has(ext) || COMPLEXITY_RULES.has(langId);
+  const langSupportsCfg = CFG_EXTENSIONS.has(ext) || CFG_RULES.has(langId);
+  const langSupportsDataflow = DATAFLOW_EXTENSIONS.has(ext) || DATAFLOW_RULES.has(langId);
+
+  return {
+    complexity:
+      opts.doComplexity &&
+      langSupportsComplexity &&
+      defs.some((d) => hasFuncBody(d) && !d.complexity),
+    cfg:
+      opts.doCfg &&
+      langSupportsCfg &&
+      defs.some((d) => hasFuncBody(d) && d.cfg !== null && !Array.isArray(d.cfg?.blocks)),
+    dataflow: opts.doDataflow && !symbols.dataflow && langSupportsDataflow,
+  };
+}
+
+/** Run native analysis passes for a single file. */
+function runNativeFileAnalysis(
+  native: NativeAddon,
+  source: string,
+  absPath: string,
+  relPath: string,
+  langId: string,
+  symbols: ExtractorOutput,
+  needs: NativeAnalysisNeeds,
+): void {
+  const defs = symbols.definitions || [];
+
+  if (needs.complexity && native.analyzeComplexity) {
+    try {
+      const results = native.analyzeComplexity(source, absPath, langId);
+      storeNativeComplexityResults(results, defs);
+    } catch (err: unknown) {
+      debug(`native analyzeComplexity failed for ${relPath}: ${toErrorMessage(err)}`);
+    }
+  }
+
+  if (needs.cfg && native.buildCfgAnalysis) {
+    try {
+      const results = native.buildCfgAnalysis(source, absPath, langId);
+      storeNativeCfgResults(results, defs);
+    } catch (err: unknown) {
+      debug(`native buildCfgAnalysis failed for ${relPath}: ${toErrorMessage(err)}`);
+    }
+  }
+
+  if (needs.dataflow && native.extractDataflowAnalysis) {
+    try {
+      const result = native.extractDataflowAnalysis(source, absPath, langId);
+      if (result) symbols.dataflow = result;
+    } catch (err: unknown) {
+      debug(`native extractDataflowAnalysis failed for ${relPath}: ${toErrorMessage(err)}`);
+    }
+  }
+}
+
 function runNativeAnalysis(
   native: NativeAddon,
   fileSymbols: Map<string, ExtractorOutput>,
@@ -115,68 +187,31 @@ function runNativeAnalysis(
   opts: AnalysisOpts,
   extToLang: Map<string, string>,
 ): void {
-  const doComplexity = opts.complexity !== false;
-  const doCfg = opts.cfg !== false;
-  const doDataflow = opts.dataflow !== false;
+  const optsFlags = {
+    doComplexity: opts.complexity !== false,
+    doCfg: opts.cfg !== false,
+    doDataflow: opts.dataflow !== false,
+  };
 
   for (const [relPath, symbols] of fileSymbols) {
-    if (symbols._tree) continue; // already has WASM tree, skip native
+    if (symbols._tree) continue;
     const ext = path.extname(relPath).toLowerCase();
     const langId = symbols._langId || extToLang.get(ext);
     if (!langId) continue;
 
-    const defs = symbols.definitions || [];
-
-    const needsComplexity =
-      doComplexity &&
-      COMPLEXITY_EXTENSIONS.has(ext) &&
-      defs.some((d) => hasFuncBody(d) && !d.complexity);
-    const needsCfg =
-      doCfg &&
-      CFG_EXTENSIONS.has(ext) &&
-      defs.some((d) => hasFuncBody(d) && d.cfg !== null && !Array.isArray(d.cfg?.blocks));
-    const needsDataflow = doDataflow && !symbols.dataflow && DATAFLOW_EXTENSIONS.has(ext);
+    const needs = detectNativeNeeds(symbols, ext, langId, optsFlags);
+    if (!needs.complexity && !needs.cfg && !needs.dataflow) continue;
 
-    if (!needsComplexity && !needsCfg && !needsDataflow) continue;
-
-    // Read source from disk
     const absPath = path.join(rootDir, relPath);
     let source: string;
     try {
       source = fs.readFileSync(absPath, 'utf-8');
-    } catch {
+    } catch (e) {
+      debug(`runNativeAnalysis: failed to read ${relPath}: ${toErrorMessage(e)}`);
       continue;
     }
 
-    // Complexity
-    if (needsComplexity && native.analyzeComplexity) {
-      try {
-        const results = native.analyzeComplexity(source, absPath);
-        storeNativeComplexityResults(results, defs);
-      } catch (err: unknown) {
-        debug(`native analyzeComplexity failed for ${relPath}: ${(err as Error).message}`);
-      }
-    }
-
-    // CFG
-    if (needsCfg && native.buildCfgAnalysis) {
-      try {
-        const results = native.buildCfgAnalysis(source, absPath);
-        storeNativeCfgResults(results, defs);
-      } catch (err: unknown) {
-        debug(`native buildCfgAnalysis failed for ${relPath}: ${(err as Error).message}`);
-      }
-    }
-
-    // Dataflow
-    if (needsDataflow && native.extractDataflowAnalysis) {
-      try {
-        const result = native.extractDataflowAnalysis(source, absPath);
-        if (result) symbols.dataflow = result;
-      } catch (err: unknown) {
-        debug(`native extractDataflowAnalysis failed for ${relPath}: ${(err as Error).message}`);
-      }
-    }
+    runNativeFileAnalysis(native, source, absPath, relPath, langId, symbols, needs);
   }
 }
 
@@ -207,6 +242,12 @@ function storeNativeComplexityResults(
         maxNesting: c.maxNesting,
         halstead: c.halstead
           ? {
+              n1: c.halstead.n1,
+              n2: c.halstead.n2,
+              bigN1: c.halstead.bigN1,
+              bigN2: c.halstead.bigN2,
+              vocabulary: c.halstead.vocabulary,
+              length: c.halstead.length,
               volume: c.halstead.volume,
               difficulty: c.halstead.difficulty,
               effort: c.halstead.effort,
@@ -222,6 +263,25 @@ function storeNativeComplexityResults(
   }
 }
 
+/** Override a definition's cyclomatic complexity with a CFG-derived value and recompute MI. */
+function overrideCyclomaticFromCfg(def: Definition, cfgCyclomatic: number): void {
+  if (!def.complexity) return;
+  if (cfgCyclomatic <= 0) {
+    debug(`overrideCyclomaticFromCfg: skipping ${def.name} — cfgCyclomatic=${cfgCyclomatic}`);
+    return;
+  }
+  def.complexity.cyclomatic = cfgCyclomatic;
+  const { loc, halstead } = def.complexity;
+  const volume = halstead ? halstead.volume : 0;
+  const commentRatio = loc && loc.loc > 0 ? loc.commentLines / loc.loc : 0;
+  def.complexity.maintainabilityIndex = computeMaintainabilityIndex(
+    volume,
+    cfgCyclomatic,
+    loc?.sloc ?? 0,
+    commentRatio,
+  );
+}
+
 /** Store native CFG results on definitions, matched by line number. */
 function storeNativeCfgResults(results: NativeFunctionCfgResult[], defs: Definition[]): void {
   const byLine = new Map<number, NativeFunctionCfgResult[]>();
@@ -248,19 +308,43 @@ function storeNativeCfgResults(results: NativeFunctionCfgResult[], defs: Definit
 
       // Override complexity cyclomatic with CFG-derived value
       const { edges, blocks } = match.cfg;
-      if (def.complexity && edges && blocks) {
-        const cfgCyclomatic = edges.length - blocks.length + 2;
-        if (cfgCyclomatic > 0) {
-          def.complexity.cyclomatic = cfgCyclomatic;
-          const { loc, halstead } = def.complexity;
-          const volume = halstead ? halstead.volume : 0;
-          const commentRatio = loc && loc.loc > 0 ? loc.commentLines / loc.loc : 0;
-          def.complexity.maintainabilityIndex = computeMaintainabilityIndex(
-            volume,
-            cfgCyclomatic,
-            loc?.sloc ?? 0,
-            commentRatio,
-          );
+      if (edges && blocks) {
+        overrideCyclomaticFromCfg(def, edges.length - blocks.length + 2);
+      }
+    }
+  }
+}
+
+// ─── CFG cyclomatic reconciliation ──────────────────────────────────────
+
+/**
+ * Apply CFG-derived cyclomatic override for definitions that already have both
+ * `complexity` and `cfg` with blocks/edges but whose cyclomatic was never
+ * overridden (e.g., native extractors provide both fields inline, so the
+ * normal override path in storeNativeCfgResults / storeCfgResults is skipped).
+ */
+/** Type guard for cfg objects with blocks and edges arrays. */
+function hasCfgBlocksAndEdges(cfg: unknown): cfg is { blocks: unknown[]; edges: unknown[] } {
+  return (
+    cfg != null &&
+    typeof cfg === 'object' &&
+    Array.isArray((cfg as { blocks?: unknown }).blocks) &&
+    Array.isArray((cfg as { edges?: unknown }).edges)
+  );
+}
+
+function reconcileCfgCyclomatic(fileSymbols: Map<string, ExtractorOutput>): void {
+  for (const [, symbols] of fileSymbols) {
+    const defs = symbols.definitions || [];
+    for (const def of defs) {
+      if (
+        (def.kind === 'function' || def.kind === 'method') &&
+        def.complexity &&
+        hasCfgBlocksAndEdges(def.cfg)
+      ) {
+        const cfgCyclomatic = Math.max(def.cfg.edges.length - def.cfg.blocks.length + 2, 1);
+        if (cfgCyclomatic !== def.complexity.cyclomatic) {
+          overrideCyclomaticFromCfg(def, cfgCyclomatic);
         }
       }
     }
@@ -287,34 +371,22 @@ async function ensureWasmTreesIfNeeded(
     const ext = path.extname(relPath).toLowerCase();
     const defs = symbols.definitions || [];
 
-    // Only consider definitions with a real function body.
-    // Interface/type property signatures are extracted as methods but correctly
-    // lack complexity/CFG data from the native engine. Exclude them by:
-    // 1. Single-line span (endLine === line) — type property on one line
-    // 2. Dotted names (e.g. "Interface.prop") — child definitions of types
-    const hasFuncBody = (d: {
-      name: string;
-      kind: string;
-      line: number;
-      endLine?: number | null;
-    }) =>
-      (d.kind === 'function' || d.kind === 'method') &&
-      d.line > 0 &&
-      d.endLine != null &&
-      d.endLine > d.line &&
-      !d.name.includes('.');
-
     // AST: need tree when native didn't provide non-call astNodes
-    const needsAst = doAst && !Array.isArray(symbols.astNodes) && WALK_EXTENSIONS.has(ext);
+    const lid = symbols._langId || '';
+    const needsAst =
+      doAst &&
+      !Array.isArray(symbols.astNodes) &&
+      (WALK_EXTENSIONS.has(ext) || AST_TYPE_MAPS.has(lid));
     const needsComplexity =
       doComplexity &&
-      COMPLEXITY_EXTENSIONS.has(ext) &&
+      (COMPLEXITY_EXTENSIONS.has(ext) || COMPLEXITY_RULES.has(lid)) &&
       defs.some((d) => hasFuncBody(d) && !d.complexity);
     const needsCfg =
       doCfg &&
-      CFG_EXTENSIONS.has(ext) &&
+      (CFG_EXTENSIONS.has(ext) || CFG_RULES.has(lid)) &&
       defs.some((d) => hasFuncBody(d) && d.cfg !== null && !Array.isArray(d.cfg?.blocks));
-    const needsDataflow = doDataflow && !symbols.dataflow && DATAFLOW_EXTENSIONS.has(ext);
+    const needsDataflow =
+      doDataflow && !symbols.dataflow && (DATAFLOW_EXTENSIONS.has(ext) || DATAFLOW_RULES.has(lid));
 
     if (needsAst || needsComplexity || needsCfg || needsDataflow) {
       needsWasmTrees = true;
@@ -327,7 +399,7 @@ async function ensureWasmTreesIfNeeded(
       const { ensureWasmTrees } = await getParserModule();
       await ensureWasmTrees(fileSymbols, rootDir);
     } catch (err: unknown) {
-      debug(`ensureWasmTrees failed: ${(err as Error).message}`);
+      debug(`ensureWasmTrees failed: ${toErrorMessage(err)}`);
     }
   }
 }
@@ -396,9 +468,9 @@ function setupComplexityVisitorForFile(
 }
 
 /** Set up CFG visitor if any definitions need WASM CFG analysis. */
-function setupCfgVisitorForFile(defs: Definition[], langId: string, ext: string): Visitor | null {
+function setupCfgVisitorForFile(defs: Definition[], langId: string): Visitor | null {
   const cfgRulesForLang = CFG_RULES.get(langId);
-  if (!cfgRulesForLang || !CFG_EXTENSIONS.has(ext)) return null;
+  if (!cfgRulesForLang) return null;
 
   const needsWasmCfg = defs.some(
     (d) => hasFuncBody(d) && d.cfg !== null && !Array.isArray(d.cfg?.blocks),
@@ -432,12 +504,12 @@ function setupVisitors(
     opts.complexity !== false ? setupComplexityVisitorForFile(defs, langId, walkerOpts) : null;
   if (complexityVisitor) visitors.push(complexityVisitor);
 
-  const cfgVisitor = opts.cfg !== false ? setupCfgVisitorForFile(defs, langId, ext) : null;
+  const cfgVisitor = opts.cfg !== false ? setupCfgVisitorForFile(defs, langId) : null;
   if (cfgVisitor) visitors.push(cfgVisitor);
 
   let dataflowVisitor: Visitor | null = null;
   const dfRules = DATAFLOW_RULES.get(langId);
-  if (opts.dataflow !== false && dfRules && DATAFLOW_EXTENSIONS.has(ext) && !symbols.dataflow) {
+  if (opts.dataflow !== false && dfRules && !symbols.dataflow) {
     dataflowVisitor = createDataflowVisitor(dfRules);
     visitors.push(dataflowVisitor);
   }
@@ -510,17 +582,8 @@ function storeCfgResults(results: WalkResults, defs: Definition[]): void {
       def.cfg = { blocks: cfgResult.blocks, edges: cfgResult.edges };
 
       // Override complexity's cyclomatic with CFG-derived value (single source of truth)
-      if (def.complexity && cfgResult.cyclomatic != null) {
-        def.complexity.cyclomatic = cfgResult.cyclomatic;
-        const { loc, halstead } = def.complexity;
-        const volume = halstead ? halstead.volume : 0;
-        const commentRatio = loc && loc.loc > 0 ? loc.commentLines / loc.loc : 0;
-        def.complexity.maintainabilityIndex = computeMaintainabilityIndex(
-          volume,
-          cfgResult.cyclomatic,
-          loc?.sloc ?? 0,
-          commentRatio,
-        );
+      if (cfgResult.cyclomatic != null) {
+        overrideCyclomaticFromCfg(def, cfgResult.cyclomatic);
       }
     }
   }
@@ -542,7 +605,7 @@ async function delegateToBuildFunctions(
       const { buildAstNodes } = await import('../features/ast.js');
       await buildAstNodes(db, fileSymbols as Map<string, any>, rootDir, engineOpts);
     } catch (err: unknown) {
-      debug(`buildAstNodes failed: ${(err as Error).message}`);
+      debug(`buildAstNodes failed: ${toErrorMessage(err)}`);
     }
     timing.astMs = performance.now() - t0;
   }
@@ -553,7 +616,7 @@ async function delegateToBuildFunctions(
       const { buildComplexityMetrics } = await import('../features/complexity.js');
       await buildComplexityMetrics(db, fileSymbols as Map<string, any>, rootDir, engineOpts);
     } catch (err: unknown) {
-      debug(`buildComplexityMetrics failed: ${(err as Error).message}`);
+      debug(`buildComplexityMetrics failed: ${toErrorMessage(err)}`);
     }
     timing.complexityMs = performance.now() - t0;
   }
@@ -564,7 +627,7 @@ async function delegateToBuildFunctions(
       const { buildCFGData } = await import('../features/cfg.js');
       await buildCFGData(db, fileSymbols, rootDir, engineOpts);
     } catch (err: unknown) {
-      debug(`buildCFGData failed: ${(err as Error).message}`);
+      debug(`buildCFGData failed: ${toErrorMessage(err)}`);
     }
     timing.cfgMs = performance.now() - t0;
   }
@@ -575,7 +638,7 @@ async function delegateToBuildFunctions(
       const { buildDataflowEdges } = await import('../features/dataflow.js');
       await buildDataflowEdges(db, fileSymbols, rootDir, engineOpts);
     } catch (err: unknown) {
-      debug(`buildDataflowEdges failed: ${(err as Error).message}`);
+      debug(`buildDataflowEdges failed: ${toErrorMessage(err)}`);
     }
     timing.dataflowMs = performance.now() - t0;
   }
@@ -644,6 +707,15 @@ export async function runAnalyses(
 
   timing._unifiedWalkMs = performance.now() - t0walk;
 
+  // Reconcile: apply CFG-derived cyclomatic override for any definitions that have
+  // both precomputed complexity and CFG data but whose cyclomatic was never overridden.
+  // This closes a parity gap where native extractors provide both fields inline but
+  // the override step (storeNativeCfgResults / storeCfgResults) is skipped because
+  // detectNativeNeeds sees both as already present.
+  if (doComplexity && doCfg) {
+    reconcileCfgCyclomatic(fileSymbols);
+  }
+
   // Delegate to buildXxx functions for DB writes + native fallback
   await delegateToBuildFunctions(db, fileSymbols, rootDir, opts, engineOpts, timing);
 

package/src/ast-analysis/metrics.ts

@@ -9,6 +9,16 @@ import type { HalsteadDerivedMetrics, LOCMetrics, TreeSitterNode } from '../type
 
 // ─── Halstead Derived Metrics ─────────────────────────────────────────────
 
+/** Halstead delivered-bugs denominator (industry standard: V / 3000). */
+const HALSTEAD_BUGS_DIVISOR = 3000;
+
+/** Sum all values in a count map. */
+function sumCounts(map: Map<string, number>): number {
+  let total = 0;
+  for (const c of map.values()) total += c;
+  return total;
+}
+
 /**
  * Compute Halstead derived metrics from raw operator/operand counts.
  *
@@ -22,17 +32,15 @@ export function computeHalsteadDerived(
 ): HalsteadDerivedMetrics {
   const n1 = operators.size;
   const n2 = operands.size;
-  let bigN1 = 0;
-  for (const c of operators.values()) bigN1 += c;
-  let bigN2 = 0;
-  for (const c of operands.values()) bigN2 += c;
+  const bigN1 = sumCounts(operators);
+  const bigN2 = sumCounts(operands);
 
   const vocabulary = n1 + n2;
   const length = bigN1 + bigN2;
   const volume = vocabulary > 0 ? length * Math.log2(vocabulary) : 0;
   const difficulty = n2 > 0 ? (n1 / 2) * (bigN2 / n2) : 0;
   const effort = difficulty * volume;
-  const bugs = volume / 3000;
+  const bugs = volume / HALSTEAD_BUGS_DIVISOR;
 
   return {
     n1,
@@ -97,10 +105,20 @@ export function computeLOCMetrics(functionNode: TreeSitterNode, language?: strin
 // ─── Maintainability Index ────────────────────────────────────────────────
 
 /**
- * Compute normalized Maintainability Index (0-100 scale).
- *
- * Original SEI formula: MI = 171 - 5.2*ln(V) - 0.23*G - 16.2*ln(LOC) + 50*sin(sqrt(2.4*CM))
+ * SEI Maintainability Index formula coefficients.
+ * Original: MI = 171 - 5.2*ln(V) - 0.23*G - 16.2*ln(LOC) + 50*sin(sqrt(2.4*CM))
  * Microsoft normalization: max(0, min(100, MI * 100/171))
+ */
+const MI_BASE = 171;
+const MI_VOLUME_COEFF = 5.2;
+const MI_CYCLOMATIC_COEFF = 0.23;
+const MI_LOC_COEFF = 16.2;
+const MI_COMMENT_AMPLITUDE = 50;
+const MI_COMMENT_SCALE = 2.4;
+const MI_NORMALIZE_SCALE = 100;
+
+/**
+ * Compute normalized Maintainability Index (0-100 scale).
  *
  * @param {number} volume - Halstead volume
  * @param {number} cyclomatic - Cyclomatic complexity
@@ -117,12 +135,16 @@ export function computeMaintainabilityIndex(
   const safeVolume = Math.max(volume, 1);
   const safeSLOC = Math.max(sloc, 1);
 
-  let mi = 171 - 5.2 * Math.log(safeVolume) - 0.23 * cyclomatic - 16.2 * Math.log(safeSLOC);
+  let mi =
+    MI_BASE -
+    MI_VOLUME_COEFF * Math.log(safeVolume) -
+    MI_CYCLOMATIC_COEFF * cyclomatic -
+    MI_LOC_COEFF * Math.log(safeSLOC);
 
   if (commentRatio != null && commentRatio > 0) {
-    mi += 50 * Math.sin(Math.sqrt(2.4 * commentRatio));
+    mi += MI_COMMENT_AMPLITUDE * Math.sin(Math.sqrt(MI_COMMENT_SCALE * commentRatio));
   }
 
-  const normalized = Math.max(0, Math.min(100, (mi * 100) / 171));
+  const normalized = Math.max(0, Math.min(MI_NORMALIZE_SCALE, (mi * MI_NORMALIZE_SCALE) / MI_BASE));
   return +normalized.toFixed(1);
 }

package/src/ast-analysis/shared.ts

@@ -150,6 +150,38 @@ export function makeDataflowRules(overrides: Partial<DataflowRulesConfig>): Data
 
 // ─── AST Helpers ──────────────────────────────────────────────────────────
 
+/** Compute the span (row count) of a tree-sitter node. */
+function nodeSpan(node: TreeSitterNode): number {
+  return node.endPosition.row - node.startPosition.row;
+}
+
+/**
+ * Recursively search for the narrowest function node at the target line.
+ */
+function searchFunctionNode(
+  node: TreeSitterNode,
+  targetStart: number,
+  functionNodeTypes: Set<string>,
+  best: TreeSitterNode | null,
+): TreeSitterNode | null {
+  const nodeStart = node.startPosition.row;
+  const nodeEnd = node.endPosition.row;
+
+  // Prune branches outside range
+  if (nodeEnd < targetStart || nodeStart > targetStart + 1) return best;
+
+  if (functionNodeTypes.has(node.type) && nodeStart === targetStart) {
+    if (!best || nodeSpan(node) < nodeSpan(best)) {
+      best = node;
+    }
+  }
+
+  for (let i = 0; i < node.childCount; i++) {
+    best = searchFunctionNode(node.child(i)!, targetStart, functionNodeTypes, best);
+  }
+  return best;
+}
+
 export function findFunctionNode(
   rootNode: TreeSitterNode,
   startLine: number,
@@ -158,30 +190,7 @@ export function findFunctionNode(
 ): TreeSitterNode | null {
   // tree-sitter lines are 0-indexed
   const targetStart = startLine - 1;
-
-  let best: TreeSitterNode | null = null;
-
-  function search(node: TreeSitterNode): void {
-    const nodeStart = node.startPosition.row;
-    const nodeEnd = node.endPosition.row;
-
-    // Prune branches outside range
-    if (nodeEnd < targetStart || nodeStart > targetStart + 1) return;
-
-    if (rules.functionNodes.has(node.type) && nodeStart === targetStart) {
-      // Found a function node at the right position — pick it
-      if (!best || nodeEnd - nodeStart < best.endPosition.row - best.startPosition.row) {
-        best = node;
-      }
-    }
-
-    for (let i = 0; i < node.childCount; i++) {
-      search(node.child(i)!);
-    }
-  }
-
-  search(rootNode);
-  return best;
+  return searchFunctionNode(rootNode, targetStart, rules.functionNodes, null);
 }
 
 // ─── Extension / Language Mapping ─────────────────────────────────────────

package/src/ast-analysis/visitor-utils.ts

@@ -88,6 +88,41 @@ export function extractParams(
   return result;
 }
 
+/** Extract names from a rest parameter (e.g. `...args`). */
+function extractRestParamNames(node: TreeSitterNode, rules: LanguageRules): string[] {
+  const nameNode = node.childForFieldName('name');
+  if (nameNode) return [nameNode.text];
+  for (const child of node.namedChildren) {
+    if (child.type === rules.paramIdentifier) return [child.text];
+  }
+  return [];
+}
+
+/** Extract names from an object destructuring pattern (e.g. `{ a, b: c }`). */
+function extractObjectDestructNames(node: TreeSitterNode, rules: LanguageRules): string[] {
+  const names: string[] = [];
+  for (const child of node.namedChildren) {
+    if (rules.shorthandPropPattern && child.type === rules.shorthandPropPattern) {
+      names.push(child.text);
+    } else if (rules.pairPatternType && child.type === rules.pairPatternType) {
+      const value = child.childForFieldName('value');
+      if (value) names.push(...extractParamNames(value, rules));
+    } else if (rules.restParamType && child.type === rules.restParamType) {
+      names.push(...extractParamNames(child, rules));
+    }
+  }
+  return names;
+}
+
+/** Extract names from an array destructuring pattern (e.g. `[a, b]`). */
+function extractArrayDestructNames(node: TreeSitterNode, rules: LanguageRules): string[] {
+  const names: string[] = [];
+  for (const child of node.namedChildren) {
+    names.push(...extractParamNames(child, rules));
+  }
+  return names;
+}
+
 /**
  * Extract parameter names from a single parameter node.
  */
@@ -113,35 +148,15 @@ export function extractParamNames(node: TreeSitterNode | null, rules: LanguageRu
   }
 
   if (rules.restParamType && t === rules.restParamType) {
-    const nameNode = node.childForFieldName('name');
-    if (nameNode) return [nameNode.text];
-    for (const child of node.namedChildren) {
-      if (child.type === rules.paramIdentifier) return [child.text];
-    }
-    return [];
+    return extractRestParamNames(node, rules);
   }
 
   if (rules.objectDestructType && t === rules.objectDestructType) {
-    const names: string[] = [];
-    for (const child of node.namedChildren) {
-      if (rules.shorthandPropPattern && child.type === rules.shorthandPropPattern) {
-        names.push(child.text);
-      } else if (rules.pairPatternType && child.type === rules.pairPatternType) {
-        const value = child.childForFieldName('value');
-        if (value) names.push(...extractParamNames(value, rules));
-      } else if (rules.restParamType && child.type === rules.restParamType) {
-        names.push(...extractParamNames(child, rules));
-      }
-    }
-    return names;
+    return extractObjectDestructNames(node, rules);
   }
 
   if (rules.arrayDestructType && t === rules.arrayDestructType) {
-    const names: string[] = [];
-    for (const child of node.namedChildren) {
-      names.push(...extractParamNames(child, rules));
-    }
-    return names;
+    return extractArrayDestructNames(node, rules);
   }
 
   return [];
@@ -155,6 +170,19 @@ export function isIdent(nodeType: string, rules: LanguageRules): boolean {
   return rules.extraIdentifierTypes ? rules.extraIdentifierTypes.has(nodeType) : false;
 }
 
+/** Resolve callee name from an optional chain node (e.g. `obj?.method()`). */
+function resolveOptionalChainCallee(fn: TreeSitterNode, rules: LanguageRules): string | null {
+  const target = fn.namedChildren[0];
+  if (!target) return null;
+  if (target.type === rules.memberNode) {
+    const prop = target.childForFieldName(rules.memberPropertyField);
+    return prop ? prop.text : null;
+  }
+  if (target.type === 'identifier') return target.text;
+  const prop = fn.childForFieldName(rules.memberPropertyField);
+  return prop ? prop.text : null;
+}
+
 /**
  * Resolve the name a call expression is calling using rules.
  */
@@ -170,15 +198,7 @@ export function resolveCalleeName(callNode: TreeSitterNode, rules: LanguageRules
     return prop ? prop.text : null;
   }
   if (rules.optionalChainNode && fn.type === rules.optionalChainNode) {
-    const target = fn.namedChildren[0];
-    if (!target) return null;
-    if (target.type === rules.memberNode) {
-      const prop = target.childForFieldName(rules.memberPropertyField);
-      return prop ? prop.text : null;
-    }
-    if (target.type === 'identifier') return target.text;
-    const prop = fn.childForFieldName(rules.memberPropertyField);
-    return prop ? prop.text : null;
+    return resolveOptionalChainCallee(fn, rules);
   }
   return null;
 }