refactor: decompose ast-analysis visitor framework (#771)

* fix: replace empty catch blocks with structured error handling

Replace catch blocks that silently swallow errors with proper error
variable capture and debug() logging across 10 files. This addresses
Pillar II (Rule 10: emptyCatch) violations identified by the gauntlet
audit. Files that already had proper error handling were verified and
left unchanged.

* refactor: add error-handling helpers for intentional catch suppression

* refactor: extract visitor dispatch helpers from walkWithVisitors

Decompose walkWithVisitors (cognitive=65, halstead.bugs=1.05) into focused
helper functions: mergeFunctionNodeTypes, initVisitors, isSkipped,
dispatchEnterFunction, dispatchEnterNode, dispatchExitNode, clearSkipFlags,
dispatchExitFunction, collectResults. The main function is now a thin
orchestrator delegating to single-purpose dispatch helpers.

* refactor: extract parameter and callee resolution helpers from visitor-utils

Split extractParamNames by extracting extractRestParamNames,
extractObjectDestructNames, and extractArrayDestructNames. Extract
resolveOptionalChainCallee from resolveCalleeName. Reduces cognitive
complexity and cyclomatic complexity of the two main functions.

* refactor: decompose handleVarDeclarator in dataflow-visitor

Extract resolveValueNode, unwrapExpressionList, recordDestructuredAssignment,
and recordSimpleAssignment from the monolithic handleVarDeclarator function.
Reduces cognitive complexity from 48 to focused single-purpose helpers.

* refactor: extract classifyNode helper and simplify complexity-visitor

Consolidate the enterNode classification logic into a single classifyNode
function. Simplify enterFunction/exitFunction by merging equivalent branches
for fileLevelWalk mode. Reduces cognitive complexity from 37 to focused
single-purpose helpers.

* refactor: decompose ast-store-visitor name extraction and node collection

Extract extractThrowName, extractAwaitName from extractName (removed).
Extract resolveNameAndText from collectNode to separate per-kind name/text
resolution from the row-building logic. Reduces cognitive complexity and
cyclomatic branching in the visitor factory.

* refactor: decompose engine.ts native analysis and deduplicate MI override

Extract detectNativeNeeds and runNativeFileAnalysis from runNativeAnalysis
to separate needs-detection from per-file dispatch. Extract shared
overrideCyclomaticFromCfg helper to eliminate duplicated MI recalculation
in storeNativeCfgResults and storeCfgResults.

* refactor: extract named constants and sumCounts helper in metrics

Replace magic numbers in the MI formula with named constants (MI_BASE,
MI_VOLUME_COEFF, etc.) and the Halstead bugs divisor. Extract sumCounts
helper from computeHalsteadDerived. Reduces halsteadEffort and addresses
Rule 7 magic-values warning.

* fix: address Greptile review comments in engine.ts (#771)

- Move NativeAnalysisNeeds interface before JSDoc block and fix stale
  doc-comment that referenced a non-existent return value
- Add debug log when overrideCyclomaticFromCfg skips due to
  cfgCyclomatic <= 0, making the WASM-path behavior change visible
- Remove duplicate hasFuncBody arrow in ensureWasmTreesIfNeeded,
  reuse the module-level function instead

* fix: relocate orphaned JSDoc to runNativeAnalysis (#771)

* fix: remove duplicate function declarations from merge (#771)

Author: carlos-alm

src/ast-analysis/engine.ts

@@ -103,18 +103,18 @@ async function getParserModule(): Promise<typeof import('../domain/parser.js')>
 
 // ─── Native standalone analysis ─────────────────────────────────────────
 
-/**
- * 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).
- */
 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.
+ */
+
 /** Determine which native analyses a file still needs. */
 function detectNativeNeeds(
   symbols: ExtractorOutput,
@@ -259,7 +259,11 @@ 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 || cfgCyclomatic <= 0) return;
+  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;
@@ -325,23 +329,6 @@ 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 lid = symbols._langId || '';
     const needsAst =