@optave/codegraph 3.3.1 → 3.4.0

package/src/domain/graph/{watcher.js → watcher.ts}

@@ -5,28 +5,34 @@ import { info } from '../../infrastructure/logger.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from '../../shared/constants.js';
 import { DbError } from '../../shared/errors.js';
 import { createParseTreeCache, getActiveEngine } from '../parser.js';
-import { rebuildFile } from './builder/incremental.js';
+import { type IncrementalStmts, rebuildFile } from './builder/incremental.js';
 import { appendChangeEvents, buildChangeEvent, diffSymbols } from './change-journal.js';
 import { appendJournalEntries } from './journal.js';
 
-function shouldIgnore(filePath) {
+function shouldIgnore(filePath: string): boolean {
   const parts = filePath.split(path.sep);
   return parts.some((p) => IGNORE_DIRS.has(p));
 }
 
-function isTrackedExt(filePath) {
+function isTrackedExt(filePath: string): boolean {
   return EXTENSIONS.has(path.extname(filePath));
 }
 
-export async function watchProject(rootDir, opts = {}) {
+export async function watchProject(rootDir: string, opts: { engine?: string } = {}): Promise<void> {
   const dbPath = path.join(rootDir, '.codegraph', 'graph.db');
   if (!fs.existsSync(dbPath)) {
     throw new DbError('No graph.db found. Run `codegraph build` first.', { file: dbPath });
   }
 
-  const db = openDb(dbPath);
+  const db = openDb(dbPath) as import('better-sqlite3').Database;
+  // Alias for functions expecting the project's BetterSqlite3Database interface
+  const typedDb = db as unknown as import('../../types.js').BetterSqlite3Database;
   initSchema(db);
-  const engineOpts = { engine: opts.engine || 'auto' };
+  const engineOpts: import('../../types.js').EngineOpts = {
+    engine: (opts.engine || 'auto') as import('../../types.js').EngineMode,
+    dataflow: false,
+    ast: false,
+  };
   const { name: engineName, version: engineVersion } = getActiveEngine(engineOpts);
   console.log(
     `Watch mode using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`,
@@ -44,8 +50,8 @@ export async function watchProject(rootDir, opts = {}) {
       'INSERT OR IGNORE INTO nodes (name, kind, file, line, end_line) VALUES (?, ?, ?, ?, ?)',
     ),
     getNodeId: {
-      get: (name, kind, file, line) => {
-        const id = getNodeIdQuery(db, name, kind, file, line);
+      get: (name: string, kind: string, file: string, line: number) => {
+        const id = getNodeIdQuery(typedDb, name, kind, file, line);
         return id != null ? { id } : undefined;
       },
     },
@@ -53,9 +59,9 @@ export async function watchProject(rootDir, opts = {}) {
       'INSERT INTO edges (source_id, target_id, kind, confidence, dynamic) VALUES (?, ?, ?, ?, ?)',
     ),
     deleteNodes: db.prepare('DELETE FROM nodes WHERE file = ?'),
-    deleteEdgesForFile: null,
+    deleteEdgesForFile: null as { run: (f: string) => void } | null,
     countNodes: db.prepare('SELECT COUNT(*) as c FROM nodes WHERE file = ?'),
-    countEdgesForFile: null,
+    countEdgesForFile: null as { get: (f: string) => { c: number } | undefined } | null,
     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 = ?",
     ),
@@ -72,22 +78,42 @@ export async function watchProject(rootDir, opts = {}) {
   const origCountEdges = db.prepare(
     `SELECT COUNT(*) as c FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = @f) OR target_id IN (SELECT id FROM nodes WHERE file = @f)`,
   );
-  stmts.deleteEdgesForFile = { run: (f) => origDeleteEdges.run({ f }) };
-  stmts.countEdgesForFile = { get: (f) => origCountEdges.get({ f }) };
+  stmts.deleteEdgesForFile = { run: (f: string) => origDeleteEdges.run({ f }) };
+  stmts.countEdgesForFile = {
+    get: (f: string) => origCountEdges.get({ f }) as { c: number } | undefined,
+  };
 
-  const pending = new Set();
-  let timer = null;
+  const pending = new Set<string>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
   const DEBOUNCE_MS = 300;
 
-  async function processPending() {
+  async function processPending(): Promise<void> {
     const files = [...pending];
     pending.clear();
 
-    const results = [];
+    const results: Array<{
+      file: string;
+      deleted?: boolean;
+      event: string;
+      symbolDiff: unknown;
+      nodesBefore: number;
+      nodesAfter: number;
+      nodesAdded: number;
+      nodesRemoved: number;
+      edgesAdded: number;
+    }> = [];
     for (const filePath of files) {
-      const result = await rebuildFile(db, rootDir, filePath, stmts, engineOpts, cache, {
-        diffSymbols,
-      });
+      const result = (await rebuildFile(
+        db,
+        rootDir,
+        filePath,
+        stmts as IncrementalStmts,
+        engineOpts,
+        cache,
+        {
+          diffSymbols: diffSymbols as (old: unknown[], new_: unknown[]) => unknown,
+        },
+      )) as (typeof results)[number] | null;
       if (result) results.push(result);
     }
     const updates = results;

package/src/domain/{parser.js → parser.ts}

@@ -1,9 +1,17 @@
 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 type {
+  EngineMode,
+  ExtractorOutput,
+  LanguageId,
+  LanguageRegistryEntry,
+  TypeMapEntry,
+} from '../types.js';
 
 // Re-export all extractors for backward compatibility
 export {
@@ -32,23 +40,47 @@ import {
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-function grammarPath(name) {
+function grammarPath(name: string): string {
   return path.join(__dirname, '..', '..', 'grammars', name);
 }
 
-let _initialized = false;
+let _initialized: boolean = false;
 
 // Memoized parsers — avoids reloading WASM grammars on every createParsers() call
-let _cachedParsers = null;
+let _cachedParsers: Map<string, Parser | null> | null = null;
 
 // Cached Language objects — WASM-backed, must be .delete()'d explicitly
-let _cachedLanguages = null;
+let _cachedLanguages: Map<string, Language> | null = null;
 
 // Query cache for JS/TS/TSX extractors (populated during createParsers)
-const _queryCache = new Map();
+const _queryCache: Map<string, Query> = 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';
+  // biome-ignore lint/suspicious/noExplicitAny: native addon has no type declarations
+  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 = [
+const COMMON_QUERY_PATTERNS: string[] = [
   '(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)',
@@ -62,16 +94,16 @@ const COMMON_QUERY_PATTERNS = [
 ];
 
 // JS: class name is (identifier)
-const JS_CLASS_PATTERN = '(class_declaration name: (identifier) @cls_name) @cls_node';
+const JS_CLASS_PATTERN: string = '(class_declaration name: (identifier) @cls_name) @cls_node';
 
 // TS/TSX: class name is (type_identifier), plus interface and type alias
-const TS_EXTRA_PATTERNS = [
+const TS_EXTRA_PATTERNS: string[] = [
   '(class_declaration 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',
 ];
 
-export async function createParsers() {
+export async function createParsers(): Promise<Map<string, Parser | null>> {
   if (_cachedParsers) return _cachedParsers;
 
   if (!_initialized) {
@@ -79,8 +111,8 @@ export async function createParsers() {
     _initialized = true;
   }
 
-  const parsers = new Map();
-  const languages = new Map();
+  const parsers = new Map<string, Parser | null>();
+  const languages = new Map<string, Language>();
   for (const entry of LANGUAGE_REGISTRY) {
     try {
       const lang = await Language.load(grammarPath(entry.grammarFile));
@@ -96,10 +128,10 @@ export async function createParsers() {
           : [...COMMON_QUERY_PATTERNS, JS_CLASS_PATTERN];
         _queryCache.set(entry.id, new Query(lang, patterns.join('\n')));
       }
-    } catch (e) {
+    } catch (e: unknown) {
       if (entry.required) throw e;
       warn(
-        `${entry.id} parser failed to initialize: ${e.message}. ${entry.id} files will be skipped.`,
+        `${entry.id} parser failed to initialize: ${(e as Error).message}. ${entry.id} files will be skipped.`,
       );
       parsers.set(entry.id, null);
     }
@@ -114,14 +146,14 @@ export async function createParsers() {
  * Call this between repeated builds in the same process (e.g. benchmarks)
  * to prevent memory accumulation that can cause segfaults.
  */
-export function disposeParsers() {
+export function disposeParsers(): void {
   if (_cachedParsers) {
     for (const [id, parser] of _cachedParsers) {
       if (parser && typeof parser.delete === 'function') {
         try {
           parser.delete();
-        } catch (e) {
-          debug(`Failed to dispose parser ${id}: ${e.message}`);
+        } catch (e: unknown) {
+          debug(`Failed to dispose parser ${id}: ${(e as Error).message}`);
         }
       }
     }
@@ -131,19 +163,20 @@ export function disposeParsers() {
     if (query && typeof query.delete === 'function') {
       try {
         query.delete();
-      } catch (e) {
-        debug(`Failed to dispose query ${id}: ${e.message}`);
+      } catch (e: unknown) {
+        debug(`Failed to dispose query ${id}: ${(e as Error).message}`);
       }
     }
   }
   _queryCache.clear();
   if (_cachedLanguages) {
     for (const [id, lang] of _cachedLanguages) {
-      if (lang && typeof lang.delete === 'function') {
+      // biome-ignore lint/suspicious/noExplicitAny: .delete() exists at runtime on WASM Language objects but is missing from typings
+      if (lang && typeof (lang as any).delete === 'function') {
         try {
-          lang.delete();
-        } catch (e) {
-          debug(`Failed to dispose language ${id}: ${e.message}`);
+          (lang as any).delete();
+        } catch (e: unknown) {
+          debug(`Failed to dispose language ${id}: ${(e as Error).message}`);
         }
       }
     }
@@ -152,7 +185,7 @@ export function disposeParsers() {
   _initialized = false;
 }
 
-export function getParser(parsers, filePath) {
+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;
@@ -163,11 +196,12 @@ export function getParser(parsers, filePath) {
  * Pre-parse files missing `_tree` via WASM so downstream phases (CFG, dataflow)
  * don't each need to create parsers and re-parse independently.
  * Only parses files whose extension is in SUPPORTED_EXTENSIONS.
- *
- * @param {Map<string, object>} fileSymbols - Map<relPath, { definitions, _tree, _langId, ... }>
- * @param {string} rootDir - absolute project root
  */
-export async function ensureWasmTrees(fileSymbols, rootDir) {
+// biome-ignore lint/suspicious/noExplicitAny: fileSymbols values have dynamic shape from extractors
+export async function ensureWasmTrees(
+  fileSymbols: Map<string, any>,
+  rootDir: string,
+): Promise<void> {
   // Check if any file needs a tree
   let needsParse = false;
   for (const [relPath, symbols] of fileSymbols) {
@@ -192,18 +226,18 @@ export async function ensureWasmTrees(fileSymbols, rootDir) {
     if (!parser) continue;
 
     const absPath = path.join(rootDir, relPath);
-    let code;
+    let code: string;
     try {
       code = fs.readFileSync(absPath, 'utf-8');
-    } catch (e) {
-      debug(`ensureWasmTrees: cannot read ${relPath}: ${e.message}`);
+    } catch (e: unknown) {
+      debug(`ensureWasmTrees: cannot read ${relPath}: ${(e as Error).message}`);
       continue;
     }
     try {
       symbols._tree = parser.parse(code);
       symbols._langId = entry.id;
-    } catch (e) {
-      debug(`ensureWasmTrees: parse failed for ${relPath}: ${e.message}`);
+    } catch (e: unknown) {
+      debug(`ensureWasmTrees: parse failed for ${relPath}: ${(e as Error).message}`);
     }
   }
 }
@@ -211,7 +245,7 @@ export async function ensureWasmTrees(fileSymbols, rootDir) {
 /**
  * Check whether the required WASM grammar files exist on disk.
  */
-export function isWasmAvailable() {
+export function isWasmAvailable(): boolean {
   return LANGUAGE_REGISTRY.filter((e) => e.required).every((e) =>
     fs.existsSync(grammarPath(e.grammarFile)),
   );
@@ -219,7 +253,7 @@ export function isWasmAvailable() {
 
 // ── Unified API ──────────────────────────────────────────────────────────────
 
-function resolveEngine(opts = {}) {
+function resolveEngine(opts: ParseEngineOpts = {}): ResolvedEngine {
   const pref = opts.engine || 'auto';
   if (pref === 'wasm') return { name: 'wasm', native: null };
   if (pref === 'native' || pref === 'auto') {
@@ -238,9 +272,10 @@ function resolveEngine(opts = {}) {
  * This only handles:
  *  - _lineCount compat for builder.js
  *  - Backward compat for older native binaries missing js_name annotations
- *  - dataflow argFlows/mutations bindingType → binding wrapper
+ *  - dataflow argFlows/mutations bindingType -> binding wrapper
  */
-function patchNativeResult(r) {
+// biome-ignore lint/suspicious/noExplicitAny: native addon result has no type declarations
+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;
@@ -268,6 +303,20 @@ function patchNativeResult(r) {
     }
   }
 
+  // typeMap: native returns an array of {name, typeName}; normalize to Map.
+  // Non-TS languages may omit typeMap entirely — default to empty Map so
+  // callers can safely access .entries()/.size without null checks.
+  if (!r.typeMap) {
+    r.typeMap = new Map();
+  } else if (!(r.typeMap instanceof Map)) {
+    r.typeMap = new Map(
+      r.typeMap.map((e: { name: string; typeName: string }) => [
+        e.name,
+        { type: e.typeName, confidence: 0.9 } as TypeMapEntry,
+      ]),
+    );
+  }
+
   // dataflow: wrap bindingType into binding object for argFlows and mutations
   if (r.dataflow) {
     if (r.dataflow.argFlows) {
@@ -289,7 +338,7 @@ function patchNativeResult(r) {
  * Declarative registry of all supported languages.
  * Adding a new language requires only a new entry here + its extractor function.
  */
-export const LANGUAGE_REGISTRY = [
+export const LANGUAGE_REGISTRY: LanguageRegistryEntry[] = [
   {
     id: 'javascript',
     extensions: ['.js', '.jsx', '.mjs', '.cjs'],
@@ -369,14 +418,14 @@ export const LANGUAGE_REGISTRY = [
   },
 ];
 
-const _extToLang = new Map();
+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 = new Set(_extToLang.keys());
+export const SUPPORTED_EXTENSIONS: Set<string> = new Set(_extToLang.keys());
 
 /**
  * WASM-based typeMap backfill for older native binaries that don't emit typeMap.
@@ -384,26 +433,26 @@ export const SUPPORTED_EXTENSIONS = new Set(_extToLang.keys());
  * matches inside comments and string literals.
  * TODO: Remove once all published native binaries include typeMap extraction (>= 3.2.0)
  */
-async function backfillTypeMap(filePath, source) {
+// biome-ignore lint/suspicious/noExplicitAny: return shape matches native result typeMap
+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 {
-      return { typeMap: [], backfilled: false };
+      return { typeMap: new Map(), backfilled: false };
     }
   }
   const parsers = await createParsers();
   const extracted = wasmExtractSymbols(parsers, filePath, code);
   try {
-    if (!extracted?.symbols?.typeMap) {
-      return { typeMap: [], backfilled: false };
+    if (!extracted || extracted.symbols.typeMap.size === 0) {
+      return { typeMap: new Map(), backfilled: false };
     }
-    const tm = extracted.symbols.typeMap;
-    return {
-      typeMap: tm instanceof Map ? tm : new Map(tm.map((e) => [e.name, e.typeName])),
-      backfilled: true,
-    };
+    return { typeMap: extracted.symbols.typeMap, backfilled: true };
   } finally {
     // Free the WASM tree to prevent memory accumulation across repeated builds
     if (extracted?.tree && typeof extracted.tree.delete === 'function') {
@@ -417,35 +466,41 @@ async function backfillTypeMap(filePath, source) {
 /**
  * WASM extraction helper: picks the right extractor based on file extension.
  */
-function wasmExtractSymbols(parsers, filePath, code) {
+function wasmExtractSymbols(
+  parsers: Map<string, Parser | null>,
+  filePath: string,
+  code: string,
+): WasmExtractResult | null {
   const parser = getParser(parsers, filePath);
   if (!parser) return null;
 
-  let tree;
+  let tree: Tree | null;
   try {
     tree = parser.parse(code);
-  } catch (e) {
-    warn(`Parse error in ${filePath}: ${e.message}`);
+  } 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) || null;
-  const symbols = entry.extractor(tree, filePath, query);
+  const query = _queryCache.get(entry.id) ?? undefined;
+  // Query (web-tree-sitter) is structurally compatible with TreeSitterQuery at runtime
+  // biome-ignore lint/suspicious/noExplicitAny: thin WASM wrapper type mismatch
+  const symbols = entry.extractor(tree as any, filePath, query as any);
   return symbols ? { symbols, tree, langId: entry.id } : null;
 }
 
 /**
  * Parse a single file and return normalized symbols.
- *
- * @param {string} filePath  Absolute path to the file.
- * @param {string} source    Source code string.
- * @param {object} [opts]    Options: { engine: 'native'|'wasm'|'auto' }
- * @returns {Promise<{definitions, calls, imports, classes, exports}|null>}
  */
-export async function parseFileAuto(filePath, source, opts = {}) {
+export async function parseFileAuto(
+  filePath: string,
+  source: string,
+  opts: ParseEngineOpts = {},
+): Promise<ExtractorOutput | null> {
   const { native } = resolveEngine(opts);
 
   if (native) {
@@ -454,11 +509,7 @@ export async function parseFileAuto(filePath, source, opts = {}) {
     const patched = patchNativeResult(result);
     // Only backfill typeMap for TS/TSX — JS files have no type annotations,
     // and the native engine already handles `new Expr()` patterns.
-    const TS_BACKFILL_EXTS = new Set(['.ts', '.tsx']);
-    if (
-      (!patched.typeMap || patched.typeMap.length === 0) &&
-      TS_BACKFILL_EXTS.has(path.extname(filePath))
-    ) {
+    if (patched.typeMap.size === 0 && TS_BACKFILL_EXTS.has(path.extname(filePath))) {
       const { typeMap, backfilled } = await backfillTypeMap(filePath, source);
       patched.typeMap = typeMap;
       if (backfilled) patched._typeMapBackfilled = true;
@@ -474,15 +525,14 @@ export async function parseFileAuto(filePath, source, opts = {}) {
 
 /**
  * Parse multiple files in bulk and return a Map<relPath, symbols>.
- *
- * @param {string[]} filePaths  Absolute paths to files.
- * @param {string}   rootDir    Project root for computing relative paths.
- * @param {object}   [opts]     Options: { engine: 'native'|'wasm'|'auto' }
- * @returns {Promise<Map<string, {definitions, calls, imports, classes, exports}>>}
  */
-export async function parseFilesAuto(filePaths, rootDir, opts = {}) {
+export async function parseFilesAuto(
+  filePaths: string[],
+  rootDir: string,
+  opts: ParseEngineOpts = {},
+): Promise<Map<string, ExtractorOutput>> {
   const { native } = resolveEngine(opts);
-  const result = new Map();
+  const result = new Map<string, ExtractorOutput>();
 
   if (native) {
     const nativeResults = native.parseFiles(
@@ -491,13 +541,13 @@ export async function parseFilesAuto(filePaths, rootDir, opts = {}) {
       !!opts.dataflow,
       opts.ast !== false,
     );
-    const needsTypeMap = [];
+    const needsTypeMap: { filePath: string; relPath: string }[] = [];
     for (const r of nativeResults) {
       if (!r) continue;
       const patched = patchNativeResult(r);
       const relPath = path.relative(rootDir, r.file).split(path.sep).join('/');
       result.set(relPath, patched);
-      if (!patched.typeMap || patched.typeMap.length === 0) {
+      if (patched.typeMap.size === 0) {
         needsTypeMap.push({ filePath: r.file, relPath });
       }
     }
@@ -505,21 +555,20 @@ export async function parseFilesAuto(filePaths, rootDir, opts = {}) {
     if (needsTypeMap.length > 0) {
       // Only backfill for languages where WASM extraction can produce typeMap
       // (TS/TSX have type annotations; JS only has `new Expr()` which native already handles)
-      const TS_EXTS = new Set(['.ts', '.tsx']);
-      const tsFiles = needsTypeMap.filter(({ filePath }) => TS_EXTS.has(path.extname(filePath)));
+      const tsFiles = needsTypeMap.filter(({ filePath }) =>
+        TS_BACKFILL_EXTS.has(path.extname(filePath)),
+      );
       if (tsFiles.length > 0) {
         const parsers = await createParsers();
         for (const { filePath, relPath } of tsFiles) {
-          let extracted;
+          let extracted: WasmExtractResult | null | undefined;
           try {
             const code = fs.readFileSync(filePath, 'utf-8');
             extracted = wasmExtractSymbols(parsers, filePath, code);
-            if (extracted?.symbols?.typeMap) {
+            if (extracted?.symbols && extracted.symbols.typeMap.size > 0) {
               const symbols = result.get(relPath);
-              symbols.typeMap =
-                extracted.symbols.typeMap instanceof Map
-                  ? extracted.symbols.typeMap
-                  : new Map(extracted.symbols.typeMap.map((e) => [e.name, e.typeName]));
+              if (!symbols) continue;
+              symbols.typeMap = extracted.symbols.typeMap;
               symbols._typeMapBackfilled = true;
             }
           } catch {
@@ -541,11 +590,11 @@ export async function parseFilesAuto(filePaths, rootDir, opts = {}) {
   // WASM path
   const parsers = await createParsers();
   for (const filePath of filePaths) {
-    let code;
+    let code: string;
     try {
       code = fs.readFileSync(filePath, 'utf-8');
-    } catch (err) {
-      warn(`Skipping ${path.relative(rootDir, filePath)}: ${err.message}`);
+    } catch (err: unknown) {
+      warn(`Skipping ${path.relative(rootDir, filePath)}: ${(err as Error).message}`);
       continue;
     }
     const extracted = wasmExtractSymbols(parsers, filePath, code);
@@ -562,13 +611,13 @@ export async function parseFilesAuto(filePaths, rootDir, opts = {}) {
 
 /**
  * Report which engine is active.
- *
- * @param {object} [opts]  Options: { engine: 'native'|'wasm'|'auto' }
- * @returns {{ name: 'native'|'wasm', version: string|null }}
  */
-export function getActiveEngine(opts = {}) {
+export function getActiveEngine(opts: ParseEngineOpts = {}): {
+  name: 'native' | 'wasm';
+  version: string | null;
+} {
   const { name, native } = resolveEngine(opts);
-  let version = native
+  let version: string | null = native
     ? typeof native.engineVersion === 'function'
       ? native.engineVersion()
       : null
@@ -578,8 +627,8 @@ export function getActiveEngine(opts = {}) {
   if (native) {
     try {
       version = getNativePackageVersion() ?? version;
-    } catch (e) {
-      debug(`getNativePackageVersion failed: ${e.message}`);
+    } catch (e: unknown) {
+      debug(`getNativePackageVersion failed: ${(e as Error).message}`);
     }
   }
   return { name, version };
@@ -589,7 +638,8 @@ export function getActiveEngine(opts = {}) {
  * Create a native ParseTreeCache for incremental parsing.
  * Returns null if the native engine is unavailable (WASM fallback).
  */
-export function createParseTreeCache() {
+// biome-ignore lint/suspicious/noExplicitAny: native ParseTreeCache has no type declarations
+export function createParseTreeCache(): any {
   const native = loadNative();
   if (!native || !native.ParseTreeCache) return null;
   return new native.ParseTreeCache();
@@ -597,25 +647,21 @@ export function createParseTreeCache() {
 
 /**
  * Parse a file incrementally using the cache, or fall back to full parse.
- *
- * @param {object|null} cache  ParseTreeCache instance (or null for full parse)
- * @param {string} filePath    Absolute path to the file
- * @param {string} source      Source code string
- * @param {object} [opts]      Options forwarded to parseFileAuto on fallback
- * @returns {Promise<{definitions, calls, imports, classes, exports}|null>}
  */
-export async function parseFileIncremental(cache, filePath, source, opts = {}) {
+// biome-ignore lint/suspicious/noExplicitAny: cache is native ParseTreeCache with no type declarations
+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);
     // Only backfill typeMap for TS/TSX — JS files have no type annotations,
     // and the native engine already handles `new Expr()` patterns.
-    const TS_BACKFILL_EXTS = new Set(['.ts', '.tsx']);
-    if (
-      (!patched.typeMap || patched.typeMap.length === 0) &&
-      TS_BACKFILL_EXTS.has(path.extname(filePath))
-    ) {
+    if (patched.typeMap.size === 0 && TS_BACKFILL_EXTS.has(path.extname(filePath))) {
       const { typeMap, backfilled } = await backfillTypeMap(filePath, source);
       patched.typeMap = typeMap;
       if (backfilled) patched._typeMapBackfilled = true;

package/src/domain/{queries.js → queries.ts}

@@ -1,5 +1,5 @@
 /**
- * queries.js — Barrel re-export file.
+ * queries.ts — Barrel re-export file.
  *
  * All query logic lives in the sub-modules under src/analysis/ and src/shared/.
  * This file exists purely for backward compatibility so that all existing