vfs: replace fs patching with toggleable toRealPath for module loading

ESM resolve.js captures `realpathSync` via destructuring at import
time, so patching `fs.realpathSync` later has no effect on ESM
resolution. Replace the direct `realpathSync` call in
`finalizeResolution()` with the shared `toRealPath()` from helpers,
which dispatches to a VFS-aware override at runtime.

Split `installHooks()` into `installModuleHooks()` (Module._stat,
toRealPath override, ESM hooks) and `installFsPatches()` (fs.*
patches for user code transparency) for clearer separation of
concerns.

Author: mcollina

lib/internal/modules/esm/resolve.js

@@ -9,7 +9,6 @@ const {
   ObjectPrototypeHasOwnProperty,
   RegExpPrototypeExec,
   RegExpPrototypeSymbolReplace,
-  SafeMap,
   SafeSet,
   String,
   StringPrototypeEndsWith,
@@ -23,9 +22,8 @@ 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 { toRealPath } = 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');
@@ -153,8 +151,6 @@ function emitLegacyIndexDeprecation(url, path, pkgPath, base, main) {
   }
 }
 
-const realpathCache = new SafeMap();
-
 const legacyMainResolveExtensions = [
   '',
   '.js',
@@ -277,9 +273,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/helpers.js

@@ -55,17 +55,43 @@ let debug = require('internal/util/debuglog').debuglog('module', (fn) => {
  * @type {Map<string, string>}
  */
 const realpathCache = new SafeMap();
+
+let customToRealPath = null;
+
 /**
- * Resolves the path of a given `require` specifier, following symlinks.
+ * Default implementation: resolves the path following symlinks.
  * @param {string} requestPath The `require` specifier
  * @returns {string}
  */
-function toRealPath(requestPath) {
+function defaultToRealPath(requestPath) {
   return fs.realpathSync(requestPath, {
     [internalFS.realpathCacheKey]: realpathCache,
   });
 }
 
+/**
+ * Resolves the path of a given `require` specifier, following symlinks.
+ * When a custom override is set (e.g. for VFS), it is called first.
+ * @param {string} requestPath The `require` specifier
+ * @returns {string}
+ */
+function toRealPath(requestPath) {
+  if (customToRealPath !== null) {
+    return customToRealPath(requestPath, defaultToRealPath);
+  }
+  return defaultToRealPath(requestPath);
+}
+
+/**
+ * Set a custom toRealPath override (e.g. for VFS-aware resolution).
+ * The function receives (requestPath, defaultToRealPath) and should
+ * return the resolved real path.
+ * @param {Function|null} fn The custom function, or null to reset
+ */
+function setCustomToRealPath(fn) {
+  customToRealPath = fn;
+}
+
 /** @type {Set<string>} */
 let cjsConditions;
 /** @type {string[]} */
@@ -512,6 +538,7 @@ module.exports = {
   makeRequireFunction,
   normalizeReferrerURL,
   stringify,
+  setCustomToRealPath,
   stripBOM,
   toRealPath,
   hasStartedUserCJSExecution() {

lib/internal/vfs/module_hooks.js

@@ -478,24 +478,15 @@ function vfsLoadHook(url, context, nextLoad) {
 }
 
 /**
- * Install hooks into Module._stat and various fs functions.
- * Note: fs and internal modules are required here (not at top level) to avoid
- * circular dependencies during bootstrap. This module may be loaded early.
+ * Install module loading hooks (Module._stat, toRealPath override, ESM hooks).
+ * These make CJS/ESM module resolution VFS-aware without patching fs globally.
  */
-function installHooks() {
-  if (hooksInstalled) {
-    return;
-  }
-
+function installModuleHooks() {
   const Module = require('internal/modules/cjs/loader').Module;
-  const fs = require('fs');
+  const { setCustomToRealPath } = require('internal/modules/helpers');
 
-  // Save originals
+  // Save original Module._stat
   originalStat = Module._stat;
-  originalReadFileSync = fs.readFileSync;
-  originalRealpathSync = fs.realpathSync;
-  originalLstatSync = fs.lstatSync;
-  originalStatSync = fs.statSync;
 
   // Override Module._stat
   // This uses the setter which emits an experimental warning, but that's acceptable
@@ -508,6 +499,37 @@ function installHooks() {
     return originalStat(filename);
   };
 
+  // Set VFS-aware toRealPath override for internal module resolution.
+  // This is called at runtime (not captured at import time), so it works
+  // correctly with both CJS toRealPath and ESM finalizeResolution.
+  setCustomToRealPath(function vfsAwareToRealPath(requestPath, defaultFn) {
+    const vfsResult = findVFSForRealpath(requestPath);
+    if (vfsResult !== null) {
+      return vfsResult.realpath;
+    }
+    return defaultFn(requestPath);
+  });
+
+  // Register ESM hooks using Module.registerHooks
+  Module.registerHooks({
+    resolve: vfsResolveHook,
+    load: vfsLoadHook,
+  });
+}
+
+/**
+ * Install fs patches for user code transparency.
+ * These make fs.readFileSync('/vfs/path'), fs.statSync, etc. work for user code.
+ */
+function installFsPatches() {
+  const fs = require('fs');
+
+  // Save originals
+  originalReadFileSync = fs.readFileSync;
+  originalRealpathSync = fs.realpathSync;
+  originalLstatSync = fs.lstatSync;
+  originalStatSync = fs.statSync;
+
   // Override fs.readFileSync
   // We need to be careful to only intercept when VFS should handle the path
   fs.readFileSync = function readFileSync(path, options) {
@@ -687,12 +709,20 @@ function installHooks() {
     }
     return FunctionPrototypeCall(originalPromisesWatch, fsPromises, filename, options);
   };
+}
 
-  // Register ESM hooks using Module.registerHooks
-  Module.registerHooks({
-    resolve: vfsResolveHook,
-    load: vfsLoadHook,
-  });
+/**
+ * Install all VFS hooks: module loading hooks and fs patches.
+ * Note: fs and internal modules are required here (not at top level) to avoid
+ * circular dependencies during bootstrap. This module may be loaded early.
+ */
+function installHooks() {
+  if (hooksInstalled) {
+    return;
+  }
+
+  installModuleHooks();
+  installFsPatches();
 
   hooksInstalled = true;
 }