vfs: extend toggleable wrappers to readFileSync and internalModuleStat

ESM files capture fs methods at import time before VFS patches are
applied. Extend the toggle pattern (used for toRealPath) to
readFileSync and internalModuleStat so VFS can intercept these calls
in the ESM loader.

- Add readFileSync/setCustomReadFileSync wrappers to helpers.js
- Add internalModuleStat/setCustomInternalModuleStat wrappers
- Update esm/load.js and esm/translators.js to use helpers.readFileSync
- Update esm/resolve.js to use helpers.internalModuleStat
- Fix pre-existing bug: StringPrototypeEndsWith received wrong first arg
- Revert inline extensionFormatMap, import from esm/formats instead
- Register new VFS overrides in module_hooks.js installModuleHooks()
- Add buffer independence test for SEA VFS
- Document C++ package.json reader gap for VFS packages

Author: mcollina

lib/internal/modules/esm/load.js

@@ -9,7 +9,7 @@ const {
 
 const { defaultGetFormat } = require('internal/modules/esm/get_format');
 const { validateAttributes, emitImportAssertionWarning } = require('internal/modules/esm/assert');
-const { readFileSync } = require('fs');
+const { readFileSync } = require('internal/modules/helpers');
 
 const { Buffer: { from: BufferFrom } } = require('buffer');
 

lib/internal/modules/esm/resolve.js

@@ -23,7 +23,7 @@ const {
 } = primordials;
 const assert = require('internal/assert');
 const { BuiltinModule } = require('internal/bootstrap/realm');
-const { toRealPath } = require('internal/modules/helpers');
+const { toRealPath, internalModuleStat } = require('internal/modules/helpers');
 const { getOptionValue } = require('internal/options');
 // Do not eagerly grab .manifest, it may be in TDZ
 const { sep, posix: { relative: relativePosixPath }, resolve } = require('path');
@@ -51,7 +51,6 @@ const {
 const { Module: CJSModule } = require('internal/modules/cjs/loader');
 const { getConditionsSet } = require('internal/modules/esm/utils');
 const packageJsonReader = require('internal/modules/package_json_reader');
-const internalFsBinding = internalBinding('fs');
 
 /**
  * @typedef {import('internal/modules/esm/package_config.js').PackageConfig} PackageConfig
@@ -244,8 +243,8 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
     throw err;
   }
 
-  const stats = internalFsBinding.internalModuleStat(
-    StringPrototypeEndsWith(internalFsBinding, path, '/') ? StringPrototypeSlice(path, -1) : path,
+  const stats = internalModuleStat(
+    StringPrototypeEndsWith(path, '/') ? StringPrototypeSlice(path, -1) : path,
   );
 
   // Check for stats.isDirectory()

lib/internal/modules/esm/translators.js

@@ -22,11 +22,11 @@ const {
 
 const { BuiltinModule } = require('internal/bootstrap/realm');
 const assert = require('internal/assert');
-const { readFileSync } = require('fs');
 const { dirname, extname } = require('path');
 const {
   assertBufferSource,
   loadBuiltinModule,
+  readFileSync,
   stringify,
   stripBOM,
   urlToFilename,

lib/internal/modules/helpers.js

@@ -92,6 +92,75 @@ function setCustomToRealPath(fn) {
   customToRealPath = fn;
 }
 
+let customReadFileSync = null;
+
+/**
+ * Default implementation: reads a file from disk.
+ * @param {string} path The file path
+ * @param {string|object} options Read options
+ * @returns {string|Buffer}
+ */
+function defaultReadFileSync(path, options) {
+  return fs.readFileSync(path, options);
+}
+
+/**
+ * Reads a file, delegating to a custom override when set (e.g. for VFS).
+ * @param {string} path The file path
+ * @param {string|object} options Read options
+ * @returns {string|Buffer}
+ */
+function readFileSync(path, options) {
+  if (customReadFileSync !== null) {
+    return customReadFileSync(path, options, defaultReadFileSync);
+  }
+  return defaultReadFileSync(path, options);
+}
+
+/**
+ * Set a custom readFileSync override (e.g. for VFS-aware reading).
+ * The function receives (path, options, defaultReadFileSync) and should
+ * return the file content.
+ * @param {Function|null} fn The custom function, or null to reset
+ */
+function setCustomReadFileSync(fn) {
+  customReadFileSync = fn;
+}
+
+const internalFsBinding = internalBinding('fs');
+let customInternalModuleStat = null;
+
+/**
+ * Default implementation: calls the C++ internalModuleStat binding.
+ * @param {string} path The file path
+ * @returns {number} 0 for file, 1 for directory, negative for not found
+ */
+function defaultInternalModuleStat(path) {
+  return internalFsBinding.internalModuleStat(path);
+}
+
+/**
+ * Checks the stat of a module path, delegating to a custom override when set.
+ * @param {string} path The file path
+ * @returns {number} 0 for file, 1 for directory, negative for not found
+ */
+function internalModuleStat(path) {
+  if (customInternalModuleStat !== null) {
+    return customInternalModuleStat(path, defaultInternalModuleStat);
+  }
+  return defaultInternalModuleStat(path);
+}
+
+/**
+ * Set a custom internalModuleStat override (e.g. for VFS-aware stat).
+ * The function receives (path, defaultInternalModuleStat) and should
+ * return the stat result.
+ * @param {Function|null} fn The custom function, or null to reset
+ */
+function setCustomInternalModuleStat(fn) {
+  customInternalModuleStat = fn;
+}
+
 /** @type {Set<string>} */
 let cjsConditions;
 /** @type {string[]} */
@@ -533,12 +602,16 @@ module.exports = {
   getCjsConditionsArray,
   getCompileCacheDir,
   initializeCjsConditions,
+  internalModuleStat,
   loadBuiltinModuleForEmbedder,
   loadBuiltinModule,
   makeRequireFunction,
   normalizeReferrerURL,
-  stringify,
+  readFileSync,
+  setCustomInternalModuleStat,
+  setCustomReadFileSync,
   setCustomToRealPath,
+  stringify,
   stripBOM,
   toRealPath,
   hasStartedUserCJSExecution() {

lib/internal/vfs/module_hooks.js

@@ -11,13 +11,7 @@ const {
 const path = require('path');
 const { dirname, extname, isAbsolute, resolve } = path;
 const pathPosix = path.posix;
-// Inline format map to avoid dependency on internal/modules/esm/formats,
-// which may not be available during early bootstrap (e.g. SEA).
-// VFS defaults .js to 'commonjs' (see getFormatFromExtension below).
-const extensionFormatMap = {
-  '__proto__': null, '.cjs': 'commonjs', '.mjs': 'module',
-  '.json': 'json', '.wasm': 'wasm',
-};
+const { extensionFormatMap } = require('internal/modules/esm/formats');
 
 /**
  * Normalizes a VFS path. Uses POSIX normalization for Unix-style paths (starting with /)
@@ -489,7 +483,11 @@ function vfsLoadHook(url, context, nextLoad) {
  */
 function installModuleHooks() {
   const Module = require('internal/modules/cjs/loader').Module;
-  const { setCustomToRealPath } = require('internal/modules/helpers');
+  const {
+    setCustomToRealPath,
+    setCustomReadFileSync,
+    setCustomInternalModuleStat,
+  } = require('internal/modules/helpers');
 
   // Save original Module._stat
   originalStat = Module._stat;
@@ -516,6 +514,31 @@ function installModuleHooks() {
     return defaultFn(requestPath);
   });
 
+  // Set VFS-aware readFileSync override for internal module loading.
+  // ESM load.js and translators.js capture readFileSync at import time,
+  // so this toggle pattern ensures VFS intercepts those calls.
+  setCustomReadFileSync(function vfsAwareReadFileSync(path, options, defaultFn) {
+    if (typeof path === 'string' || path instanceof URL) {
+      const pathStr = typeof path === 'string' ? path : path.pathname;
+      const vfsResult = findVFSForRead(pathStr, options);
+      if (vfsResult !== null) {
+        return vfsResult.content;
+      }
+    }
+    return defaultFn(path, options);
+  });
+
+  // Set VFS-aware internalModuleStat override for ESM resolution.
+  // ESM resolve.js captures internalModuleStat at import time,
+  // so this toggle pattern ensures VFS intercepts those calls.
+  setCustomInternalModuleStat(function vfsAwareModuleStat(path, defaultFn) {
+    const vfsResult = findVFSForStat(path);
+    if (vfsResult !== null) {
+      return vfsResult.result;
+    }
+    return defaultFn(path);
+  });
+
   // Register ESM hooks using Module.registerHooks
   Module.registerHooks({
     resolve: vfsResolveHook,

test/fixtures/sea/vfs/sea.js

@@ -55,6 +55,21 @@ const vfsAsset = fs.readFileSync('/sea/data/greeting.txt', 'utf8');
 assert.strictEqual(seaAsset, vfsAsset, 'node:sea and VFS should return the same content');
 console.log('node:sea API and VFS coexistence test passed');
 
+// Test buffer independence: multiple reads return independent copies
+const buf1 = fs.readFileSync('/sea/data/greeting.txt');
+const buf2 = fs.readFileSync('/sea/data/greeting.txt');
+const original = buf1[0];
+buf1[0] = 0xFF;
+assert.strictEqual(buf2[0], original, 'buf2 should be unaffected by buf1 mutation');
+assert.strictEqual(buf1[0], 0xFF, 'buf1 mutation should persist');
+console.log('buffer independence test passed');
+
+// TODO(mcollina): The CJS module loader reads package.json via C++ binding
+// (internalBinding('modules').readPackageJSON), which doesn't go through VFS.
+// This means "exports" conditions in package.json won't work for VFS packages.
+// The test below works because "main": "index.js" matches the default fallback.
+// A follow-up PR should make the C++ package.json reader VFS-aware.
+
 // Test node_modules package lookup via VFS
 const testPkg = require('test-pkg');
 assert.strictEqual(testPkg.name, 'test-pkg', 'package name should match');