vfs: replace fs monkey-patching with toggleable loader wrappers

Add loaderStat(), loaderReadFile(), and setLoaderFsOverrides() to
helpers.js, and modify toRealPath() to support a VFS toggle. Replace
direct internalFsBinding.internalModuleStat() and fs.readFileSync()
calls in the CJS loader, ESM resolver, ESM loader, translators, and
package_json_reader with these wrappers.

The VFS module_hooks.js now calls setLoaderFsOverrides() first in
installHooks(), making loader fs interception order-independent and
eliminating conflicts with cached fs method references.

Fix two pre-existing bugs in esm/resolve.js finalizeResolution():
- StringPrototypeEndsWith() was called with internalFsBinding as
  first arg instead of path
- StringPrototypeSlice(path, -1) returned the last char instead of
  stripping the trailing slash (now correctly uses path, 0, -1)

Existing fs patches for user-facing operations are kept unchanged.

Author: mcollina

lib/internal/modules/cjs/loader.js

@@ -155,14 +155,14 @@ const {
 } = internalBinding('contextify');
 
 const assert = require('internal/assert');
-const fs = require('fs');
 const path = require('path');
-const internalFsBinding = internalBinding('fs');
 const { safeGetenv } = internalBinding('credentials');
 const {
   getCjsConditions,
   getCjsConditionsArray,
   initializeCjsConditions,
+  loaderReadFile,
+  loaderStat,
   loadBuiltinModule,
   makeRequireFunction,
   setHasStartedUserCJSExecution,
@@ -272,7 +272,7 @@ function stat(filename) {
     const result = statCache.get(filename);
     if (result !== undefined) { return result; }
   }
-  const result = internalFsBinding.internalModuleStat(filename);
+  const result = loaderStat(filename);
   if (statCache !== null && result >= 0) {
     // Only set cache when `internalModuleStat(filename)` succeeds.
     statCache.set(filename, result);
@@ -1164,7 +1164,7 @@ function defaultLoadImpl(filename, format) {
     case 'module-typescript':
     case 'commonjs-typescript':
     case 'typescript': {
-      return fs.readFileSync(filename, 'utf8');
+      return loaderReadFile(filename, 'utf8');
     }
     case 'builtin':
       return null;

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 { loaderReadFile } = require('internal/modules/helpers');
 
 const { Buffer: { from: BufferFrom } } = require('buffer');
 
@@ -34,7 +34,7 @@ function getSourceSync(url, context) {
   const responseURL = href;
   let source;
   if (protocol === 'file:') {
-    source = readFileSync(url);
+    source = loaderReadFile(url);
   } else if (protocol === 'data:') {
     const result = dataURLProcessor(url);
     if (result === 'failure') {

lib/internal/modules/esm/resolve.js

@@ -9,7 +9,6 @@ const {
   ObjectPrototypeHasOwnProperty,
   RegExpPrototypeExec,
   RegExpPrototypeSymbolReplace,
-  SafeMap,
   SafeSet,
   String,
   StringPrototypeEndsWith,
@@ -23,9 +22,7 @@ const {
   encodeURIComponent,
 } = primordials;
 const assert = require('internal/assert');
-const internalFS = require('internal/fs/utils');
 const { BuiltinModule } = require('internal/bootstrap/realm');
-const { realpathSync } = require('fs');
 const { getOptionValue } = require('internal/options');
 // Do not eagerly grab .manifest, it may be in TDZ
 const { sep, posix: { relative: relativePosixPath }, resolve } = require('path');
@@ -49,7 +46,7 @@ const {
 const { defaultGetFormatWithoutErrors } = require('internal/modules/esm/get_format');
 const { getConditionsSet } = require('internal/modules/esm/utils');
 const packageJsonReader = require('internal/modules/package_json_reader');
-const internalFsBinding = internalBinding('fs');
+const { loaderStat, toRealPath } = require('internal/modules/helpers');
 
 /**
  * @typedef {import('internal/modules/esm/package_config.js').PackageConfig} PackageConfig
@@ -149,8 +146,6 @@ function emitLegacyIndexDeprecation(url, path, pkgPath, base, main) {
   }
 }
 
-const realpathCache = new SafeMap();
-
 const legacyMainResolveExtensions = [
   '',
   '.js',
@@ -244,8 +239,8 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
     throw err;
   }
 
-  const stats = internalFsBinding.internalModuleStat(
-    StringPrototypeEndsWith(internalFsBinding, path, '/') ? StringPrototypeSlice(path, -1) : path,
+  const stats = loaderStat(
+    StringPrototypeEndsWith(path, '/') ? StringPrototypeSlice(path, 0, -1) : path,
   );
 
   // Check for stats.isDirectory()
@@ -273,9 +268,7 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
   }
 
   if (!preserveSymlinks) {
-    const real = realpathSync(path, {
-      [internalFS.realpathCacheKey]: realpathCache,
-    });
+    const real = toRealPath(path);
     const { search, hash } = resolved;
     resolved =
         pathToFileURL(real + (StringPrototypeEndsWith(path, sep) ? '/' : ''));

lib/internal/modules/esm/translators.js

@@ -22,10 +22,10 @@ const {
 
 const { BuiltinModule } = require('internal/bootstrap/realm');
 const assert = require('internal/assert');
-const { readFileSync } = require('fs');
 const { dirname, extname } = require('path');
 const {
   assertBufferSource,
+  loaderReadFile,
   loadBuiltinModule,
   stringify,
   stripBOM,
@@ -341,7 +341,7 @@ translators.set('commonjs', function commonjsStrategy(url, translateContext, par
 
   try {
     // We still need to read the FS to detect the exports.
-    translateContext.source ??= readFileSync(new URL(url), 'utf8');
+    translateContext.source ??= loaderReadFile(new URL(url), 'utf8');
   } catch {
     // Continue regardless of error.
   }

lib/internal/modules/helpers.js

@@ -34,6 +34,7 @@ const { emitWarningSync } = require('internal/process/warning');
 const lazyTmpdir = getLazy(() => require('os').tmpdir());
 const { join } = path;
 
+const internalFsBinding = internalBinding('fs');
 const { canParse: URLCanParse } = internalBinding('url');
 const {
   enableCompileCache: _enableCompileCache,
@@ -56,12 +57,56 @@ let debug = require('internal/util/debuglog').debuglog('module', (fn) => {
  * @type {Map<string, string>}
  */
 const realpathCache = new SafeMap();
+// Toggleable loader fs overrides for VFS support.
+// When null, the fast path (no VFS) is taken with zero overhead.
+let _loaderStat = null;
+let _loaderReadFile = null;
+let _loaderRealpath = null;
+
+/**
+ * Set override functions for the module loader's fs operations.
+ * @param {{ stat?: Function, readFile?: Function, realpath?: Function }} overrides
+ */
+function setLoaderFsOverrides({ stat, readFile, realpath }) {
+  _loaderStat = stat;
+  _loaderReadFile = readFile;
+  _loaderRealpath = realpath;
+}
+
+/**
+ * Wrapper for internalModuleStat that supports VFS toggle.
+ * @param {string} filename Absolute path to stat
+ * @returns {number}
+ */
+function loaderStat(filename) {
+  if (_loaderStat !== null) { return _loaderStat(filename); }
+  return internalFsBinding.internalModuleStat(filename);
+}
+
+/**
+ * Wrapper for fs.readFileSync that supports VFS toggle.
+ * @param {string|URL} filename Path to read
+ * @param {string|object} options Read options
+ * @returns {string|Buffer}
+ */
+function loaderReadFile(filename, options) {
+  if (_loaderReadFile !== null) {
+    const result = _loaderReadFile(filename, options);
+    if (result !== undefined) { return result; }
+  }
+  return fs.readFileSync(filename, options);
+}
+
 /**
  * Resolves the path of a given `require` specifier, following symlinks.
  * @param {string} requestPath The `require` specifier
  * @returns {string}
  */
 function toRealPath(requestPath) {
+  if (_loaderRealpath !== null) {
+    const result = _loaderRealpath(requestPath);
+    if (result !== undefined) { return result; }
+  }
   return fs.realpathSync(requestPath, {
     [internalFS.realpathCacheKey]: realpathCache,
   });
@@ -524,10 +569,13 @@ module.exports = {
   getCjsConditionsArray,
   getCompileCacheDir,
   initializeCjsConditions,
+  loaderReadFile,
+  loaderStat,
   loadBuiltinModuleForEmbedder,
   loadBuiltinModule,
   makeRequireFunction,
   normalizeReferrerURL,
+  setLoaderFsOverrides,
   stringify,
   stripBOM,
   toRealPath,

lib/internal/modules/package_json_reader.js

@@ -27,7 +27,7 @@ const { kEmptyObject } = require('internal/util');
 const modulesBinding = internalBinding('modules');
 const path = require('path');
 const { validateString } = require('internal/validators');
-const internalFsBinding = internalBinding('fs');
+const { loaderStat } = require('internal/modules/helpers');
 
 
 /**
@@ -280,7 +280,7 @@ function getPackageJSONURL(specifier, base) {
   let packageJSONPath = fileURLToPath(packageJSONUrl);
   let lastPath;
   do {
-    const stat = internalFsBinding.internalModuleStat(
+    const stat = loaderStat(
       StringPrototypeSlice(packageJSONPath, 0, packageJSONPath.length - 13),
     );
     // Check for !stat.isDirectory()

lib/internal/vfs/module_hooks.js

@@ -8,6 +8,7 @@ const {
   FunctionPrototypeCall,
   JSONParse,
   ObjectGetOwnPropertyNames,
+  String,
   StringPrototypeEndsWith,
   StringPrototypeIndexOf,
   StringPrototypeSlice,
@@ -1071,13 +1072,42 @@ function installFsPatches() {
 }
 
 /**
- * Install all VFS hooks: module loading hooks and fs patches.
+ * Install toggleable loader overrides so that the module loader's
+ * internal fs operations (stat, readFile, realpath) are redirected
+ * to VFS when appropriate. This is order-independent - unlike fs
+ * monkey-patches, it works even when the loader has already cached
+ * references to the original fs methods.
+ */
+function installModuleLoaderOverrides() {
+  const { setLoaderFsOverrides } = require('internal/modules/helpers');
+  setLoaderFsOverrides({
+    stat(filename) {
+      const result = findVFSForStat(filename);
+      if (result !== null) return result.result;
+      return internalBinding('fs').internalModuleStat(filename);
+    },
+    readFile(filename, options) {
+      const pathStr = typeof filename === 'string' ? filename :
+        (filename instanceof URL ? fileURLToPath(filename) : String(filename));
+      const result = findVFSForRead(pathStr, options);
+      return result !== null ? result.content : undefined;
+    },
+    realpath(filename) {
+      const result = findVFSForRealpath(filename);
+      return result !== null ? result.realpath : undefined;
+    },
+  });
+}
+
+/**
+ * Install all VFS hooks: loader overrides, module hooks, and fs patches.
  */
 function installHooks() {
   if (hooksInstalled) {
     return;
   }
 
+  installModuleLoaderOverrides();
   installModuleHooks();
   installFsPatches();