feat: migrate 17 leaf modules from JavaScript to TypeScript

package.json

@@ -33,9 +33,9 @@
     "build:wasm": "node scripts/build-wasm.js",
     "typecheck": "tsc --noEmit",
     "verify-imports": "node scripts/verify-imports.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test": "node scripts/test.js run",
+    "test:watch": "node scripts/test.js",
+    "test:coverage": "node scripts/test.js run --coverage",
     "lint": "biome check src/ tests/",
     "lint:fix": "biome check --write src/ tests/",
     "format": "biome format --write src/ tests/",

scripts/test.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Test runner wrapper that configures Node.js for the TypeScript migration
+ * before spawning vitest. Adds --experimental-strip-types on Node >= 22.6
+ * so child processes can execute .ts files natively.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const hook = pathToFileURL(resolve(__dirname, 'ts-resolver-hook.js')).href;
+
+const args = process.argv.slice(2);
+const vitestBin = resolve(__dirname, '..', 'node_modules', 'vitest', 'vitest.mjs');
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+const supportsStripTypes = major > 22 || (major === 22 && minor >= 6);
+
+// Build NODE_OPTIONS: resolver hook + type stripping (Node >= 22.6)
+const hookImport = `--import ${hook}`;
+const existing = process.env.NODE_OPTIONS || '';
+const parts = [
+  existing.includes(hookImport) ? null : hookImport,
+  supportsStripTypes && !existing.includes('--experimental-strip-types')
+    ? '--experimental-strip-types'
+    : null,
+  existing || null,
+].filter(Boolean);
+
+// Spawn vitest via node directly — avoids shell: true and works cross-platform
+const result = spawnSync(process.execPath, [vitestBin, ...args], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    NODE_OPTIONS: parts.join(' '),
+  },
+});
+
+if (result.error) {
+  process.stderr.write(`[test runner] Failed to spawn vitest: ${result.error.message}\n`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

scripts/ts-resolver-hook.js

@@ -0,0 +1,10 @@
+/**
+ * Node.js module resolution hook for incremental TypeScript migration.
+ *
+ * Registered via --import. Uses the module.register() API (Node >= 20.6)
+ * to install a resolve hook that falls back to .ts when .js is missing.
+ */
+
+import { register } from 'node:module';
+
+register('./ts-resolver-loader.js', import.meta.url);

scripts/ts-resolver-loader.js

@@ -0,0 +1,43 @@
+/**
+ * ESM loader: resolve .js → .ts fallback for incremental migration.
+ *
+ * - resolve hook: when a .js specifier is not found, retry with .ts
+ * - load hook: strip type annotations from .ts files using Node's built-in
+ *   amaro (Node >= 22.6) so the loader works outside of Vitest/Vite too
+ */
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (err) {
+    if (err.code !== 'ERR_MODULE_NOT_FOUND' || !specifier.endsWith('.js')) throw err;
+
+    const tsSpecifier = specifier.replace(/\.js$/, '.ts');
+    try {
+      return await nextResolve(tsSpecifier, context);
+    } catch {
+      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;
+  }
+
+  // Fallback: read the file and return as module source
+  // This path is reached on Node < 22.6 where --experimental-strip-types
+  // is unavailable. TypeScript-only syntax will cause a parse error — callers
+  // should ensure .ts files contain only erasable type annotations.
+  const source = await readFile(fileURLToPath(url), 'utf-8');
+  return { format: 'module', source, shortCircuit: true };
+}

src/graph/algorithms/bfs.js → src/graph/algorithms/bfs.ts

@@ -1,18 +1,26 @@
+import type { CodeGraph } from '../model.js';
+
+export interface BfsOpts {
+  maxDepth?: number;
+  direction?: 'forward' | 'backward' | 'both';
+}
+
 /**
  * Breadth-first traversal on a CodeGraph.
  *
- * @param {import('../model.js').CodeGraph} graph
- * @param {string|string[]} startIds - One or more starting node IDs
- * @param {{ maxDepth?: number, direction?: 'forward'|'backward'|'both' }} [opts]
- * @returns {Map<string, number>} nodeId → depth from nearest start node
+ * @returns nodeId → depth from nearest start node
  */
-export function bfs(graph, startIds, opts = {}) {
+export function bfs(
+  graph: CodeGraph,
+  startIds: string | string[],
+  opts: BfsOpts = {},
+): Map<string, number> {
   const maxDepth = opts.maxDepth ?? Infinity;
   const direction = opts.direction ?? 'forward';
   const starts = Array.isArray(startIds) ? startIds : [startIds];
 
-  const depths = new Map();
-  const queue = [];
+  const depths = new Map<string, number>();
+  const queue: string[] = [];
 
   for (const id of starts) {
     const key = String(id);
@@ -24,11 +32,11 @@ export function bfs(graph, startIds, opts = {}) {
 
   let head = 0;
   while (head < queue.length) {
-    const current = queue[head++];
-    const depth = depths.get(current);
+    const current = queue[head++]!;
+    const depth = depths.get(current)!;
     if (depth >= maxDepth) continue;
 
-    let neighbors;
+    let neighbors: string[];
     if (direction === 'forward') {
       neighbors = graph.successors(current);
     } else if (direction === 'backward') {

src/graph/algorithms/centrality.js → src/graph/algorithms/centrality.ts

@@ -1,11 +1,15 @@
+import type { CodeGraph } from '../model.js';
+
+export interface FanInOut {
+  fanIn: number;
+  fanOut: number;
+}
+
 /**
  * Fan-in / fan-out centrality for all nodes in a CodeGraph.
- *
- * @param {import('../model.js').CodeGraph} graph
- * @returns {Map<string, { fanIn: number, fanOut: number }>}
  */
-export function fanInOut(graph) {
-  const result = new Map();
+export function fanInOut(graph: CodeGraph): Map<string, FanInOut> {
+  const result = new Map<string, FanInOut>();
   for (const id of graph.nodeIds()) {
     result.set(id, {
       fanIn: graph.inDegree(id),

src/graph/algorithms/leiden/rng.js → src/graph/algorithms/leiden/rng.ts

@@ -1,11 +1,12 @@
+export interface Rng {
+  nextDouble(): number;
+}
+
 /**
  * Seeded PRNG (mulberry32).
  * Drop-in replacement for ngraph.random — only nextDouble() is needed.
- *
- * @param {number} [seed]
- * @returns {{ nextDouble(): number }}
  */
-export function createRng(seed = 42) {
+export function createRng(seed: number = 42): Rng {
   let s = seed | 0;
   return {
     nextDouble() {

src/graph/algorithms/shortest-path.js → src/graph/algorithms/shortest-path.ts

@@ -1,35 +1,34 @@
+import type { CodeGraph } from '../model.js';
+
 /**
  * BFS-based shortest path on a CodeGraph.
  *
- * @param {import('../model.js').CodeGraph} graph
- * @param {string} fromId
- * @param {string} toId
- * @returns {string[]|null} Path from fromId to toId (inclusive), or null if unreachable
+ * @returns Path from fromId to toId (inclusive), or null if unreachable
  */
-export function shortestPath(graph, fromId, toId) {
+export function shortestPath(graph: CodeGraph, fromId: string, toId: string): string[] | null {
   const from = String(fromId);
   const to = String(toId);
 
   if (!graph.hasNode(from) || !graph.hasNode(to)) return null;
   if (from === to) return [from];
 
-  const parent = new Map();
+  const parent = new Map<string, string | null>();
   parent.set(from, null);
   const queue = [from];
   let head = 0;
 
   while (head < queue.length) {
-    const current = queue[head++];
+    const current = queue[head++]!;
     for (const neighbor of graph.successors(current)) {
       if (parent.has(neighbor)) continue;
       parent.set(neighbor, current);
       if (neighbor === to) {
         // Reconstruct path
-        const path = [];
-        let node = to;
+        const path: string[] = [];
+        let node: string | null = to;
         while (node !== null) {
           path.push(node);
-          node = parent.get(node);
+          node = parent.get(node) ?? null;
         }
         return path.reverse();
       }

src/graph/algorithms/tarjan.js → src/graph/algorithms/tarjan.ts

@@ -1,19 +1,20 @@
+import type { CodeGraph } from '../model.js';
+
 /**
  * Tarjan's strongly connected components algorithm.
  * Operates on a CodeGraph instance.
  *
- * @param {import('../model.js').CodeGraph} graph
- * @returns {string[][]} SCCs with length > 1 (cycles)
+ * @returns SCCs with length > 1 (cycles)
  */
-export function tarjan(graph) {
+export function tarjan(graph: CodeGraph): string[][] {
   let index = 0;
-  const stack = [];
-  const onStack = new Set();
-  const indices = new Map();
-  const lowlinks = new Map();
-  const sccs = [];
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+  const indices = new Map<string, number>();
+  const lowlinks = new Map<string, number>();
+  const sccs: string[][] = [];
 
-  function strongconnect(v) {
+  function strongconnect(v: string): void {
     indices.set(v, index);
     lowlinks.set(v, index);
     index++;
@@ -23,17 +24,17 @@ export function tarjan(graph) {
     for (const w of graph.successors(v)) {
       if (!indices.has(w)) {
         strongconnect(w);
-        lowlinks.set(v, Math.min(lowlinks.get(v), lowlinks.get(w)));
+        lowlinks.set(v, Math.min(lowlinks.get(v)!, lowlinks.get(w)!));
       } else if (onStack.has(w)) {
-        lowlinks.set(v, Math.min(lowlinks.get(v), indices.get(w)));
+        lowlinks.set(v, Math.min(lowlinks.get(v)!, indices.get(w)!));
       }
     }
 
     if (lowlinks.get(v) === indices.get(v)) {
-      const scc = [];
-      let w;
+      const scc: string[] = [];
+      let w: string | undefined;
       do {
-        w = stack.pop();
+        w = stack.pop()!;
         onStack.delete(w);
         scc.push(w);
       } while (w !== v);