@optave/codegraph 3.11.0 → 3.11.1

package/src/domain/graph/cycles.ts

@@ -3,6 +3,45 @@ import { loadNative } from '../../infrastructure/native.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
 import type { BetterSqlite3Database } from '../../types.js';
 
+type Edge = { source: string; target: string };
+type DbEdge = { source_id: number; target_id: number };
+
+/**
+ * Build a label-based edge list from DB rows, filtering to known nodes and
+ * deduplicating. Self-loops are skipped (Tarjan treats them as trivial SCCs).
+ */
+function buildLabelEdges(dbEdges: DbEdge[], idToLabel: Map<number, string>): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  for (const e of dbEdges) {
+    if (e.source_id === e.target_id) continue;
+    const src = idToLabel.get(e.source_id);
+    const tgt = idToLabel.get(e.target_id);
+    if (src === undefined || tgt === undefined) continue;
+    const key = `${src}\0${tgt}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push({ source: src, target: tgt });
+  }
+  return edges;
+}
+
+function buildFileLevelEdges(db: BetterSqlite3Database, noTests: boolean): Edge[] {
+  let nodes = getFileNodesAll(db);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+  const idToLabel = new Map<number, string>();
+  for (const n of nodes) idToLabel.set(n.id, n.file);
+  return buildLabelEdges(getImportEdges(db), idToLabel);
+}
+
+function buildCallableEdges(db: BetterSqlite3Database, noTests: boolean): Edge[] {
+  let nodes = getCallableNodes(db);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+  const idToLabel = new Map<number, string>();
+  for (const n of nodes) idToLabel.set(n.id, `${n.name}|${n.file}`);
+  return buildLabelEdges(getCallEdges(db), idToLabel);
+}
+
 /**
  * Find cycles using Tarjan's SCC algorithm.
  *
@@ -16,66 +55,20 @@ export function findCycles(
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
 
-  const edges: Array<{ source: string; target: string }> = [];
-  const seen = new Set<string>();
-
-  if (fileLevel) {
-    let nodes = getFileNodesAll(db);
-    if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
-    const nodeIds = new Set<number>();
-    const idToFile = new Map<number, string>();
-    for (const n of nodes) {
-      nodeIds.add(n.id);
-      idToFile.set(n.id, n.file);
-    }
-    for (const e of getImportEdges(db)) {
-      if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
-      if (e.source_id === e.target_id) continue;
-      const src = idToFile.get(e.source_id)!;
-      const tgt = idToFile.get(e.target_id)!;
-      const key = `${src}\0${tgt}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      edges.push({ source: src, target: tgt });
-    }
-  } else {
-    let nodes = getCallableNodes(db);
-    if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
-    const nodeIds = new Set<number>();
-    const idToLabel = new Map<number, string>();
-    for (const n of nodes) {
-      nodeIds.add(n.id);
-      idToLabel.set(n.id, `${n.name}|${n.file}`);
-    }
-    for (const e of getCallEdges(db)) {
-      if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
-      if (e.source_id === e.target_id) continue;
-      const src = idToLabel.get(e.source_id)!;
-      const tgt = idToLabel.get(e.target_id)!;
-      const key = `${src}\0${tgt}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      edges.push({ source: src, target: tgt });
-    }
-  }
+  const edges = fileLevel ? buildFileLevelEdges(db, noTests) : buildCallableEdges(db, noTests);
 
   const native = loadNative();
   if (native) {
     return native.detectCycles(edges) as string[][];
   }
-
   return tarjanFromEdges(edges);
 }
 
-export function findCyclesJS(edges: Array<{ source: string; target: string }>): string[][] {
+export function findCyclesJS(edges: Edge[]): string[][] {
   return tarjanFromEdges(edges);
 }
 
-/**
- * Run Tarjan's SCC on a flat edge list. Returns SCCs with length > 1 (cycles).
- * Uses a simple adjacency-list Map instead of a full CodeGraph.
- */
-function tarjanFromEdges(edges: Array<{ source: string; target: string }>): string[][] {
+function buildAdjacency(edges: Edge[]): { adj: Map<string, string[]>; allNodes: Set<string> } {
   const adj = new Map<string, string[]>();
   const allNodes = new Set<string>();
   for (const { source, target } of edges) {
@@ -88,6 +81,15 @@ function tarjanFromEdges(edges: Array<{ source: string; target: string }>): stri
     }
     list.push(target);
   }
+  return { adj, allNodes };
+}
+
+/**
+ * Run Tarjan's SCC on a flat edge list. Returns SCCs with length > 1 (cycles).
+ * Uses a simple adjacency-list Map instead of a full CodeGraph.
+ */
+function tarjanFromEdges(edges: Edge[]): string[][] {
+  const { adj, allNodes } = buildAdjacency(edges);
 
   let index = 0;
   const stack: string[] = [];

package/src/domain/graph/journal.ts

@@ -91,62 +91,69 @@ function trySteal(lockPath: string): AcquiredLock | null {
   return { fd, nonce };
 }
 
-function acquireJournalLock(lockPath: string): AcquiredLock {
-  const start = Date.now();
-  for (;;) {
-    const nonce = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+/**
+ * Try to create the lockfile fresh via `wx`. Returns the acquired lock on
+ * success, `null` if another holder exists, or throws on unexpected errors.
+ *
+ * If the stamp write fails (ENOSPC, I/O error) we release the empty file —
+ * leaving it would look stale to concurrent waiters and admit double-acquire.
+ */
+function tryFreshAcquire(lockPath: string): AcquiredLock | null {
+  const nonce = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+  let fd: number;
+  try {
+    fd = fs.openSync(lockPath, 'wx');
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'EEXIST') return null;
+    throw e;
+  }
+  try {
+    fs.writeSync(fd, `${process.pid}\n${nonce}\n`);
+  } catch {
     try {
-      const fd = fs.openSync(lockPath, 'wx');
-      try {
-        fs.writeSync(fd, `${process.pid}\n${nonce}\n`);
-      } catch {
-        // Stamp write failed (ENOSPC, I/O error). An empty lockfile would
-        // look stale to concurrent waiters (Number('') === 0, isPidAlive(0)
-        // returns false), so they'd steal our live lock. Release and retry.
-        try {
-          fs.closeSync(fd);
-        } catch {
-          /* ignore */
-        }
-        try {
-          fs.unlinkSync(lockPath);
-        } catch {
-          /* ignore */
-        }
-        if (Date.now() - start > LOCK_TIMEOUT_MS) {
-          throw new Error(
-            `Failed to acquire journal lock at ${lockPath} within ${LOCK_TIMEOUT_MS}ms`,
-          );
-        }
-        sleepSync(LOCK_RETRY_MS);
-        continue;
-      }
-      return { fd, nonce };
-    } catch (e) {
-      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
+      fs.closeSync(fd);
+    } catch {
+      /* ignore */
     }
-
-    let holderAlive = true;
     try {
-      const pidContent = fs.readFileSync(lockPath, 'utf-8').split('\n')[0]!.trim();
-      holderAlive = isPidAlive(Number(pidContent));
+      fs.unlinkSync(lockPath);
     } catch {
-      /* unreadable — fall through to age check */
+      /* ignore */
     }
+    return null;
+  }
+  return { fd, nonce };
+}
 
-    let shouldSteal = !holderAlive;
-    if (holderAlive) {
-      try {
-        const stat = fs.statSync(lockPath);
-        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-          shouldSteal = true;
-        }
-      } catch {
-        /* stat failed — keep retrying */
-      }
-    }
+/**
+ * Decide whether the current lock holder is stale and should be stolen.
+ * Returns true if the PID is dead, or if the lockfile mtime exceeds the
+ * staleness threshold.
+ */
+function isLockStale(lockPath: string): boolean {
+  let holderAlive = true;
+  try {
+    const pidContent = fs.readFileSync(lockPath, 'utf-8').split('\n')[0]!.trim();
+    holderAlive = isPidAlive(Number(pidContent));
+  } catch {
+    /* unreadable — fall through to age check */
+  }
+  if (!holderAlive) return true;
+  try {
+    const stat = fs.statSync(lockPath);
+    return Date.now() - stat.mtimeMs > LOCK_STALE_MS;
+  } catch {
+    return false;
+  }
+}
 
-    if (shouldSteal) {
+function acquireJournalLock(lockPath: string): AcquiredLock {
+  const start = Date.now();
+  for (;;) {
+    const fresh = tryFreshAcquire(lockPath);
+    if (fresh) return fresh;
+
+    if (isLockStale(lockPath)) {
       const stolen = trySteal(lockPath);
       if (stolen) return stolen;
       // Steal failed or lost the race — fall through to timeout check & retry.
@@ -227,27 +234,20 @@ interface JournalResult {
   removed?: string[];
 }
 
-export function readJournal(rootDir: string): JournalResult {
-  const journalPath = path.join(rootDir, '.codegraph', JOURNAL_FILENAME);
-  let content: string;
-  try {
-    content = fs.readFileSync(journalPath, 'utf-8');
-  } catch {
-    return { valid: false };
-  }
-
-  const lines = content.split('\n');
-  if (lines.length === 0 || !lines[0]!.startsWith(HEADER_PREFIX)) {
+function parseJournalHeader(firstLine: string | undefined): number | null {
+  if (!firstLine || !firstLine.startsWith(HEADER_PREFIX)) {
     debug('Journal has malformed or missing header');
-    return { valid: false };
+    return null;
   }
-
-  const timestamp = Number(lines[0]!.slice(HEADER_PREFIX.length).trim());
+  const timestamp = Number(firstLine.slice(HEADER_PREFIX.length).trim());
   if (!Number.isFinite(timestamp) || timestamp <= 0) {
     debug('Journal has invalid timestamp');
-    return { valid: false };
+    return null;
   }
+  return timestamp;
+}
 
+function parseJournalBody(lines: string[]): { changed: string[]; removed: string[] } {
   const changed: string[] = [];
   const removed: string[] = [];
   const seenChanged = new Set<string>();
@@ -263,14 +263,29 @@ export function readJournal(rootDir: string): JournalResult {
         seenRemoved.add(filePath);
         removed.push(filePath);
       }
-    } else {
-      if (!seenChanged.has(line)) {
-        seenChanged.add(line);
-        changed.push(line);
-      }
+    } else if (!seenChanged.has(line)) {
+      seenChanged.add(line);
+      changed.push(line);
     }
   }
 
+  return { changed, removed };
+}
+
+export function readJournal(rootDir: string): JournalResult {
+  const journalPath = path.join(rootDir, '.codegraph', JOURNAL_FILENAME);
+  let content: string;
+  try {
+    content = fs.readFileSync(journalPath, 'utf-8');
+  } catch {
+    return { valid: false };
+  }
+
+  const lines = content.split('\n');
+  const timestamp = parseJournalHeader(lines[0]);
+  if (timestamp === null) return { valid: false };
+
+  const { changed, removed } = parseJournalBody(lines);
   return { valid: true, timestamp, changed, removed };
 }
 

package/src/domain/graph/watcher.ts

@@ -31,6 +31,9 @@ function prepareWatcherStatements(db: ReturnType<typeof openDb>): IncrementalStm
       'INSERT INTO edges (source_id, target_id, kind, confidence, dynamic) VALUES (?, ?, ?, ?, ?)',
     ),
     countNodes: db.prepare('SELECT COUNT(*) as c FROM nodes WHERE file = ?'),
+    countEdges: db.prepare(
+      'SELECT COUNT(*) as c FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
     findNodeInFile: db.prepare(
       "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant') AND file = ?",
     ),
@@ -52,6 +55,7 @@ interface RebuildResult {
   nodesAdded: number;
   nodesRemoved: number;
   edgesAdded: number;
+  edgesBefore: number;
 }
 
 /** Process a batch of pending file changes: rebuild, journal, and log. */
@@ -107,7 +111,7 @@ function writeJournalAndChangeEvents(rootDir: string, updates: RebuildResult[]):
     buildChangeEvent(r.file, r.event, r.symbolDiff, {
       nodesBefore: r.nodesBefore,
       nodesAfter: r.nodesAfter,
-      edgesAdded: r.edgesAdded,
+      edgesAdded: r.edgesAdded - r.edgesBefore,
     }),
   );
   try {
@@ -125,7 +129,9 @@ function logRebuildResults(updates: RebuildResult[]): void {
     if (r.deleted) {
       info(`Removed: ${r.file} (-${r.nodesRemoved} nodes)`);
     } else {
-      info(`Updated: ${r.file} (${nodeStr} nodes, +${r.edgesAdded} edges)`);
+      const edgeDelta = r.edgesAdded - r.edgesBefore;
+      const edgeStr = edgeDelta >= 0 ? `+${edgeDelta}` : `${edgeDelta}`;
+      info(`Updated: ${r.file} (${nodeStr} nodes, ${edgeStr} edges)`);
     }
   }
 }

package/src/domain/parser.ts

@@ -322,12 +322,15 @@ export function getParser(parsers: Map<string, Parser | null>, filePath: string)
  * without _tree", which was the source of #1036 — a single file missing one
  * analysis triggered a full-build re-parse of every WASM-parseable file.
  */
-export async function ensureWasmTrees(
+/**
+ * Select files from `fileSymbols` that still need analysis data and are
+ * parseable by an installed WASM grammar. Pure (no I/O) — safe to unit-test.
+ */
+function collectBackfillPending(
   fileSymbols: Map<string, any>,
   rootDir: string,
   needsFn?: (relPath: string, symbols: any) => boolean,
-): Promise<void> {
-  // Collect files that still need analysis data and are parseable by WASM.
+): Array<{ relPath: string; absPath: string; symbols: any }> {
   const pending: Array<{ relPath: string; absPath: string; symbols: any }> = [];
   for (const [relPath, symbols] of fileSymbols) {
     if (symbols._tree) continue; // legacy path — leave existing trees alone
@@ -335,6 +338,15 @@ export async function ensureWasmTrees(
     if (needsFn && !needsFn(relPath, symbols)) continue;
     pending.push({ relPath, absPath: path.join(rootDir, relPath), symbols });
   }
+  return pending;
+}
+
+export async function ensureWasmTrees(
+  fileSymbols: Map<string, any>,
+  rootDir: string,
+  needsFn?: (relPath: string, symbols: any) => boolean,
+): Promise<void> {
+  const pending = collectBackfillPending(fileSymbols, rootDir, needsFn);
   if (pending.length === 0) return;
 
   const pool = getWasmWorkerPool();
@@ -352,30 +364,37 @@ export async function ensureWasmTrees(
   }
 }
 
-/**
- * Merge pre-computed analysis data from a worker result onto existing symbols.
- * Only fills gaps — never overwrites fields the caller already populated.
- * Used to patch native-parsed symbols with worker-produced astNodes / dataflow /
- * per-definition complexity and cfg.
- */
-function mergeAnalysisData(symbols: any, worker: ExtractorOutput): void {
+/** Fill gap-only scalar metadata (`_langId`, `_lineCount`) from the worker output. */
+function mergeScalarMetadata(symbols: any, worker: ExtractorOutput): void {
   if (!symbols._langId && worker._langId) symbols._langId = worker._langId;
   if (!symbols._lineCount && worker._lineCount) symbols._lineCount = worker._lineCount;
+}
+
+/** Fill gap-only analysis arrays (`astNodes`, `dataflow`) from the worker output. */
+function mergeAnalysisArrays(symbols: any, worker: ExtractorOutput): void {
   if (!Array.isArray(symbols.astNodes) && Array.isArray(worker.astNodes)) {
     symbols.astNodes = worker.astNodes;
   }
   if (!symbols.dataflow && worker.dataflow) symbols.dataflow = worker.dataflow;
-  if (worker.typeMap && worker.typeMap.size > 0) {
-    if (!symbols.typeMap || !(symbols.typeMap instanceof Map)) {
-      symbols.typeMap = new Map(worker.typeMap);
-    } else {
-      for (const [k, v] of worker.typeMap) {
-        if (!symbols.typeMap.has(k)) symbols.typeMap.set(k, v);
-      }
-    }
+}
+
+/** Merge worker typeMap into existing symbols.typeMap with first-wins semantics. */
+function mergeTypeMap(symbols: any, worker: ExtractorOutput): void {
+  if (!worker.typeMap || worker.typeMap.size === 0) return;
+  if (!symbols.typeMap || !(symbols.typeMap instanceof Map)) {
+    symbols.typeMap = new Map(worker.typeMap);
+    return;
   }
+  for (const [k, v] of worker.typeMap) {
+    if (!symbols.typeMap.has(k)) symbols.typeMap.set(k, v);
+  }
+}
+
+/** Patch existing definitions with worker complexity/cfg when absent. */
+function mergeDefinitionAnalysis(symbols: any, worker: ExtractorOutput): void {
   const existingDefs: any[] = Array.isArray(symbols.definitions) ? symbols.definitions : [];
   const workerDefs: any[] = Array.isArray(worker.definitions) ? worker.definitions : [];
+  if (existingDefs.length === 0 || workerDefs.length === 0) return;
   // Index existing defs by (kind, name, line) — mirrors engine.ts matching key.
   const byKey = new Map<string, any>();
   for (const d of existingDefs) byKey.set(`${d.kind}|${d.name}|${d.line}`, d);
@@ -389,6 +408,19 @@ function mergeAnalysisData(symbols: any, worker: ExtractorOutput): void {
   }
 }
 
+/**
+ * Merge pre-computed analysis data from a worker result onto existing symbols.
+ * Only fills gaps — never overwrites fields the caller already populated.
+ * Used to patch native-parsed symbols with worker-produced astNodes / dataflow /
+ * per-definition complexity and cfg.
+ */
+function mergeAnalysisData(symbols: any, worker: ExtractorOutput): void {
+  mergeScalarMetadata(symbols, worker);
+  mergeAnalysisArrays(symbols, worker);
+  mergeTypeMap(symbols, worker);
+  mergeDefinitionAnalysis(symbols, worker);
+}
+
 /**
  * Check whether the required WASM grammar files exist on disk.
  */
@@ -539,25 +571,36 @@ export function classifyNativeDrops(relPaths: Iterable<string>): NativeDropClass
 }
 
 /**
- * Render `{ ext → paths[] }` as `ext (n: sample.ext, ...)` slices for log lines.
- * Caps at 3 sample paths per extension and 6 extensions total to keep warnings
- * readable when many languages are dropped at once. Extensions are sorted by
- * descending file count so the loudest offender shows up first; ties keep
- * insertion order. Pure function — safe to unit-test independently.
+ * Render `{ ext → paths[] }` as a multi-line tabular breakdown for log lines.
+ * Each extension occupies its own line so a long warning scans like a table
+ * instead of a wall of semicolon-separated slices. Caps at 3 sample paths per
+ * extension and 6 extensions total to keep output bounded when many languages
+ * are dropped at once. Extensions are sorted by descending file count so the
+ * loudest offender shows up first; ties keep insertion order.
+ *
+ * Returns the empty string for empty input, and otherwise a string that
+ * begins with `\n` so callers can append it directly after the header line
+ * (`"Backfilling via WASM:" + formatDropExtensionSummary(...)`).
+ *
+ * Pure function — safe to unit-test independently.
  */
 export function formatDropExtensionSummary(buckets: Map<string, string[]>): string {
   const MAX_EXTS = 6;
   const MAX_SAMPLES = 3;
   const entries = Array.from(buckets.entries()).sort((a, b) => b[1].length - a[1].length);
-  const shown = entries.slice(0, MAX_EXTS).map(([ext, paths]) => {
+  if (entries.length === 0) return '';
+  const shown = entries.slice(0, MAX_EXTS);
+  const extWidth = Math.max(...shown.map(([ext]) => ext.length));
+  const countWidth = Math.max(...shown.map(([, paths]) => String(paths.length).length));
+  const lines = shown.map(([ext, paths]) => {
     const sample = paths.slice(0, MAX_SAMPLES).join(', ');
-    const more = paths.length > MAX_SAMPLES ? `, +${paths.length - MAX_SAMPLES} more` : '';
-    return `${ext} (${paths.length}: ${sample}${more})`;
+    const more = paths.length > MAX_SAMPLES ? ` (+${paths.length - MAX_SAMPLES} more)` : '';
+    return `  ${ext.padEnd(extWidth)}  ${String(paths.length).padStart(countWidth)}  ${sample}${more}`;
   });
   if (entries.length > MAX_EXTS) {
-    shown.push(`+${entries.length - MAX_EXTS} more extension(s)`);
+    lines.push(`  (+${entries.length - MAX_EXTS} more extension(s))`);
   }
-  return shown.join('; ');
+  return `\n${lines.join('\n')}`;
 }
 
 // ── Unified API ──────────────────────────────────────────────────────────────
@@ -592,24 +635,36 @@ function patchDefinitions(definitions: any[]): void {
   }
 }
 
+/**
+ * Field renames applied to each import record to bridge older native binaries
+ * that emit snake_case names. Each `[camel, snake]` pair becomes:
+ *   `if (imp[camel] === undefined) imp[camel] = imp[snake];`
+ * Defined as data so the loop body stays trivially linear in cognitive complexity.
+ */
+const IMPORT_FIELD_RENAMES: ReadonlyArray<readonly [string, string]> = [
+  ['typeOnly', 'type_only'],
+  ['wildcardReexport', 'wildcard_reexport'],
+  ['pythonImport', 'python_import'],
+  ['goImport', 'go_import'],
+  ['rustUse', 'rust_use'],
+  ['javaImport', 'java_import'],
+  ['csharpUsing', 'csharp_using'],
+  ['rubyRequire', 'ruby_require'],
+  ['phpUse', 'php_use'],
+  ['cInclude', 'c_include'],
+  ['kotlinImport', 'kotlin_import'],
+  ['swiftImport', 'swift_import'],
+  ['scalaImport', 'scala_import'],
+  ['bashSource', 'bash_source'],
+  ['dynamicImport', 'dynamic_import'],
+];
+
 /** Patch import fields for backward compat with older native binaries. */
 function patchImports(imports: any[]): void {
   for (const i of imports) {
-    if (i.typeOnly === undefined) i.typeOnly = i.type_only;
-    if (i.wildcardReexport === undefined) i.wildcardReexport = i.wildcard_reexport;
-    if (i.pythonImport === undefined) i.pythonImport = i.python_import;
-    if (i.goImport === undefined) i.goImport = i.go_import;
-    if (i.rustUse === undefined) i.rustUse = i.rust_use;
-    if (i.javaImport === undefined) i.javaImport = i.java_import;
-    if (i.csharpUsing === undefined) i.csharpUsing = i.csharp_using;
-    if (i.rubyRequire === undefined) i.rubyRequire = i.ruby_require;
-    if (i.phpUse === undefined) i.phpUse = i.php_use;
-    if (i.cInclude === undefined) i.cInclude = i.c_include;
-    if (i.kotlinImport === undefined) i.kotlinImport = i.kotlin_import;
-    if (i.swiftImport === undefined) i.swiftImport = i.swift_import;
-    if (i.scalaImport === undefined) i.scalaImport = i.scala_import;
-    if (i.bashSource === undefined) i.bashSource = i.bash_source;
-    if (i.dynamicImport === undefined) i.dynamicImport = i.dynamic_import;
+    for (const [camel, snake] of IMPORT_FIELD_RENAMES) {
+      if (i[camel] === undefined) i[camel] = i[snake];
+    }
   }
 }
 
@@ -1159,18 +1214,16 @@ export async function parseFilesWasmForBackfill(
 }
 
 /**
- * Parse multiple files in bulk and return a Map<relPath, symbols>.
+ * Run the native engine over `filePaths` and ingest the results into `result`.
+ * Returns the set of file paths the native engine successfully parsed and the
+ * TS/TSX files that need a typeMap backfill pass.
  */
-export async function parseFilesAuto(
+function ingestNativeResults(
+  native: any,
   filePaths: string[],
   rootDir: string,
-  opts: ParseEngineOpts = {},
-): Promise<Map<string, ExtractorOutput>> {
-  const { native } = resolveEngine(opts);
-
-  if (!native) return parseFilesWasm(filePaths, rootDir);
-
-  const result = new Map<string, ExtractorOutput>();
+  result: Map<string, ExtractorOutput>,
+): { nativeParsed: Set<string>; needsTypeMap: { filePath: string; relPath: string }[] } {
   // Always extract all analysis data (dataflow + AST nodes) during native parse.
   // This eliminates the need for any downstream WASM re-parse or native standalone calls.
   const nativeResults = native.parseFilesFull
@@ -1193,27 +1246,51 @@ export async function parseFilesAuto(
       needsTypeMap.push({ filePath: r.file, relPath });
     }
   }
-  if (needsTypeMap.length > 0) {
-    await backfillTypeMapBatch(needsTypeMap, result);
-  }
+  return { nativeParsed, needsTypeMap };
+}
 
-  // Engine parity: native may silently drop files whose extensions are in
-  // SUPPORTED_EXTENSIONS (because a WASM grammar exists) but whose Rust
-  // extractor/grammar is missing or fails. WASM handles these — fall back so
-  // both engines process the same file set (#967). Restrict to installed WASM
-  // grammars so we don't warn about files that neither engine can parse.
+/**
+ * Engine parity: native may silently drop files whose extensions are in
+ * SUPPORTED_EXTENSIONS (because a WASM grammar exists) but whose Rust
+ * extractor/grammar is missing or fails. WASM handles these — fall back so
+ * both engines process the same file set (#967). Restrict to installed WASM
+ * grammars so we don't warn about files that neither engine can parse.
+ */
+async function backfillNativeDrops(
+  filePaths: string[],
+  nativeParsed: Set<string>,
+  rootDir: string,
+  result: Map<string, ExtractorOutput>,
+): Promise<void> {
   const installedExts = getInstalledWasmExtensions();
   const dropped = filePaths.filter(
     (f) => !nativeParsed.has(f) && installedExts.has(path.extname(f).toLowerCase()),
   );
-  if (dropped.length > 0) {
-    warn(`Native engine dropped ${dropped.length} file(s); falling back to WASM for parity`);
-    const wasmResults = await parseFilesWasmForBackfill(dropped, rootDir);
-    for (const [relPath, symbols] of wasmResults) {
-      result.set(relPath, symbols);
-    }
+  if (dropped.length === 0) return;
+  warn(`Native engine dropped ${dropped.length} file(s); falling back to WASM for parity`);
+  const wasmResults = await parseFilesWasmForBackfill(dropped, rootDir);
+  for (const [relPath, symbols] of wasmResults) {
+    result.set(relPath, symbols);
   }
+}
+
+/**
+ * Parse multiple files in bulk and return a Map<relPath, symbols>.
+ */
+export async function parseFilesAuto(
+  filePaths: string[],
+  rootDir: string,
+  opts: ParseEngineOpts = {},
+): Promise<Map<string, ExtractorOutput>> {
+  const { native } = resolveEngine(opts);
+  if (!native) return parseFilesWasm(filePaths, rootDir);
 
+  const result = new Map<string, ExtractorOutput>();
+  const { nativeParsed, needsTypeMap } = ingestNativeResults(native, filePaths, rootDir, result);
+  if (needsTypeMap.length > 0) {
+    await backfillTypeMapBatch(needsTypeMap, result);
+  }
+  await backfillNativeDrops(filePaths, nativeParsed, rootDir, result);
   return result;
 }