Skip to content

fix(core): resolve helper imports against the loader, not the user file - #803

Merged
Brooooooklyn merged 7 commits into
mainfrom
fix/helper-specifier-resolution
Oct 8, 2026
Merged

Brooooooklyn merged 7 commits into
mainfrom
fix/helper-specifier-resolution

Conversation

@Brooooooklyn

@Brooooooklyn Brooooooklyn commented Oct 8, 2026 •

Copy link
Copy Markdown
Member

Summary

Helper imports emitted by the transformer (import/require("@oxc-node/core/helpers/*")) resolved relative to the transformed file, so any file without @oxc-node/core in its own resolution scope — a global oxnode, or node --import <abs-path>/register.mjs on a script outside a project — failed with ERR_MODULE_NOT_FOUND on the first class field (issue #794).

The fix resolves helper specifiers against the loader's own copy, which is versioned with the emitted code:

  • Tagged helper specifiers: each copy derives a tag from its own module URL (register.mjs on the main thread, esm.mjs on module.register's worker) and passes @oxc-node/core@<tag> as the transformer's helper_loader.module_name, so emitted specifiers (@oxc-node/core@<tag>/helpers/x) name the copy that emitted them
  • Resolver registry: a Symbol.for-keyed map on globalThis records each registered copy's createRequire resolver under its tag — populated per realm by register.mjs (main thread, require() and registerHooks) and esm.mjs (the module.register worker). A tagged specifier resolves through exactly its owner's resolver, which never consults the hook chain; the resolved file URL is then passed to nextResolve so format detection and foreign hooks still run
  • CJS (register.mjs): require() never reaches module.register() hooks and registerHooks() forwards it to Node's own CommonJS resolution, which funnels through Module._resolveFilename — patched to consult the same registry, with a process-wide (Symbol.for) re-entrancy flag so inner lookups fall through every copy's wrapper
  • Untagged specifiers — emitted by older published copies that share a process with this one — try every registered resolver, newest registration first
  • Multiple registered copies: two copies can coexist (NODE_OPTIONS preload + global oxnode, project + global install), and chained hooks transform each file more than once — on both paths the first-registered copy transforms the raw source. Tagging makes helper resolution independent of registration order and version skew
  • Non-helper specifiers are untouched on both paths (the project's own node_modules still resolves/fails exactly as before)
  • The loader's helpers win even if the project has its own @oxc-node/core — deliberate, since helper versions are coupled to the transformer version

Out of scope: the reporter's second point — not lowering class_properties/class_static_block/ERM on Node versions with native support. It's a separate optimization (would eliminate most helper imports) and worth a follow-up issue.

Closes #794

Test plan

Extended helper-imports.spec.ts with a global install suite (linkCore: false + absolute-path --import simulates the global CLI):

  • bare-directory repro of the issue verbatim: class Counter { count = 1 } prints count: 1
  • ESM helper imports resolve from the loader's copy with no package in scope
  • unrelated specifiers still resolve (and still ERR_MODULE_NOT_FOUND) from the project
  • a poisoned project-local @oxc-node/core (no helpers export) cannot shadow the loader's helpers
  • CJS path covered by the existing helper-imports cases (they exercise require through the patched _resolveFilename)

Verified: vp fmt + vp check, cargo test, pnpm test (all integrate-* suites) green.

Emitted @oxc-node/core/helpers/* specifiers resolved relative to the
transformed file, so a global oxnode or a script outside a project
failed with ERR_MODULE_NOT_FOUND on the first class field (issue #794).
ESM: the resolve hooks resolve helper specifiers with parentURL =
import.meta.url. CJS: Module._resolveFilename resolves them via a
createRequire bound to this package — require() never reaches
module.register() hooks, and registerHooks() funnels require through
_resolveFilename, making it the single point that covers every runtime.

Closes #794
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 8, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-08T13:34:53.029897Z 58d76ed New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9fc1b7cc66

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/core/register.mjs Resolved
Two copies of the loader can be registered in one process — NODE_OPTIONS
preloading one version while a global oxnode adds another. The previous
commit forwarded the helper specifier down the hook chain, where an
earlier-registered copy's resolve hook re-claimed it and rewrote parentURL
to its own module; the nested Module._resolveFilename wrappers did the same
for require(). Helpers could come from a different copy than the transform
that emitted them.

- resolve hooks now compute the file URL with createRequire(import.meta.url)
  .resolve() — Node's own resolver, no hook chain — and pass only the URL
  down via nextResolve, so format detection still runs.
- the _resolveFilename re-entrancy flag moves to Symbol.for so the inner
  resolve falls through every copy's wrapper; the outermost (last-registered)
  copy owns the resolution, matching the copy whose transform hooks wrapped
  the importing file.
- regression test: two dereferenced copies with marked helpers, registered
  in order; both the CJS and ESM helper must come from the second copy.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4227e46992

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/core/esm.mjs Resolved
The WASI job has no .node binding in packages/core — its oxc-node.wasi.cjs
needs @oxc-node/core-wasm32-wasi and @napi-rs/wasm-runtime from the
workspace store, which a bare copy of the directory lacks. Gate on the
native binding's presence, matching the addon tests in register-hooks.
The registry approach from 4227e46 still had one shared specifier —
`@oxc-node/core/helpers/x` — so when two copies of different versions were
registered, every helper resolved to whichever copy owned the global slot,
which could lack a helper the emitter used or carry different semantics.

Each copy now derives a tag from its own module URL (`register.mjs` in the
main thread, `esm.mjs` on module.register's worker) and passes
`@oxc-node/core@<tag>` as the transformer's helper module name, so emitted
specifiers name their emitter. A `Symbol.for` registry maps tag → that
copy's `createRequire` resolver, shared by the `_resolveFilename` patch and
the `resolve` hooks:

- tagged specifier → its owner's resolver; unknown tag falls through to
  Node's own resolution
- untagged specifier — emitted by older published copies — tries every
  registered resolver, newest registration first

`OxcTransformer` and `load` take an optional `helperModuleName`; the public
`transform`/`transformAsync` keep emitting the bare specifier.

The dual-copy test now proves routing, not just ownership: each tagged
specifier resolves into its own copy's `src/helpers/`, untagged resolves
newest-first, and a transformed file's emitted helper reports the
first-registered copy that actually transformed the raw source (pirates
chains `_compile`, module.register chains `nextLoad`).
…gged helpers

Round-3 review pointed out that an untagged `@oxc-node/core/helpers/x` —
emitted by an older registered copy (whose own hook already serves it from
itself on the ESM path) or by the public `transform()` API inside a project
that has its own `@oxc-node/core` — should keep the resolution a plain
`require`/`import` would get, with registered copies only as the fallback
for loaders running where no copy is in scope.

- `_resolveFilename` patch: untagged specifiers attempt the captured native
  resolution first; only on failure does the registry try each copy,
  newest first. A failed fallback re-throws `MODULE_NOT_FOUND`.
- resolve hooks: untagged specifiers go to `nextResolve` unchanged (the
  esm.mjs worker path awaits a rejection, the sync registerHooks path
  catches a throw), then fall back to the registry.
- Test scrub: vitest exports the workspace node_modules via NODE_PATH,
  which legitimately resolved the untagged specifier to the repo's copy —
  NODE_PATH is now stripped like NODE_OPTIONS.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 58d76ed653

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/core/register.mjs Resolved
…ged helper

A bare `new Error` loses the `code` and `requireStack` callers use to
detect optional modules; re-throw the error from Node.js' own resolution.
@Brooooooklyn
Brooooooklyn merged commit cfc5900 into main Oct 8, 2026
67 checks passed
@Brooooooklyn
Brooooooklyn deleted the fix/helper-specifier-resolution branch October 8, 2026 14:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Runtime helpers resolve from the user's file, so a global oxnode fails with ERR_MODULE_NOT_FOUND

1 participant