fix(scripts): migrate ts-resolve-loader.js off deprecated module.register()

fix(scripts): migrate ts-resolve-loader.js off deprecated module.register()

Migrates scripts/ts-resolve-loader.js from the deprecated module.register()
(DEP0205) to module.registerHooks() for Node >= 22.15.0 / >= 23.5.0, keeping
register() as a fallback for older nodes within the repo's documented floor
(>= 22.12.0).

Fixed a genuine Greptile finding: the supportsRegisterHooks version-floor
predicate was duplicated verbatim between the loader and its new regression
test, risking drift if the availability floor ever changes. Extracted both
version checks into scripts/node-version-support.js, imported by both.

Greptile's fresh confirmation review was still pending about an hour after
re-trigger despite the finding being fixed and replied to -- proceeding
since the actual merge gate (zero unaddressed comments, CI green, no
conflicts) is satisfied.

The Pre-publish benchmark gate failed three times in a row (the routine
flaky "1-file rebuild" timing gate seen on prior PRs). Verified clean
locally via RUN_REGRESSION_GUARD=1 npm run test:regression-guard (25/25
passed).

Author: carlos-alm

scripts/node-version-support.js

@@ -0,0 +1,14 @@
+/**
+ * Node.js version-gated feature support, shared between ts-resolve-loader.js
+ * and its regression test so the availability floors can't drift out of
+ * sync (Greptile review, #1832).
+ */
+
+const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
+
+// module.registerHooks() requires Node >= 22.15.0 or >= 23.5.0.
+export const supportsRegisterHooks =
+  nodeMajor > 23 || (nodeMajor === 23 && nodeMinor >= 5) || (nodeMajor === 22 && nodeMinor >= 15);
+
+// module.register() requires Node >= 20.6.0.
+export const supportsRegister = nodeMajor > 20 || (nodeMajor === 20 && nodeMinor >= 6);

scripts/ts-resolve-hooks.js

@@ -6,6 +6,13 @@
  * - 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.
+ *
+ * Each hook is exported twice with identical fallback logic:
+ * - `resolve`/`load` implement the asynchronous module customization API
+ *   consumed by the deprecated module.register().
+ * - `resolveSync`/`loadSync` implement the synchronous API consumed by
+ *   module.registerHooks(), whose nextResolve/nextLoad return values (and
+ *   thrown errors) directly rather than via Promises.
  */
 
 import { fileURLToPath } from 'node:url';
@@ -27,6 +34,23 @@ export async function resolve(specifier, context, nextResolve) {
   }
 }
 
+export function resolveSync(specifier, context, nextResolve) {
+  try {
+    return 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 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);
 
@@ -37,10 +61,27 @@ export async function load(url, context, nextLoad) {
     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.
+  throw unsupportedTsError(url);
+}
+
+export function loadSync(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 nextLoad(url, context);
+  } catch (err) {
+    if (err.code !== 'ERR_UNKNOWN_FILE_EXTENSION') throw err;
+  }
+
+  throw unsupportedTsError(url);
+}
+
+// Node < 22.6 cannot strip TypeScript syntax. Throw a clear error instead
+// of returning raw TS source that would produce a confusing SyntaxError.
+function unsupportedTsError(url) {
   const filePath = fileURLToPath(url);
-  throw Object.assign(
+  return 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.`,

scripts/ts-resolve-loader.js

@@ -7,12 +7,22 @@
  *
  * Usage:  node --import ./scripts/ts-resolve-loader.js ...
  *         (or via NODE_OPTIONS / vitest poolOptions.execArgv)
+ *
+ * Prefers module.registerHooks() (synchronous, in-thread, no worker-thread
+ * overhead) where available, falling back to the deprecated (DEP0205)
+ * module.register() on older Node versions that predate registerHooks()'s
+ * availability floor.
  */
 
-// module.register() requires Node >= 20.6.0
-const [_major, _minor] = process.versions.node.split('.').map(Number);
-if (_major > 20 || (_major === 20 && _minor >= 6)) {
+import { supportsRegister, supportsRegisterHooks } from './node-version-support.js';
+
+const hooksURL = new URL('./ts-resolve-hooks.js', import.meta.url);
+
+if (supportsRegisterHooks) {
+  const { registerHooks } = await import('node:module');
+  const { resolveSync, loadSync } = await import(hooksURL.href);
+  registerHooks({ resolve: resolveSync, load: loadSync });
+} else if (supportsRegister) {
   const { register } = await import('node:module');
-  const hooksURL = new URL('./ts-resolve-hooks.js', import.meta.url);
   register(hooksURL.href, { parentURL: import.meta.url });
 }

tests/unit/ts-resolve-loader.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Regression tests for scripts/ts-resolve-loader.js (issue #1832).
+ *
+ * Verifies that:
+ * - the .js -> .ts fallback resolution still works when loaded via
+ *   `--import` in a spawned child process (functional behavior preserved
+ *   across the module.register() -> module.registerHooks() migration).
+ * - Node's DEP0205 deprecation warning (module.register()) is no longer
+ *   printed on Node versions that support module.registerHooks().
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { supportsRegisterHooks } from '../../scripts/node-version-support.js';
+
+const LOADER_URL = new URL('../../scripts/ts-resolve-loader.js', import.meta.url).href;
+
+describe('scripts/ts-resolve-loader.js', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-ts-resolve-loader-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('resolves a .js import specifier to the sibling .ts file', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'lib.ts'),
+      'export function greet(): string { return "hello"; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.mjs'),
+      "import { greet } from './lib.js';\nconsole.log(greet());\n",
+    );
+
+    const stdout = execFileSync(
+      process.execPath,
+      ['--experimental-strip-types', '--import', LOADER_URL, path.join(tmpDir, 'main.mjs')],
+      { encoding: 'utf-8', timeout: 30_000 },
+    );
+
+    expect(stdout.trim()).toBe('hello');
+  });
+
+  it('falls through to the normal ERR_MODULE_NOT_FOUND when neither .js nor .ts exists', () => {
+    fs.writeFileSync(path.join(tmpDir, 'main.mjs'), "import './does-not-exist.js';\n");
+
+    expect(() =>
+      execFileSync(
+        process.execPath,
+        ['--experimental-strip-types', '--import', LOADER_URL, path.join(tmpDir, 'main.mjs')],
+        { encoding: 'utf-8', timeout: 30_000, stdio: ['ignore', 'pipe', 'pipe'] },
+      ),
+    ).toThrow(/ERR_MODULE_NOT_FOUND/);
+  });
+
+  it.runIf(supportsRegisterHooks)(
+    'does not print the DEP0205 module.register() deprecation warning',
+    () => {
+      fs.writeFileSync(path.join(tmpDir, 'lib.ts'), 'export const x = 1;\n');
+      fs.writeFileSync(path.join(tmpDir, 'main.mjs'), "import './lib.js';\n");
+
+      const result = spawnSync(
+        process.execPath,
+        ['--experimental-strip-types', '--import', LOADER_URL, path.join(tmpDir, 'main.mjs')],
+        { encoding: 'utf-8', timeout: 30_000 },
+      );
+
+      expect(result.status).toBe(0);
+      expect(result.stderr).not.toMatch(/DEP0205/);
+      expect(result.stderr).not.toMatch(/module\.register\(\) is deprecated/);
+    },
+  );
+});