vfs: split followup tests into named test files

Replace the monolithic test-vfs-followups.js with individual test files:
- test-vfs-overlapping-mounts.js
- test-vfs-promises-open.js
- test-vfs-stream-properties.js
- test-vfs-dir-disposal.js
- test-vfs-stats-ino-dev.js
- test-vfs-append-write.js
- test-vfs-cross-device.js
- test-vfs-readdir-symlink-recursive.js
- test-vfs-package-json-cache.js
- test-vfs-readfile-async.js

Author: mcollina

JAMES_RESPONSE.md

@@ -0,0 +1,76 @@
+**Status update on follow-ups from #62328**
+
+Here's a summary of what has been addressed so far and what remains open.
+
+### Addressed
+
+| # | Item | Status |
+|---|------|--------|
+| **1.1** | VFS bypasses permission model | Addressed — `registerVFS()` throws when `permission.isEnabled()` unless `--allow-fs-vfs` runtime flag is set (added to `src/node_options.cc` in the permission namespace) |
+| **1.3** | Overlapping mounts undefined behavior | Addressed — `registerVFS()` detects prefix-overlapping mount points (using `/`-terminated prefix comparison to avoid false positives like `/virtual` vs `/virtual2`) and rejects with `ERR_INVALID_STATE` |
+| **1.4** | RealFSProvider symlink jail escape | Addressed — `symlinkSync` validates target stays within root, `readlinkSync` translates paths to VFS-relative, `realpathSync` throws EACCES on escape |
+| **2.1** | VirtualFileHandle missing methods | Partially addressed — added `chmod`/`chown`/`utimes`/`datasync`/`sync` (no-op stubs), `readv`/`writev`/`appendFile`, `[Symbol.asyncDispose]()`, `readLines`/`readableWebStream`/`createReadStream`/`createWriteStream` (throw `ERR_METHOD_NOT_IMPLEMENTED`). **Still missing**: `fd` property and `EventEmitter` extension (no `'close'` event) |
+| **2.2** | `fsPromises.open()` not intercepted | Addressed — separate `promisesOpen` handler in `setup.js` returns VirtualFileHandle for `fsPromises.open()`, while `open` handler returns numeric FD for callback `fs.open()` |
+| **2.3** | Streams missing properties | Addressed — added `bytesRead`/`pending` on VirtualReadStream, `bytesWritten`/`pending` on VirtualWriteStream |
+| **2.4** | VirtualDir missing disposal | Addressed — added `[Symbol.asyncDispose]()`, `[Symbol.dispose]()`, `entries()` auto-close via try/finally |
+| **2.5** | Stats ino/dev always 0 | Addressed — unique incrementing `ino`, distinctive `dev = 4085` (0xFF9) applied to all three stats factory functions |
+| **2.7** | Watcher API mismatches | Partially addressed — `VFSStatWatcher.addListener`/`removeListener` fixed to `(event, listener)` signature. **Still missing**: `VFSWatcher` does not emit `'error'` events from catch blocks |
+| **3.1** | Streams stall on destroyed/null fd | Addressed — `_write()` calls `callback(createEBADF('write'))`, `_read()` calls `this.destroy(createEBADF('read'))` |
+| **3.2** | `#checkClosed()` always reports 'read' | Addressed — parameterized with `syscall` argument, all call sites pass correct syscall name, both base and subclass `#checkClosed(syscall)` pass it to `createEBADF(syscall)` |
+| **3.3** | `writeFileSync` misses 'ax'/'ax+' | Addressed — uses `#isAppend()` instead of manual flag check |
+| **3.4** | Dead ternary in `#hookProcessCwd` | Addressed — simplified to single `resolvePath(directory)` |
+| **3.5** | SEAProvider statSync reads full asset | Addressed — asset sizes cached in `_assetSizes` map on first access |
+| **3.6** | SEAProvider recursive readdir | Addressed — `#readdirRecursive()` walks subdirectories |
+| **3.7** | SEAProvider numeric flags | Addressed — `openSync()` handles numeric `0` (O_RDONLY) inline |
+| **3.8** | Shared mutable statsArray | Addressed — safety comment added explaining synchronous-copy invariant |
+| **5.1** | readFile handler still sync | Partially addressed — `readFile` handler in `setup.js` converted to async (`vfs.promises.readFile`), `lib/fs.js` uses `vfsResult()` to route promise to callback. Other callback handlers still use sync+nextTick |
+| **6.2** | Cross-VFS operations | Addressed — `checkSameVFS()` helper validates `rename`/`copyFile`/`link` src and dest resolve to same VFS; throws EXDEV otherwise |
+| **6.3** | Package.json cache not invalidated on unmount | Addressed — `deregisterVFS()` calls `clearPackageJSONCache()` exported from `package_json_reader.js` |
+| **7.1** | `restoreAll()` error handling | Addressed — each `restore()` wrapped in try/catch, AggregateError thrown after all mocks restored |
+| **7.2** | `MockFSContext.vfs` exposes full instance | Addressed — changed to `#vfs` private field with read-only getter |
+| **7.3** | Platform-specific root check | Addressed — uses `path.parse(parentDir).root !== parentDir` instead of `!== '/'` |
+| **8.1** | MemoryProvider stat size 0 for dynamic files | Addressed — `#createStats` calls `entry.getContentSync().length` when `entry.isDynamic()` |
+| **8.2** | MemoryProvider symlinkSync auto-creates dirs | Addressed — changed to `#ensureParent(normalized, false, 'symlink')` consistent with other operations |
+| **8.3** | MemoryProvider recursive readdir doesn't follow symlinks | Addressed — `#readdirRecursive` resolves symlinks before checking `isDirectory()` |
+| **8.5** | RealFSProvider no watch support | Addressed — `watch()`/`watchFile()`/`unwatchFile()` implemented with path translation, `supportsWatch = true` |
+| **10.1** | Watcher unbounded memory growth | Addressed — `kMaxPendingEvents = 1024` cap on `#pendingEvents`, oldest events dropped when full |
+| **10.2** | Redundant `#destroyed` in streams | Addressed — removed, uses inherited `this.destroyed` |
+| **10.3** | SEAProvider primordials | Addressed — uses `StringPrototypeReplaceAll`, `ArrayFrom`, `StringPrototypeStartsWith` from primordials |
+
+### Tests added
+
+- `test-vfs-overlapping-mounts.js` — overlapping mount rejection, including non-overlapping prefix and root cases (1.3)
+- `test-vfs-promises-open.js` — `fsPromises.open()` interception (2.2)
+- `test-vfs-stream-properties.js` — `bytesRead`/`bytesWritten`/`pending` (2.3)
+- `test-vfs-dir-disposal.js` — `Symbol.asyncDispose`/`Symbol.dispose` (2.4)
+- `test-vfs-stats-ino-dev.js` — unique ino, distinctive dev (2.5)
+- `test-vfs-append-write.js` — append mode correctness (3.3)
+- `test-vfs-cross-device.js` — EXDEV for cross-VFS rename/copyFile/link (6.2)
+- `test-vfs-readdir-symlink-recursive.js` — recursive readdir follows symlinks (8.3)
+- `test-vfs-package-json-cache.js` — cache cleared on unmount (6.3)
+- `test-vfs-readfile-async.js` — readFile uses async handler (5.1)
+
+### Not addressed (requires further work)
+
+| # | Item | Notes |
+|---|------|-------|
+| **1.2** | Any loaded code can call `mount()` | Design/policy discussion — needs `--experimental-vfs` flag or security event |
+| **2.1** (partial) | `fd` property, EventEmitter extension | VirtualFileHandle doesn't expose `fd` numeric property or emit `'close'` event |
+| **2.3** (partial) | VirtualWriteStream `close(callback)` | Missing explicit `close(callback)` method |
+| **2.7** (partial) | VFSWatcher error events | `VFSWatcher` does not emit `'error'` events from catch blocks in `#getStats()`/`#getStatsFor()` |
+| **4.1** | Case-insensitive path comparison (Windows) | Requires Windows-specific path normalization |
+| **4.2** | UNC paths unsupported | Windows-specific |
+| **4.3** | Virtual CWD hardcoded `/` separator | Windows-specific |
+| **4.4** | findVFSPackageJSON mixed separator | Note only |
+| **5.1** (partial) | Other callback APIs still sync | Only `readFile` converted; broader pattern remains |
+| **5.2** | `existsSync` in async code paths | `findVFSWith()` still uses `existsSync` in paths used by async handlers |
+| **5.3** | Linear scan of activeVFSList | Note only, unlikely to matter in practice |
+| **6.1** | Maintenance burden of 164+ interception points | Design discussion |
+| **6.4** | C++ format coupling in package.json serialization | Note only |
+| **6.5** | legacyMainResolve hardcoded extensions | Note only |
+| **8.4** | RealFSProvider path traversal via real-fs symlinks | `#resolvePath` validates logical path but doesn't resolve real-fs symlinks before checking |
+| **9.1** | Windows tests minimal | Blocked on Windows path handling (4.x items) |
+| **9.4** | Permission model interaction untested | Needs subprocess test with `--permission` flag |
+| **10.4** | VirtualFileHandle `#checkClosed` duplication | Note only — inherent to JS private fields |
+| **10.5** | file_system.js and setup.js are very large | Note only |
+| **10.6** | VirtualFD range starts at 10,000 | Note only |

lib/internal/fs/promises.js

@@ -643,7 +643,7 @@ async function copyFile(src, dest, mode) {
 async function open(path, flags, mode) {
   const h = vfsState.handlers;
   if (h !== null) {
-    const result = h.open(path, flags, mode);
+    const result = h.promisesOpen(path, flags, mode);
     if (result !== undefined) return result;
   }
   path = getValidatedPath(path);

lib/internal/vfs/file_system.js

@@ -46,7 +46,6 @@ const kVirtualCwd = Symbol('kVirtualCwd');
 const kVirtualCwdEnabled = Symbol('kVirtualCwdEnabled');
 const kOriginalChdir = Symbol('kOriginalChdir');
 const kOriginalCwd = Symbol('kOriginalCwd');
-const kAllowWithPermissionModel = Symbol('kAllowWithPermissionModel');
 
 // Lazy-loaded VFS setup
 let registerVFS;
@@ -109,7 +108,6 @@ class VirtualFileSystem {
     this[kVirtualCwd] = null; // Set when chdir() is called
     this[kOriginalChdir] = null; // Saved process.chdir
     this[kOriginalCwd] = null; // Saved process.cwd
-    this[kAllowWithPermissionModel] = options.allowWithPermissionModel === true;
   }
 
   /**
@@ -162,14 +160,6 @@ class VirtualFileSystem {
     return this[kVirtualCwdEnabled];
   }
 
-  /**
-   * Returns true if this VFS allows being used with the permission model.
-   * @returns {boolean}
-   */
-  get allowWithPermissionModel() {
-    return this[kAllowWithPermissionModel];
-  }
-
   // ==================== Virtual Working Directory ====================
 
   /**

lib/internal/vfs/providers/memory.js

@@ -985,7 +985,7 @@ class MemoryProvider extends VirtualProvider {
     }
 
     if (listener) {
-      watcher.addListener(listener);
+      watcher.addListener('change', listener);
     }
 
     return watcher;
@@ -1005,7 +1005,7 @@ class MemoryProvider extends VirtualProvider {
     }
 
     if (listener) {
-      watcher.removeListener(listener);
+      watcher.removeListener('change', listener);
     } else {
       // Remove all listeners
       watcher.removeAllListeners('change');

lib/internal/vfs/setup.js

@@ -30,6 +30,7 @@ const { createENOENT, createEXDEV } = require('internal/vfs/errors');
 const { getVirtualFd, closeVirtualFd } = require('internal/vfs/fd');
 const { vfsState, setVfsHandlers } = require('internal/fs/utils');
 const permission = require('internal/process/permission');
+const { getOptionValue } = require('internal/options');
 
 /**
  * Converts a path argument (string or URL) to a string path.
@@ -72,10 +73,10 @@ let vfsHandlerObj;
  * @param {VirtualFileSystem} vfs The VFS instance to register
  */
 function registerVFS(vfs) {
-  if (permission.isEnabled() && !vfs.allowWithPermissionModel) {
+  if (permission.isEnabled() && !getOptionValue('--allow-fs-vfs')) {
     throw new ERR_INVALID_STATE(
       'VFS cannot be used when the permission model is enabled. ' +
-      'Set allowWithPermissionModel: true to override.',
+      'Use --allow-fs-vfs to allow it.',
     );
   }
   if (ArrayPrototypeIndexOf(activeVFSList, vfs) === -1) {
@@ -85,8 +86,11 @@ function registerVFS(vfs) {
       for (let i = 0; i < activeVFSList.length; i++) {
         const existingMount = activeVFSList[i].mountPoint;
         if (existingMount == null) continue;
-        if (StringPrototypeStartsWith(newMount, existingMount) ||
-            StringPrototypeStartsWith(existingMount, newMount)) {
+        const newPrefix = newMount === '/' ? '/' : newMount + '/';
+        const existingPrefix = existingMount === '/' ? '/' : existingMount + '/';
+        if (newMount === existingMount ||
+            StringPrototypeStartsWith(newMount, existingPrefix) ||
+            StringPrototypeStartsWith(existingMount, newPrefix)) {
           throw new ERR_INVALID_STATE(
             `VFS mount '${newMount}' overlaps with existing mount '${existingMount}'`,
           );
@@ -884,6 +888,9 @@ function createVfsHandlers() {
     chmod: (path, mode) => vfsOp(path, (vfs, n) => vfs.promises.chmod(n, mode).then(() => true)),
     utimes: (path, atime, mtime) => vfsOp(path, (vfs, n) => vfs.promises.utimes(n, atime, mtime).then(() => true)),
     open(path, flags, mode) {
+      return vfsOp(path, (vfs, n) => PromiseResolve(vfs.openSync(n, flags, mode)));
+    },
+    promisesOpen(path, flags, mode) {
       const pathStr = toPathStr(path);
       if (pathStr !== null) {
         const r = findVFSForPath(pathStr);

src/node_options.cc

@@ -663,6 +663,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             kAllowedInEnvvar,
             false,
             OptionNamespaces::kPermissionNamespace);
+  AddOption("--allow-fs-vfs",
+            "allow use of virtual filesystem when any permissions are set",
+            &EnvironmentOptions::allow_fs_vfs,
+            kAllowedInEnvvar,
+            false,
+            OptionNamespaces::kPermissionNamespace);
   AddOption("--allow-child-process",
             "allow use of child process when any permissions are set",
             &EnvironmentOptions::allow_child_process,

src/node_options.h

@@ -142,6 +142,7 @@ class EnvironmentOptions : public Options {
   std::vector<std::string> allow_fs_read;
   std::vector<std::string> allow_fs_write;
   bool allow_addons = false;
+  bool allow_fs_vfs = false;
   bool allow_inspector = false;
   bool allow_child_process = false;
   bool allow_net = false;

test/parallel/test-vfs-append-write.js

@@ -0,0 +1,18 @@
+'use strict';
+
+// writeSync in append mode must append, not overwrite.
+
+require('../common');
+const assert = require('assert');
+const vfs = require('node:vfs');
+
+const myVfs = vfs.create();
+myVfs.writeFileSync('/append.txt', 'init');
+
+const fd = myVfs.openSync('/append.txt', 'a');
+const buf = Buffer.from(' more');
+myVfs.writeSync(fd, buf, 0, buf.length);
+myVfs.closeSync(fd);
+
+const content = myVfs.readFileSync('/append.txt', 'utf8');
+assert.strictEqual(content, 'init more');

test/parallel/test-vfs-cross-device.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// Cross-VFS rename, copyFile, and link must throw EXDEV.
+
+require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const vfs = require('node:vfs');
+
+const vfs1 = vfs.create();
+vfs1.writeFileSync('/src.txt', 'data');
+vfs1.mount('/xdev_a');
+
+const vfs2 = vfs.create();
+vfs2.mkdirSync('/dest');
+vfs2.mount('/xdev_b');
+
+assert.throws(() => fs.renameSync('/xdev_a/src.txt', '/xdev_b/dest/src.txt'), {
+  code: 'EXDEV',
+});
+
+assert.throws(() => fs.copyFileSync('/xdev_a/src.txt', '/xdev_b/dest/src.txt'), {
+  code: 'EXDEV',
+});
+
+assert.throws(() => fs.linkSync('/xdev_a/src.txt', '/xdev_b/dest/link.txt'), {
+  code: 'EXDEV',
+});
+
+vfs2.unmount();
+vfs1.unmount();

test/parallel/test-vfs-dir-disposal.js

@@ -0,0 +1,30 @@
+'use strict';
+
+// VirtualDir must support Symbol.dispose and Symbol.asyncDispose.
+
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const vfs = require('node:vfs');
+
+const myVfs = vfs.create();
+myVfs.mkdirSync('/dir');
+myVfs.writeFileSync('/dir/a.txt', 'a');
+myVfs.mount('/mnt_dirdispose');
+
+// Symbol.dispose via closeSync
+{
+  const dir = fs.opendirSync('/mnt_dirdispose/dir');
+  dir[Symbol.dispose]();
+  assert.throws(() => dir.closeSync(), { code: 'ERR_DIR_CLOSED' });
+}
+
+// Symbol.asyncDispose via close
+{
+  const dir = fs.opendirSync('/mnt_dirdispose/dir');
+  dir[Symbol.asyncDispose]().then(common.mustCall(() => {
+    assert.throws(() => dir.closeSync(), { code: 'ERR_DIR_CLOSED' });
+  }));
+}
+
+myVfs.unmount();