feat(types): migrate core modules to TypeScript (Phase 5.4) (#554)

* feat(types): add SQLite, StmtCache, and NativeAddon foundation types

Add §21 (SqliteStatement, BetterSqlite3Database, StmtCache) and §22
(NativeAddon, NativeParseTreeCache) to types.ts. These interfaces
capture the exact better-sqlite3 and napi-rs surfaces used by the
repository and native modules, enabling type-safe migration without
@types/better-sqlite3.

Impact: 24 functions changed, 0 affected

* feat(types): convert db/repository layer from JS to TypeScript

Rename all 14 src/db/repository/*.js files to .ts and add type
annotations throughout the repository module (base, nodes, edges,
embeddings, complexity, cfg, cochange, dataflow, graph-read,
build-stmts, cached-stmt, in-memory-repository, sqlite-repository,
index barrel).

Add Node.js ESM loader hook (scripts/ts-resolve-hooks.js) that falls
back from .js to .ts imports when the .js file no longer exists on
disk, enabling gradual migration where .js consumers still use .js
import specifiers. Update vitest.config.js with a Vite resolve plugin
and NODE_OPTIONS registration so require() calls and child processes
in tests resolve correctly.

* feat(types): migrate core modules to TypeScript (Phase 5.4)

Migrate 22 core source files from .js to .ts with full type annotations:
- extractors/ (11 files): all language extractors typed with ExtractorOutput
- domain/parser.ts: LANGUAGE_REGISTRY typed, parser functions annotated
- domain/graph/resolve.ts: import resolution with BareSpecifier, PathAliases
- domain/analysis/ (9 files): query-layer analysis modules typed

All 2034 tests pass, zero type errors, biome clean.

Impact: 2 functions changed, 0 affected

* fix: add .js → .ts fallback to dynamic import verifier (#554)

The verify-imports script checks exact .js paths but doesn't account
for the resolver hook fallback to .ts during incremental migration.

Impact: 1 functions changed, 0 affected

* fix: add load hook, remove unused imports, fix Node 20 compat (#554)

- Remove unused imports (existsSync, pathToFileURL) from ts-resolve-hooks.js
- Add load hook for .ts files with fallback for Node < 22.6
- Make --experimental-strip-types conditional on Node >= 22.6 in vitest config

Impact: 1 functions changed, 6 affected

* fix: add load hook, preserve NODE_OPTIONS, fix Node 20 compat (#554)

- ts-resolve-hooks.js load hook throws ERR_TS_UNSUPPORTED on Node < 22.6
- vitest.config.js preserves existing NODE_OPTIONS and uses --strip-types on Node >= 23
- skip child-process tests on Node < 22.6 (cli, batch CLI, CJS wrapper)

* fix: replace CJS require() with ESM import in formatCycles tests (#554)

require() bypasses Vite's .js→.ts resolver plugin, causing
ERR_MODULE_NOT_FOUND for renamed .ts files on all Node versions.
Use the top-level ESM import instead.

* fix: add dedup guards, Node 20.6 guard, simplify type assertion (#554)

- vitest.config.js: dedup --strip-types and --import flags
- ts-resolve-loader.js: guard module.register() for Node >= 20.6
- in-memory-repository.ts: simplify complex type assertion to `as string`
- Fix TS errors from main merge (models.ts, helpers.ts, pipeline.ts, watcher.ts)

* fix: cast kind to SymbolKind instead of string in includes() (#554)

The `as string` cast widened the type beyond what `includes()` accepts
on `SymbolKind[]`. Cast to `SymbolKind` instead.

* fix: resolve readonly array includes TS errors from main merge

EVERY_SYMBOL_KIND and CORE_SYMBOL_KINDS are readonly-typed after
kinds.js was converted to kinds.ts in #553. Array.prototype.includes
on a readonly T[] rejects a wider argument type — cast to
readonly string[] at call sites where the argument is string/AnyNodeKind.
Also spread CORE_SYMBOL_KINDS where a mutable string[] is expected.

* fix: guard --import flag for Node >= 20.6 and add implements IRepository to base class

- vitest.config.js: only inject --import <loader> into NODE_OPTIONS when
  Node >= 20.6, matching the same boundary enforced inside ts-resolve-loader.js
- src/db/repository/base.ts: add implements IRepository so TypeScript
  statically enforces that the class stays in sync with the interface in types.ts

* fix: correct NativeAddon.resolveImports signature and remove unused disposeParsers parameter

- types.ts: fix resolveImport and resolveImports signatures to match
  actual native call sites in resolve.ts (remove spurious extensions
  param, add knownFiles param, fix return type)
- domain/parser.ts: remove unused _parsers parameter from disposeParsers
  — no caller ever passes it, and the function always operates on
  module-level caches
- domain/analysis/dependencies.ts: move biome-ignore to correct line
  (suppression had no effect on wrong line)

Impact: 4 functions changed, 9 affected

* fix: correct NativeAddon.parseFiles signature and relax transaction type

parseFiles: fix parameter order/types to match actual call site in parser.ts
(string[], rootDir, dataflow, ast) instead of ({filePath,source}[], dataflow, ast).
transaction: relax parameter types to be compatible with better-sqlite3's
generic Transaction<F>, allowing direct cast without intermediate unknown.

* fix: document double-cast in purgeFilesFromGraph

Add comment explaining why as unknown as BetterSqlite3Database is needed:
better-sqlite3 types don't declare open/name properties that the project
interface requires.

* fix: restore typed db in watcher.ts instead of widening to any

Replace db: any with proper BetterSqlite3.Database type annotation.
Use typedDb alias for functions expecting the project's BetterSqlite3Database
interface, avoiding untyped code paths.

Author: carlos-alm

scripts/ts-resolve-hooks.js

@@ -0,0 +1,50 @@
+/**
+ * ESM resolve/load hooks for .js → .ts fallback during gradual migration.
+ *
+ * - resolve: when a .js specifier resolves to a path that doesn't exist,
+ *   check if a .ts version exists and redirect to it.
+ * - load: for .ts files, delegate to Node's native loader (works on
+ *   Node >= 22.6 with --experimental-strip-types). On older Node versions,
+ *   throws a clear error instead of returning unparseable TypeScript source.
+ */
+
+import { fileURLToPath } from 'node:url';
+
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (err) {
+    // Only intercept ERR_MODULE_NOT_FOUND for .js specifiers
+    if (err.code === 'ERR_MODULE_NOT_FOUND' && specifier.endsWith('.js')) {
+      const tsSpecifier = specifier.replace(/\.js$/, '.ts');
+      try {
+        return await nextResolve(tsSpecifier, context);
+      } catch {
+        // .ts also not found — throw the original error
+      }
+    }
+    throw err;
+  }
+}
+
+export async function load(url, context, nextLoad) {
+  if (!url.endsWith('.ts')) return nextLoad(url, context);
+
+  // On Node >= 22.6 with --experimental-strip-types, Node handles .ts natively
+  try {
+    return await nextLoad(url, context);
+  } catch (err) {
+    if (err.code !== 'ERR_UNKNOWN_FILE_EXTENSION') throw err;
+  }
+
+  // Node < 22.6 cannot strip TypeScript syntax. Throw a clear error instead
+  // of returning raw TS source that would produce a confusing SyntaxError.
+  const filePath = fileURLToPath(url);
+  throw Object.assign(
+    new Error(
+      `Cannot load TypeScript file ${filePath} on Node ${process.versions.node}. ` +
+      `TypeScript type stripping requires Node >= 22.6 with --experimental-strip-types.`,
+    ),
+    { code: 'ERR_TS_UNSUPPORTED' },
+  );
+}

scripts/ts-resolve-loader.js

@@ -0,0 +1,18 @@
+/**
+ * Node.js ESM loader hook for the JS → TS gradual migration.
+ *
+ * When a .js import specifier can't be found on disk, this loader tries the
+ * corresponding .ts file.  This lets plain .js files import from already-
+ * migrated .ts modules without changing their import specifiers.
+ *
+ * Usage:  node --import ./scripts/ts-resolve-loader.js ...
+ *         (or via NODE_OPTIONS / vitest poolOptions.execArgv)
+ */
+
+// module.register() requires Node >= 20.6.0
+const [_major, _minor] = process.versions.node.split('.').map(Number);
+if (_major > 20 || (_major === 20 && _minor >= 6)) {
+  const { register } = await import('node:module');
+  const hooksURL = new URL('./ts-resolve-hooks.js', import.meta.url);
+  register(hooksURL.href, { parentURL: import.meta.url });
+}

scripts/verify-imports.js

@@ -111,6 +111,12 @@ function resolveSpecifier(specifier, fromFile) {
   // Exact file exists
   if (existsSync(target) && statSync(target).isFile()) return null;
 
+  // .js → .ts fallback (mirrors the ESM resolver hook for incremental TS migration)
+  if (specifier.endsWith('.js')) {
+    const tsTarget = target.replace(/\.js$/, '.ts');
+    if (existsSync(tsTarget) && statSync(tsTarget).isFile()) return null;
+  }
+
   // Try implicit extensions (.js, .ts, .mjs, .cjs)
   for (const ext of ['.js', '.ts', '.mjs', '.cjs']) {
     if (!extname(target) && existsSync(target + ext)) return null;