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/compiler.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Pinned in `test/compiler.test.ts` and `test/types.test-d.ts`.
- **Method keys** are `JSON.stringify`-ed (user input; raw quotes break JIT and inject code in AOT).
- **Data slots:** JIT passes them as parameters `$N` (faster than array reads) up to `DATA_ARGS_MAX` (32,000), then recompiles with one array argument `$[N]` (engine argument limits). `serializeData()` dedupes via `ctx.dataMap`; regexes dedupe separately via `ctx.regexpMap` (a regex must not collide with an equal-looking string) and always live in slots (an inline literal allocates per evaluation).
- **Wildcard tails** with an all-static prefix → `p.slice(K)`; else `s.slice(i).join('/')`. Valid because the prologue keeps every segment of `p`.
- **Values:** a `:name` / `**:name` (also `:name+` / `:name*`) needs one (see [matching.md](matching.md#empty-segments-and-normalization)): `nonEmptyGuard()` adds `s[i]` (truthy: not `""`) per `:name`, and `(l>c+n+1||s[c])` per `**:name` (two segments or more, or one that is not empty; `n` segments after it). A `*` (`empty`) and a bare `**` get none. A `:name`'s guard is counted in `guardConditions`, not the weight, so the emit order doesn't change; a catch-all's counts, so a `**:name` outweighs a `*` on their node (see [matching.md](matching.md#same-node-siblings)).
- **Values:** a `:name` / `**:name` (also `:name+` / `:name*`) needs one in each segment (see [matching.md](matching.md#empty-segments-and-normalization)): `nonEmptyGuard()` adds `s[i]` (truthy: not `""`) per `:name`, and `$V(s,c,l-n)` per `**:name` (`VALUES`, a helper in a data slot like `RANK`, `helperRef`: a plain loop that `s[c]` to `s[l-n-1]` are non-empty; `n` segments after it). Only a lookup that reaches a `**:name` matcher pays it; measured faster than `Array#lastIndexOf("")` or a per-lookup `p.includes("//")` flag. A `*` (`empty`) and a bare `**` get none. A `:name`'s guard is counted in `guardConditions`, not the weight, so the emit order doesn't change; a catch-all's counts, so a `**:name` outweighs a `*` on their node (see [matching.md](matching.md#same-node-siblings)).
- **Bare `**` over zero segments** is unset (see [matching.md](matching.md#unnamed-captures)): `compileFinalMatch` emits `l>c?{…,params:{…,"N":_w=tail,_:_w}}:{…,params:{…}}` (`_` is the deprecated alias; `_w` is declared once with the regex temps when `ctx.starStarTemp`), with the `suffixGuard` (`l>c+j`) as the condition in a suffix trie. The only matchers whose result object is a ternary.
- **Regex params:** `scanRegExpGroups()` resolves group names at compile time → direct `.groups.<name>` reads with one `exec` into a `_mN` temp (declared via `ctx.regexTemps`). A whole-segment `^(?<name>…)$` uses `.test()` + `params:{name:seg}`. An in-place optional param (its name flagged by `getParamRegexp`, `paramsMap` entry's fifth element) is spread in only when set, `...(_m0.groups.x!==void 0&&{x:…})`, so an absent one has no key, as in the interpreter. Unparseable names fall back to exec + spread + runtime `_normalizeGroups`.
- **A `*` inside a segment** (see [matching.md](matching.md#greedy-)): its pieces (the `pre*` / `*post` regex groups and the `join` `**`'s tail) are one property, placed where the first piece is (`\0` in `paramsCode`) and filled after the loop: `pre+(nonEmpty?"/"+tail:"")+"/"+post`, the `**`'s only where it has a segment (`l>c`, or the `suffixGuard`).
Expand Down
8 changes: 5 additions & 3 deletions .agents/matching.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,9 @@ Least → most specific; interpreter and compiled matchAll agree exactly (`toEqu

A3 can't be fixed by weights; a real fix is a global re-sort against `compareRoutes` (major design change).

Swept by "lists a containing route before a contained one (sweep)" in `find-all.test.ts` (`*` included, both registration orders, compiled JIT/AOT and `findRoute` too): a pattern-level miss passes only as a carve-out where no matched entry of the broader pattern is itself strictly broader than one of the narrower listed before it, and every carve-out there is A1 (an entry of the narrower pattern listed before one of the broader with the same match set). Blind spot: `compareRoutes` says `partial` for in-place optionals (`:a:b?`) and constraints that take any non-empty segment (`(.+)`), so the sweep can't see their order. It uses one method: the `""`-first tie rule would break its both-orders reading with mixed methods.
**Carve-out B (known, do not "fix"):** every segment of a `**:name` (`:x+`, `:x*`) needs a value, so a route with a `:name` and a `*` / `**` over its segments contains it (`/p/:x/**` ⊋ `/p/:x+`, `/**/:y/p` ⊋ `/**:n/p`, `/:a/**/p` ⊋ `/**:n/p`: the broader one also takes the paths with an empty segment there). The traversal lists a node's wildcard before its param child, and a suffix trie's shallower entry first (`collectSuffix`, ties in `rankFromEnd`), so the narrower route comes first and `findRoute` picks the broader one. Pinned in `find-all.test.ts` ("catch-all carve-out (B)") and README; the same fix as A3. It is the price of URLPattern's `:x+`: with empty segments inside the value (before 0.12) the two were incomparable.

Swept by "lists a containing route before a contained one (sweep)" in `find-all.test.ts` (`*` included, both registration orders, compiled JIT/AOT and `findRoute` too): a pattern-level miss passes only as a carve-out where no matched entry of the broader pattern is itself strictly broader than one of the narrower listed before it, and every carve-out there is A1 (an entry of the narrower pattern listed before one of the broader with the same match set), or where each such pair is B (`catchAllFirst`: the narrower entry's `**:name`, a `:name` of the broader one from where it starts and a bare catch-all; `suffix.test.ts`' sweep reads the same on patterns). Blind spot: `compareRoutes` says `partial` for in-place optionals (`:a:b?`) and constraints that take any non-empty segment (`(.+)`), so the sweep can't see their order. It uses one method: the `""`-first tie rule would break its both-orders reading with mixed methods.

## Greedy `*`

Expand All @@ -55,7 +57,7 @@ A `*` is URLPattern's `*`, a greedy `(.*)` after its `/`: a catch-all. One per r

## Segments after a catch-all

Segments after a `**` (or a `*`) match from the **end** of the path; the catch-all takes what is between (≥ 0 segments for `**`, ≥ 1 for `*`, ≥ 1 with a value for `**:name`). Mid-route `:x+` / `:x*` become `**:x` and keep the segments after them.
Segments after a `**` (or a `*`) match from the **end** of the path; the catch-all takes what is between (≥ 0 segments for `**`, ≥ 1 for `*`, ≥ 1 for `**:name`, each with a value). Mid-route `:x+` / `:x*` become `**:x` and keep the segments after them.

- **Syntax:** one catch-all per route (`*`, `**`, `:x+`, `:x*`); `_add` throws `rou3: a route can have only one ...` quoting the input as written (threaded through expansion as `input`).
- **Params:** `MethodData.suffix = [wildcard index w, suffix length n]`; a param at route index `k` after the `**` maps to `index - w - 1 + (n - k)` at match time (`getMatchParams`, `collectSuffix`, compiled `s[l-j]`). A bare `**` between them over zero segments is unset (see [Unnamed captures](#unnamed-captures)).
Expand All @@ -78,7 +80,7 @@ Segments after a `**` (or a `*`) match from the **end** of the path; the catch-a

- **Pattern** trailing empties: `splitRoute()` pops all of them (`/a//` ≡ `/a/` ≡ `/a`).
- **Lookup** paths: at most **one** trailing `/` is ignored and `splitPath` keeps every other segment, so `/a//` has an empty last segment that only a `*`, `**` or a constraint takes (`0: ""`). Do not add a pop to `splitPath` or the compiled prologue; the regexp and compiler rely on this rule.
- **`:name` / `**:name` need a value** (URLPattern): `emptyParam()` (`operations/_utils.ts`) rejects an entry that gives a `:name` an empty segment or a `**:name` an empty value (exactly one empty segment; `/a///` gives `/`). It tells them apart in `paramsMap`: a `*` is digit-named (no param name starts with a digit), a constraint is a RegExp and decides itself (`:id(\d*)` takes `""`, as in URLPattern), a bare `**` is `optional`. `:name+`, `:name*`, `:name?` and `{/:x}?` follow from their expansions: `:x+` is `**:x`, `:x*` is `**:x` plus the route without it (`{/:x+}?`), so on `/a//` a `/a/:x*` falls through like a `/a/:x+` (URLPattern: no match), and still matches `/a`. Empty segments *inside* a longer value stay (`/a/:x*` on `/a//b` is `x: "/b"`, URLPattern rejects it; README differences).
- **`:name` / `**:name` need a value, in every segment** (URLPattern's `:x+` is `[^/]+(?:/[^/]+)*`): `emptyParam()` (`operations/_utils.ts`) rejects an entry that gives a `:name` an empty segment, or a `**:name` an empty one anywhere in its value (it reads the value `getMatchParams` gives: `""`, or a leading, trailing or doubled `/`), at the end of the route and before more of it (a suffix route). It tells them apart in `paramsMap`: a `*` and a bare `**` are digit-named (no param name starts with a digit), a constraint is a RegExp and decides itself (`:id(\d*)` takes `""`, as in URLPattern). `:name+`, `:name*`, `:name?` and `{/:x}?` follow from their expansions: `:x+` is `**:x`, `:x*` is `**:x` plus the route without it (`{/:x+}?`), so on `/a//` or `/a/b//c` a `/a/:x*` falls through like a `/a/:x+` (URLPattern: no match), and still matches `/a`. A user-written `**:name` is the same entry as `:name+`, so it follows the same rule (its docs say it needs a value; one rule, no second flag). One ignored trailing slash still applies: `/a/:x+` on `/a/b/` is `x: "b"`. With it, `/p/:x/**` ⊋ `/p/:x+` (carve-out B above).
- Interpreter: `findRoute` sends paths with an empty segment (`segments.includes("")`, rare) through `_findRanked` (`find-all.ts`: `findAllRoutes`' walk, filtered by `emptyParam`, ranked from the end when a suffix route is among them), whose last match is `_lookupTree`'s pick (same traversal, weights and ties), so `_lookupTree` / `_selectMatcher` / `collectSuffix` never check. Paths without one pay a single `includes("")`; paths with one take this slower path (~2× in `findRoute`: it collects every match, so its cost is bounded by the matches found).
- Compiler: see [compiler.md](compiler.md#codegen-invariants). Pinned by the "empty segments (compiled parity, sweep)" in `find.test.ts`.
- **Middle** empties are real static `""` segments: `/a//b` matches only the doubled-slash path. Never collapse them (normalization-mismatch bypass).
Expand Down
4 changes: 2 additions & 2 deletions .agents/overlap.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Both features are tree-shakeable and never touch the core bundle.

Files: `src/_overlap.ts` (shape model), `src/_subsume.ts` (subsumption, canonicalization), `src/operations/overlap.ts` (public API, tree traversal).

- **Shape** (`RouteShape`): fixed single-segment matchers (`string` literal | `RegExp` | `NON_EMPTY` for a `:name`, which needs a value; `undefined` = any is only a tail position) + a tail length range `[tailMin, tailMax]` (`**` and a trailing `*` → `[0,∞]`, a `*` elsewhere / `**:name` / `:x+` → `[1,∞]`, none → `[0,0]`; the tail constrains count only, except `some`: a `**:name`'s one-segment tail can't be `""`, a `*`'s can) + `suffix`: matchers aligned to the path **end** for segments after a catch-all. A trailing `*` is optional (see [matching.md](matching.md#greedy-)), so `/a/*` and `/a/**` have one shape. With a suffix or a `some` tail, overlap/subsumption check each path length position by position (`matcherAt`, which gives the `some` tail's only segment `NON_EMPTY`) up to `stableLength` (max fixed + max suffix, + 2 with `some`), which stands for all longer lengths.
- **Shape** (`RouteShape`): fixed single-segment matchers (`string` literal | `RegExp` | `NON_EMPTY` for a `:name`, which needs a value; `undefined` = any is only a tail position) + a tail length range `[tailMin, tailMax]` (`**` and a trailing `*` → `[0,∞]`, a `*` elsewhere / `**:name` / `:x+` → `[1,∞]`, none → `[0,0]`; the tail constrains count only, except `some`: no segment of a `**:name`'s tail can be `""`, a `*`'s can) + `suffix`: matchers aligned to the path **end** for segments after a catch-all. A trailing `*` is optional (see [matching.md](matching.md#greedy-)), so `/a/*` and `/a/**` have one shape. With a suffix or a `some` tail, overlap/subsumption check each path length position by position (`matcherAt`, which gives each segment of a `some` tail `NON_EMPTY`) up to `stableLength` (max fixed + max suffix, + 1 with `some`: one position in both tails, which longer lengths only repeat), which stands for all longer lengths. So `/a/**:x` ⊊ `/a/**`, `/a/:y+` ⊊ `/a/:x/**` and `/**:n/p` ⊊ `/**/:y/p` (ordering carve-out B, [matching.md](matching.md#findallroutes-ordering-public-contract)), and `/a/**:x` vs `/a/b/**` is `partial` (`/a/b//`).
- Shapes come from tree entries (`shapeOf`, kind-tagged edges so an escaped static `\*` stays distinct from a param), cached per entry in a `WeakMap`. Query patterns go through the real `addRoute` on a throwaway router (`routeToShapes`, memoized per string, cleared at 1024 entries; returned shapes are immutable). A multi-expansion pattern has several shapes; patterns overlap when any pair does.
- **Canonicalization:** shapes with identical fixed prefixes (`_segmentEqual`, strict identity) and contiguous ranges merge (`mergeShapes`; suffixes must be identical; `some` survives only if both ranges' one-segment tails need a value or don't exist). So `/a/:x*` == `/a{/**:y}?` ⊊ `/a/**` == `/a/*` == `/a{/*}?`, and `/a/:x?` ⊊ `/a/*`. Known precision loss: a `NON_EMPTY` `:x` doesn't fold into a tail, so `compareRoutes("/:q*/:x", "/**/b")` is `partial` (true: `superset`); and an in-place optional param is one regex, compared by source only, so `compareRoutes("/a/*-:x?", "/a/*-:x")` is `partial` (true: `superset`) and `("/a/:a:b?", "/a/:id")` is `subset` (true: `equal`). Weaker verdicts, never wrong ones.
- **Canonicalization:** shapes with identical fixed prefixes (`_segmentEqual`, strict identity) and contiguous ranges merge (`mergeShapes`; suffixes must be identical; `some` survives only if both tails need a value in each segment or don't exist). So `/a/:x*` == `/a{/**:y}?` ⊊ `/a/**` == `/a/*` == `/a{/*}?`, and `/a/:x?` ⊊ `/a/*`. Known precision loss: a `NON_EMPTY` `:x` doesn't fold into a tail, so `compareRoutes("/:q*/:x", "/:y+")` is `subset` (true: `equal`, each a segment or more with a value); and an in-place optional param is one regex, compared by source only, so `compareRoutes("/a/*-:x?", "/a/*-:x")` is `partial` (true: `superset`) and `("/a/:a:b?", "/a/:id")` is `subset` (true: `equal`). Weaker verdicts, never wrong ones.
- **Overlap** = some concrete path matches both. Static/static and static/regex are exact; any-vs-anything and regex/regex over-approximate to overlap.
- **`compareRoutes(a, b)`** → `disjoint` | `equal` | `superset` (a ⊇ b) | `subset` | `partial`, named after ES2025 Set methods. `shapeSubsumes()`: b's length range inside a's + per-position containment (any ⊇ all; literals by equality; regex ⊇ literal via `test()`; `NON_EMPTY` ⊇ a regex that can't match `""`; regex ⊇ regex only by source equality modulo group names, `_regExpKey`) + a's fixed positions under b's tail must be any. Pattern containment is proven shape by shape (sufficient, not necessary; union coverage degrades to `partial`). **Containment claims are proofs; undecidable cases degrade to a weaker verdict, never a wrong claim.** Inherent: strictness is best-effort (`/u/:id(42)` vs `/u/42`), and `partial` may be disjoint for regex pairs.
- **`findOverlappingRoutes`** traverses in `findAllRoutes` order (wildcard, param, static, self; suffix tries after bare `**` entries, unpruned), prunes unreachable static subtrees, reports `""` entries then the method's, and dedupes per registration identity + bucket + data (`Map<data, Set<route>>`): a route's expansions collapse, distinct routes sharing data are all reported. The same route registered twice with the same data is reported once. Matches carry `data` only.
Expand Down
Loading
Loading