vfs: integrate with CJS and ESM module loaders

[mcollina]

Makes require() and import resolve files served by node:vfs. Before this PR, mounted VFS files were only visible through fs.*; the loaders went straight to the real filesystem.

Design

vfs.mount() takes no arguments and returns the reserved absolute mount point of the instance: ${os.devNull}/vfs/<layerId> (for example /dev/null/vfs/0). os.devNull is a character device on POSIX and a device-namespace path on Windows; neither can have child filesystem entries, so no real path can ever exist under this root.

Everything about ownership is decidable from the path alone:

• Dispatch: one path normalization, one prefix comparison against the namespace root, one map lookup on the layer id. O(1) in the number of mounted layers — the benchmark (benchmark/vfs/bench-fs-dispatch.js) reports flat per-call latency across 1..10 mounted layers.
• Real-fs paths short-circuit with a single prefix check.
• Unmount purges loader caches by prefix-scanning the mount point — no per-VFS ownership tracking is needed, and no other-VFS or real-fs entries are ever touched.
• Symlink correctness: realpathSync of a VFS entry always resolves to another path under the same mount point, so cache entries hidden behind symlinks are captured by the prefix scan.
• Dynamic-import identity: resolved URLs are plain file: URLs under the mount point; import(import.meta.resolve(x)) re-hits the same module job.

Two instances mounting simultaneously never collide (each gets its own layer-<id> segment), so there is no overlap validation and no ordering hazard between mounts.

Loader integration

Toggleable wrappers in the loaders. Null fast-path when no VFS is mounted; otherwise the VFS answers stat / readFile / realpath / legacyMainResolve / getFormatOfExtensionlessFile and the four package.json C++-binding calls.

Module identity follows the path: __filename, module.filename, and import.meta.url are the plain absolute path (or file: URL) of the module under the mount point — no synthetic decorations.

Review guide

Suggested reading order:

#	File	Role
1	lib/internal/vfs/router.js	Reserved-namespace helpers: getVfsRoot, getLayerRoot, getLayerIdFromPath.
2	lib/internal/vfs/file_system.js	mount() returns the layer's reserved mount point.
3	lib/internal/vfs/setup.js	Heart of the PR. findVFS (O(1) lookup), fs handler, loader overrides with parity to src/node_modules.cc / src/node_file.cc, prefix-scan cache purge.
4	lib/internal/modules/helpers.js	Hook surface: loader* wrappers, setLoaderFsOverrides / setLoaderPackageOverrides, purgeRealpathCacheForPrefix.
5	lib/internal/modules/cjs/loader.js	stat() + TS read routed through wrappers; purgeModuleCachesForPrefix for unmount.
6	lib/internal/modules/esm/resolve.js	legacyMainResolve + internalModuleStat + toRealPath routed. No URL decoration.
7	lib/internal/modules/esm/load.js	getSourceSync reads via the wrapper.
8	lib/internal/modules/esm/get_format.js	Extensionless format detection routed.
9	lib/internal/modules/package_json_reader.js	4 C++ binding calls routed; purgePackageJSONCacheForPrefix.
10	lib/fs.js	statSync / lstatSync honour throwIfNoEntry:false on ENOENT from the VFS handler.
11	doc/api/vfs.md	Mount semantics + Module loader integration section.

Tests (all gated by --experimental-vfs): test-vfs-mount, test-vfs-mount-errors, test-vfs-multi-mount, test-vfs-require, test-vfs-import, test-vfs-module-hooks, test-vfs-module-hooks-cleanup, test-vfs-package-json, test-vfs-package-json-cache, test-vfs-invalid-package-json, test-vfs-scoped-cache-purge, test-vfs-layer-id, test-vfs-layer-tag-prefix.

Refs

The reserved-namespace design follows the "no interference with valid paths in the file system" requirement from the SEA VFS requirements doc.

Out of scope

SEA + VFS, overlay/stacking of multiple VFS layers under one prefix, migrating the C++ package_configs_ cache, broader permission-model integration.

[nodejs-github-bot]

Review requested:

• @nodejs/loaders

[codecov]

Codecov Report

❌ Patch coverage is 92.32532% with 67 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.13%. Comparing base (4bd9821) to head (7f564e4).
⚠️ Report is 189 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/vfs/setup.js	88.59%	48 Missing ⚠️
src/node_modules.cc	80.70%	1 Missing and 10 partials ⚠️
lib/internal/modules/cjs/loader.js	90.00%	4 Missing ⚠️
lib/internal/vfs/file_system.js	97.18%	2 Missing ⚠️
lib/internal/vfs/router.js	96.42%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63653      +/-   ##
==========================================
+ Coverage   90.10%   90.13%   +0.02%     
==========================================
  Files         752      752              
  Lines      252197   252868     +671     
  Branches    47440    47580     +140     
==========================================
+ Hits       227245   227925     +680     
+ Misses      16251    16246       -5     
+ Partials     8701     8697       -4     

Files with missing lines	Coverage Δ
lib/fs.js	98.39% <100.00%> (+<0.01%)	⬆️
lib/internal/modules/esm/get_format.js	95.20% <100.00%> (ø)
lib/internal/modules/esm/load.js	91.40% <100.00%> (ø)
lib/internal/modules/esm/resolve.js	99.02% <100.00%> (-0.04%)	⬇️
lib/internal/modules/helpers.js	98.74% <100.00%> (-0.19%)	⬇️
lib/internal/modules/package_json_reader.js	99.28% <100.00%> (+0.04%)	⬆️
lib/internal/modules/run_main.js	97.64% <100.00%> (ø)
src/node_modules.h	100.00% <ø> (ø)
lib/internal/vfs/file_system.js	99.69% <97.18%> (+0.31%)	⬆️
lib/internal/vfs/router.js	97.46% <96.42%> (-0.36%)	⬇️
... and 3 more

... and 63 files with indirect coverage changes

🚀 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.

[mcollina]

@joyeecheung take a look, should be easier to review.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/73901/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/73902/

[joyeecheung]

A design question recently occurred to me: have we explored the versioning of the mounting?

[mcollina]

A design question recently occurred to me: have we explored the versioning of the mounting?

what do you mean? You mean multiple vfs layers on top of each other?

[joyeecheung]

what do you mean? You mean multiple vfs layers on top of each other?

For the stacks to have some kind of version number/ID to identify the current status?

BTW I just noticed that there's no mention of unmount() and mount() in the VFS docs..

[mcollina]

BTW I just noticed that there's no mention of unmount() and mount() in the VFS docs..

I did purge them when doing the splitting; I forgot to bring them back. I'll add them to this PR.

[mcollina]

For the stacks to have some kind of version number/ID to identify the current status?

No but we totally should.

[mcollina]

@joyeecheung PTAL

[pipobscure]

Can we get full CI on this? I‘d really like to avoid having this pick up more conflicts with main. Thanks!

[mcollina]

@joyeecheung PTAL, I plan to land this on Monday/when I can get a clean CI. If there are more things to fix, could you please open an issue?

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/76654/