Skip to content

Implement path.matchesGlob - #8390

Merged
jasnell merged 1 commit into
mainfrom
littledivy/2026-11-12-path-matches-glob
Nov 12, 2026
Merged

jasnell merged 1 commit into
mainfrom
littledivy/2026-11-12-path-matches-glob

Conversation

@littledivy

Copy link
Copy Markdown
Member

node:path matchesGlob() threw "not implemented" on both path.posix and path.win32, so code that filters paths with a glob couldn't run.

In this patch:

  • matchesGlob() matches like Node's, which runs minimatch with windowsPathsNoEscape, nonegate, nocomment and optimizationLevel: 2, and caches the last 250 compiled patterns per platform. Instead of vendoring minimatch (about 2k lines), a small GlobMatcher reuses fs.glob's brace and segment parsing. It adds minimatch's rules for dotfiles, absolute patterns, ./.. parts, {1..3} sequences, a trailing ** and Windows drives.
  • The pattern helpers move unchanged from internal_fs_glob.ts to a new dependency-free internal_glob_pattern.ts, so node:path doesn't load the node:fs internals. The minimatch-only syntax sits behind a minimatch argument, so fs.glob behaves as before.
  • A differential fuzz of 2M random path/pattern pairs against minimatch 10.2.6 (the version Node 26 vendors) found no mismatches outside three cases left out: POSIX classes like [[:alpha:]], empty extglob alternatives like @(a|), and minimatch's rewrite of **/...
before after
path.matchesGlob('foo/bar/baz', 'foo/**') throws true
path.matchesGlob('foo/.git', 'foo/*') throws false
path.win32.matchesGlob('foo\\bar', 'foo/bar') throws true

The test table is upstream test-path-glob.js plus 36 cases for the rules above, each checked against Node.

No compatibility flag: both functions threw before, so no working code changes behaviour.

@littledivy
littledivy requested review from a team as code owners November 12, 2026 11:45

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 8b940e75.

This review, of cb7b00cb

💬 Approved with comments — Two WARNINGs: reversed character-class ranges throw a SyntaxError instead of returning false, and brace expansion has no total limit, so one pattern can exhaust memory. Neither blocks the merge, but both are worth fixing.

Findings: 2 warnings · 1 info (3 are inline comments on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8390.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Security] Brace expansion is capped per sequence but not in total, so `{1..100000}/{1..100000}` or repeated `{a,b}` groups can exhaust the isolate's memory or CPU in the GlobMatcher constructor
- **File:** src/node/internal/internal_glob_pattern.ts:81

### [Code Quality] Reversed character-class ranges such as `[z-a]` make `matchesGlob()` throw a raw SyntaxError instead of returning false as Node does
- **File:** src/node/internal/internal_glob_pattern.ts:227

## INFO (1)

### [Documentation] The known differences from Node's matcher (POSIX classes, empty extglob alternatives, `**/..` rewrite) are not documented
- **File:** src/node/internal/internal_glob_pattern.ts:399

🔒 Security: ⚠️ 1 warning

Brace expansion has no limit on its total output

Recommendation: 📝 Minor Comments

  • [WARNING] Brace expansion is capped per sequence but not in total, so {1..100000}/{1..100000} or repeated {a,b} groups can exhaust the isolate's memory or CPU in the GlobMatcher constructor (src/node/internal/internal_glob_pattern.ts:81)
View full review

Brace expansion has no total limit (src/node/internal/internal_glob_pattern.ts:81, :409)

  • kMaxSequenceLength caps each {a..b} sequence at 100,000 items, but expandBraces multiplies the alternatives of every brace group with no cap on the total.
  • {1..100000}/{1..100000} expands to 10^10 strings, and about 30 repetitions of {a,b} give about 10^9.
  • All of these are built eagerly in the GlobMatcher constructor (collected into a Set, then split and compiled). One path.matchesGlob call with such a pattern can block the isolate or run it out of memory. The pattern cache does not help, because the cost is paid when the matcher is built.
  • The brace-expansion library that minimatch uses caps its total output, so Node does not have this failure mode.
  • Fix: count results across the whole expandBraces call in minimatch mode and stop, or throw, once the count passes a limit such as 100,000.

📋 Code Quality: ⚠️ 1 warning

Reversed character-class ranges make matchesGlob throw a raw SyntaxError

Recommendation: 📝 Minor Comments

  • [WARNING] Reversed character-class ranges such as [z-a] make matchesGlob() throw a raw SyntaxError instead of returning false as Node does (src/node/internal/internal_glob_pattern.ts:227)
View full review

Reversed character-class ranges throw (src/node/internal/internal_glob_pattern.ts:227, :366)

  • In minimatch mode, the [...] body is copied into the regex source after escaping only [, ] and ^.
  • compilePart then passes that source to new RegExp(...). For a pattern such as [z-a] or foo/[9-0], V8 throws SyntaxError: Range out of order in character class.
  • The error comes out of the GlobMatcher constructor and reaches the caller of path.matchesGlob unhandled.
  • minimatch drops a reversed range while parsing the class, so in Node the class matches nothing and matchesGlob returns false.
  • Fix: skip reversed ranges when building the class body, or treat a part whose regex fails to compile as one that never matches. Add a test row such as ['a', '[z-a]', false].

📝 Documentation: 💬 1 info

Known differences from Node's matcher are not written down

Recommendation: 💬 Optional Nits

  • [INFO] The known differences from Node's matcher (POSIX classes, empty extglob alternatives, **/.. rewrite) are not documented (src/node/internal/internal_glob_pattern.ts:399)
View full review

src/node/README.md says that any difference from Node will be documented. The pull request description lists three known gaps: POSIX classes like [[:alpha:]], empty extglob alternatives like @(a|), and minimatch's rewrite of **/... They are not recorded next to the code.


✅ All other checks passed

📖 AGENTS.md: ✅ LGTM

No AGENTS.md concerns.


⚡ Performance: ✅ LGTM

No further performance issues. The missing limit on total brace expansion is described in the security section.


Reviewed commit: cb7b00cb

@littledivy
littledivy force-pushed the littledivy/2026-11-12-path-matches-glob branch from cb7b00c to 8b940e7 Compare November 12, 2026 11:49

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 23d357ec.

This review, of 8b940e75

💬 Approved with comments — Two WARNINGs remain from the last review: a reversed character-class range throws a SyntaxError where Node returns false, and brace expansion has no total limit. Neither makes the change unsafe to merge.

Findings: 2 warnings · 1 info (2 are inline comments on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8390.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Security] Brace expansion is capped per sequence but not in total. `{1..100000}/{1..100000}` or many repeated `{a,b}` groups can exhaust the isolate's memory or CPU in the GlobMatcher constructor.
- **File:** src/node/internal/internal_glob_pattern.ts:81

### [Code Quality] A reversed character-class range such as `[z-a]` makes matchesGlob() throw a raw SyntaxError. Node returns false for it.
- **File:** src/node/internal/internal_glob_pattern.ts:229

## INFO (1)

### [Documentation] The known differences from Node's matcher (POSIX classes, empty extglob alternatives, the `**/..` rewrite) are not documented next to the code.
- **File:** src/node/internal/internal_glob_pattern.ts:301

🔒 Security: ⚠️ 1 warning

Brace expansion is still unbounded in total, so one pattern can exhaust memory or CPU.

Recommendation: 📝 Minor Comments

  • [WARNING] Brace expansion is capped per sequence but not in total. {1..100000}/{1..100000} or many repeated {a,b} groups can exhaust the isolate's memory or CPU in the GlobMatcher constructor. (src/node/internal/internal_glob_pattern.ts:81)
View full review

Brace expansion has no total limit (src/node/internal/internal_glob_pattern.ts:81-89, :411)

  • kMaxSequenceLength caps each {a..b} sequence at 100,000 items, but expandBraces multiplies the alternatives of every brace group with no limit on the total.
  • {1..100000}/{1..100000} expands to 10^10 strings, and about 30 repeated {a,b} groups give about 10^9.
  • The GlobMatcher constructor builds all of them eagerly, first into a Set and then into compiled parts. One path.matchesGlob call can therefore block the isolate or run it out of memory. The pattern cache does not help, because the cost is paid while the matcher is built.
  • The brace-expansion library that minimatch uses caps its total output, so Node does not have this problem.
  • Fix: count results across the whole expansion in minimatch mode, and stop or throw once the count passes a limit such as 100,000.

📋 Code Quality: ⚠️ 1 warning

A reversed character-class range still makes matchesGlob() throw a raw SyntaxError.

Recommendation: 📝 Minor Comments

  • [WARNING] A reversed character-class range such as [z-a] makes matchesGlob() throw a raw SyntaxError. Node returns false for it. (src/node/internal/internal_glob_pattern.ts:229)
View full review

Reversed character-class ranges throw (src/node/internal/internal_glob_pattern.ts:229-230, :368)

  • In minimatch mode, the [...] body is copied into the regex source with only [, ], ^ and \ escaped. The - is not checked.
  • compilePart then passes that source to new RegExp(...). For [z-a] or foo/[9-0], V8 throws SyntaxError: Range out of order in character class.
  • The error escapes the GlobMatcher constructor and reaches the caller of path.matchesGlob. A matcher whose constructor threw is not cached, so every later call with that pattern throws again.
  • minimatch drops a reversed range, so in Node the class matches nothing and the call returns false.
  • Fix: drop reversed ranges when building the class body, or catch the RegExp error in compilePart and return a part that never matches. Add a test row such as ['a', '[z-a]', false].

📝 Documentation: 💬 1 info

The known differences from Node's matcher are still not documented.

Recommendation: 💬 Optional Nits

  • [INFO] The known differences from Node's matcher (POSIX classes, empty extglob alternatives, the **/.. rewrite) are not documented next to the code. (src/node/internal/internal_glob_pattern.ts:301)
View full review

The comment at src/node/internal/internal_glob_pattern.ts:301-303 lists the minimatch options the matcher follows. It does not list the known gaps from the pull request description: POSIX classes like [[:alpha:]], empty extglob alternatives like @(a|), and minimatch's rewrite of **/... src/node/README.md asks that differences from Node be documented.


✅ All other checks passed

📖 AGENTS.md: ✅ LGTM

No AGENTS.md concerns.


⚡ Performance: ✅ LGTM

No performance issues beyond the unbounded brace expansion described in the security section.


Reviewed commit: 8b940e75

@littledivy
littledivy force-pushed the littledivy/2026-11-12-path-matches-glob branch from 8b940e7 to 23d357e Compare November 12, 2026 11:52

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 84b17f54.

This review, of 23d357ec

✅ Approved — The earlier warnings (reversed class ranges throwing, and no total limit on brace expansion) are fixed, and the gaps from Node's matcher are now documented. No new issues were found.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

expandBraces stops at kMaxExpansions (100,000) in minimatch mode (src/node/internal/internal_glob_pattern.ts:89), and expandSequence is capped at the same number (:120). The cost of building a GlobMatcher is therefore bounded.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md concerns.


📋 Code Quality: ✅ LGTM

Reversed ranges such as [z-a] are now dropped (src/node/internal/internal_glob_pattern.ts:229-240), and an empty class compiles to (?!). New test rows cover this. Moving the helpers out of internal_fs_glob.ts doesn't change how fs.glob behaves.


⚡ Performance: ✅ LGTM

Brace expansion is now bounded. The pattern cache holds at most 250 entries per platform, and each lookup is O(1).


📝 Documentation: ✅ LGTM

The comment above GlobMatcher now lists POSIX classes, empty extglob alternatives and the **/.. rewrite as the known differences from minimatch.


Reviewed commit: 23d357ec

`node:path` `matchesGlob()` threw "not implemented" on both `path.posix` and `path.win32`, so code that filters paths with a glob couldn't run.

In this patch:

- `matchesGlob()` matches like Node's, which runs minimatch with `windowsPathsNoEscape`, `nonegate`, `nocomment` and `optimizationLevel: 2`, and caches the last 250 compiled patterns per platform. Instead of vendoring minimatch (about 2k lines), a small `GlobMatcher` reuses `fs.glob`'s brace and segment parsing. It adds minimatch's rules for dotfiles, absolute patterns, `.`/`..` parts, `{1..3}` sequences, a trailing `**` and Windows drives.
- The pattern helpers move unchanged from `internal_fs_glob.ts` to a new dependency-free `internal_glob_pattern.ts`, so `node:path` doesn't load the `node:fs` internals. The minimatch-only syntax sits behind a `minimatch` argument, so `fs.glob` behaves as before.
- A differential fuzz of 2M random path/pattern pairs against minimatch 10.2.6 (the version Node 26 vendors) found no mismatches outside three cases left out: POSIX classes like `[[:alpha:]]`, empty extglob alternatives like `@(a|)`, and minimatch's rewrite of `**/..`.

| | before | after |
|---|---|---|
| `path.matchesGlob('foo/bar/baz', 'foo/**')` | throws | `true` |
| `path.matchesGlob('foo/.git', 'foo/*')` | throws | `false` |
| `path.win32.matchesGlob('foo\\bar', 'foo/bar')` | throws | `true` |

The test table is upstream `test-path-glob.js` plus 36 cases for the rules above, each checked against Node.

No compatibility flag: both functions threw before, so no working code changes behaviour.
@littledivy
littledivy force-pushed the littledivy/2026-11-12-path-matches-glob branch from 23d357e to 84b17f5 Compare November 12, 2026 11:56

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved — No issues found. The brace-expansion caps, the class-range handling and the per-platform pattern cache in the changed internal_glob_pattern.ts all check out, and fs.glob behaves as before.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

  • In minimatch mode, expandBraces stops at kMaxExpansions (src/node/internal/internal_glob_pattern.ts:91) and expandSequence is capped at the same number (:122). Nested braces cannot multiply past this cap.
  • The character-class branch escapes [, ], ^ and \ (:238), so a pattern cannot inject regex syntax.
  • The pattern cache holds at most 250 entries per platform.

📖 AGENTS.md: ✅ LGTM

No AGENTS.md concerns.


📋 Code Quality: ✅ LGTM

  • Class bodies such as []], [a-cz-a], [!] and [a-b-c] all compile to valid regexes, and an empty class compiles to (?!).
  • fs.glob still calls segmentToRegexStr/expandBraces with minimatch set to its false default. The minimatch-only syntax applies only when that argument is true, so fs.glob behaves as before.
  • Each platform has its own pattern cache, so a pattern compiled for posix is never reused for win32.
  • The tests cover both platforms, the cache separation, reversed and empty classes, and argument validation.

⚡ Performance: ✅ LGTM

Brace expansion has an upper limit, and the pattern cache holds at most 250 entries per platform.


📝 Documentation: ✅ LGTM

No documentation issues.


Reviewed commit: 84b17f54

@jasnell
jasnell merged commit 096b672 into main Nov 12, 2026
36 of 38 checks passed
@jasnell
jasnell deleted the littledivy/2026-11-12-path-matches-glob branch November 12, 2026 15:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants