From fada5109ae9a13c8e63ee6e794a74ab3d14a33b6 Mon Sep 17 00:00:00 2001
From: mag123c <diehreo@gmail.com>
Date: Mon, 14 Jul 2025 09:55:20 +0900
Subject: [PATCH] path: add exclude option to matchesGlob method

Add support for exclude patterns in path.matchesGlob() to provide consistency with fs.glob().
The exclude option accepts strings, arrays, or functions to filter out matching paths.

Fixes: https://github.com/nodejs/node/issues/59015
---
 doc/api/path.md                 | 30 +++++++++++++++--
 lib/internal/fs/glob.js         | 58 +++++++++++++++++++++++++++++----
 lib/path.js                     | 12 +++++--
 test/parallel/test-path-glob.js | 38 +++++++++++++++++++++
 4 files changed, 128 insertions(+), 10 deletions(-)

diff --git a/doc/api/path.md b/doc/api/path.md
index 2c8398c877572d..bb95825f3e867d 100644
--- a/doc/api/path.md
+++ b/doc/api/path.md
@@ -283,7 +283,7 @@ path.format({
 // Returns: 'C:\\path\\dir\\file.txt'
 ```
 
-## `path.matchesGlob(path, pattern)`
+## `path.matchesGlob(path, pattern[, options])`
 
 <!-- YAML
 added:
@@ -295,17 +295,43 @@ added:
 
 * `path` {string} The path to glob-match against.
 * `pattern` {string} The glob to check the path against.
+* `options` {Object}
+  * `exclude` {string|string\[]|Function} Patterns to exclude from matching.
 * Returns: {boolean} Whether or not the `path` matched the `pattern`.
 
-The `path.matchesGlob()` method determines if `path` matches the `pattern`.
+The `path.matchesGlob()` method determines if `path` matches the `pattern`,
+optionally excluding paths that match the `exclude` patterns.
 
 For example:
 
 ```js
 path.matchesGlob('/foo/bar', '/foo/*'); // true
 path.matchesGlob('/foo/bar*', 'foo/bird'); // false
+
+// Using exclude with string
+path.matchesGlob('/foo/bar', '/foo/*', { exclude: '/foo/bar' }); // false
+path.matchesGlob('/foo/baz', '/foo/*', { exclude: '/foo/bar' }); // true
+
+// Using exclude with array
+path.matchesGlob('/foo/bar', '/foo/*', {
+  exclude: ['/foo/bar', '/foo/baz'],
+}); // false
+
+// Using exclude with function
+path.matchesGlob('/foo/bar', '/foo/*', {
+  exclude: (path) => path.includes('bar'),
+}); // false
 ```
 
+The `exclude` option can be:
+
+* A string pattern that will exclude matching paths
+* An array of string patterns
+* A function that receives the path and returns `true` to exclude it
+
+Unlike `fs.glob()`, the `exclude` patterns in `path.matchesGlob()` are
+matched against the input path directly, without path resolution.
+
 A [`TypeError`][] is thrown if `path` or `pattern` are not strings.
 
 ## `path.isAbsolute(path)`
diff --git a/lib/internal/fs/glob.js b/lib/internal/fs/glob.js
index def75f85e17bb2..69e0e9de463fc4 100644
--- a/lib/internal/fs/glob.js
+++ b/lib/internal/fs/glob.js
@@ -760,22 +760,68 @@ class Glob {
  * Check if a path matches a glob pattern
  * @param {string} path the path to check
  * @param {string} pattern the glob pattern to match
- * @param {boolean} windows whether the path is on a Windows system, defaults to `isWindows`
+ * @param {boolean|object} windowsOrOptions whether the path is on a Windows system, or options object
  * @returns {boolean}
  */
-function matchGlobPattern(path, pattern, windows = isWindows) {
+function matchGlobPattern(path, pattern, windowsOrOptions = isWindows) {
   validateString(path, 'path');
   validateString(pattern, 'pattern');
-  return lazyMinimatch().minimatch(path, pattern, {
-    kEmptyObject,
-    nocase: isMacOS || isWindows,
+
+  let windows = isWindows;
+  let options = kEmptyObject;
+
+  // Handle backward compatibility: third param can be boolean or options object
+  if (typeof windowsOrOptions === 'boolean') {
+    windows = windowsOrOptions;
+  } else if (windowsOrOptions != null) {
+    validateObject(windowsOrOptions, 'options');
+    options = windowsOrOptions;
+    windows = options.windows ?? isWindows;
+  }
+
+  const minimatchOptions = {
+    __proto__: null,
+    nocase: windows || isMacOS,
     windowsPathsNoEscape: true,
     nonegate: true,
     nocomment: true,
     optimizationLevel: 2,
     platform: windows ? 'win32' : 'posix',
     nocaseMagicOnly: true,
-  });
+  };
+
+  // Check if path matches the main pattern
+  const matches = lazyMinimatch().minimatch(path, pattern, minimatchOptions);
+
+  if (!matches) {
+    return false;
+  }
+
+  // Handle exclude patterns
+  const { exclude } = options;
+  if (!exclude) {
+    return matches;
+  }
+
+  if (typeof exclude === 'function') {
+    return !exclude(path);
+  }
+
+  if (typeof exclude === 'string') {
+    const excludeMatch = lazyMinimatch().minimatch(path, exclude, minimatchOptions);
+    return !excludeMatch;
+  }
+
+  if (ArrayIsArray(exclude)) {
+    for (const excludePattern of exclude) {
+      validateString(excludePattern, 'exclude pattern');
+      if (lazyMinimatch().minimatch(path, excludePattern, minimatchOptions)) {
+        return false;
+      }
+    }
+  }
+
+  return matches;
 }
 
 module.exports = {
diff --git a/lib/path.js b/lib/path.js
index 1a59a66f66bb2a..b35718d3ee31dd 100644
--- a/lib/path.js
+++ b/lib/path.js
@@ -1140,8 +1140,12 @@ const win32 = {
     return ret;
   },
 
-  matchesGlob(path, pattern) {
+  matchesGlob(path, pattern, options) {
     emitExperimentalWarning('glob');
+    if (options != null) {
+      validateObject(options, 'options');
+      return lazyMatchGlobPattern()(path, pattern, { windows: true, ...options });
+    }
     return lazyMatchGlobPattern()(path, pattern, true);
   },
 
@@ -1617,8 +1621,12 @@ const posix = {
     return ret;
   },
 
-  matchesGlob(path, pattern) {
+  matchesGlob(path, pattern, options) {
     emitExperimentalWarning('glob');
+    if (options != null) {
+      validateObject(options, 'options');
+      return lazyMatchGlobPattern()(path, pattern, { windows: false, ...options });
+    }
     return lazyMatchGlobPattern()(path, pattern, false);
   },
 
diff --git a/test/parallel/test-path-glob.js b/test/parallel/test-path-glob.js
index 47647e12784e5a..b9fdf378f9c61b 100644
--- a/test/parallel/test-path-glob.js
+++ b/test/parallel/test-path-glob.js
@@ -42,3 +42,41 @@ for (const [platform, platformGlobs] of Object.entries(globs)) {
 // Test for non-string input
 assert.throws(() => path.matchesGlob(123, 'foo/bar/baz'), /.*must be of type string.*/);
 assert.throws(() => path.matchesGlob('foo/bar/baz', 123), /.*must be of type string.*/);
+
+// Test exclude functionality
+const excludeTests = {
+  win32: [
+    // Basic exclude with string
+    ['foo\\bar\\baz', 'foo\\**\\*', { exclude: 'foo\\bar\\*' }, false],
+    ['foo\\bar\\baz', 'foo\\**\\*', { exclude: 'foo\\other\\*' }, true],
+
+    // Exclude with array
+    ['foo\\bar\\baz', 'foo\\**\\*', { exclude: ['foo\\bar\\*', 'foo\\other\\*'] }, false],
+    ['foo\\test\\file', 'foo\\**\\*', { exclude: ['foo\\bar\\*', 'foo\\other\\*'] }, true],
+
+    // Exclude with function
+    ['foo\\bar\\baz', 'foo\\**\\*', { exclude: (path) => path.includes('bar') }, false],
+    ['foo\\test\\file', 'foo\\**\\*', { exclude: (path) => path.includes('bar') }, true],
+  ],
+  posix: [
+    // Basic exclude with string
+    ['foo/bar/baz', 'foo/**/*', { exclude: 'foo/bar/*' }, false],
+    ['foo/bar/baz', 'foo/**/*', { exclude: 'foo/other/*' }, true],
+
+    // Exclude with array
+    ['foo/bar/baz', 'foo/**/*', { exclude: ['foo/bar/*', 'foo/other/*'] }, false],
+    ['foo/test/file', 'foo/**/*', { exclude: ['foo/bar/*', 'foo/other/*'] }, true],
+
+    // Exclude with function
+    ['foo/bar/baz', 'foo/**/*', { exclude: (path) => path.includes('bar') }, false],
+    ['foo/test/file', 'foo/**/*', { exclude: (path) => path.includes('bar') }, true],
+  ],
+};
+
+for (const [platform, platformTests] of Object.entries(excludeTests)) {
+  for (const [pathStr, pattern, options, expected] of platformTests) {
+    const actual = path[platform].matchesGlob(pathStr, pattern, options);
+    assert.strictEqual(actual, expected,
+                       `Expected ${pathStr} to ${expected ? '' : 'not '}match ${pattern} with exclude on ${platform}`);
+  }
+}