Merge remote-tracking branch 'origin/main' into feat/unified-ast-analysis-framework

Impact: 74 functions changed, 55 affected

Author: carlos-alm

src/ast-analysis/engine.js

@@ -7,14 +7,12 @@
  *   - CFG construction (basic blocks + edges)
  *   - Dataflow analysis (define-use chains, arg flows, mutations)
  *
- * Two modes:
- *   Mode A (node-level visitor): AST + complexity + dataflow — single DFS per file
- *   Mode B (statement-level): CFG keeps its own traversal via buildFunctionCFG
+ * All 4 analyses run as visitors in a single DFS walk via walkWithVisitors.
  *
  * Optimization strategy: for files with WASM trees, run all applicable visitors
- * in a single walkWithVisitors call, then store results in the format that the
- * existing buildXxx functions expect as pre-computed data. This eliminates ~3
- * redundant tree traversals per file.
+ * in a single walkWithVisitors call. Store results in the format that buildXxx
+ * functions already expect as pre-computed data (same fields as native engine
+ * output). This eliminates redundant tree traversals per file.
  */
 
 import path from 'node:path';
@@ -33,6 +31,7 @@ import { buildExtensionSet, buildExtToLangMap } from './shared.js';
 import { walkWithVisitors } from './visitor.js';
 import { functionName as getFuncName } from './visitor-utils.js';
 import { createAstStoreVisitor } from './visitors/ast-store-visitor.js';
+import { createCfgVisitor } from './visitors/cfg-visitor.js';
 import { createComplexityVisitor } from './visitors/complexity-visitor.js';
 import { createDataflowVisitor } from './visitors/dataflow-visitor.js';
 
@@ -75,25 +74,15 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
   const extToLang = buildExtToLangMap();
 
   // ── WASM pre-parse for files that need it ───────────────────────────
-  if (doCfg || doDataflow) {
+  // CFG now runs as a visitor in the unified walk, so only dataflow
+  // triggers WASM pre-parse when no tree exists.
+  if (doDataflow) {
     let needsWasmTrees = false;
     for (const [relPath, symbols] of fileSymbols) {
       if (symbols._tree) continue;
       const ext = path.extname(relPath).toLowerCase();
 
-      if (doCfg && CFG_EXTENSIONS.has(ext)) {
-        const fnDefs = (symbols.definitions || []).filter(
-          (d) => (d.kind === 'function' || d.kind === 'method') && d.line,
-        );
-        if (
-          fnDefs.length > 0 &&
-          !fnDefs.every((d) => d.cfg === null || Array.isArray(d.cfg?.blocks))
-        ) {
-          needsWasmTrees = true;
-          break;
-        }
-      }
-      if (doDataflow && !symbols.dataflow && DATAFLOW_EXTENSIONS.has(ext)) {
+      if (!symbols.dataflow && DATAFLOW_EXTENSIONS.has(ext)) {
         needsWasmTrees = true;
         break;
       }
@@ -179,6 +168,24 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
       }
     }
 
+    // ─ CFG visitor ─
+    const cfgRulesForLang = CFG_RULES.get(langId);
+    let cfgVisitor = null;
+    if (doCfg && cfgRulesForLang && CFG_EXTENSIONS.has(ext)) {
+      // Only use visitor if some functions lack pre-computed CFG
+      const needsWasmCfg = defs.some(
+        (d) =>
+          (d.kind === 'function' || d.kind === 'method') &&
+          d.line &&
+          d.cfg !== null &&
+          !Array.isArray(d.cfg?.blocks),
+      );
+      if (needsWasmCfg) {
+        cfgVisitor = createCfgVisitor(cfgRulesForLang);
+        visitors.push(cfgVisitor);
+      }
+    }
+
     // ─ Dataflow visitor ─
     const dfRules = DATAFLOW_RULES.get(langId);
     let dataflowVisitor = null;
@@ -210,12 +217,21 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
       for (const r of complexityResults) {
         if (r.funcNode) {
           const line = r.funcNode.startPosition.row + 1;
-          resultByLine.set(line, r);
+          if (!resultByLine.has(line)) resultByLine.set(line, []);
+          resultByLine.get(line).push(r);
         }
       }
       for (const def of defs) {
         if ((def.kind === 'function' || def.kind === 'method') && def.line && !def.complexity) {
-          const funcResult = resultByLine.get(def.line);
+          const candidates = resultByLine.get(def.line);
+          const funcResult = !candidates
+            ? undefined
+            : candidates.length === 1
+              ? candidates[0]
+              : (candidates.find((r) => {
+                  const n = r.funcNode.childForFieldName('name');
+                  return n && n.text === def.name;
+                }) ?? candidates[0]);
           if (funcResult) {
             const { metrics } = funcResult;
             const loc = computeLOCMetrics(funcResult.funcNode, langId);
@@ -241,6 +257,54 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
       }
     }
 
+    // ─ Store CFG results on definitions (buildCFGData will find def.cfg and skip its walk) ─
+    if (cfgVisitor) {
+      const cfgResults = results.cfg || [];
+      const cfgByLine = new Map();
+      for (const r of cfgResults) {
+        if (r.funcNode) {
+          const line = r.funcNode.startPosition.row + 1;
+          if (!cfgByLine.has(line)) cfgByLine.set(line, []);
+          cfgByLine.get(line).push(r);
+        }
+      }
+      for (const def of defs) {
+        if (
+          (def.kind === 'function' || def.kind === 'method') &&
+          def.line &&
+          !def.cfg?.blocks?.length
+        ) {
+          const candidates = cfgByLine.get(def.line);
+          const cfgResult = !candidates
+            ? undefined
+            : candidates.length === 1
+              ? candidates[0]
+              : (candidates.find((r) => {
+                  const n = r.funcNode.childForFieldName('name');
+                  return n && n.text === def.name;
+                }) ?? candidates[0]);
+          if (cfgResult) {
+            def.cfg = { blocks: cfgResult.blocks, edges: cfgResult.edges };
+
+            // Override complexity's cyclomatic with CFG-derived value (single source of truth)
+            // and recompute maintainability index to stay consistent
+            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 > 0 ? loc.commentLines / loc.loc : 0;
+              def.complexity.maintainabilityIndex = computeMaintainabilityIndex(
+                volume,
+                cfgResult.cyclomatic,
+                loc?.sloc ?? 0,
+                commentRatio,
+              );
+            }
+          }
+        }
+      }
+    }
+
     // ─ Store dataflow results (buildDataflowEdges will find symbols.dataflow and skip its walk) ─
     if (dataflowVisitor) {
       symbols.dataflow = results.dataflow;