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

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;