feat: package map support

[sapphi-red]

Implements support for https://nodejs.org/docs/latest/api/packages.html#package-maps

Note: this is totally written by AI and I have not reviewed it

(tested on Windows)

---

1. Feature: package maps in oxc-resolver

Implemented Node.js package maps, enabled by an option taking the path to a .package-map.json.

• ResolveOptions.package_map: Option<PathBuf> (+ with_package_map builder); new src/package_map.rs (parse urls relative + file:, importer/dependency lookup).
• Hooked into require_bare: when configured, bare specifiers resolve exclusively through the map (hashmap lookup) instead of walking node_modules; relative/absolute/builtin unaffected.
• Strict, Node-compatible: importer outside any package → PackageMapExternalFile (ERR_PACKAGE_MAP_EXTERNAL_FILE); undeclared dependency → NotFound; no node_modules fallback. Lazy + OnceLock-memoized load via the FileSystem trait.
• Tests in src/tests/package_map.rs + unit tests; NAPI binding left unexposed (package_map: None).

2. Rolldown integration

• Local [patch.crates-io] in rolldown/Cargo.toml → local oxc-resolver (both oxc_resolver and oxc_resolver_napi).
• crates/rolldown_resolver/src/resolver_config.rs: env ROLLDOWN_PACKAGE_MAP (empty disables; path enables) else auto-detect cwd/node_modules/.package-map.json.
• Built with just build-rolldown-release (LTO release .node, ~2m25s).

3. Benchmark setup

• pnpm nodeExperimentalPackageMap landed in v11.8.0; used pnpm 11.9.0.
• The upstream rolldown-benchmarks workspace couldn't install under pnpm 11.9 (its pkg.pr.new overrides lack integrity → rejected); configs restored to original.
• Benchmarked an isolated copy (D:/documents/GitHub/pm-bench-10000): identical apps/10000/src (10,002 files; ~30k bare-specifier resolves), deps declared so pnpm 11.9 generated node_modules/.package-map.json (standard mode). Same CLI + config for both arms; only ROLLDOWN_PACKAGE_MAP differs.

4. Results (Rolldown build, median internal ms)

Run	Baseline	Package map	Speedup
Sequential ×10	1170	962	~18%
Interleaved ×8	1150	958	16.7% (192 ms)
Interleaved ×10 (re-run)	1180	966	18.1% (214 ms)

~17–18% faster rolldown builds, reproducible; interleaving rules out ordering/cache bias.

Correctness: treatment produces the correct ~9.8 MB bundle; removing react from the map makes rolldown fail with UNRESOLVED_IMPORT despite react being on disk — proving bare specifiers route exclusively through the map.

5. State / locations

• rolldown-benchmarks — restored to original.
• pm-bench-10000 — kept (re-run commands in the file).
• oxc-resolver feature + rolldown patch — uncommitted; ⚠️ remove the [patch.crates-io] block before committing rolldown.

[codecov]

Codecov Report

❌ Patch coverage is 84.66667% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.54%. Comparing base (82940eb) to head (0faca8a).

Files with missing lines	Patch %	Lines
src/lib.rs	80.24%	16 Missing ⚠️
src/options.rs	44.44%	5 Missing ⚠️
src/package_map.rs	96.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1246      +/-   ##
==========================================
- Coverage   93.86%   93.54%   -0.33%     
==========================================
  Files          21       22       +1     
  Lines        4221     4368     +147     
==========================================
+ Hits         3962     4086     +124     
- Misses        259      282      +23     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[codspeed-hq]

Merging this PR will improve performance by 5.59%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 5 improved benchmarks
✅ 16 untouched benchmarks
⏩ 5 skipped benchmarks¹

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	pm/bun-isolated	1.1 ms	1 ms	+8.08%
⚡	pm/yarn-flat	982.5 µs	924.3 µs	+6.29%
⚡	resolver_memory[multi-thread]	293.3 µs	276.3 µs	+6.13%
⚡	pm/yarn-isolated	1 ms	1 ms	+3.8%
⚡	pm/pnpm-isolated	1.1 ms	1 ms	+3.7%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing feat/package-map-support (0faca8a) with main (82940eb)}

Footnotes

1. 5 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[arcanis]

Note that this works for a first iteration but is an approximation: multiple entries from package maps are allowed to have the same path on disk, so relying on the path to get the package ID leaves room for ambiguity.

The ideal fix would be to change CachedPath to be a combination of a PackageId and a Path. It's more involved since it touches the public interface so it probably should be a separate work.

And for context, this ability to have multiple packages share the same path with different package IDs is important to unlock proper peer dependencies semantics in workspaces (ie get rid of injectWorkspacePackages).