test(shared): pin createPathMatcher contract surface

[jacekradko]

Summary

Adds regression-proofing tests for createPathMatcher / normalizePath / MalformedURLError. This is a pure test-coverage hardening, no functional code changes.

The matcher is security-load-bearing (powers clerkMiddleware's public/protected route checks) and several of its current behaviors are easy to flip silently in a refactor. Pinning them with explicit tests makes any future change to the contract deliberate.

What's pinned

• No dot-segment resolution — createPathMatcher does not resolve ... Callers (frameworks built on the WHATWG URL parser) handle this upstream.
• Single-decode only — decodeURI is called exactly once. %2561dmin decodes to %61dmin, not admin.
• UTF-8 multi-byte decoding — multi-byte sequences and surrogate pairs round-trip cleanly.
• Backslash stays literal — %5C decodes to \, not /. Aliasing is the URL parser's job.
• MalformedURLError shape — name, statusCode, cause, instanceof Error.
• isMalformedURLError contract — name-based detection for cross-bundle compatibility, with negative cases.

Test plan

• pnpm test pathMatcher — 34/34 pass (was 25, +9)
• No production code changes
• Empty changeset (test-only, no published-package effect)

[changeset-bot]

🦋 Changeset detected

Latest commit: 8c2cd34

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Apr 28, 2026 10:49pm

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8416

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8416

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8416

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8416

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8416

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8416

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8416

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8416

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8416

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8416

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8416

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8416

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8416

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8416

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8416

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8416

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8416

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8416

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8416

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8416

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8416

commit: 8c2cd34

[coderabbitai]

📝 Walkthrough

Walkthrough

A new changeset file is added with empty YAML front-matter to document changes. The test suite for pathMatcher is expanded with comprehensive test coverage for URL decoding semantics and edge cases in createPathMatcher/normalizePath, including tests for dot-segment preservation, single-pass percent-decoding, UTF-8 multi-byte character handling, and backslash character decoding. Additional tests pin the externally observable contract of MalformedURLError by verifying its error inheritance, properties, and detection mechanism.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'test(shared): pin createPathMatcher contract surface' accurately describes the main change: adding tests to pin the contract surface of createPathMatcher and related functions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description accurately describes the changeset: adding regression-proofing tests for createPathMatcher/normalizePath/MalformedURLError with specific behaviors being pinned, no production code changes, and an empty changeset file.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}