Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/matching.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Segments after a `**` match from the **end** of the path; the `**` takes what is

- Plain pattern: identity = the rewritten segment join (static keys via `segmentKey`, dynamic segments as written, suffix included), the same string `ctx.static` is keyed by. Spellings the tree can't distinguish remove each other (`/a/` ≡ `/a`, `\)` ≡ `)`, `/**.md` ≡ `/**/*.md`, `/café-:id` ≡ `/caf%C3%A9-:id`).
- Identities are compared canonically (`routeId`: each segment through `dynamicKey`, which percent-encodes a dynamic segment's literal text like `getParamRegexp`, outside constraints, `?{}` kept as syntax, and is a no-op on a static key), in `removeRoute` and `findOverlappingRoutes`' dedupe, so both spellings alias; a constraint is regex and stays distinct (`:x(é)` vs `:x(%C3%A9)`). Escapes are not canonicalized (`/:x-a` vs `/:x-\a` stay distinct): a missed alias, never a wrong one. The canonical form is computed where identities are compared, not stamped by `addRoute`, so the core bundle (routers that never remove) doesn't carry it.
- Expanding pattern (groups, modifiers): every entry gets the pre-expansion text normalized by `expandedRouteId()` (static segments via `segmentKey`), so the `/admin` entry of `/admin/:page?` never collides with a separately registered `/admin`. A group that expands to a single route (`/a/*-{:x}?` is `/a/*-:x?`, `/a{b}` is `/ab`) is that route: it takes the rewritten route's identity (both `_add` and `_removeRoute` skip `expandedRouteId` there). `expandGroupDelimiters` returns that rewrite alone, also next to another group, so the next group is expanded from the rewritten text: its identity is `expandedRouteId` of `/*-:x?/b{.json}?` for `/*-{:x}?/b{.json}?` too, and `skipGroup` renumbers the right group (`/a/*{:x}?/b{/(\d+)}?/*` on `/a/q/b/z` is `{0:"q", 2:"z"}`, as in URLPattern).
- Expanding pattern (groups, modifiers): every entry gets the pre-expansion text normalized by `expandedRouteId()` (static segments via `segmentKey`), so the `/admin` entry of `/admin/:page?` never collides with a separately registered `/admin`. A group that expands to a single route (`/a/*-{:x}?` is `/a/*-:x?`, `/a{b}` is `/ab`) is that route: it takes the rewritten route's identity (both `_add` and `_removeRoute` skip `expandedRouteId` there). `expandGroupDelimiters` returns that rewrite alone, also next to another group, so the next group is expanded from the rewritten text: its identity is `expandedRouteId` of `/*-:x?/b{.json}?` for `/*-{:x}?/b{.json}?` too, and `skipGroup` renumbers the right group (`/a/*{:x}?/b{/(\d+)}?/*` on `/a/q/b/z` is `{0:"q", 2:"z"}`, as in URLPattern). A pattern starting with a group (no `/` in front, see [syntax.md](syntax.md#leading-)) is read after a `/` (the split drops a path's first piece) and marked with a leading `{`: read after a `/`, `{a}?/b` is the text of `/{a}?/b`, and both register `/a/b`. A malformed `{…` removes nothing.
- All entries with that identity go (duplicates together). An emptied static node deletes its `ctx.static` key via the join accumulated during the walk (no value scan).
- Removal is by registered pattern: `/x/*` does not remove `/x/:id`; `:id(\d+)` and `:x(\d+)` are distinct.
- Suffix routes: `_removeSuffix` walks back from the last segment, prunes empty trie nodes, then `wildcard.suffix`, then the wildcard (`_isEmptyNode` counts `suffix`).
Expand Down
4 changes: 2 additions & 2 deletions .agents/regexp.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A path matches iff the body matches it with one trailing `/` stripped. The gener

### Optional group inlining (`inlineOptionalGroup`)

The tree expands `{…}?` into two routes, but `routeToRegExp` inlines a single optional group as `(?:…)?` to avoid repeating named groups across alternation branches (PCRE2 and Node 22 reject duplicates). The group must end a segment (or start one, see below); both expansions (`routeToRegExpSegments`) must line up as shared head + one differing segment (or added whole segments) + shared tail; with a tail, the head must pass `isFixedSegment()`. When the base segment ends in its only capture, `mergeCapture()` makes it split like the router, whose extended route wins where it matches: a lazy `:name` is emitted as `(?<x>[^/]+?)(?:rest)?` (shortest first with the group before without it finds the router's split, `archive.tar.gz` → `archive` + `tar.gz`). A greedy `*` or a constraint gets a look-ahead instead, unless a `\d`/`\w` run can't take the group's first char. Look-ahead forms are RE2-incompatible and not reversible (`LOOKAHEAD_ROUTES`). An appended part after other captures is inlined only where `appendsCleanly` holds: every capture before it is a lazy `:name` (`/f/:x.a{.a}?/m`), the segment and its extension can't end in the same char (`/*-x{.png}?`), or every capture before it can't match the literal char right after it (`/:id(\d+)-x{.png}?`, `/img/:w(\d+)x:h(\d+){.png}?`), so it splits one way. A group that starts its segment before more of it (`/{:x}?(\d+)`, `inSegment`) is inlined as `(?:X)?rest` where the full segment is `X` + the base one and `X` compiles alone (`isRegExpSource`), with a fixed head: `(?:X)?C` tries `XC`, then `C`, the router's order (with equal weights the route with the group, registered first, wins); `regExpToRoute` reads the rest of the segment after such a unit as part of a segment (`reverseSegment(…, part)`: a `(.+)` is no `:_0+`), and throws where another in-segment optional unit follows it (`/{:x}?(.+)-:y?`: a `{:y}?` would route otherwise than the in-place `-:y?`). Falls back to alternation for multi-group routes, non-aligning expansions (an in-segment group followed by optional segments, `/:x{.:e}?/:y?`), a mid-segment optional group after other captures otherwise (`/media/*{.webp}?`, `/*-x{-x}?`), and router-order expansion shapes.
The tree expands `{…}?` into two routes, but `routeToRegExp` inlines a single optional group as `(?:…)?` to avoid repeating named groups across alternation branches (PCRE2 and Node 22 reject duplicates). The group must end a segment (or start one, see below); a leading group's expansions get the `/` `expandGroupDelimiters` gives them (`{a}?/b` is `(?:\/a)?\/b`), and one with an empty base (`{/:a}?`) falls back; both expansions (`routeToRegExpSegments`) must line up as shared head + one differing segment (or added whole segments) + shared tail; with a tail, the head must pass `isFixedSegment()`. When the base segment ends in its only capture, `mergeCapture()` makes it split like the router, whose extended route wins where it matches: a lazy `:name` is emitted as `(?<x>[^/]+?)(?:rest)?` (shortest first with the group before without it finds the router's split, `archive.tar.gz` → `archive` + `tar.gz`). A greedy `*` or a constraint gets a look-ahead instead, unless a `\d`/`\w` run can't take the group's first char. Look-ahead forms are RE2-incompatible and not reversible (`LOOKAHEAD_ROUTES`). An appended part after other captures is inlined only where `appendsCleanly` holds: every capture before it is a lazy `:name` (`/f/:x.a{.a}?/m`), the segment and its extension can't end in the same char (`/*-x{.png}?`), or every capture before it can't match the literal char right after it (`/:id(\d+)-x{.png}?`, `/img/:w(\d+)x:h(\d+){.png}?`), so it splits one way. A group that starts its segment before more of it (`/{:x}?(\d+)`, `inSegment`) is inlined as `(?:X)?rest` where the full segment is `X` + the base one and `X` compiles alone (`isRegExpSource`), with a fixed head: `(?:X)?C` tries `XC`, then `C`, the router's order (with equal weights the route with the group, registered first, wins); `regExpToRoute` reads the rest of the segment after such a unit as part of a segment (`reverseSegment(…, part)`: a `(.+)` is no `:_0+`), and throws where another in-segment optional unit follows it (`/{:x}?(.+)-:y?`: a `{:y}?` would route otherwise than the in-place `-:y?`). Falls back to alternation for multi-group routes, non-aligning expansions (an in-segment group followed by optional segments, `/:x{.:e}?/:y?`), a mid-segment optional group after other captures otherwise (`/media/*{.webp}?`, `/*-x{-x}?`), and router-order expansion shapes.

### Duplicate names

Expand All @@ -57,7 +57,7 @@ Inverse of `routeToRegExp`: parses an anchored, PCRE-compatible regex (or source
- **Endings** are normalized structurally, exact shapes only (`ROOT_REPEAT`, `plainBody()` for closed endings, `TRAILING_CATCH_ALL`, `TRAILING_DOT`), then the look-behind suffix, the legacy two-slash suffix or a plain `\/?` is stripped. No generic `.*?` rewrite, so lazy quantifiers inside user constraints survive.
- **Body walk** recognizes `\/` separators, optional units `(?:…)?` / `(?:…)??`, nested optionals, catch-alls (an unnamed `(?<_N>[\s\S]*)` → `**`, greedy or lazy; for a group named `_`, how 0.11 and older emitted `**`: greedy `(?:\/(?<_>[\s\S]*))?` → `**`, a lazy group with a lazy body → `**`, with a greedy body → `{/**}?` (merged; `:_*` where no group can be)), `\/(?<x>[\s\S]+)` → `:x+`, root forms, `NESTED_CATCH_ALL`: `:x*` then `*` (`[\s\S]+`; `[\s\S]*` in 0.11, and 0.10's `**` / `:x*` then `:y?`)). `.*` / `.+` read as catch-alls (legacy output), unless the regex has a lazy user-`.` ending.
- **Segments:** `(?<x>[^/]+)`, `[^/]+?` (in a mixed segment) / legacy `[^/]*` → `:x`; `\/(?<x>[\s\S]+)` → `:x+` (legacy `[\s\S]*` too), in an optional unit `:x*` (same route as `{/:x+}?`; 0.11's empty-capable `[\s\S]*` one too, which now needs a value); the closed `**:x` ending `(?:\/\/|(?<x>…)\/?)` → `(?<x>[\s\S]+)` (`REQUIRED_VALUE`, the 0.10 `(?:\/|…)` one → `[\s\S]*`); an in-segment optional lone param comes back as `pre-:x?` (`mergeGroup`); unnamed `[^/]*` → `*`; `(pat)` → `(pat)`; `(?<x>pat)` → `:x(pat)`; route-syntax literals re-escaped; a word char or non-ASCII char after a bare `:name` is escaped (`:x\abc`, `:x\é`; a `-` ends a name, so it stays bare); a group after a bare `:name` gives the name its body without a `/` (`(?<x>[^/]+?)(?<_0>\d+)` → `:x([^\x2f]+?)(\d+)`, which `getParamRegexp` emits back as `[^/]+?`: the regex for `{:x}(\d+)`, see `joinGroup`); a constraint body holding a capturing group throws, and so does a `*` right after a `*` (would read as `**`): `addRoute` rejects both. Optional units classify by inner shape into `:x?` / `:x*` / `*` / merged `{…}?` groups. Equivalent outputs come back in one spelling (`/a{/:x+}?` → `/a/:x*`, `/a{/:x+}?/b` → `/a/:x*/b`, `/a{/**}?` → `/a/**`, and so does `/a{/([\s\S]*)}?`, an over-matching constraint with the same regex).
- **Unnamed captures** (`(?<_N>…)`) are told apart by the raw group name (`matchNamedGroup`'s `unnamed`, `UNNAMED`), never the decoded one: a param `:_0` is emitted escaped (`__rou3_esc___0`) and decodes to the same `_0`. An optional one stays unnamed: `(?:\/(?<_0>pat))?` → `{/(pat)}?` on the previous segment (`:_0(pat)?` would be a param keyed `_0`, not `0`; with no previous segment, inside a group (`{…}` can't nest), or a body with no constraint form like `[^/]+`, it throws). A `[^/]*` is a bare `*` only where that is optional (ending the route, or with the next optionals nested in its group), else `{/*}?` (`/a{/*}?/b`).
- **Unnamed captures** (`(?<_N>…)`) are told apart by the raw group name (`matchNamedGroup`'s `unnamed`, `UNNAMED`), never the decoded one: a param `:_0` is emitted escaped (`__rou3_esc___0`) and decodes to the same `_0`. An optional one stays unnamed: `(?:\/(?<_0>pat))?` → `{/(pat)}?` on the previous segment, or starting the route with none (`{/(pat)}?/b`, absolute, see [syntax.md](syntax.md#leading-)) (`:_0(pat)?` would be a param keyed `_0`, not `0`; inside a group (`{…}` can't nest), or a body with no constraint form like `[^/]+`, it throws). Other root optionals of whole segments with nothing to merge onto lead the route the same way (`^(?:\/a)?\/b` → `{/a}?/b`); a root in-segment one (`^(?:foo)?`), text after a leading group (`^(?:\/a)?(?:b)?\/c`) and a group in a group (`^(?:\/a(?:\/b)?)?\/c`, also after a segment) throw: `addRoute` rejects those routes. A `[^/]*` is a bare `*` only where that is optional (ending the route, or with the next optionals nested in its group), else `{/*}?` (`/a{/*}?/b`).
- **Percent-encoding:** `%XX` comes back as written (`/caf%C3%A9`, never decoded: `%2F`, `%25` would change the route), and `reverseSegment`'s `literal` throws on a char (read by code point) `encodeLiteral` would change (`é`, space, `\{`, `\?`, `\^`) or a U+FFFD-U+FFFF placeholder, naming its encoded form: route text is encoded, so no route has it (see [syntax.md](syntax.md#percent-encoding)).
- **Reject by default:** `reverseSegment()` is a whitelist; look-arounds and other `(?…)` constructs, backreferences / metaclass escapes outside a constraint, bare regex operators, constraint bodies with `/`, flags `i`/`m`/`s`/`u`/`v` (`g`/`y`/`d` ignored), unanchored input, and group names that decode to no valid param name all throw. Constraint bodies are opaque and kept verbatim.
- **Legacy inputs** (older look-behind, pre-trailing-slash-change two-slash, 0.9.x `\/?` endings with `.*` / `.+` catch-alls, 0.10's closed endings for an empty-capable `:x` / `**:x`, 0.11's empty-capable `:x*` forms and `ROOT_REPEAT`) are accepted and read as the route they were emitted for, which may now match fewer paths; pinned in `regexp-to-route.test.ts`.
Expand Down
Loading
Loading