optave-codegraph 3.13.0

package/src/domain/parser.ts

@@ -0,0 +1,1437 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Tree } from 'web-tree-sitter';
+import { Language, Parser, Query } from 'web-tree-sitter';
+import { debug, warn } from '../infrastructure/logger.js';
+import { getNative, getNativePackageVersion, loadNative } from '../infrastructure/native.js';
+import { ParseError, toErrorMessage } from '../shared/errors.js';
+import type {
+  EngineMode,
+  ExtractorOutput,
+  LanguageId,
+  LanguageRegistryEntry,
+  TypeMapEntry,
+} from '../types.js';
+import { disposeWasmWorkerPool, getWasmWorkerPool } from './wasm-worker-pool.js';
+import type { WorkerAnalysisOpts } from './wasm-worker-protocol.js';
+
+/** Default worker opts: run all analyses so output matches parseFilesFull. */
+const FULL_ANALYSIS: WorkerAnalysisOpts = {
+  ast: true,
+  complexity: true,
+  cfg: true,
+  dataflow: true,
+};
+
+/** Extract-only opts: skip visitor walk for typeMap backfill / similar fast paths. */
+const EXTRACT_ONLY: WorkerAnalysisOpts = {
+  ast: false,
+  complexity: false,
+  cfg: false,
+  dataflow: false,
+};
+
+// Re-export all extractors for backward compatibility
+export {
+  extractBashSymbols,
+  extractClojureSymbols,
+  extractCppSymbols,
+  extractCSharpSymbols,
+  extractCSymbols,
+  extractCudaSymbols,
+  extractDartSymbols,
+  extractElixirSymbols,
+  extractErlangSymbols,
+  extractFSharpSymbols,
+  extractGleamSymbols,
+  extractGoSymbols,
+  extractGroovySymbols,
+  extractHaskellSymbols,
+  extractHCLSymbols,
+  extractJavaSymbols,
+  extractJuliaSymbols,
+  extractKotlinSymbols,
+  extractLuaSymbols,
+  extractObjCSymbols,
+  extractOCamlSymbols,
+  extractPHPSymbols,
+  extractPythonSymbols,
+  extractRSymbols,
+  extractRubySymbols,
+  extractRustSymbols,
+  extractScalaSymbols,
+  extractSoliditySymbols,
+  extractSwiftSymbols,
+  extractSymbols,
+  extractVerilogSymbols,
+  extractZigSymbols,
+} from '../extractors/index.js';
+
+import {
+  extractBashSymbols,
+  extractClojureSymbols,
+  extractCppSymbols,
+  extractCSharpSymbols,
+  extractCSymbols,
+  extractCudaSymbols,
+  extractDartSymbols,
+  extractElixirSymbols,
+  extractErlangSymbols,
+  extractFSharpSymbols,
+  extractGleamSymbols,
+  extractGoSymbols,
+  extractGroovySymbols,
+  extractHaskellSymbols,
+  extractHCLSymbols,
+  extractJavaSymbols,
+  extractJuliaSymbols,
+  extractKotlinSymbols,
+  extractLuaSymbols,
+  extractObjCSymbols,
+  extractOCamlSymbols,
+  extractPHPSymbols,
+  extractPythonSymbols,
+  extractRSymbols,
+  extractRubySymbols,
+  extractRustSymbols,
+  extractScalaSymbols,
+  extractSoliditySymbols,
+  extractSwiftSymbols,
+  extractSymbols,
+  extractVerilogSymbols,
+  extractZigSymbols,
+} from '../extractors/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function grammarPath(name: string): string {
+  return path.join(__dirname, '..', '..', 'grammars', name);
+}
+
+let _initialized: boolean = false;
+
+// Memoized parsers — avoids reloading WASM grammars on every createParsers() call
+let _cachedParsers: Map<string, Parser | null> | null = null;
+
+// Cached Language objects — WASM-backed, must be .delete()'d explicitly
+let _cachedLanguages: Map<string, Language> | null = null;
+
+// Query cache for JS/TS/TSX extractors (populated during createParsers)
+const _queryCache: Map<string, Query> = new Map();
+
+// Tracks whether ALL grammars have been loaded (vs. a lazy subset)
+let _allParsersLoaded: boolean = false;
+
+// In-flight grammar loads keyed by language id — prevents concurrent duplicate loads
+const _loadingPromises: Map<string, Promise<void>> = new Map();
+
+// Extensions that need typeMap backfill (type annotations only exist in TS/TSX)
+const TS_BACKFILL_EXTS = new Set(['.ts', '.tsx']);
+
+// Re-export for backward compatibility
+export type { LanguageRegistryEntry } from '../types.js';
+
+interface ParseEngineOpts {
+  engine?: EngineMode;
+  dataflow?: boolean;
+  ast?: boolean;
+}
+
+interface ResolvedEngine {
+  name: 'native' | 'wasm';
+  native: any;
+}
+
+interface WasmExtractResult {
+  symbols: ExtractorOutput;
+  tree: Tree;
+  langId: LanguageId;
+}
+
+// Shared patterns for all JS/TS/TSX (class_declaration excluded — name type differs)
+const COMMON_QUERY_PATTERNS: string[] = [
+  '(function_declaration name: (identifier) @fn_name) @fn_node',
+  '(generator_function_declaration name: (identifier) @fn_name) @fn_node',
+  '(variable_declarator name: (identifier) @varfn_name value: (arrow_function) @varfn_value)',
+  '(variable_declarator name: (identifier) @varfn_name value: (function_expression) @varfn_value)',
+  '(variable_declarator name: (identifier) @varfn_name value: (generator_function) @varfn_value)',
+  '(method_definition name: (property_identifier) @meth_name) @meth_node',
+  '(method_definition name: (private_property_identifier) @meth_name) @meth_node',
+  '(method_definition name: (computed_property_name) @meth_name) @meth_node',
+  '(import_statement source: (string) @imp_source) @imp_node',
+  '(export_statement) @exp_node',
+  '(call_expression function: (identifier) @callfn_name) @callfn_node',
+  '(call_expression function: (member_expression) @callmem_fn) @callmem_node',
+  '(call_expression function: (subscript_expression) @callsub_fn) @callsub_node',
+  '(new_expression constructor: (identifier) @newfn_name) @newfn_node',
+  '(new_expression constructor: (member_expression) @newmem_fn) @newmem_node',
+  '(expression_statement (assignment_expression left: (member_expression) @assign_left right: (_) @assign_right)) @assign_node',
+];
+
+// JS: class name is (identifier) — declarations and expressions
+const JS_CLASS_PATTERNS: string[] = [
+  '(class_declaration name: (identifier) @cls_name) @cls_node',
+  // class expressions: `return class Foo extends Bar { ... }` or `const X = class Foo { ... }`
+  '(class name: (identifier) @cls_name) @cls_node',
+];
+
+// TS/TSX: class name is (type_identifier), plus interface and type alias
+// abstract_class_declaration is a separate node type in tree-sitter-typescript
+const TS_EXTRA_PATTERNS: string[] = [
+  '(class_declaration name: (type_identifier) @cls_name) @cls_node',
+  '(abstract_class_declaration name: (type_identifier) @cls_name) @cls_node',
+  // class expressions: `return class Foo extends Bar { ... }`
+  '(class name: (type_identifier) @cls_name) @cls_node',
+  '(interface_declaration name: (type_identifier) @iface_name) @iface_node',
+  '(type_alias_declaration name: (type_identifier) @type_name) @type_node',
+];
+
+/**
+ * Load a single language grammar and cache the parser + language + query.
+ * Uses in-flight deduplication so concurrent callers awaiting the same grammar
+ * share a single load rather than producing orphaned WASM instances.
+ * Assumes Parser.init() has already been called and _cachedParsers/_cachedLanguages exist.
+ */
+async function loadLanguage(entry: LanguageRegistryEntry): Promise<void> {
+  if (_cachedParsers!.has(entry.id)) return;
+  const inflight = _loadingPromises.get(entry.id);
+  if (inflight) return inflight;
+  const p = doLoadLanguage(entry).finally(() => _loadingPromises.delete(entry.id));
+  _loadingPromises.set(entry.id, p);
+  return p;
+}
+
+async function doLoadLanguage(entry: LanguageRegistryEntry): Promise<void> {
+  try {
+    const lang = await Language.load(grammarPath(entry.grammarFile));
+    const parser = new Parser();
+    parser.setLanguage(lang);
+    _cachedParsers!.set(entry.id, parser);
+    _cachedLanguages!.set(entry.id, lang);
+    if (entry.extractor === extractSymbols && !_queryCache.has(entry.id)) {
+      const isTS = entry.id === 'typescript' || entry.id === 'tsx';
+      const patterns = isTS
+        ? [...COMMON_QUERY_PATTERNS, ...TS_EXTRA_PATTERNS]
+        : [...COMMON_QUERY_PATTERNS, ...JS_CLASS_PATTERNS];
+      _queryCache.set(entry.id, new Query(lang, patterns.join('\n')));
+    }
+  } catch (e: unknown) {
+    if (entry.required)
+      throw new ParseError(`Required parser ${entry.id} failed to initialize`, {
+        file: entry.grammarFile,
+        cause: e as Error,
+      });
+    const isEnoent = (e as NodeJS.ErrnoException).code === 'ENOENT';
+    const log = isEnoent ? debug : warn;
+    log(
+      `${entry.id} parser failed to initialize: ${(e as Error).message}. ${entry.id} files will be skipped.`,
+    );
+    _cachedParsers!.set(entry.id, null);
+  }
+}
+
+async function initParserRuntime(): Promise<void> {
+  if (!_initialized) {
+    await Parser.init();
+    _initialized = true;
+  }
+  if (!_cachedParsers) _cachedParsers = new Map();
+  if (!_cachedLanguages) _cachedLanguages = new Map();
+}
+
+/**
+ * Load only the WASM grammars needed for the given file paths.
+ * Grammars already in cache are reused. This avoids the ~500ms cold-start
+ * penalty of loading all 23+ grammars when only 1-2 are needed (e.g. incremental rebuilds).
+ */
+async function ensureParsersForFiles(filePaths: string[]): Promise<Map<string, Parser | null>> {
+  await initParserRuntime();
+  const needed = new Set<LanguageRegistryEntry>();
+  for (const fp of filePaths) {
+    const ext = path.extname(fp).toLowerCase();
+    const entry = _extToLang.get(ext);
+    if (entry && !_cachedParsers!.has(entry.id)) needed.add(entry);
+  }
+  for (const entry of needed) {
+    await loadLanguage(entry);
+  }
+  return _cachedParsers!;
+}
+
+/**
+ * Load ALL WASM grammars. Used by full builds and feature modules (CFG, dataflow, complexity)
+ * that may process files of any language.
+ */
+export async function createParsers(): Promise<Map<string, Parser | null>> {
+  if (_cachedParsers && _allParsersLoaded) return _cachedParsers;
+
+  await initParserRuntime();
+  for (const entry of LANGUAGE_REGISTRY) {
+    if (!_cachedParsers!.has(entry.id)) {
+      await loadLanguage(entry);
+    }
+  }
+  _allParsersLoaded = true;
+  return _cachedParsers!;
+}
+
+/**
+ * Dispose all cached WASM parsers and queries to free WASM linear memory.
+ * Call this between repeated builds in the same process (e.g. benchmarks)
+ * to prevent memory accumulation that can cause segfaults.
+ */
+function disposeMapEntries(entries: Iterable<[string, any]>, label: string): void {
+  for (const [id, item] of entries) {
+    if (item && typeof item.delete === 'function') {
+      try {
+        item.delete();
+      } catch (e: unknown) {
+        debug(`Failed to dispose ${label} ${id}: ${(e as Error).message}`);
+      }
+    }
+  }
+}
+
+export async function disposeParsers(): Promise<void> {
+  if (_cachedParsers) {
+    disposeMapEntries(_cachedParsers, 'parser');
+    _cachedParsers = null;
+  }
+  disposeMapEntries(_queryCache, 'query');
+  _queryCache.clear();
+  if (_cachedLanguages) {
+    disposeMapEntries(_cachedLanguages, 'language');
+    _cachedLanguages = null;
+  }
+  _initialized = false;
+  _allParsersLoaded = false;
+  _loadingPromises.clear();
+  await disposeWasmWorkerPool();
+}
+
+export function getParser(parsers: Map<string, Parser | null>, filePath: string): Parser | null {
+  const ext = path.extname(filePath);
+  const entry = _extToLang.get(ext);
+  if (!entry) return null;
+  return parsers.get(entry.id) || null;
+}
+
+/**
+ * Backfill missing AST-analysis data (astNodes, dataflow, def.complexity,
+ * def.cfg) via the WASM worker pool for files that were parsed by the native
+ * engine but are missing one or more analyses.
+ *
+ * Historically this function populated `symbols._tree` so the main-thread
+ * visitor walk in `ast-analysis/engine.ts` could run. After the worker-isolation
+ * refactor (#965), the worker runs every visitor itself and returns pre-computed
+ * analysis data — `_tree` is never set on the main thread.
+ *
+ * Name is preserved for caller compatibility; the function now ensures
+ * *analysis data* rather than *trees*.
+ *
+ * `needsFn` (optional): when provided, only files for which it returns true are
+ * re-parsed. Without it the function falls back to "any WASM-parseable file
+ * 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.
+ */
+/**
+ * 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,
+): 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
+    if (!_extToLang.has(path.extname(relPath).toLowerCase())) continue;
+    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();
+  for (const { relPath, absPath, symbols } of pending) {
+    let code: string;
+    try {
+      code = fs.readFileSync(absPath, 'utf-8');
+    } catch (e: unknown) {
+      debug(`ensureWasmTrees: cannot read ${relPath}: ${(e as Error).message}`);
+      continue;
+    }
+    const output = await pool.parse(absPath, code, FULL_ANALYSIS);
+    if (!output) continue; // worker crashed or returned null — skip silently
+    mergeAnalysisData(symbols, output);
+  }
+}
+
+/** 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;
+}
+
+/** 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);
+  for (const wd of workerDefs) {
+    const existing = byKey.get(`${wd.kind}|${wd.name}|${wd.line}`);
+    if (!existing) continue;
+    if (!existing.complexity && wd.complexity) existing.complexity = wd.complexity;
+    if ((!existing.cfg || !Array.isArray(existing.cfg.blocks)) && wd.cfg?.blocks) {
+      existing.cfg = wd.cfg;
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+export function isWasmAvailable(): boolean {
+  return LANGUAGE_REGISTRY.filter((e) => e.required).every((e) =>
+    fs.existsSync(grammarPath(e.grammarFile)),
+  );
+}
+
+/**
+ * Return the set of lowercase file extensions whose WASM grammar is actually
+ * installed on disk. Used to scope engine-parity backfill to files that WASM
+ * can recover — languages without an installed grammar are skipped by both
+ * engines, so they don't represent a native-engine drop.
+ *
+ * Cached on first call; the grammars directory is shipped immutable.
+ */
+let _installedWasmExts: Set<string> | null = null;
+export function getInstalledWasmExtensions(): Set<string> {
+  if (_installedWasmExts) return _installedWasmExts;
+  const exts = new Set<string>();
+  for (const entry of LANGUAGE_REGISTRY) {
+    if (fs.existsSync(grammarPath(entry.grammarFile))) {
+      for (const ext of entry.extensions) exts.add(ext.toLowerCase());
+    }
+  }
+  _installedWasmExts = exts;
+  return exts;
+}
+
+/**
+ * Lowercase file extensions covered by the native Rust addon.
+ *
+ * Mirrors `LanguageKind::from_extension` in
+ * `crates/codegraph-core/src/domain/parser.rs`. Used to classify why the
+ * native orchestrator dropped a file: extensions outside this set are a
+ * legitimate parser limit (no Rust extractor exists), while extensions inside
+ * it indicate a real native bug (parse/read/extract failure).
+ *
+ * Keep this list in sync with the Rust enum — the native addon is a separate
+ * npm package, so JS has no runtime way to discover its language coverage.
+ */
+export const NATIVE_SUPPORTED_EXTENSIONS: ReadonlySet<string> = new Set([
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.tsx',
+  '.py',
+  '.pyi',
+  '.tf',
+  '.hcl',
+  '.go',
+  '.rs',
+  '.java',
+  '.cs',
+  '.rb',
+  '.rake',
+  '.gemspec',
+  '.php',
+  '.phtml',
+  '.c',
+  '.h',
+  '.cpp',
+  '.cc',
+  '.cxx',
+  '.hpp',
+  '.cu',
+  '.cuh',
+  '.kt',
+  '.kts',
+  '.swift',
+  '.scala',
+  '.sh',
+  '.bash',
+  '.ex',
+  '.exs',
+  '.lua',
+  '.dart',
+  '.zig',
+  '.hs',
+  '.ml',
+  '.mli',
+  '.fs',
+  '.fsx',
+  '.fsi',
+  '.m',
+  '.gleam',
+  '.jl',
+  '.clj',
+  '.cljs',
+  '.cljc',
+  '.erl',
+  '.hrl',
+  '.groovy',
+  '.gvy',
+  '.r',
+  '.sol',
+  '.v',
+  '.sv',
+]);
+
+/**
+ * Classification for a file the native orchestrator dropped.
+ * - `unsupported-by-native`: extension has no Rust extractor (legitimate parser limit).
+ * - `native-extractor-failure`: extension is supported by native but the file was
+ *   still dropped — points at a real bug (read error, parse failure, extractor crash).
+ */
+export type NativeDropReason = 'unsupported-by-native' | 'native-extractor-failure';
+
+export interface NativeDropClassification {
+  /** Per-reason → per-extension → list of relative paths that hit that bucket. */
+  byReason: Record<NativeDropReason, Map<string, string[]>>;
+  /** Total file count per reason. */
+  totals: Record<NativeDropReason, number>;
+}
+
+/**
+ * Group the missing files (relative paths) by drop reason and extension so the
+ * caller can log per-extension counts and a sample path. Pure function — no
+ * I/O, safe to unit-test independently of the build pipeline.
+ */
+export function classifyNativeDrops(relPaths: Iterable<string>): NativeDropClassification {
+  const byReason: Record<NativeDropReason, Map<string, string[]>> = {
+    'unsupported-by-native': new Map(),
+    'native-extractor-failure': new Map(),
+  };
+  const totals: Record<NativeDropReason, number> = {
+    'unsupported-by-native': 0,
+    'native-extractor-failure': 0,
+  };
+  for (const rel of relPaths) {
+    const ext = path.extname(rel).toLowerCase();
+    const reason: NativeDropReason = NATIVE_SUPPORTED_EXTENSIONS.has(ext)
+      ? 'native-extractor-failure'
+      : 'unsupported-by-native';
+    const bucket = byReason[reason];
+    let list = bucket.get(ext);
+    if (!list) {
+      list = [];
+      bucket.set(ext, list);
+    }
+    list.push(rel);
+    totals[reason]++;
+  }
+  return { byReason, totals };
+}
+
+/**
+ * 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);
+  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.padEnd(extWidth)}  ${String(paths.length).padStart(countWidth)}  ${sample}${more}`;
+  });
+  if (entries.length > MAX_EXTS) {
+    lines.push(`  (+${entries.length - MAX_EXTS} more extension(s))`);
+  }
+  return `\n${lines.join('\n')}`;
+}
+
+// ── Unified API ──────────────────────────────────────────────────────────────
+
+function resolveEngine(opts: ParseEngineOpts = {}): ResolvedEngine {
+  const pref = opts.engine || 'auto';
+  if (pref === 'wasm') return { name: 'wasm', native: null };
+  if (pref === 'native' || pref === 'auto') {
+    const native = loadNative();
+    if (native) return { name: 'native', native };
+    if (pref === 'native') {
+      getNative(); // throws with detailed error + install instructions
+    }
+  }
+  return { name: 'wasm', native: null };
+}
+
+/**
+ * Patch native engine output in-place for the few remaining semantic transforms.
+ * With #[napi(js_name)] on Rust types, most fields already arrive as camelCase.
+ * This only handles:
+ *  - _lineCount compat for builder.js
+ *  - Backward compat for older native binaries missing js_name annotations
+ *  - dataflow argFlows/mutations bindingType -> binding wrapper
+ */
+/** Patch definition fields for backward compat with older native binaries. */
+function patchDefinitions(definitions: any[]): void {
+  for (const d of definitions) {
+    if (d.endLine === undefined && d.end_line !== undefined) {
+      d.endLine = d.end_line;
+    }
+  }
+}
+
+/**
+ * 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) {
+    for (const [camel, snake] of IMPORT_FIELD_RENAMES) {
+      if (i[camel] === undefined) i[camel] = i[snake];
+    }
+  }
+}
+
+/** Normalize native typeMap array to a Map instance.
+ *  Uses first-wins semantics at equal confidence to match the WASM/JS extractor. */
+function patchTypeMap(r: any): void {
+  if (!r.typeMap) {
+    r.typeMap = new Map();
+  } else if (!(r.typeMap instanceof Map)) {
+    const map = new Map<string, TypeMapEntry>();
+    for (const e of r.typeMap as Array<{ name: string; typeName: string }>) {
+      if (!map.has(e.name)) {
+        map.set(e.name, { type: e.typeName, confidence: (e as any).confidence ?? 0.9 });
+      }
+    }
+    r.typeMap = map;
+  }
+}
+
+/** Normalize native returnTypeMap array to a Map instance, keeping highest-confidence entry per key. */
+function patchReturnTypeMap(r: any): void {
+  if (!r.returnTypeMap || r.returnTypeMap instanceof Map) return;
+  const map = new Map<string, TypeMapEntry>();
+  for (const e of r.returnTypeMap as Array<{
+    name: string;
+    typeName: string;
+    confidence?: number;
+  }>) {
+    const conf = e.confidence ?? 1.0;
+    const existing = map.get(e.name);
+    if (!existing || conf > existing.confidence) {
+      map.set(e.name, { type: e.typeName, confidence: conf });
+    }
+  }
+  r.returnTypeMap = map.size > 0 ? map : new Map();
+}
+
+/** Wrap bindingType into binding object for dataflow argFlows and mutations. */
+/**
+ * Normalise a DataflowResult from the native Rust extractor to the VisitorArgFlow
+ * shape expected by the TypeScript dataflow analysis layer.
+ *
+ * The Rust `DataflowArgFlow` emits `bindingType: string | null` as a flat field.
+ * The TS analysis layer (`buildDataflowVerticesAndEdges`, `collectCallerStitchCandidates`)
+ * expects `binding: { type: string; index?: number }` on each argFlow/mutation entry.
+ * This normalisation must be applied whenever `extractDataflowAnalysis` is called
+ * outside the standard `patchNativeResult` pipeline.
+ */
+export function patchDataflowResult(dataflow: any): void {
+  if (dataflow.argFlows) {
+    for (const f of dataflow.argFlows) {
+      f.binding = f.bindingType ? { type: f.bindingType } : null;
+    }
+  }
+  if (dataflow.mutations) {
+    for (const m of dataflow.mutations) {
+      m.binding = m.bindingType ? { type: m.bindingType } : null;
+    }
+  }
+}
+
+function patchNativeResult(r: any): ExtractorOutput {
+  // lineCount: napi(js_name) emits "lineCount"; older binaries may emit "line_count"
+  r.lineCount = r.lineCount ?? r.line_count ?? null;
+  r._lineCount = r.lineCount;
+
+  if (r.definitions) patchDefinitions(r.definitions);
+  if (r.imports) patchImports(r.imports);
+  patchTypeMap(r);
+  patchReturnTypeMap(r);
+  if (r.dataflow) patchDataflowResult(r.dataflow);
+
+  return r;
+}
+
+/**
+ * Declarative registry of all supported languages.
+ * Adding a new language requires only a new entry here + its extractor function.
+ */
+export const LANGUAGE_REGISTRY: LanguageRegistryEntry[] = [
+  {
+    id: 'javascript',
+    extensions: ['.js', '.jsx', '.mjs', '.cjs'],
+    grammarFile: 'tree-sitter-javascript.wasm',
+    extractor: extractSymbols,
+    required: true,
+  },
+  {
+    id: 'typescript',
+    extensions: ['.ts'],
+    grammarFile: 'tree-sitter-typescript.wasm',
+    extractor: extractSymbols,
+    required: true,
+  },
+  {
+    id: 'tsx',
+    extensions: ['.tsx'],
+    grammarFile: 'tree-sitter-tsx.wasm',
+    extractor: extractSymbols,
+    required: true,
+  },
+  {
+    id: 'hcl',
+    extensions: ['.tf', '.hcl'],
+    grammarFile: 'tree-sitter-hcl.wasm',
+    extractor: extractHCLSymbols,
+    required: false,
+  },
+  {
+    id: 'python',
+    extensions: ['.py', '.pyi'],
+    grammarFile: 'tree-sitter-python.wasm',
+    extractor: extractPythonSymbols,
+    required: false,
+  },
+  {
+    id: 'go',
+    extensions: ['.go'],
+    grammarFile: 'tree-sitter-go.wasm',
+    extractor: extractGoSymbols,
+    required: false,
+  },
+  {
+    id: 'rust',
+    extensions: ['.rs'],
+    grammarFile: 'tree-sitter-rust.wasm',
+    extractor: extractRustSymbols,
+    required: false,
+  },
+  {
+    id: 'java',
+    extensions: ['.java'],
+    grammarFile: 'tree-sitter-java.wasm',
+    extractor: extractJavaSymbols,
+    required: false,
+  },
+  {
+    id: 'csharp',
+    extensions: ['.cs'],
+    grammarFile: 'tree-sitter-c_sharp.wasm',
+    extractor: extractCSharpSymbols,
+    required: false,
+  },
+  {
+    id: 'ruby',
+    extensions: ['.rb', '.rake', '.gemspec'],
+    grammarFile: 'tree-sitter-ruby.wasm',
+    extractor: extractRubySymbols,
+    required: false,
+  },
+  {
+    id: 'php',
+    extensions: ['.php', '.phtml'],
+    grammarFile: 'tree-sitter-php.wasm',
+    extractor: extractPHPSymbols,
+    required: false,
+  },
+  {
+    id: 'c',
+    extensions: ['.c', '.h'],
+    grammarFile: 'tree-sitter-c.wasm',
+    extractor: extractCSymbols,
+    required: false,
+  },
+  {
+    id: 'cpp',
+    extensions: ['.cpp', '.cc', '.cxx', '.hpp'],
+    grammarFile: 'tree-sitter-cpp.wasm',
+    extractor: extractCppSymbols,
+    required: false,
+  },
+  {
+    id: 'kotlin',
+    extensions: ['.kt', '.kts'],
+    grammarFile: 'tree-sitter-kotlin.wasm',
+    extractor: extractKotlinSymbols,
+    required: false,
+  },
+  {
+    id: 'swift',
+    extensions: ['.swift'],
+    grammarFile: 'tree-sitter-swift.wasm',
+    extractor: extractSwiftSymbols,
+    required: false,
+  },
+  {
+    id: 'scala',
+    extensions: ['.scala'],
+    grammarFile: 'tree-sitter-scala.wasm',
+    extractor: extractScalaSymbols,
+    required: false,
+  },
+  {
+    id: 'bash',
+    extensions: ['.sh', '.bash'],
+    grammarFile: 'tree-sitter-bash.wasm',
+    extractor: extractBashSymbols,
+    required: false,
+  },
+  {
+    id: 'elixir',
+    extensions: ['.ex', '.exs'],
+    grammarFile: 'tree-sitter-elixir.wasm',
+    extractor: extractElixirSymbols,
+    required: false,
+  },
+  {
+    id: 'lua',
+    extensions: ['.lua'],
+    grammarFile: 'tree-sitter-lua.wasm',
+    extractor: extractLuaSymbols,
+    required: false,
+  },
+  {
+    id: 'dart',
+    extensions: ['.dart'],
+    grammarFile: 'tree-sitter-dart.wasm',
+    extractor: extractDartSymbols,
+    required: false,
+  },
+  {
+    id: 'zig',
+    extensions: ['.zig'],
+    grammarFile: 'tree-sitter-zig.wasm',
+    extractor: extractZigSymbols,
+    required: false,
+  },
+  {
+    id: 'haskell',
+    extensions: ['.hs'],
+    grammarFile: 'tree-sitter-haskell.wasm',
+    extractor: extractHaskellSymbols,
+    required: false,
+  },
+  {
+    id: 'ocaml',
+    extensions: ['.ml'],
+    grammarFile: 'tree-sitter-ocaml.wasm',
+    extractor: extractOCamlSymbols,
+    required: false,
+  },
+  {
+    id: 'ocaml-interface',
+    extensions: ['.mli'],
+    grammarFile: 'tree-sitter-ocaml_interface.wasm',
+    extractor: extractOCamlSymbols,
+    required: false,
+  },
+  {
+    id: 'fsharp',
+    extensions: ['.fs', '.fsx'],
+    grammarFile: 'tree-sitter-fsharp.wasm',
+    extractor: extractFSharpSymbols,
+    required: false,
+  },
+  {
+    id: 'fsharp-signature',
+    extensions: ['.fsi'],
+    grammarFile: 'tree-sitter-fsharp_signature.wasm',
+    extractor: extractFSharpSymbols,
+    required: false,
+  },
+  {
+    id: 'gleam',
+    extensions: ['.gleam'],
+    grammarFile: 'tree-sitter-gleam.wasm',
+    extractor: extractGleamSymbols,
+    required: false,
+  },
+  {
+    id: 'clojure',
+    extensions: ['.clj', '.cljs', '.cljc'],
+    grammarFile: 'tree-sitter-clojure.wasm',
+    extractor: extractClojureSymbols,
+    required: false,
+  },
+  {
+    id: 'julia',
+    extensions: ['.jl'],
+    grammarFile: 'tree-sitter-julia.wasm',
+    extractor: extractJuliaSymbols,
+    required: false,
+  },
+  {
+    id: 'r',
+    extensions: ['.r', '.R'],
+    grammarFile: 'tree-sitter-r.wasm',
+    extractor: extractRSymbols,
+    required: false,
+  },
+  {
+    id: 'erlang',
+    extensions: ['.erl', '.hrl'],
+    grammarFile: 'tree-sitter-erlang.wasm',
+    extractor: extractErlangSymbols,
+    required: false,
+  },
+  {
+    id: 'solidity',
+    extensions: ['.sol'],
+    grammarFile: 'tree-sitter-solidity.wasm',
+    extractor: extractSoliditySymbols,
+    required: false,
+  },
+  {
+    id: 'objc',
+    extensions: ['.m'],
+    grammarFile: 'tree-sitter-objc.wasm',
+    extractor: extractObjCSymbols,
+    required: false,
+  },
+  {
+    id: 'cuda',
+    extensions: ['.cu', '.cuh'],
+    grammarFile: 'tree-sitter-cuda.wasm',
+    extractor: extractCudaSymbols,
+    required: false,
+  },
+  {
+    id: 'groovy',
+    extensions: ['.groovy', '.gvy'],
+    grammarFile: 'tree-sitter-groovy.wasm',
+    extractor: extractGroovySymbols,
+    required: false,
+  },
+  {
+    id: 'verilog',
+    extensions: ['.v', '.sv'],
+    grammarFile: 'tree-sitter-verilog.wasm',
+    extractor: extractVerilogSymbols,
+    required: false,
+  },
+];
+
+const _extToLang: Map<string, LanguageRegistryEntry> = new Map();
+for (const entry of LANGUAGE_REGISTRY) {
+  for (const ext of entry.extensions) {
+    _extToLang.set(ext, entry);
+  }
+}
+
+export const SUPPORTED_EXTENSIONS: Set<string> = new Set(_extToLang.keys());
+
+/**
+ * WASM-based typeMap backfill for TS/TSX files parsed by the native engine.
+ * Serves two purposes:
+ * 1. Compatibility with older native binaries that don't emit typeMap (< 3.2.0).
+ * 2. Workaround for native parser scope-collision bugs — when the same variable
+ *    name appears at multiple scopes, native type extraction can produce
+ *    incorrect results. WASM's JS-based extractor handles scope traversal
+ *    more accurately. TODO: Remove purpose (2) once the Rust extractor handles
+ *    nested scopes correctly.
+ *
+ * Uses tree-sitter AST extraction instead of regex to avoid false positives from
+ * matches inside comments and string literals.
+ */
+async function backfillTypeMap(
+  filePath: string,
+  source?: string,
+): Promise<{ typeMap: Map<string, TypeMapEntry>; backfilled: boolean }> {
+  let code = source;
+  if (!code) {
+    try {
+      code = fs.readFileSync(filePath, 'utf-8');
+    } catch (e) {
+      debug(`backfillTypeMap: failed to read ${filePath}: ${toErrorMessage(e)}`);
+      return { typeMap: new Map(), backfilled: false };
+    }
+  }
+  const pool = getWasmWorkerPool();
+  // Extract-only — no visitor walk, we only need the typeMap from this pass.
+  const output = await pool.parse(filePath, code, EXTRACT_ONLY);
+  if (!output || output.typeMap.size === 0) {
+    return { typeMap: new Map(), backfilled: false };
+  }
+  return { typeMap: output.typeMap, backfilled: true };
+}
+
+/**
+ * WASM extraction helper: picks the right extractor based on file extension.
+ */
+function wasmExtractSymbols(
+  parsers: Map<string, Parser | null>,
+  filePath: string,
+  code: string,
+): WasmExtractResult | null {
+  const parser = getParser(parsers, filePath);
+  if (!parser) return null;
+
+  let tree: Tree | null;
+  try {
+    tree = parser.parse(code);
+  } catch (e: unknown) {
+    warn(`Parse error in ${filePath}: ${(e as Error).message}`);
+    return null;
+  }
+  if (!tree) return null;
+
+  const ext = path.extname(filePath);
+  const entry = _extToLang.get(ext);
+  if (!entry) return null;
+  const query = _queryCache.get(entry.id) ?? undefined;
+  // Query (web-tree-sitter) is structurally compatible with TreeSitterQuery at runtime
+  let symbols: ExtractorOutput | null;
+  try {
+    symbols = entry.extractor(tree as any, filePath, query as any);
+  } catch (e: unknown) {
+    warn(`Extractor error in ${filePath}: ${(e as Error).message}`);
+    // Free WASM tree to prevent memory leak — web-tree-sitter trees are backed
+    // by WASM linear memory and are not garbage-collected automatically.
+    if (typeof (tree as any).delete === 'function') (tree as any).delete();
+    return null;
+  }
+  return symbols ? { symbols, tree, langId: entry.id } : null;
+}
+
+/**
+ * Parse a single file and return normalized symbols.
+ */
+export async function parseFileAuto(
+  filePath: string,
+  source: string,
+  opts: ParseEngineOpts = {},
+): Promise<ExtractorOutput | null> {
+  const { native } = resolveEngine(opts);
+
+  if (native) {
+    const result = native.parseFile(filePath, source, true, true);
+    if (!result) return null;
+    const patched = patchNativeResult(result);
+    // Always backfill typeMap for TS/TSX from WASM — native parser's type
+    // extraction can produce incorrect scope-collision results. Non-TS files
+    // are skipped to stay consistent with the batch path (backfillTypeMapBatch).
+    if (TS_BACKFILL_EXTS.has(path.extname(filePath))) {
+      const { typeMap, backfilled } = await backfillTypeMap(filePath, source);
+      if (backfilled) {
+        patched.typeMap = typeMap;
+        patched._typeMapBackfilled = true;
+      }
+    }
+    return patched;
+  }
+
+  // WASM path — dispatch to isolated worker
+  const pool = getWasmWorkerPool();
+  return pool.parse(filePath, source, FULL_ANALYSIS);
+}
+
+/** Backfill typeMap via WASM for TS/TSX files parsed by the native engine. */
+async function backfillTypeMapBatch(
+  needsTypeMap: { filePath: string; relPath: string }[],
+  result: Map<string, ExtractorOutput>,
+): Promise<void> {
+  const tsFiles = needsTypeMap.filter(({ filePath }) =>
+    TS_BACKFILL_EXTS.has(path.extname(filePath)),
+  );
+  if (tsFiles.length === 0) return;
+
+  const pool = getWasmWorkerPool();
+  for (const { filePath, relPath } of tsFiles) {
+    let code: string;
+    try {
+      code = fs.readFileSync(filePath, 'utf-8');
+    } catch (e) {
+      debug(`batchExtract: cannot read ${filePath}: ${toErrorMessage(e)}`);
+      continue;
+    }
+    const output = await pool.parse(filePath, code, EXTRACT_ONLY);
+    if (!output || output.typeMap.size === 0) continue;
+    const symbols = result.get(relPath);
+    if (!symbols) continue;
+    symbols.typeMap = output.typeMap;
+    symbols._typeMapBackfilled = true;
+  }
+}
+
+/**
+ * Parse files via WASM engine, returning a Map<relPath, symbols>.
+ *
+ * Each file is dispatched to the WASM worker pool. The worker parses, extracts,
+ * and runs all AST analyses (complexity, CFG, dataflow, ast-store) in its own
+ * thread, returning fully pre-computed ExtractorOutput. V8 fatal errors from
+ * tree-sitter WASM (#965) kill only the worker — the pool skips the file and
+ * restarts the worker for the next one.
+ *
+ * `_tree` is NEVER set by this path. All downstream analyses operate on the
+ * pre-computed `astNodes` / `dataflow` / `def.complexity` / `def.cfg` fields.
+ */
+async function parseFilesWasm(
+  filePaths: string[],
+  rootDir: string,
+  analysis: WorkerAnalysisOpts = FULL_ANALYSIS,
+): Promise<Map<string, ExtractorOutput>> {
+  const result = new Map<string, ExtractorOutput>();
+  const pool = getWasmWorkerPool();
+  for (const filePath of filePaths) {
+    if (!_extToLang.has(path.extname(filePath).toLowerCase())) continue;
+    let code: string;
+    try {
+      code = fs.readFileSync(filePath, 'utf-8');
+    } catch (err: unknown) {
+      warn(`Skipping ${path.relative(rootDir, filePath)}: ${(err as Error).message}`);
+      continue;
+    }
+    const output = await pool.parse(filePath, code, analysis);
+    if (output) {
+      const relPath = path.relative(rootDir, filePath).split(path.sep).join('/');
+      result.set(relPath, output);
+    }
+  }
+  return result;
+}
+
+/**
+ * Files at or below this count use the inline parse path (no worker spawn).
+ *
+ * The worker pool exists for crash safety (#965): exotic (non-required) WASM
+ * grammars can trigger uncatchable V8 fatal errors that would kill the main
+ * process. Running them in a worker means only the worker dies; the pool
+ * detects the exit, skips the file, respawns, and continues.
+ *
+ * JS/TS/TSX are required-tier grammars — they have never triggered the V8
+ * fatal crash class and are safe to run inline. The primary hot caller
+ * (this/super dispatch post-pass) exclusively handles JS/TS/TSX files and
+ * measured ~55–64ms/file through the pool vs ~8–10ms/file inline (#1435);
+ * IPC overhead scales linearly with file count, not amortised.
+ *
+ * The threshold is set high enough to keep typical this-dispatch batches
+ * (≤ 18 files on the codegraph corpus) on the inline path, while still
+ * routing truly large exotic-language drops (rare; typical HCL case is 4
+ * files) through the pool for crash isolation. Exotic-language drops are
+ * almost always well under this limit anyway, so they benefit from the
+ * inline fast path too without meaningful crash risk increase.
+ */
+const INLINE_BACKFILL_THRESHOLD = 32;
+
+/**
+ * Inline WASM parse (no worker) for small file batches.
+ *
+ * Used by the engine-parity backfill path when the native engine drops a
+ * handful of files (typically test fixtures). The worker pool's per-call
+ * IPC + grammar-init overhead can cost 1–2s on slow CI runners — for a
+ * 4-file backfill, that dwarfs the ~10ms of actual parse work.
+ *
+ * Returns symbols with `_tree` set so `runAnalyses` can run AST/CFG/dataflow
+ * visitors via the unified walker (mirrors how WASM-engine results behaved
+ * before the worker pool was introduced), unless `symbolsOnly` is true — in
+ * that case `_tree` is not set, skipping all analysis visitor walks. Use
+ * `symbolsOnly` when only definitions/calls/typeMap are needed (e.g. the
+ * this/super dispatch post-pass) to avoid the analysis overhead on the inline
+ * path, matching the optimization already applied to the worker-pool path.
+ */
+async function parseFilesWasmInline(
+  filePaths: string[],
+  rootDir: string,
+  symbolsOnly = false,
+): Promise<Map<string, ExtractorOutput>> {
+  const result = new Map<string, ExtractorOutput>();
+  if (filePaths.length === 0) return result;
+  const parsers = await ensureParsersForFiles(filePaths);
+  for (const filePath of filePaths) {
+    if (!_extToLang.has(path.extname(filePath).toLowerCase())) continue;
+    let code: string;
+    try {
+      code = fs.readFileSync(filePath, 'utf-8');
+    } catch (err: unknown) {
+      warn(`Skipping ${path.relative(rootDir, filePath)}: ${(err as Error).message}`);
+      continue;
+    }
+    const extracted = wasmExtractSymbols(parsers, filePath, code);
+    if (!extracted) continue;
+    const relPath = path.relative(rootDir, filePath).split(path.sep).join('/');
+    const symbols = extracted.symbols as ExtractorOutput & { _tree?: unknown; _langId?: string };
+    // When symbolsOnly=true, skip setting _tree so runAnalyses does not run
+    // AST/complexity/CFG/dataflow visitor walks — only definitions/calls/typeMap
+    // are needed by callers like the this/super dispatch post-pass.
+    if (!symbolsOnly) {
+      symbols._tree = extracted.tree;
+    } else if (typeof (extracted.tree as any)?.delete === 'function') {
+      // Free the WASM-backed tree immediately — web-tree-sitter trees are backed
+      // by WASM linear memory and require explicit disposal.  When symbolsOnly is
+      // true the tree is never stored anywhere, so we must delete it here to
+      // avoid leaking WASM heap on every incremental rebuild.
+      (extracted.tree as any).delete();
+    }
+    symbols._langId = extracted.langId;
+    result.set(relPath, symbols);
+  }
+  return result;
+}
+
+/**
+ * Backfill helper: small batches use the inline (main-thread) path; larger
+ * batches keep the worker-pool isolation against tree-sitter WASM crashes
+ * (#965). See INLINE_BACKFILL_THRESHOLD for threshold rationale.
+ *
+ * `opts.symbolsOnly` skips the AST/complexity/CFG/dataflow visitors in the
+ * worker (and their result serialization across the thread boundary) for
+ * callers that only consume definitions/calls/typeMap — the native
+ * orchestrator's this-dispatch post-pass. Callers that ingest the files into
+ * the DB (dropped-language backfill) must keep
+ * the default full analysis.
+ */
+export async function parseFilesWasmForBackfill(
+  filePaths: string[],
+  rootDir: string,
+  opts: { symbolsOnly?: boolean } = {},
+): Promise<Map<string, ExtractorOutput>> {
+  if (filePaths.length <= INLINE_BACKFILL_THRESHOLD) {
+    return parseFilesWasmInline(filePaths, rootDir, opts.symbolsOnly);
+  }
+  return parseFilesWasm(filePaths, rootDir, opts.symbolsOnly ? EXTRACT_ONLY : FULL_ANALYSIS);
+}
+
+/**
+ * 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.
+ */
+function ingestNativeResults(
+  native: any,
+  filePaths: string[],
+  rootDir: string,
+  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
+    ? native.parseFilesFull(filePaths, rootDir)
+    : native.parseFiles(filePaths, rootDir, true, true);
+  const needsTypeMap: { filePath: string; relPath: string }[] = [];
+  const nativeParsed = new Set<string>();
+  for (const r of nativeResults) {
+    if (!r) continue;
+    nativeParsed.add(r.file);
+    const patched = patchNativeResult(r);
+    const relPath = path.relative(rootDir, r.file).split(path.sep).join('/');
+    result.set(relPath, patched);
+    // Always backfill TS/TSX type maps from WASM — the native parser's type
+    // extraction can produce incorrect results when the same variable name
+    // appears at multiple scopes (e.g. `node: TreeSitterNode` in one function
+    // vs `node: NodeRow` in another). The WASM JS extractor handles scope
+    // traversal order more accurately.
+    if (TS_BACKFILL_EXTS.has(path.extname(r.file))) {
+      needsTypeMap.push({ filePath: r.file, relPath });
+    }
+  }
+  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.
+ */
+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) 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;
+}
+
+/**
+ * Report which engine is active.
+ */
+export function getActiveEngine(opts: ParseEngineOpts = {}): {
+  name: 'native' | 'wasm';
+  version: string | null;
+  binaryVersion: string | null;
+} {
+  const { name, native } = resolveEngine(opts);
+  const binaryVersion: string | null =
+    native && typeof native.engineVersion === 'function' ? native.engineVersion() : null;
+  // The display version prefers the platform package.json so the "Using native
+  // engine (vX)" log matches the npm release the user installed. The Rust
+  // orchestrator's check_version_mismatch compares against CARGO_PKG_VERSION
+  // (the binary's own value), so build_meta writes must use `binaryVersion`,
+  // not this display value — see pipeline.ts and finalize.ts (#1066).
+  let version: string | null = binaryVersion;
+  if (native) {
+    try {
+      version = getNativePackageVersion() ?? version;
+    } catch (e: unknown) {
+      debug(`getNativePackageVersion failed: ${(e as Error).message}`);
+    }
+  }
+  return { name, version, binaryVersion };
+}
+
+/**
+ * Create a native ParseTreeCache for incremental parsing.
+ * Returns null if the native engine is unavailable (WASM fallback).
+ */
+export function createParseTreeCache(): any {
+  const native = loadNative();
+  if (!native?.ParseTreeCache) return null;
+  return new native.ParseTreeCache();
+}
+
+/**
+ * Parse a file incrementally using the cache, or fall back to full parse.
+ */
+export async function parseFileIncremental(
+  cache: any,
+  filePath: string,
+  source: string,
+  opts: ParseEngineOpts = {},
+): Promise<ExtractorOutput | null> {
+  if (cache) {
+    const result = cache.parseFile(filePath, source);
+    if (!result) return null;
+    const patched = patchNativeResult(result);
+    // Always backfill typeMap for TS/TSX from WASM (see parseFileAuto comment).
+    if (TS_BACKFILL_EXTS.has(path.extname(filePath))) {
+      const { typeMap, backfilled } = await backfillTypeMap(filePath, source);
+      if (backfilled) {
+        patched.typeMap = typeMap;
+        patched._typeMapBackfilled = true;
+      }
+    }
+    return patched;
+  }
+  return parseFileAuto(filePath, source, opts);
+}