From a990e8fec8149d008efe5b8681873bb4983386e0 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sat, 2 Dec 2023 23:49:21 +0100
Subject: [PATCH 1/7] 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: https://github.com/nodejs/node/pull/50976
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: LiviaMedeiros <livia@cirno.name>
---
 doc/api/fs.md                    | 13 +++++++++++++
 lib/fs.js                        |  2 +-
 lib/internal/fs/utils.js         |  1 +
 test/parallel/test-fs-opendir.js |  8 +++++---
 4 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index bc2d6b64ca2e51..d6ac052b3c9f04 100644
--- a/doc/api/fs.md
+++ b/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
diff --git a/lib/fs.js b/lib/fs.js
index 55e6373327c846..91ed441188f5f2 100644
--- a/lib/fs.js
+++ b/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 {
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index 00889ffccc4b99..a7127cb52c982f 100644
--- a/lib/internal/fs/utils.js
+++ b/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;
   }
diff --git a/test/parallel/test-fs-opendir.js b/test/parallel/test-fs-opendir.js
index 82ee8e20da31cd..4956b219ee5d43 100644
--- a/test/parallel/test-fs-opendir.js
+++ b/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);

From b44b3dedd77bc95a5365f7ecf46b4c0d389a1101 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 3 Dec 2023 10:30:04 +0100
Subject: [PATCH 2/7] fixup! fs: introduce `dirent.parentPath`

---
 lib/internal/fs/dir.js   | 2 +-
 lib/internal/fs/utils.js | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/internal/fs/dir.js b/lib/internal/fs/dir.js
index ec0562843d5f5c..0a0431c6b1540f 100644
--- a/lib/internal/fs/dir.js
+++ b/lib/internal/fs/dir.js
@@ -152,7 +152,7 @@ class Dir {
       ArrayPrototypePush(
         this[kDirBufferedEntries],
         getDirent(
-          pathModule.join(path, result[i]),
+          path,
           result[i],
           result[i + 1],
         ),
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index a7127cb52c982f..4174beff00543d 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -164,7 +164,7 @@ class Dirent {
   constructor(name, type, path) {
     this.name = name;
     this.parentPath = path;
-    this.path = path;
+    this.path = pathModule.join(path, name);
     this[kType] = type;
   }
 
@@ -234,7 +234,7 @@ function join(path, name) {
   }
 
   if (typeof path === 'string' && typeof name === 'string') {
-    return pathModule.basename(path) === name ? path : pathModule.join(path, name);
+    return pathModule.join(path, name);
   }
 
   if (isUint8Array(path) && isUint8Array(name)) {

From 181eca560ea6954295be2d3c4c7652fd904dc3d9 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 3 Dec 2023 23:56:29 +0100
Subject: [PATCH 3/7] fixup! fs: introduce `dirent.parentPath`

---
 lib/fs.js                |  2 +-
 lib/internal/fs/utils.js | 16 ++++++++--------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/lib/fs.js b/lib/fs.js
index 91ed441188f5f2..55e6373327c846 100644
--- a/lib/fs.js
+++ b/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.parentPath, dirent.name));
+          ArrayPrototypePush(pathsQueue, pathModule.join(dirent.path, dirent.name));
         }
       }
     } else {
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index 4174beff00543d..061dd129a9f156 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -161,10 +161,10 @@ function assertEncoding(encoding) {
 }
 
 class Dirent {
-  constructor(name, type, path) {
+  constructor(name, type, path, filepath = path && join(path, name)) {
     this.name = name;
     this.parentPath = path;
-    this.path = pathModule.join(path, name);
+    this.path = filepath;
     this[kType] = type;
   }
 
@@ -198,8 +198,8 @@ class Dirent {
 }
 
 class DirentFromStats extends Dirent {
-  constructor(name, stats, path) {
-    super(name, null, path);
+  constructor(name, stats, path, filepath) {
+    super(name, null, path, filepath);
     this[kStats] = stats;
   }
 }
@@ -234,7 +234,7 @@ function join(path, name) {
   }
 
   if (typeof path === 'string' && typeof name === 'string') {
-    return pathModule.join(path, name);
+    return pathModule.basename(path) === name ? path : pathModule.join(path, name);
   }
 
   if (isUint8Array(path) && isUint8Array(name)) {
@@ -269,7 +269,7 @@ function getDirents(path, { 0: names, 1: types }, callback) {
             callback(err);
             return;
           }
-          names[idx] = new DirentFromStats(name, stats, path);
+          names[idx] = new DirentFromStats(name, stats, path, filepath);
           if (--toFinish === 0) {
             callback(null, names);
           }
@@ -305,7 +305,7 @@ function getDirent(path, name, type, callback) {
           callback(err);
           return;
         }
-        callback(null, new DirentFromStats(name, stats, filepath));
+        callback(null, new DirentFromStats(name, stats, path, filepath));
       });
     } else {
       callback(null, new Dirent(name, type, path));
@@ -313,7 +313,7 @@ function getDirent(path, name, type, callback) {
   } else if (type === UV_DIRENT_UNKNOWN) {
     const filepath = join(path, name);
     const stats = lazyLoadFs().lstatSync(filepath);
-    return new DirentFromStats(name, stats, path);
+    return new DirentFromStats(name, stats, path, filepath);
   } else {
     return new Dirent(name, type, path);
   }

From 3db63d2abddf5da02c1f2e7ee2f27142ac197af0 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Mon, 4 Dec 2023 23:06:25 +0100
Subject: [PATCH 4/7] fixup! fs: introduce `dirent.parentPath`

---
 lib/internal/fs/dir.js   |  1 +
 lib/internal/fs/utils.js | 10 +++++++---
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/lib/internal/fs/dir.js b/lib/internal/fs/dir.js
index 0a0431c6b1540f..a06106affe7d52 100644
--- a/lib/internal/fs/dir.js
+++ b/lib/internal/fs/dir.js
@@ -155,6 +155,7 @@ class Dir {
           path,
           result[i],
           result[i + 1],
+          true, // Quirk to not introduce a breaking change.
         ),
       );
     }
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index 061dd129a9f156..2e9054a675426b 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -234,7 +234,7 @@ function join(path, name) {
   }
 
   if (typeof path === 'string' && typeof name === 'string') {
-    return pathModule.basename(path) === name ? path : pathModule.join(path, name);
+    return pathModule.join(path, name);
   }
 
   if (isUint8Array(path) && isUint8Array(name)) {
@@ -313,9 +313,13 @@ function getDirent(path, name, type, callback) {
   } else if (type === UV_DIRENT_UNKNOWN) {
     const filepath = join(path, name);
     const stats = lazyLoadFs().lstatSync(filepath);
-    return new DirentFromStats(name, stats, path, filepath);
-  } else {
+    // callback === true: Quirk to not introduce a breaking change.
+    return new DirentFromStats(name, stats, path, callback === true ? filepath : path);
+  } else if (callback === true) {
+    // callback === true: Quirk to not introduce a breaking change.
     return new Dirent(name, type, path);
+  } else {
+    return new Dirent(name, type, path, path);
   }
 }
 

From ec5f84bc8e914658e888e84d6030a2a726171e59 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Tue, 5 Dec 2023 00:11:36 +0100
Subject: [PATCH 5/7] doc: deprecate `dirent.path`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/51020
Reviewed-By: Yagiz Nizipli <yagiz.nizipli@sentry.io>
Reviewed-By: LiviaMedeiros <livia@cirno.name>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
---
 doc/api/deprecations.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 9882b802bf3e3b..e5e36c7cef6a39 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -3321,6 +3321,27 @@ In a future version of Node.js, [`message.headers`][],
 [`message.headersDistinct`][], [`message.trailers`][], and
 [`message.trailersDistinct`][] will be read-only.
 
+<!-- md-lint skip-deprecation DEP0172 -->
+<!-- md-lint skip-deprecation DEP0173 -->
+<!-- md-lint skip-deprecation DEP0174 -->
+<!-- md-lint skip-deprecation DEP0175 -->
+<!-- md-lint skip-deprecation DEP0176 -->
+<!-- md-lint skip-deprecation DEP0177 -->
+
+### DEP0178: `dirent.path`
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/51020
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+The [`dirent.path`][] is deprecated due to its lack of consistency across
+release lines. Please use [`dirent.parentPath`][] instead.
+
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
 [RFC 8247 Section 2.4]: https://www.rfc-editor.org/rfc/rfc8247#section-2.4
@@ -3366,6 +3387,8 @@ In a future version of Node.js, [`message.headers`][],
 [`decipher.setAuthTag()`]: crypto.md#deciphersetauthtagbuffer-encoding
 [`diagnostics_channel.subscribe(name, onMessage)`]: diagnostics_channel.md#diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.unsubscribe(name, onMessage)`]: diagnostics_channel.md#diagnostics_channelunsubscribename-onmessage
+[`dirent.parentPath`]: fs.md#direntparentpath
+[`dirent.path`]: fs.md#direntpath
 [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback
 [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options
 [`domain`]: domain.md

From 99ac462aef8e2bef188c80889e7e17e0f1f260c9 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Tue, 5 Dec 2023 22:15:23 +0100
Subject: [PATCH 6/7] doc: add deprecation notice to `dirent.path`

Refs: https://github.com/nodejs/node/pull/51020
PR-URL: https://github.com/nodejs/node/pull/51059
Reviewed-By: Debadree Chatterjee <debadree333@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
---
 doc/api/fs.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index d6ac052b3c9f04..6c5944878e0ebf 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -6454,8 +6454,11 @@ The path to the parent directory of the file this {fs.Dirent} object refers to.
 
 <!-- YAML
 added: v18.17.0
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated: Use [`dirent.parentPath`][] instead.
+
 * {string}
 
 The base path that this {fs.Dirent} object refers to.
@@ -7995,6 +7998,7 @@ the file contents.
 [`Number.MAX_SAFE_INTEGER`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
 [`ReadDirectoryChangesW`]: https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw
 [`UV_THREADPOOL_SIZE`]: cli.md#uv_threadpool_sizesize
+[`dirent.parentPath`]: #direntparentpath
 [`event ports`]: https://illumos.org/man/port_create
 [`filehandle.createReadStream()`]: #filehandlecreatereadstreamoptions
 [`filehandle.createWriteStream()`]: #filehandlecreatewritestreamoptions

From 650888ee5803d0662e7cd680381673b2bcade3f7 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Wed, 6 Dec 2023 00:28:02 +0100
Subject: [PATCH 7/7] fixup! doc: deprecate `dirent.path`

---
 doc/api/deprecations.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index e5e36c7cef6a39..5ed95d9dcf8f5a 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -3322,10 +3322,15 @@ In a future version of Node.js, [`message.headers`][],
 [`message.trailersDistinct`][] will be read-only.
 
 <!-- md-lint skip-deprecation DEP0172 -->
+
 <!-- md-lint skip-deprecation DEP0173 -->
+
 <!-- md-lint skip-deprecation DEP0174 -->
+
 <!-- md-lint skip-deprecation DEP0175 -->
+
 <!-- md-lint skip-deprecation DEP0176 -->
+
 <!-- md-lint skip-deprecation DEP0177 -->
 
 ### DEP0178: `dirent.path`