From 2622646f350800a9986476632791f12ee8413bd2 Mon Sep 17 00:00:00 2001
From: jorge guerrero <grrr.jrg@gmail.com>
Date: Sun, 1 Mar 2026 20:03:54 -0500
Subject: [PATCH] fs: honor encoding option in glob APIs

Align glob, globSync, and fsPromises.glob with encoding semantics.

When encoding is 'buffer', return Buffer paths and Buffer dirent names.

Add regression tests and documentation updates to lock behavior.
---
 doc/api/fs.md                  |  23 +++-
 lib/internal/fs/glob.js        | 204 ++++++++++++++++++++++++---------
 test/parallel/test-fs-glob.mjs | 181 ++++++++++++++++++++++++++++-
 3 files changed, 350 insertions(+), 58 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 66d29bc80fbf18..482bceeaf3f96a 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1086,6 +1086,8 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v22.0.0
 changes:
+  - version: v26.0.0
+    description: Add support for `encoding` as an option.
   - version:
       - v24.1.0
       - v22.17.0
@@ -1115,10 +1117,14 @@ changes:
     If a string array is provided, each string should be a glob pattern that
     specifies paths to exclude. Note: Negation patterns (e.g., '!foo.js') are
     not supported.
+  * `encoding` {string} The path encoding. If set to `'buffer'`, the iterator
+    yields `Buffer` paths (or `Dirent` entries with `Buffer` names when
+    `withFileTypes` is `true`). **Default:** `'utf8'`.
   * `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
     `false` otherwise. **Default:** `false`.
-* Returns: {AsyncIterator} An AsyncIterator that yields the paths of files
-  that match the pattern.
+* Returns: {AsyncIterator} An AsyncIterator that yields matching paths as
+  {string} values, or {Buffer} values if `encoding` is `'buffer'` (or
+  {fs.Dirent} values when `withFileTypes` is `true`).
 
 ```mjs
 import { glob } from 'node:fs/promises';
@@ -3195,6 +3201,8 @@ descriptor. See [`fs.utimes()`][].
 <!-- YAML
 added: v22.0.0
 changes:
+  - version: v26.0.0
+    description: Add support for `encoding` as an option.
   - version:
       - v24.1.0
       - v22.17.0
@@ -3222,11 +3230,15 @@ changes:
   * `exclude` {Function|string\[]} Function to filter out files/directories or a
     list of glob patterns to be excluded. If a function is provided, return
     `true` to exclude the item, `false` to include it. **Default:** `undefined`.
+  * `encoding` {string} The path encoding. If set to `'buffer'`, `matches`
+    contains `Buffer` paths (or `Dirent` entries with `Buffer` names when
+    `withFileTypes` is `true`). **Default:** `'utf8'`.
   * `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
     `false` otherwise. **Default:** `false`.
 
 * `callback` {Function}
   * `err` {Error}
+  * `matches` {string\[]|Buffer\[]|fs.Dirent\[]}
 
 * Retrieves the files matching the specified pattern.
 
@@ -5760,6 +5772,8 @@ Synchronous version of [`fs.futimes()`][]. Returns `undefined`.
 <!-- YAML
 added: v22.0.0
 changes:
+  - version: v26.0.0
+    description: Add support for `encoding` as an option.
   - version:
       - v24.1.0
       - v22.17.0
@@ -5786,9 +5800,12 @@ changes:
   * `exclude` {Function|string\[]} Function to filter out files/directories or a
     list of glob patterns to be excluded. If a function is provided, return
     `true` to exclude the item, `false` to include it. **Default:** `undefined`.
+  * `encoding` {string} The path encoding. If set to `'buffer'`, returns
+    `Buffer` paths (or `Dirent` entries with `Buffer` names when
+    `withFileTypes` is `true`). **Default:** `'utf8'`.
   * `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
     `false` otherwise. **Default:** `false`.
-* Returns: {string\[]} paths of files that match the pattern.
+* Returns: {string\[]|Buffer\[]|fs.Dirent\[]} paths of files that match the pattern.
 
 ```mjs
 import { globSync } from 'node:fs';
diff --git a/lib/internal/fs/glob.js b/lib/internal/fs/glob.js
index 526efd4c010d7c..0ca38c00a1ce21 100644
--- a/lib/internal/fs/glob.js
+++ b/lib/internal/fs/glob.js
@@ -9,8 +9,12 @@ const {
   ArrayPrototypePop,
   ArrayPrototypePush,
   ArrayPrototypeSome,
+  ObjectDefineProperty,
+  ObjectGetOwnPropertyDescriptor,
+  ObjectGetPrototypeOf,
   Promise,
   PromisePrototypeThen,
+  ReflectOwnKeys,
   SafeMap,
   SafeSet,
   StringPrototypeEndsWith,
@@ -18,7 +22,8 @@ const {
 
 const { lstatSync, readdirSync } = require('fs');
 const { lstat, readdir } = require('fs/promises');
-const { join, resolve, basename, isAbsolute, dirname } = require('path');
+const { join: pathJoin, resolve, basename, isAbsolute, dirname } = require('path');
+const { Buffer } = require('buffer');
 
 const {
   kEmptyObject,
@@ -30,7 +35,7 @@ const {
   validateString,
   validateStringArray,
 } = require('internal/validators');
-const { DirentFromStats } = require('internal/fs/utils');
+const { DirentFromStats, assertEncoding } = require('internal/fs/utils');
 const {
   codes: {
     ERR_INVALID_ARG_TYPE,
@@ -47,31 +52,33 @@ function lazyMinimatch() {
 }
 
 /**
- * @param {string} path
+ * @param {string|Buffer} path
+ * @param {string} pathForName
  * @returns {Promise<DirentFromStats|null>}
  */
-async function getDirent(path) {
+async function getDirent(path, pathForName = path) {
   let stat;
   try {
     stat = await lstat(path);
   } catch {
     return null;
   }
-  return new DirentFromStats(basename(path), stat, dirname(path));
+  return new DirentFromStats(basename(pathForName), stat, dirname(pathForName));
 }
 
 /**
- * @param {string} path
+ * @param {string|Buffer} path
+ * @param {string} pathForName
  * @returns {DirentFromStats|null}
  */
-function getDirentSync(path) {
+function getDirentSync(path, pathForName = path) {
   let stat;
   try {
     stat = lstatSync(path);
   } catch {
     return null;
   }
-  return new DirentFromStats(basename(path), stat, dirname(path));
+  return new DirentFromStats(basename(pathForName), stat, dirname(pathForName));
 }
 
 /**
@@ -117,13 +124,25 @@ class Cache {
   #cache = new SafeMap();
   #statsCache = new SafeMap();
   #readdirCache = new SafeMap();
+  #encoding;
+
+  constructor(encoding = 'utf8') {
+    this.#encoding = encoding;
+  }
+
+  #toFsPath(path) {
+    if (this.#encoding === 'buffer') {
+      return Buffer.from(path, 'latin1');
+    }
+    return path;
+  }
 
   stat(path) {
     const cached = this.#statsCache.get(path);
     if (cached) {
       return cached;
     }
-    const promise = getDirent(path);
+    const promise = getDirent(this.#toFsPath(path), path);
     this.#statsCache.set(path, promise);
     return promise;
   }
@@ -133,7 +152,7 @@ class Cache {
     if (cached && !(cached instanceof Promise)) {
       return cached;
     }
-    const val = getDirentSync(path);
+    const val = getDirentSync(this.#toFsPath(path), path);
     this.#statsCache.set(path, val);
     return val;
   }
@@ -145,7 +164,15 @@ class Cache {
     if (cached) {
       return cached;
     }
-    const promise = PromisePrototypeThen(readdir(path, { __proto__: null, withFileTypes: true }), null, () => []);
+    const promise = PromisePrototypeThen(
+      readdir(this.#toFsPath(path), {
+        __proto__: null,
+        withFileTypes: true,
+        encoding: this.#encoding,
+      }),
+      null,
+      () => [],
+    );
     this.#readdirCache.set(path, promise);
     return promise;
   }
@@ -156,7 +183,11 @@ class Cache {
     }
     let val;
     try {
-      val = readdirSync(path, { __proto__: null, withFileTypes: true });
+      val = readdirSync(this.#toFsPath(path), {
+        __proto__: null,
+        withFileTypes: true,
+        encoding: this.#encoding,
+      });
     } catch {
       val = [];
     }
@@ -260,17 +291,37 @@ class ResultSet extends SafeSet {
 class Glob {
   #root;
   #exclude;
-  #cache = new Cache();
+  #cache;
   #results = new ResultSet();
   #queue = [];
   #subpatterns = new SafeMap();
   #patterns;
   #withFileTypes;
   #isExcluded = () => false;
+  #encoding;
+  #toUserPathForMatching(path) {
+    if (this.#encoding === 'buffer') {
+      return Buffer.from(path).toString('latin1');
+    }
+    return path;
+  }
+
   constructor(pattern, options = kEmptyObject) {
     validateObject(options, 'options');
-    const { exclude, cwd, withFileTypes } = options;
+    const { exclude, cwd, withFileTypes, encoding } = options;
+    if (encoding != null) {
+      if (encoding !== 'buffer') {
+        assertEncoding(encoding);
+      }
+      this.#encoding = encoding;
+    } else {
+      this.#encoding = 'utf8';
+    }
+    this.#cache = new Cache(this.#encoding);
     this.#root = toPathIfFileURL(cwd) ?? '.';
+    if (this.#encoding === 'buffer') {
+      this.#root = Buffer.from(this.#root).toString('latin1');
+    }
     this.#withFileTypes = !!withFileTypes;
     if (exclude != null) {
       validateStringArrayOrFunction(exclude, 'options.exclude');
@@ -279,7 +330,7 @@ class Glob {
         // Convert the path part of exclude patterns to absolute paths for
         // consistent comparison before instantiating matchers.
         const matchers = exclude
-          .map((pattern) => resolve(this.#root, pattern))
+          .map((pattern) => resolve(this.#root, this.#toUserPathForMatching(pattern)))
           .map((pattern) => createMatcher(pattern));
         this.#isExcluded = (value) =>
           matchers.some((matcher) => matcher.match(value));
@@ -296,6 +347,9 @@ class Glob {
       validateString(pattern, 'patterns');
       patterns = [pattern];
     }
+    if (this.#encoding === 'buffer') {
+      patterns = ArrayPrototypeMap(patterns, (pattern) => this.#toUserPathForMatching(pattern));
+    }
     this.matchers = ArrayPrototypeMap(patterns, (pattern) => createMatcher(pattern));
     this.#patterns = ArrayPrototypeFlatMap(this.matchers, (matcher) => ArrayPrototypeMap(matcher.set,
                                                                                          (pattern, i) => new Pattern(
@@ -306,6 +360,37 @@ class Glob {
                                                                                          )));
   }
 
+  #toPathForMatching(path) {
+    if (Buffer.isBuffer(path)) {
+      return path.toString('latin1');
+    }
+    return path;
+  }
+
+  #toResultPath(path) {
+    if (this.#encoding === 'buffer') {
+      return Buffer.from(path, 'latin1');
+    }
+    return path;
+  }
+
+  #toResultDirent(dirent) {
+    if (this.#encoding === 'buffer' &&
+        dirent !== null &&
+        !Buffer.isBuffer(dirent.name)) {
+      const result = { __proto__: ObjectGetPrototypeOf(dirent) };
+      for (const key of ReflectOwnKeys(dirent)) {
+        const descriptor = ObjectGetOwnPropertyDescriptor(dirent, key);
+        if (key === 'name') {
+          descriptor.value = Buffer.from(dirent.name, 'latin1');
+        }
+        ObjectDefineProperty(result, key, descriptor);
+      }
+      return result;
+    }
+    return dirent;
+  }
+
   globSync() {
     ArrayPrototypePush(this.#queue, { __proto__: null, path: '.', patterns: this.#patterns });
     while (this.#queue.length > 0) {
@@ -317,14 +402,18 @@ class Glob {
         .forEach((patterns, path) => ArrayPrototypePush(this.#queue, { __proto__: null, path, patterns }));
       this.#subpatterns.clear();
     }
-    return ArrayFrom(
+    const results = ArrayFrom(
       this.#results,
-      this.#withFileTypes ? (path) => this.#cache.statSync(
+      this.#withFileTypes ? (path) => this.#toResultDirent(this.#cache.statSync(
         isAbsolute(path) ?
           path :
-          join(this.#root, path),
-      ) : undefined,
+          pathJoin(this.#root, path),
+      )) : undefined,
     );
+    if (this.#encoding === 'buffer' && !this.#withFileTypes) {
+      return results.map((r) => this.#toResultPath(r));
+    }
+    return results;
   }
   #addSubpattern(path, pattern) {
     if (this.#isExcluded(path)) {
@@ -341,7 +430,7 @@ class Glob {
       if (this.#withFileTypes) {
         const stat = this.#cache.statSync(path);
         if (stat !== null) {
-          if (this.#exclude(stat)) {
+          if (this.#exclude(this.#toResultDirent(stat))) {
             return;
           }
         }
@@ -394,9 +483,9 @@ class Glob {
     if (isLast && typeof pattern.at(-1) === 'string') {
       // Add result if it exists
       const p = pattern.at(-1);
-      const stat = this.#cache.statSync(join(fullpath, p));
+      const stat = this.#cache.statSync(pathJoin(fullpath, p));
       if (stat && (p || isDirectory)) {
-        this.#results.add(join(path, p));
+        this.#results.add(pathJoin(path, p));
       }
       if (pattern.indexes.size === 1 && pattern.indexes.has(last)) {
         return;
@@ -415,7 +504,7 @@ class Glob {
     let children;
     const firstPattern = pattern.indexes.size === 1 && pattern.at(pattern.indexes.values().next().value);
     if (typeof firstPattern === 'string') {
-      const stat = this.#cache.statSync(join(fullpath, firstPattern));
+      const stat = this.#cache.statSync(pathJoin(fullpath, firstPattern));
       if (stat) {
         stat.name = firstPattern;
         children = [stat];
@@ -428,8 +517,9 @@ class Glob {
 
     for (let i = 0; i < children.length; i++) {
       const entry = children[i];
-      const entryPath = join(path, entry.name);
-      this.#cache.addToStatCache(join(fullpath, entry.name), entry);
+      const entryNameStr = this.#toPathForMatching(entry.name);
+      const entryPath = pathJoin(path, entryNameStr);
+      this.#cache.addToStatCache(pathJoin(fullpath, entryNameStr), entry);
 
       const subPatterns = new SafeSet();
       const nSymlinks = new SafeSet();
@@ -444,18 +534,19 @@ class Glob {
         const fromSymlink = pattern.symlinks.has(index);
 
         if (current === lazyMinimatch().GLOBSTAR) {
-          const isDot = entry.name[0] === '.';
-          const nextMatches = pattern.test(nextIndex, entry.name);
+          const isDot = entryNameStr[0] === '.';
+          const nextMatches = pattern.test(nextIndex, entryNameStr);
 
           let nextNonGlobIndex = nextIndex;
           while (pattern.at(nextNonGlobIndex) === lazyMinimatch().GLOBSTAR) {
             nextNonGlobIndex++;
           }
 
-          const matchesDot = isDot && pattern.test(nextNonGlobIndex, entry.name);
+          const matchesDot = isDot && pattern.test(nextNonGlobIndex, entryNameStr);
 
           if ((isDot && !matchesDot) ||
-              (this.#exclude && this.#exclude(this.#withFileTypes ? entry : entry.name))) {
+              (this.#exclude &&
+              this.#exclude(this.#withFileTypes ? this.#toResultDirent(entry) : entryNameStr))) {
             continue;
           }
           if (!fromSymlink && entry.isDirectory()) {
@@ -492,7 +583,7 @@ class Glob {
             // In case pattern is "**/..",
             // both parent and current directory should be added to the queue
             // if this is the last pattern, add to results instead
-            const parent = join(path, '..');
+            const parent = pathJoin(path, '..');
             if (nextIndex < last) {
               if (!this.#subpatterns.has(path) && !this.#cache.seen(path, pattern, nextIndex + 1)) {
                 this.#subpatterns.set(path, [pattern.child(new SafeSet().add(nextIndex + 1))]);
@@ -513,11 +604,11 @@ class Glob {
           }
         }
         if (typeof current === 'string') {
-          if (pattern.test(index, entry.name) && index !== last) {
+          if (pattern.test(index, entryNameStr) && index !== last) {
             // If current pattern matches entry name
             // the next pattern is a potential pattern
             subPatterns.add(nextIndex);
-          } else if (current === '.' && pattern.test(nextIndex, entry.name)) {
+          } else if (current === '.' && pattern.test(nextIndex, entryNameStr)) {
             // If current pattern is ".", proceed to test next pattern
             if (nextIndex === last) {
               this.#results.add(entryPath);
@@ -526,7 +617,7 @@ class Glob {
             }
           }
         }
-        if (typeof current === 'object' && pattern.test(index, entry.name)) {
+        if (typeof current === 'object' && pattern.test(index, entryNameStr)) {
           // If current pattern is a regex that matches entry name (e.g *.js)
           // add next pattern to potential patterns, or to results if it's the last pattern
           if (index === last) {
@@ -595,12 +686,12 @@ class Glob {
     if (isLast && typeof pattern.at(-1) === 'string') {
       // Add result if it exists
       const p = pattern.at(-1);
-      const stat = await this.#cache.stat(join(fullpath, p));
+      const stat = await this.#cache.stat(pathJoin(fullpath, p));
       if (stat && (p || isDirectory)) {
-        const result = join(path, p);
+        const result = pathJoin(path, p);
         if (!this.#results.has(result)) {
           if (this.#results.add(result)) {
-            yield this.#withFileTypes ? stat : result;
+            yield this.#withFileTypes ? this.#toResultDirent(stat) : this.#toResultPath(result);
           }
         }
       }
@@ -613,7 +704,7 @@ class Glob {
       // if path is ".", add it only if pattern starts with "." or pattern is exactly "**"
       if (!this.#results.has(path)) {
         if (this.#results.add(path)) {
-          yield this.#withFileTypes ? stat : path;
+          yield this.#withFileTypes ? this.#toResultDirent(stat) : this.#toResultPath(path);
         }
       }
     }
@@ -625,7 +716,7 @@ class Glob {
     let children;
     const firstPattern = pattern.indexes.size === 1 && pattern.at(pattern.indexes.values().next().value);
     if (typeof firstPattern === 'string') {
-      const stat = await this.#cache.stat(join(fullpath, firstPattern));
+      const stat = await this.#cache.stat(pathJoin(fullpath, firstPattern));
       if (stat) {
         stat.name = firstPattern;
         children = [stat];
@@ -638,8 +729,9 @@ class Glob {
 
     for (let i = 0; i < children.length; i++) {
       const entry = children[i];
-      const entryPath = join(path, entry.name);
-      this.#cache.addToStatCache(join(fullpath, entry.name), entry);
+      const entryNameStr = this.#toPathForMatching(entry.name);
+      const entryPath = pathJoin(path, entryNameStr);
+      this.#cache.addToStatCache(pathJoin(fullpath, entryNameStr), entry);
 
       const subPatterns = new SafeSet();
       const nSymlinks = new SafeSet();
@@ -654,18 +746,18 @@ class Glob {
         const fromSymlink = pattern.symlinks.has(index);
 
         if (current === lazyMinimatch().GLOBSTAR) {
-          const isDot = entry.name[0] === '.';
-          const nextMatches = pattern.test(nextIndex, entry.name);
+          const isDot = entryNameStr[0] === '.';
+          const nextMatches = pattern.test(nextIndex, entryNameStr);
 
           let nextNonGlobIndex = nextIndex;
           while (pattern.at(nextNonGlobIndex) === lazyMinimatch().GLOBSTAR) {
             nextNonGlobIndex++;
           }
 
-          const matchesDot = isDot && pattern.test(nextNonGlobIndex, entry.name);
+          const matchesDot = isDot && pattern.test(nextNonGlobIndex, entryNameStr);
 
           if ((isDot && !matchesDot) ||
-              (this.#exclude && this.#exclude(this.#withFileTypes ? entry : entry.name))) {
+              (this.#exclude && this.#exclude(this.#withFileTypes ? this.#toResultDirent(entry) : entryNameStr))) {
             continue;
           }
           if (!fromSymlink && entry.isDirectory()) {
@@ -674,7 +766,7 @@ class Glob {
           } else if (!fromSymlink && index === last) {
             // If ** is last, add to results
             if (!this.#results.has(entryPath) && this.#results.add(entryPath)) {
-              yield this.#withFileTypes ? entry : entryPath;
+              yield this.#withFileTypes ? this.#toResultDirent(entry) : this.#toResultPath(entryPath);
             }
           }
 
@@ -683,7 +775,7 @@ class Glob {
           if (nextMatches && nextIndex === last && !isLast) {
             // If next pattern is the last one, add to results
             if (!this.#results.has(entryPath) && this.#results.add(entryPath)) {
-              yield this.#withFileTypes ? entry : entryPath;
+              yield this.#withFileTypes ? this.#toResultDirent(entry) : this.#toResultPath(entryPath);
             }
           } else if (nextMatches && entry.isDirectory()) {
             // Pattern matched, meaning two patterns forward
@@ -706,7 +798,7 @@ class Glob {
             // In case pattern is "**/..",
             // both parent and current directory should be added to the queue
             // if this is the last pattern, add to results instead
-            const parent = join(path, '..');
+            const parent = pathJoin(path, '..');
             if (nextIndex < last) {
               if (!this.#subpatterns.has(path) && !this.#cache.seen(path, pattern, nextIndex + 1)) {
                 this.#subpatterns.set(path, [pattern.child(new SafeSet().add(nextIndex + 1))]);
@@ -719,7 +811,9 @@ class Glob {
                 this.#cache.add(path, pattern.child(new SafeSet().add(nextIndex)));
                 if (!this.#results.has(path)) {
                   if (this.#results.add(path)) {
-                    yield this.#withFileTypes ? this.#cache.statSync(fullpath) : path;
+                    yield this.#withFileTypes ?
+                      this.#toResultDirent(this.#cache.statSync(fullpath)) :
+                      this.#toResultPath(path);
                   }
                 }
               }
@@ -727,7 +821,9 @@ class Glob {
                 this.#cache.add(parent, pattern.child(new SafeSet().add(nextIndex)));
                 if (!this.#results.has(parent)) {
                   if (this.#results.add(parent)) {
-                    yield this.#withFileTypes ? this.#cache.statSync(join(this.#root, parent)) : parent;
+                    yield this.#withFileTypes ?
+                      this.#toResultDirent(this.#cache.statSync(pathJoin(this.#root, parent))) :
+                      this.#toResultPath(parent);
                   }
                 }
               }
@@ -735,16 +831,16 @@ class Glob {
           }
         }
         if (typeof current === 'string') {
-          if (pattern.test(index, entry.name) && index !== last) {
+          if (pattern.test(index, entryNameStr) && index !== last) {
             // If current pattern matches entry name
             // the next pattern is a potential pattern
             subPatterns.add(nextIndex);
-          } else if (current === '.' && pattern.test(nextIndex, entry.name)) {
+          } else if (current === '.' && pattern.test(nextIndex, entryNameStr)) {
             // If current pattern is ".", proceed to test next pattern
             if (nextIndex === last) {
               if (!this.#results.has(entryPath)) {
                 if (this.#results.add(entryPath)) {
-                  yield this.#withFileTypes ? entry : entryPath;
+                  yield this.#withFileTypes ? this.#toResultDirent(entry) : this.#toResultPath(entryPath);
                 }
               }
             } else {
@@ -752,13 +848,13 @@ class Glob {
             }
           }
         }
-        if (typeof current === 'object' && pattern.test(index, entry.name)) {
+        if (typeof current === 'object' && pattern.test(index, entryNameStr)) {
           // If current pattern is a regex that matches entry name (e.g *.js)
           // add next pattern to potential patterns, or to results if it's the last pattern
           if (index === last) {
             if (!this.#results.has(entryPath)) {
               if (this.#results.add(entryPath)) {
-                yield this.#withFileTypes ? entry : entryPath;
+                yield this.#withFileTypes ? this.#toResultDirent(entry) : this.#toResultPath(entryPath);
               }
             }
           } else if (entry.isDirectory()) {
diff --git a/test/parallel/test-fs-glob.mjs b/test/parallel/test-fs-glob.mjs
index 74791deba373e3..fae5985ba0710b 100644
--- a/test/parallel/test-fs-glob.mjs
+++ b/test/parallel/test-fs-glob.mjs
@@ -2,7 +2,15 @@ import * as common from '../common/index.mjs';
 import tmpdir from '../common/tmpdir.js';
 import { resolve, dirname, sep, relative, join, isAbsolute } from 'node:path';
 import { mkdir, writeFile, symlink, glob as asyncGlob } from 'node:fs/promises';
-import { glob, globSync, Dirent, chmodSync, writeFileSync, rmSync } from 'node:fs';
+import {
+  glob,
+  globSync,
+  Dirent,
+  chmodSync,
+  writeFileSync,
+  rmSync,
+  mkdirSync,
+} from 'node:fs';
 import { test, describe } from 'node:test';
 import { pathToFileURL } from 'node:url';
 import { promisify } from 'node:util';
@@ -14,6 +22,64 @@ function assertDirents(dirents) {
 
 tmpdir.refresh();
 
+let nonUtf8Probe;
+let nonUtf8CaseId = 0;
+
+function getNonUtf8Probe() {
+  if (nonUtf8Probe) {
+    return nonUtf8Probe;
+  }
+
+  if (common.isWindows) {
+    nonUtf8Probe = {
+      supported: false,
+      reason: 'raw-byte filenames are unsupported on Windows',
+    };
+    return nonUtf8Probe;
+  }
+
+  const probeDir = tmpdir.resolve(`glob-buffer-probe-${process.pid}`);
+  rmSync(probeDir, { recursive: true, force: true });
+  mkdirSync(probeDir, { recursive: true });
+
+  const raw = Buffer.from([0xe9]);
+  const probePath = Buffer.concat([
+    Buffer.from(probeDir),
+    Buffer.from(sep),
+    raw,
+  ]);
+
+  try {
+    writeFileSync(probePath, 'probe');
+    nonUtf8Probe = { supported: true };
+  } catch (err) {
+    nonUtf8Probe = {
+      supported: false,
+      reason: `non-UTF8 filename probe failed: ${err.code ?? err.message}`,
+    };
+  } finally {
+    rmSync(probeDir, { recursive: true, force: true });
+  }
+
+  return nonUtf8Probe;
+}
+
+function createNonUtf8CaseDir(name) {
+  const dir = tmpdir.resolve(`glob-buffer-${name}-${process.pid}-${nonUtf8CaseId++}`);
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function toHexSet(values) {
+  const hex = [];
+  for (const value of values) {
+    assert(Buffer.isBuffer(value));
+    hex.push(value.toString('hex'));
+  }
+  return hex.sort();
+}
+
 const fixtureDir = tmpdir.resolve('fixtures');
 const absDir = tmpdir.resolve('abs');
 
@@ -561,3 +627,116 @@ describe('globSync - ENOTDIR', function() {
     }
   });
 });
+
+describe('glob - encoding buffer', function() {
+  test('globSync preserves raw bytes with encoding buffer', (t) => {
+    const probe = getNonUtf8Probe();
+    if (!probe.supported) {
+      t.skip(probe.reason);
+      return;
+    }
+
+    const cwd = createNonUtf8CaseDir('sync-raw');
+    t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+    const rawName = Buffer.from([0xe9]);
+    const fullPath = Buffer.concat([
+      Buffer.from(cwd),
+      Buffer.from(sep),
+      rawName,
+    ]);
+
+    writeFileSync(fullPath, 'x');
+
+    const actual = globSync('[^a-z]', { cwd, encoding: 'buffer' });
+    assert.deepStrictEqual(actual, [rawName]);
+
+    const utf8Actual = globSync('[^a-z]', { cwd });
+    assert.strictEqual(utf8Actual.length, 1);
+    assert.strictEqual(typeof utf8Actual[0], 'string');
+  });
+
+  test('globSync rejects invalid encoding', () => {
+    assert.throws(() => globSync('*', {
+      cwd: fixtureDir,
+      encoding: 'bogus',
+    }), {
+      code: 'ERR_INVALID_ARG_VALUE',
+    });
+  });
+
+  test('encoding buffer parity across globSync/glob/fsPromises.glob', async () => {
+    const options = { cwd: fixtureDir, encoding: 'buffer' };
+
+    const syncResults = globSync('a/**', options);
+    assert(syncResults.length > 0);
+    assert(syncResults.every(Buffer.isBuffer));
+
+    const callbackResults = await promisify(glob)('a/**', options);
+    assert(callbackResults.length > 0);
+    assert(callbackResults.every(Buffer.isBuffer));
+
+    const asyncResults = [];
+    for await (const item of asyncGlob('a/**', options)) {
+      asyncResults.push(item);
+    }
+    assert(asyncResults.length > 0);
+    assert(asyncResults.every(Buffer.isBuffer));
+
+    assert.deepStrictEqual(toHexSet(callbackResults), toHexSet(syncResults));
+    assert.deepStrictEqual(toHexSet(asyncResults), toHexSet(syncResults));
+  });
+
+  test('encoding buffer supports absolute patterns', async () => {
+    const pattern = join(fixtureDir, 'a', '**');
+    const options = { encoding: 'buffer' };
+
+    const syncResults = globSync(pattern, options);
+    assert(syncResults.length > 0);
+    assert(syncResults.every(Buffer.isBuffer));
+
+    const callbackResults = await promisify(glob)(pattern, options);
+    assert(callbackResults.length > 0);
+    assert(callbackResults.every(Buffer.isBuffer));
+
+    const asyncResults = [];
+    for await (const item of asyncGlob(pattern, options)) {
+      asyncResults.push(item);
+    }
+    assert(asyncResults.length > 0);
+    assert(asyncResults.every(Buffer.isBuffer));
+
+    assert.deepStrictEqual(toHexSet(callbackResults), toHexSet(syncResults));
+    assert.deepStrictEqual(toHexSet(asyncResults), toHexSet(syncResults));
+  });
+
+  test('encoding buffer withFileTypes returns Buffer dirent names', async () => {
+    const syncDirents = globSync('a/**', {
+      cwd: fixtureDir,
+      encoding: 'buffer',
+      withFileTypes: true,
+      exclude: common.mustCallAtLeast((dirent) => {
+        assert.ok(dirent instanceof Dirent);
+        assert(Buffer.isBuffer(dirent.name));
+        return false;
+      }, 1),
+    });
+
+    assertDirents(syncDirents);
+    assert(syncDirents.length > 0);
+    assert(syncDirents.every((dirent) => Buffer.isBuffer(dirent.name)));
+
+    const asyncDirents = [];
+    for await (const item of asyncGlob('a/**', {
+      cwd: fixtureDir,
+      encoding: 'buffer',
+      withFileTypes: true,
+    })) {
+      asyncDirents.push(item);
+    }
+
+    assertDirents(asyncDirents);
+    assert(asyncDirents.length > 0);
+    assert(asyncDirents.every((dirent) => Buffer.isBuffer(dirent.name)));
+  });
+});