vfs: add comprehensive tests for bug fixes and lint cleanup

Add 18 feature-focused test files covering bug fixes from both analysis
rounds, and fix lint issues in stats.js and setup.js.

Test files added:
- test-vfs-access.js: access validation and mode enforcement
- test-vfs-buffer-encoding.js: buffer encodings and buffer path args
- test-vfs-copyfile-mode.js: copyFile COPYFILE_EXCL support
- test-vfs-dir-handle.js: Dir double-close and read/close callbacks
- test-vfs-file-url.js: file: URL handling with fileURLToPath
- test-vfs-mkdir-recursive-return.js: mkdirSync recursive return value
- test-vfs-no-auto-mkdir.js: writes/opens don't auto-create parents
- test-vfs-open-flags.js: read-only/write-only/exclusive/numeric flags
- test-vfs-readdir-recursive.js: readdir recursive with names and dirents
- test-vfs-readfile-fd.js: readFileSync with virtual fd
- test-vfs-rename-safety.js: renameSync preserves source on failure
- test-vfs-rm-edge-cases.js: rmSync dir/link edge cases
- test-vfs-stats-bigint.js: BigInt stats support
- test-vfs-stream-options.js: writestream start and stream fd option
- test-vfs-symlink-edge-cases.js: broken/intermediate symlinks
- test-vfs-watch-directory.js: directory and recursive watch
- test-vfs-watchfile.js: unwatchFile cleanup and zero stats
- test-vfs-writefile-flags.js: writeFile/appendFile flag support

Lint fixes:
- stats.js: use BigInt from primordials, add missing JSDoc @returns
- setup.js: consolidate ERR_MODULE_NOT_FOUND import

Author: mcollina

lib/fs.js

@@ -3748,7 +3748,7 @@ function mkdtemp(prefix, options, callback) {
   const h = vfsState.handlers;
   if (h !== null) {
     try {
-      const result = h.mkdtempSync(prefix);
+      const result = h.mkdtempSync(prefix, typeof options === 'function' ? undefined : options);
       if (result !== undefined) {
         process.nextTick(callback, null, result);
         return;
@@ -3778,7 +3778,7 @@ function mkdtemp(prefix, options, callback) {
 function mkdtempSync(prefix, options) {
   const h = vfsState.handlers;
   if (h !== null) {
-    const result = h.mkdtempSync(prefix);
+    const result = h.mkdtempSync(prefix, options);
     if (result !== undefined) return result;
   }
 

lib/internal/vfs/dir.js

@@ -56,6 +56,9 @@ class VirtualDir {
   }
 
   closeSync() {
+    if (this.#closed) {
+      throw new ERR_DIR_CLOSED();
+    }
     this.#closed = true;
   }
 

lib/internal/vfs/file_system.js

@@ -29,6 +29,7 @@ const {
   createENOENT,
   createENOTDIR,
   createEBADF,
+  createEISDIR,
 } = require('internal/vfs/errors');
 const { VirtualReadStream, VirtualWriteStream } = require('internal/vfs/streams');
 const { VirtualDir } = require('internal/vfs/dir');
@@ -572,18 +573,25 @@ class VirtualFileSystem {
 
     let stats;
     try {
-      stats = this.statSync(filePath);
+      stats = this.lstatSync(filePath);
     } catch (err) {
       if (force && err?.code === 'ENOENT') return;
       throw err;
     }
 
+    // Symlinks should be unlinked directly, never recursed into
+    if (stats.isSymbolicLink()) {
+      this.unlinkSync(filePath);
+      return;
+    }
+
     if (stats.isDirectory()) {
-      if (recursive) {
-        const entries = this.readdirSync(filePath);
-        for (let i = 0; i < entries.length; i++) {
-          this.rmSync(joinPath(filePath, entries[i]), options);
-        }
+      if (!recursive) {
+        throw createEISDIR('rm', filePath);
+      }
+      const entries = this.readdirSync(filePath);
+      for (let i = 0; i < entries.length; i++) {
+        this.rmSync(joinPath(filePath, entries[i]), options);
       }
       this.rmdirSync(filePath);
     } else {
@@ -1281,24 +1289,30 @@ class VirtualFileSystem {
       },
 
       async rm(filePath, options) {
-        // Delegate to sync implementation via the VFS instance
         const recursive = options?.recursive === true;
         const force = options?.force === true;
 
         let stats;
         try {
-          stats = await provider.stat(toProviderPath(filePath));
+          stats = await provider.lstat(toProviderPath(filePath));
         } catch (err) {
           if (force && err?.code === 'ENOENT') return;
           throw err;
         }
 
+        // Symlinks should be unlinked directly, never recursed into
+        if (stats.isSymbolicLink()) {
+          await provider.unlink(toProviderPath(filePath));
+          return;
+        }
+
         if (stats.isDirectory()) {
-          if (recursive) {
-            const entries = await provider.readdir(toProviderPath(filePath));
-            for (let i = 0; i < entries.length; i++) {
-              await this.rm(joinPath(filePath, entries[i]), options);
-            }
+          if (!recursive) {
+            throw createEISDIR('rm', filePath);
+          }
+          const entries = await provider.readdir(toProviderPath(filePath));
+          for (let i = 0; i < entries.length; i++) {
+            await this.rm(joinPath(filePath, entries[i]), options);
           }
           await provider.rmdir(toProviderPath(filePath));
         } else {

lib/internal/vfs/providers/memory.js

@@ -266,8 +266,8 @@ class MemoryProvider extends VirtualProvider {
     for (let i = 0; i < segments.length; i++) {
       const segment = segments[i];
 
-      // Follow symlinks for intermediate path components
-      if (current.isSymbolicLink() && followSymlinks) {
+      // Always follow symlinks for intermediate path components
+      if (current.isSymbolicLink()) {
         if (depth >= kMaxSymlinkDepth) {
           return { entry: null, resolvedPath: null, eloop: true };
         }
@@ -380,6 +380,16 @@ class MemoryProvider extends VirtualProvider {
       current = entry;
     }
 
+    // Follow symlinks on the final parent entry
+    if (current.isSymbolicLink()) {
+      const targetPath = this.#resolveSymlinkTarget(parentPath, current.target);
+      const result = this.#lookupEntry(targetPath, true, 0);
+      if (!result.entry) {
+        throw createENOENT(syscall, path);
+      }
+      current = result.entry;
+    }
+
     if (!current.isDirectory()) {
       throw createENOTDIR(syscall, path);
     }
@@ -396,12 +406,13 @@ class MemoryProvider extends VirtualProvider {
    * @param {number} [size] Override size for files
    * @returns {Stats}
    */
-  #createStats(entry, size) {
+  #createStats(entry, size, bigint) {
     const options = {
       mode: entry.mode,
       mtimeMs: entry.mtime,
       ctimeMs: entry.ctime,
       birthtimeMs: entry.birthtime,
+      bigint,
     };
 
     if (entry.isFile()) {
@@ -510,7 +521,7 @@ class MemoryProvider extends VirtualProvider {
 
   statSync(path, options) {
     const entry = this.#getEntry(path, 'stat', true);
-    return this.#createStats(entry);
+    return this.#createStats(entry, undefined, options?.bigint);
   }
 
   async stat(path, options) {
@@ -519,7 +530,7 @@ class MemoryProvider extends VirtualProvider {
 
   lstatSync(path, options) {
     const entry = this.#getEntry(path, 'lstat', false);
-    return this.#createStats(entry);
+    return this.#createStats(entry, undefined, options?.bigint);
   }
 
   async lstat(path, options) {
@@ -632,6 +643,7 @@ class MemoryProvider extends VirtualProvider {
       const segments = this.#splitPath(normalized);
       let current = this[kRoot];
       let currentPath = '/';
+      let firstCreated;
 
       for (const segment of segments) {
         currentPath = pathPosix.join(currentPath, segment);
@@ -640,20 +652,23 @@ class MemoryProvider extends VirtualProvider {
           entry = new MemoryEntry(TYPE_DIR, { mode: options?.mode });
           entry.children = new SafeMap();
           current.children.set(segment, entry);
+          if (firstCreated === undefined) {
+            firstCreated = currentPath;
+          }
         } else if (!entry.isDirectory()) {
           throw createENOTDIR('mkdir', path);
         }
         current = entry;
       }
-    } else {
-      const parent = this.#ensureParent(normalized, false, 'mkdir');
-      const name = pathPosix.basename(normalized);
-      const entry = new MemoryEntry(TYPE_DIR, { mode: options?.mode });
-      entry.children = new SafeMap();
-      parent.children.set(name, entry);
+      return firstCreated;
     }
 
-    return recursive ? normalized : undefined;
+    const parent = this.#ensureParent(normalized, false, 'mkdir');
+    const name = pathPosix.basename(normalized);
+    const entry = new MemoryEntry(TYPE_DIR, { mode: options?.mode });
+    entry.children = new SafeMap();
+    parent.children.set(name, entry);
+    return undefined;
   }
 
   async mkdir(path, options) {
@@ -805,7 +820,7 @@ class MemoryProvider extends VirtualProvider {
       throw createEEXIST('symlink', path);
     }
 
-    const parent = this.#ensureParent(normalized, true, 'symlink');
+    const parent = this.#ensureParent(normalized, false, 'symlink');
     const name = pathPosix.basename(normalized);
     const entry = new MemoryEntry(TYPE_SYMLINK);
     entry.target = target;

lib/internal/vfs/providers/real.js

@@ -192,7 +192,7 @@ class RealFSProvider extends VirtualProvider {
    * @returns {string} The real filesystem path
    * @private
    */
-  #resolvePath(vfsPath) {
+  #resolvePath(vfsPath, followSymlinks = true) {
     // Normalize the VFS path (remove leading slash, handle . and ..)
     let normalized = vfsPath;
     if (normalized.startsWith('/')) {
@@ -211,9 +211,51 @@ class RealFSProvider extends VirtualProvider {
       throw createENOENT('open', vfsPath);
     }
 
+    // Resolve symlinks to prevent escape via symbolic links
+    if (followSymlinks) {
+      try {
+        const resolved = fs.realpathSync(realPath);
+        if (resolved !== this.#rootPath &&
+            !StringPrototypeStartsWith(resolved, rootWithSep)) {
+          throw createENOENT('open', vfsPath);
+        }
+        return resolved;
+      } catch (err) {
+        if (err?.code !== 'ENOENT') throw err;
+        // Path doesn't exist yet - verify deepest existing ancestor
+        this.#verifyAncestorInRoot(realPath, rootWithSep, vfsPath);
+        return realPath;
+      }
+    }
+
+    // For lstat/readlink (no final symlink follow), check parent only
+    this.#verifyAncestorInRoot(realPath, rootWithSep, vfsPath);
     return realPath;
   }
 
+  /**
+   * Verifies that the deepest existing ancestor of a path is within rootPath.
+   * @param {string} realPath The real filesystem path
+   * @param {string} rootWithSep The rootPath with trailing separator
+   * @param {string} vfsPath The original VFS path (for error messages)
+   */
+  #verifyAncestorInRoot(realPath, rootWithSep, vfsPath) {
+    let current = path.dirname(realPath);
+    while (current.length >= this.#rootPath.length) {
+      try {
+        const resolved = fs.realpathSync(current);
+        if (resolved !== this.#rootPath &&
+            !StringPrototypeStartsWith(resolved, rootWithSep)) {
+          throw createENOENT('open', vfsPath);
+        }
+        return;
+      } catch (err) {
+        if (err?.code !== 'ENOENT') throw err;
+        current = path.dirname(current);
+      }
+    }
+  }
+
   openSync(vfsPath, flags, mode) {
     const realPath = this.#resolvePath(vfsPath);
     const fd = fs.openSync(realPath, flags, mode);
@@ -241,12 +283,12 @@ class RealFSProvider extends VirtualProvider {
   }
 
   lstatSync(vfsPath, options) {
-    const realPath = this.#resolvePath(vfsPath);
+    const realPath = this.#resolvePath(vfsPath, false);
     return fs.lstatSync(realPath, options);
   }
 
   async lstat(vfsPath, options) {
-    const realPath = this.#resolvePath(vfsPath);
+    const realPath = this.#resolvePath(vfsPath, false);
     return fs.promises.lstat(realPath, options);
   }
 
@@ -303,12 +345,12 @@ class RealFSProvider extends VirtualProvider {
   }
 
   readlinkSync(vfsPath, options) {
-    const realPath = this.#resolvePath(vfsPath);
+    const realPath = this.#resolvePath(vfsPath, false);
     return fs.readlinkSync(realPath, options);
   }
 
   async readlink(vfsPath, options) {
-    const realPath = this.#resolvePath(vfsPath);
+    const realPath = this.#resolvePath(vfsPath, false);
     return fs.promises.readlink(realPath, options);
   }