fs: introduce dirent.parentPath

The goal is to replace `dirent.path` using a name that's less likely to
create confusion.
`dirent.path` value has not been stable, moving it to a different
property name should avoid breaking some upgrading user expectations.

PR-URL: #50976
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: LiviaMedeiros <livia@cirno.name>

doc/api/fs.md

@@ -6614,6 +6614,19 @@ The file name that this {fs.Dirent} object refers to. The type of this
 value is determined by the `options.encoding` passed to [`fs.readdir()`][] or
 [`fs.readdirSync()`][].
 
+#### `dirent.parentPath`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1 – Experimental
+
+* {string}
+
+The path to the parent directory of the file this {fs.Dirent} object refers to.
+
 #### `dirent.path`
 
 <!-- YAML
@@ -6624,7 +6637,7 @@ added:
 
 * {string}
 
-The base path that this {fs.Dirent} object refers to.
+Alias for `dirent.parentPath`.
 
 ### Class: `fs.FSWatcher`
 

lib/fs.js

@@ -1426,7 +1426,7 @@ function readdirSyncRecursive(basePath, options) {
         const dirent = getDirent(path, readdirResult[0][i], readdirResult[1][i]);
         ArrayPrototypePush(readdirResults, dirent);
         if (dirent.isDirectory()) {
-          ArrayPrototypePush(pathsQueue, pathModule.join(dirent.path, dirent.name));
+          ArrayPrototypePush(pathsQueue, pathModule.join(dirent.parentPath, dirent.name));
         }
       }
     } else {

lib/internal/fs/dir.js

@@ -161,7 +161,7 @@ class Dir {
   }
 
   readSyncRecursive(dirent) {
-    const path = pathModule.join(dirent.path, dirent.name);
+    const path = pathModule.join(dirent.parentPath, dirent.name);
     const ctx = { path };
     const handle = dirBinding.opendir(
       pathModule.toNamespacedPath(path),

lib/internal/fs/utils.js

@@ -165,6 +165,7 @@ function assertEncoding(encoding) {
 class Dirent {
   constructor(name, type, path) {
     this.name = name;
+    this.parentPath = path;
     this.path = path;
     this[kType] = type;
   }

test/parallel/test-fs-opendir.js

@@ -48,9 +48,11 @@ const invalidCallbackObj = {
   const entries = files.map(() => {
     const dirent = dir.readSync();
     assertDirent(dirent);
-    return dirent.name;
-  });
-  assert.deepStrictEqual(files, entries.sort());
+    return { name: dirent.name, path: dirent.path, parentPath: dirent.parentPath, toString() { return dirent.name; } };
+  }).sort();
+  assert.deepStrictEqual(entries.map((d) => d.name), files);
+  assert.deepStrictEqual(entries.map((d) => d.path), Array(entries.length).fill(testDir));
+  assert.deepStrictEqual(entries.map((d) => d.parentPath), Array(entries.length).fill(testDir));
 
   // dir.read should return null when no more entries exist
   assert.strictEqual(dir.readSync(), null);