@optave/codegraph 3.3.1 → 3.4.1

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

@@ -1,9 +1,18 @@
 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 { toErrorMessage } from '../shared/errors.js';
+import type {
+  EngineMode,
+  ExtractorOutput,
+  LanguageId,
+  LanguageRegistryEntry,
+  TypeMapEntry,
+} from '../types.js';
 
 // Re-export all extractors for backward compatibility
 export {
@@ -32,23 +41,46 @@ 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';
+  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,19 @@ 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') {
+      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 +184,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 +195,11 @@ 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) {
+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 +224,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 +243,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 +251,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 +270,9 @@ 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) {
+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 +300,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 +335,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 +415,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,32 +430,34 @@ 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) {
+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 };
+    } catch (e) {
+      debug(`backfillTypeMap: failed to read ${filePath}: ${toErrorMessage(e)}`);
+      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') {
       try {
         extracted.tree.delete();
-      } catch {}
+      } catch (e) {
+        debug(`backfillTypeMap: WASM tree cleanup failed: ${toErrorMessage(e)}`);
+      }
     }
   }
 }
@@ -417,35 +465,40 @@ 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
+  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 +507,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 +523,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 +539,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,31 +553,32 @@ 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 {
-            /* skip — typeMap is a best-effort backfill */
+          } catch (e) {
+            debug(`batchExtract: typeMap backfill failed: ${toErrorMessage(e)}`);
           } finally {
             // Free the WASM tree to prevent memory accumulation across repeated builds
             if (extracted?.tree && typeof extracted.tree.delete === 'function') {
               try {
                 extracted.tree.delete();
-              } catch {}
+              } catch (e) {
+                debug(`batchExtract: WASM tree cleanup failed: ${toErrorMessage(e)}`);
+              }
             }
           }
         }
@@ -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,7 @@ export function getActiveEngine(opts = {}) {
  * Create a native ParseTreeCache for incremental parsing.
  * Returns null if the native engine is unavailable (WASM fallback).
  */
-export function createParseTreeCache() {
+export function createParseTreeCache(): any {
   const native = loadNative();
   if (!native || !native.ParseTreeCache) return null;
   return new native.ParseTreeCache();
@@ -597,25 +646,20 @@ 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 = {}) {
+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
@@ -8,6 +8,7 @@
 
 // ── Re-export from dedicated module for backward compat ───────────────────
 export { isTestFile, TEST_PATTERN } from '../infrastructure/test-filter.js';
+export { diffImpactMermaid } from '../presentation/diff-impact-mermaid.js';
 export { iterListFunctions, iterRoles, iterWhere } from '../shared/generators.js';
 // ── Kind/edge constants (canonical source: kinds.js) ─────────────────────
 export {
@@ -24,11 +25,10 @@ export {
 export { kindIcon, normalizeSymbol } from '../shared/normalize.js';
 export { briefData } from './analysis/brief.js';
 export { contextData, explainData } from './analysis/context.js';
-export { fileDepsData, fnDepsData, pathData } from './analysis/dependencies.js';
+export { fileDepsData, filePathData, fnDepsData, pathData } from './analysis/dependencies.js';
 export { exportsData } from './analysis/exports.js';
 export {
   diffImpactData,
-  diffImpactMermaid,
   fnImpactData,
   impactAnalysisData,
 } from './analysis/impact.js';