fix: emit ESM imports for injected helpers in ES modules

[cjnoname]

Summary

When a transform needs a runtime helper, oxc injects an import of it and picks import or require() based on the module kind of the source. For .js, .jsx, .ts and .tsx that module kind is ModuleKind::Unambiguous, so oxc infers it from the presence of import/export syntax — and a file that happens to have none is treated as a script, which gets require().

Node.js decides from the nearest package.json instead. A file with no module syntax inside a "type": "module" package is therefore executed as an ES module with a require() call in it:

// package.json
{ "type": "module" }

// a.ts — no import or export anywhere in the file
class Base {
  set field(value: unknown) {
    (this as any).setterCalled = true;
  }
}
class Derived extends Base {
  field = 1;
}
console.log(new Derived().field);

$ node --import @oxc-node/core/register ./a.ts
var _defineProperty = require("@oxc-node/core/helpers/defineProperty");
                      ^
ReferenceError: require is not defined in ES module scope, you can use import instead

Any transform that needs a helper hits this — lowered class fields, decorators, using, object rest/spread, and so on — as long as the file itself has no import or export.

Fix

The load hook already knows which it is, because Node.js reports the format, so it passes that down and the parser is told the module kind outright instead of guessing from the syntax:

let source_type = SourceType::from_path(src_path).unwrap_or_default().with_module(is_es_module);

The pirates hook and the public transform() API keep inferring it: both target CommonJS, where require() is the correct output.

Only files that have no module syntax at all change — anything with an import or export was already resolved to an ES module by the parser, and with_module(false) is a no-op.

Verification

packages/integrate-vitest/__tests__/helper-imports.spec.ts covers both module kinds, with and without module syntax:

package type	entry	module syntax	before	after
module	.ts	none	ReferenceError	ok
module	.mts	none	ok	ok
module	.ts	has export	ok	ok
commonjs	.ts	none	ok	ok
commonjs	.cts	none	ok	ok

plus an imported (rather than entry-point) module with no module syntax.

integrate-module (21/21), integrate-module-bundler (22/22) and integrate-vitest pass on Node.js 22.23.2 and 24.20.0 with OXC_TRANSFORM_ALL both set and unset. cargo clippy --all-targets --all-features -- -D warnings and pnpm lint are clean. No napi surface change, so the generated bindings are untouched.

Note

#742 touches oxc_transform a few lines away. The two are logically independent; whichever lands second needs a trivial rebase.

[cjnoname]

Cross-PR note, found by merging all three of these together and running the suites rather than assuming they compose.

They do not conflict textually — git merges all three cleanly — but #742 changes the class-field semantics that fixtures in the other two relied on, so whichever landed second would have had red CI:

• helper-imports.spec.ts (fix: emit ESM imports for injected helpers in ES modules #743) forced a helper with useDefineForClassFields: false. That is [[Define]] under today's inverted mapping, and [[Set]] once fix: honour useDefineForClassFields instead of inverting it #742 corrects it — and [[Set]] needs no helper, so the fixture stopped testing anything.
• The OXC_TRANSFORM_ALL spec (fix: migrate to module.registerHooks() and report the module format oxc-node actually generates #633) asserted the transformed dependency reports setterCalled: true, which flips with the mapping.

Both fixtures are now independent of it:

• fix: emit ESM imports for injected helpers in ES modules #743 uses target: ES2022 with the option left unset, which is [[Define]] both ways — TypeScript's default for that target, and what unwrap_or_default() produces today. Verified against both builds.
• fix: migrate to module.registerHooks() and report the module format oxc-node actually generates #633 runs the dependency under both values of the option and asserts they disagree when it was transformed and agree when it was not.

With those in place, all three merged together: 73/73 on Node.js 22.22.3, 24.8.0, 24.20.0, 26.2.0 and 26.8.1, 71 passed + 2 skipped on 22.18.0 and 24.7.0 (the two specs that need the synchronous hooks), and the engines floor job green on 20.19.0. Merge order does not matter now.

No product code changed for this — only the two fixtures.

[Brooooooklyn]

Deep review + polish pass, pushed as two commits on the rebased branch.

Rebase. #742 landed first, so the branch is now rebased onto main — the "trivial rebase" from the note above is done and was in fact clean (the class-field decoupling in 1efc9ca holds under the shipped polarity; verified against the post-#742 build).

The product change is correct and minimal. In oxc, SourceType::with_module(false) is a literal no-op (if yes { module_kind = Module }), so the only behaviour that changes is for files Node.js reports as format: "module" — exactly the broken case. The pirates hook and transform() pass false, so the CommonJS paths are byte-identical to before.

Two fixture defects found by adversarial review, both verified by reproduction before fixing:

1. Windows CI would have failed all six cases. --import was given fileURLToPath(...) — an absolute path. That parses only on POSIX; on Windows the drive letter is read as a URL scheme and Node.js exits with ERR_UNSUPPORTED_ESM_URL_SCHEME before the hooks register (reproduced the mechanism with a c: path). Now passes the file URL's href.
2. The "commonjs package / entry.ts" row never ran as CommonJS. For .ts, the loader consults the file's own tsconfig module before the package.json type, so module: "ESNext" loaded that row as an ES module — proof: it went red without the fix. Each row now gets a tsconfig that agrees with its package type, and every entry prints the module kind it actually executed as (typeof require) so a silent format flip fails the spec instead of passing under the wrong kind.

A second review round found one more: the spawned fixtures inherited TS_NODE_PROJECT / OXC_TSCONFIG_PATH, which override every fixture's tsconfig — an override with useDefineForClassFields: false turns helper injection off and the spec passes against a broken binding (reproduced: field: 1, exit 0, on the unfixed build). Both are cleared now; OXC_TRANSFORM_ALL still passes through.

Verification (macOS arm64, Node.js 24.21.0):

• Spec against a binding built from main's src/lib.rs: the two genuine ES-module cases fail with the original ReferenceError, CommonJS rows pass — the spec is not vacuous, including under a hostile OXC_TSCONFIG_PATH.
• Full pnpm test with OXC_TRANSFORM_ALL both set and unset: integrate-module 21/21, integrate-module-bundler 22/22, integrate-vitest 61/61.
• cargo clippy --all-targets --all-features -- -D warnings, cargo fmt --check, vp fmt --check, vp lint: clean.

Out of scope, noted for a separate issue: a .ts entry point with ESM syntax inside a "type": "commonjs" package fails with ERR_REQUIRE_CYCLE_MODULE via the pirates require path. Reproduced identically on main's binding, so it is pre-existing and untouched by this PR.