fix: register module hooks synchronously on Node.js >= 26.2.0

[cjnoname]

Problem

packages/core/register.mjs calls module.register(). Node.js runtime-deprecated that
API in v25.9.0 (DEP0205), so every
node --import @oxc-node/core/register now prints:

(node:94305) [DEP0205] DeprecationWarning: `module.register()` is deprecated. Use `module.registerHooks()` instead.

This is not only cosmetic — pnpm test already fails on Node.js 26 on main, because
four tests assert an empty stderr and the warning lands there. CI runs Node 22 and 24
only, so it has stayed invisible:

# main, unmodified, Node v26.8.1
 Test Files  2 failed | 7 passed | 1 skipped (10)
      Tests  4 failed | 70 passed | 7 skipped (81)

 FAIL  __tests__/stdin-tty.spec.ts > CLI properly handles stdin piping
 FAIL  __tests__/tsconfig-discovery.spec.ts > a broken project reference in an ancestor that does not own the file breaks nothing
 FAIL  __tests__/tsconfig-discovery.spec.ts > tsconfig paths apply to JavaScript importers with allowJs unset
 FAIL  __tests__/tsconfig-discovery.spec.ts > a project directory with a space and non-ASCII characters still resolves

All four are the same diff: + (node:1427) [DEP0205] DeprecationWarning: ...

Change

Use the synchronous, in-thread module.registerHooks() where it is complete, and keep
module.register() everywhere else. The ESM path is otherwise unchanged — resolve still
hands everything to createResolve and load to oxcLoad, exactly as esm.mjs does.

Three things make this more than a one-line swap. Each was measured against release
binaries rather than reasoned about, and a naive replacement fails on all three.

1. registerHooks() shows require() to the hooks; register() never did

The CommonJS resolve/load context carries no importAttributes, and both
createResolve and load reject a context without it:

Error: Missing field `importAttributes`
    at resolve (.../register.mjs:11:12)
    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1217:25)

So a request whose conditions contain require goes to nextResolve/nextLoad.
Node.js resolves those correctly by itself, because the pirates hook has put the
TypeScript extensions into Module._extensions — that is what lets its CommonJS resolver
complete require('./dep') to ./dep.ts and require('./sub') to ./sub/index.ts.

2. A file that oxc-node settles on as CommonJS must go back to nextLoad

Otherwise the pirates hook no longer produces the inline source map, and stack trace
precision regresses. cli.spec.ts covers exactly this:

	reported location
module.register()	stacktrace-cjs.cts:6:12 ✅
naive registerHooks()	stacktrace-cjs.cts:5:10 ❌

Calling oxcLoad first and only then deferring is what keeps #759 intact — a
CommonJS-reported file that actually contains ESM syntax still runs as an ES module.

3. registerHooks needs a version floor, not a typeof check

It exists from v22.15.0/v23.5.0, but two defects had to be fixed first. Bisected over
every available minor:

Node.js	ESM importing a CJS package	require() in an imported CJS entry
22.14.0 (no registerHooks)	— fallback	— fallback
22.15.0 – 22.18.0	❌	❌
22.19.0 – 22.22.1	✅	❌
23.5.0 – 23.11.1 (EOL)	❌	❌
24.0.0 – 24.4.1	❌	❌
24.5.0 – 25.9.0	✅	❌
26.0.0 – 26.1.0	✅	❌
26.2.0+	✅	✅

Those boundaries are not arbitrary — they match the Node.js fixes exactly:

• nodejs/node#59011 "module: fix conditions
  override in synchronous resolve hooks" — v24.5.0 (fe0195fdcc), backported to v22.19.0
  (0eec5cc492), never backported to the end-of-life 23.x line. Without it,
  import { jsx } from 'react/jsx-runtime' fails with does not provide an export named 'jsx'.
• nodejs/node#62920 "module: fix sync hook
  short-circuit in require() in imported CJS" — v26.2.0 (96f19a16d0). Without it, a .ts
  entry in a CommonJS package cannot require() its own files.

Hence the floor is v26.2.0. Below it the fallback runs and nothing changes for those
runtimes; v26.0/v26.1 keep the warning, which is the honest outcome given the defect.

Verification

34 release binaries, v22.14.0 → v26.8.2 (every available 22.x/23.x/24.x/25.x/26.x
minor), against three fixtures: a CommonJS require() tree (extensionless .ts,
directory index.ts, explicit .cts), an ESM tree (extensionless, .mts, tsconfig
paths, .tsx + react/jsx-runtime), and a createRequire tree.

versions tested: 34
failures:        0
still warning:   26.0.0 26.1.0

Upstream suite, same machine, Node v26.8.1:

	result
main	`4 failed
this PR	75 passed

vp fmt and vp lint are clean.

Test added

require() completing an extensionless TypeScript specifier had no coverage. The new case
in cjs-esm-syntax.spec.ts fails with Cannot find module './dep' if the pirates hook
stops registering those extensions — verified by removing it.

[Brooooooklyn]

Excellent work — the design is right and the version-floor research is thorough. Verified end-to-end on Node 26.9.0 (75/75 tests, no DEP0205) and 24.11.1 (fallback identical). Two real regressions vs main to fix before merge, both with small fixes.

1. import of .node addons / non-UTF-8 commonjs files crashes in oxcLoad

nextLoad is not equivalent across the two APIs:

• async defaultLoad (the old register() path) returns source: null for commonjs → transform_output takes the None branch → load_commonjs_esm's SourceType::from_path/from_utf8 guards return Ok(None) → Node's CJS machinery handles it.
• sync defaultLoadSync always reads the file → oxcLoad receives {format: "commonjs", source: <raw bytes>} → transform_output → oxc_transform → try_as_str → UTF-8 decode throws.

resolve reports "commonjs" for .node ("cjs" | "cts" | "node" => None → unwrap_or("commonjs") in create_resolve), so the throw happens inside oxcLoad before the format === "commonjs" deferral can run.

Repro (fixture: any dir + symlinked @oxc-node/core):

// entry.mts — a real .node binary next to it
import addon from "./addon.node";
console.log("addon:", typeof addon);

	result
Node 24.x (register())	addon: object
Node 26.9 (registerHooks)	Error: Failed to convert Uint8Array to Vec<u8> at register.mjs:93

Same crash for a latin-1-encoded .js in a "type": "commonjs" package (prints caf� on the old path). import of .node is a legitimate napi pattern — this will hit real users on 26.2+.

Suggested fix: in transform_output, treat an undecodable source on a non-JSON commonjs result like source: null (return {format, source: null, response_url} → CJS machinery) instead of propagating the decode error. load_commonjs_esm already reads the file itself, so the #759 flip still works for real JS/TS.

2. isCommonJsRequire misroutes imports under --conditions=require

--conditions appends custom conditions to every request's condition set. Verified on 26.9:

node --import @oxc-node/core/register --conditions=require ./entry.mts

Scenario	Old path	This PR
import "./dyn" (extensionless .ts)	extensionless: 5	ERR_MODULE_NOT_FOUND
import "./modpkg/flip.ts" (ESM syntax in CJS pkg — the #759 case)	format: module	ERR_REQUIRE_CYCLE_MODULE

--conditions=import is the mirror hazard: it injects "import" into require contexts, so an includes("import") check would misfire the other way and crash napi on the missing field.

Suggested fix: discriminate on the field that actually crashes — context.importAttributes === undefined. Verified via probes on 26.9: require contexts never carry importAttributes; import contexts always have it ({}), under both poisoned flags.

Non-blocking notes

• The v26.2.0 floor is conservative. nodejs/node#62920 only bites when a sync load hook customizes imported CJS (returns source) — this implementation never does, it always defers. Forcing registerHooks on 24.11.1/22.23.2 passes the whole suite including the require() fixtures; the real binding constraint is #59011 (24.5.0, backported 22.19.0, never 23.x). A lower floor would additionally silence DEP0205 on 26.0/26.1. Keeping 26.2 is a defensible safety margin — your call.
• Double nextLoad is legal but wasteful — no once-guard in nextStep; each call re-reads the file (~3 reads + 2 transforms per imported CJS file). {format: "commonjs", source: null} would be equivalent (null source → loadCJSModuleWithModuleLoad) with one less pass. Correct as-is.
• result.format === "commonjs" misses commonjs-typescript (Node-detected format for node_modules .ts resolved with format: None). Harmless today — the passthrough is equivalent — but the invariant is narrower than the comment implies.
• Test comment nit: Module._extensions is consulted per-require(), so reordering addHook/registerHooks inside register.mjs wouldn't actually fail — removing addHook is what breaks. Comment overstates the ordering requirement.

Verified working (no action needed)

require() inside imported CJS (.ts/.json/.cjs, dirs, builtins) · require(esm) · createRequire · import() in CJS · worker threads · eval/stdin · .cjs vs .mts/.ts entry condition assignment · stack-trace precision (cli.spec.ts 6:12) · JSON modules · esm.mjs/--loader fallback · promise paths (sync hooks never return Either::B).

Branch synced with main (merge e9f8cd7); suite re-verified green on 26.9 post-merge.

[cjnoname]

Thanks — both regressions confirmed locally on v26.8.1 (identical repros) and both fixed in 5125e3c. Verified: the whole suite passes on v26.8.1 (sync path) and v24.16.0 (fallback), 83 passed, and the four new tests fail on the previous commit for exactly the four reported reasons.

1. Binary / non-UTF-8 commonjs source — fixed as suggested, in transform_output: a commonjs* result whose source does not decode is handed back as source: null and the CommonJS machinery reads the file, which is what the asynchronous default load did implicitly. import addon from './addon.node' prints addon: object again, and a latin-1 file in a "type": "commonjs" package prints its replacement character as before. JSON keeps its decode error, since invalid UTF-8 there is a real failure.

2. isCommonJsRequire — now context?.importAttributes === undefined, with the reasoning in the comment. Re-probed on v26.8.1 to confirm your finding: with --conditions=require, an import still carries importAttributes ({}) and merely has require appended to conditions, while a require() carries none. Tests cover both directions under --conditions=require and --conditions=import, so neither flag can be poisoned again without a failure.

Non-blocking notes

• Double nextLoad — removed. The hook now returns { format, source: null, responseURL } directly: one read and one transform less per imported CommonJS file, and stack-trace precision is unchanged (cli.spec.ts still reports 6:12).
• commonjs-typescript — the test is now result.format.startsWith("commonjs"), so Node.js' own type-stripping format takes the same path instead of relying on the passthrough being equivalent.
• Version floor — kept at v26.2.0, comment corrected to say why: modules: fix sync hook short-circuit in require() in imported CJS nodejs/node#62920 only bites a hook that returns source for imported CommonJS, which this one never does, so the strictly required floor is #59011's v24.5.0 / v22.19.0. Keeping v26.2.0 means every runtime below it behaves exactly as it does today; it costs DEP0205 on v25.9–v26.1, which I would rather pay than widen the blast radius of a new code path across the 22/24 LTS lines. Happy to lower it if you prefer the warning gone everywhere — the diff is one line.
• CI — added a Node.js 26 job to the macOS/Windows binding matrix. Nothing in the matrix ran the synchronous path before, which is why the original DEP0205 failure was invisible.
• Test comment — reworded: dropping the pirates hook is what breaks the extensionless require(), not the registration order.

[Brooooooklyn]

Re-verified 5125e3c end-to-end — both findings are fixed and confirmed working on real binaries.

Verified

.node / non-UTF-8 commonjs deferral — the try_as_str guard in transform_output sits in the Some(source) arm before the node_modules skip, so .node and latin-1 defer correctly whether local or under node_modules:

Scenario	Before (26.9)	Now (26.9)
import './addon.node'	Failed to convert Uint8Array	addon: object
import './latin.js' (0xe9)	same crash	caf� (4 chars, matches old path)

JSON correctly keeps its decode error (invalid UTF-8 there is a real failure).

importAttributes discriminator — re-probed both directions:

Flag	import (extensionless .ts)	require()
--conditions=require	dep-ok	dep-ok
--conditions=import	dep-ok	dep-ok

require() contexts never carry importAttributes; import contexts always do — including under the flags. Neither direction can be poisoned now.

Suite — 83/83 on v26.9.0 (sync path) and v24.11.1 (fallback) with a fresh binding. Note: pnpm run test resolves node through Vite+'s bundled runtime (24.x here), so it exercises the fallback — the direct vitest binary under fnm is what actually runs the sync path. vp check clean; 61 CI checks green, and the new node: 26 matrix entry means CI now covers the synchronous path for the first time.

The four new spec tests are the right ones — extensionless import, CJS→ESM flip, and require() of .ts under both injected conditions, plus .node and latin-1. Using the package's own binding as the .node fixture is a nice touch.

Remaining notes (non-blocking)

• commonjs-typescript + source: null is still a contract violation in the abstract — it would produce ERR_INVALID_RETURN_PROPERTY_VALUE — but it's only reachable via import of .ts/.cts inside node_modules, which Node refuses on both paths anyway (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING on the old one). Dead-in-practice; if you ever want the shape airtight, exact-match === "commonjs" in the JS deferral (and == "commonjs" in the Rust guard) makes the invalid shape unreachable while losing nothing — a node_modules .ts would then get the informative node error instead of one blaming the hook. Not worth churning on.
• .node as a dep main fails on both paths (addon format quirks) — pre-existing, unchanged by this PR.

LGTM.

[Brooooooklyn]

Picked up the two remaining notes myself — "allow edits by maintainers" is off on this branch, so they're in cjnoname#1 against fix/register-hooks-sync (commit 6e730fe on fix/register-hooks-sync-followup); merge that, or cherry-pick, or flip the checkbox and I'll push it here.

1. .node under node_modules  (pre-existing, both hook paths)
   Node defaultLoad ─► {format:"addon", source:null}
   transform_output ─► source: None ──napi──► undefined ─► translateAddon: "Expected null … got undefined"
   fix: Some(Either4::D(Null)) — hand back the null Node.js gave us

2. commonjs-typescript  (this PR)
   startsWith("commonjs") ─► source:null ─► "Expected a string, an ArrayBuffer, or a TypedArray"
   fix: exact "commonjs" in register.mjs and the Rust non-UTF-8 guard; Node.js' own
        ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING is what shows for a .ts dependency now

(1) surfaced while probing the sync path but reproduces on v22/v24 with --experimental-addon-modules and the async hooks too, so it's not a regression here — just the one shared code path both fixes touch.

Verified: 85/85 on v26.9.0 (sync, direct vitest — pnpm run test resolves Vite+'s bundled 24.x and only ever exercises the fallback) and v24.11.1; the new spec alone on 22.23.2 / 24.11.1 / 26.9.0 and with OXC_TRANSFORM_ALL=true; both tests red before, green after; clippy/fmt/vp check clean.

[Brooooooklyn]

Opened #767 on the main repo: your three commits unchanged plus the two follow-ups (cjnoname#1), so the full matrix — including the new Linux node@26 jobs — runs on it. Either merge cjnoname#1 into this branch and I'll close #767, or we land #767 and it closes this one; your call, authorship stays yours in both.