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: nodejs#50976
Reviewed-By: Ethan Arrowood <[email protected]>
Reviewed-By: LiviaMedeiros <[email protected]>

Author: aduh95

doc/api/fs.md

@@ -6437,6 +6437,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

lib/fs.js

@@ -1431,7 +1431,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/utils.js

@@ -163,6 +163,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), files.map((name) => path.join(testDir, name)));
+  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);