You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 76751fc
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .agents/compiler.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ Pinned in `test/compiler.test.ts` and `test/types.test-d.ts`.
21
21
-**Wildcard tails** with an all-static prefix β `p.slice(K)`; else `s.slice(i).join('/')`. Valid because the prologue keeps every segment of `p`.
22
22
-**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 guard: counted in `guardConditions`, not the weight, so the emit order doesn't change.
23
23
-**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.
24
-
-**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 (source ending `))?$`, the last group name) 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`.
24
+
-**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`.
25
25
-**matchAll** accumulates with `r.push` and one `return r.reverse()`; ordering rules in [matching.md](matching.md#findallroutes-ordering-public-contract).
26
26
- Routers without suffix routes, and without a node holding both `""` and method entries, must compile byte-identically (snapshots).
Lookup priority: static > param > wildcard, except on paths a suffix route matches (below).
11
11
12
-
**Results** are fresh `{ data, params? }` objects, never the stored `MethodData` (one shared object per route). Static matches and `params: false` have no `params` key; interpreter params are null-proto. An absent optional param has no key, also an in-place one (`*-:x?`: its group is unset, `getMatchParams` skips `undefined`). `addRoute` stores `data ?? null`, so falsy data round-trips.
12
+
**Results** are fresh `{ data, params? }` objects, never the stored `MethodData` (one shared object per route). Static matches and `params: false` have no `params` key; interpreter params are null-proto. An absent optional param (`:x?`, `:x*`, `{β¦}?`) has no key (the expansion without it matched), nor does an absent in-place one (`*-:x?`: its group is unset, `getMatchParams` skips `undefined`). Not so a trailing optional `*` that takes no segment: its key stays, `undefined` (`/a/*` on `/a` gives `{"0": undefined}`), and a bare `**` gives `_: ""`. `addRoute` stores `data ?? null`, so falsy data round-trips.
13
13
14
14
Guard `index < segments.length` before any `node.static[...]` lookup: `undefined` must never coerce to the key `"undefined"`.
15
15
@@ -55,16 +55,17 @@ Segments after a `**` match from the **end** of the path; the `**` takes what is
55
55
56
56
-**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`). `splitRoute()` rewrites a `**<rest>` segment (rest not starting with `:`, `{`, `}`) into `**` + `*<rest>`, so `/**.md` β‘ `/**/*.md` everywhere. A `*` after `**` is required.
57
57
-**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)).
58
-
-**Ranking** (`rankFromEnd`, `operations/_suffix.ts`): when a suffix route matches (`hasSuffixMatch`, pruned by `hasSuffix`), `findRoute` collects all matches (`_findAll(β¦, reverse = true)`) and stable-sorts comparing from the last segment backwards: literal 3 > regex param 2 > plain param or `**`-covered 0 (a plain param must be 0, or `/**/:y` beats the narrower `/b/**`). `kindAt` returns a covered segment as `~start` of its `**`, so comparisons jump over ranges both `**` cover (cost β segments around the `**`, not path length). Ties keep tree order; `reverse` makes the last match the first-registered. `findAllRoutes` applies the same sort when a suffix route is among its matches. Paths no suffix route matches are untouched. Known (README): the from-end ranking also applies between non-suffix routes on those paths. Pinned by the `suffix.test.ts` sweep "never picks a strictly broader route".
58
+
-**Ranking** (`rankFromEnd`, `operations/_suffix.ts`): when a suffix route matches (`hasSuffixMatch`, pruned by `hasSuffix`), `findRoute` collects all matches (`_findAll(β¦, reverse = true)`) and stable-sorts comparing from the last segment backwards: literal 3 > regex param 2 > plain param or `**`-covered 0 (a plain param must be 0, or `/**/:y` beats the narrower `/b/**`; so must a regex that restricts no more, `paramsMap`'s `plain`: `:a:b?`, `*:x?`). `kindAt` returns a covered segment as `~start` of its `**`, so comparisons jump over ranges both `**` cover (cost β segments around the `**`, not path length). Ties keep tree order; `reverse` makes the last match the first-registered. `findAllRoutes` applies the same sort when a suffix route is among its matches. Paths no suffix route matches are untouched. Known (README): the from-end ranking also applies between non-suffix routes on those paths. Pinned by the `suffix.test.ts` sweep "never picks a strictly broader route".
59
59
-**Within a suffix trie** (`collectSuffix`): shallower first, then param child, then static child; same-node entries by weight (passing regexes + 1 for `**:name`), ties insertion order.
60
60
-**Compiler:** see [compiler.md](compiler.md#suffix-routes).
61
61
62
62
## Removal
63
63
64
64
`removeRoute` splices entries by the registration identity `_add` stamps on them (`MethodData.route`), never the whole bucket, so same-node siblings survive.
65
65
66
-
- Plain pattern: identity = the rewritten segment join (static keys via `segmentKey`, suffix included), the same string `ctx.static` is keyed by. Spellings the tree can't distinguish remove each other (`/a/` β‘ `/a`, `\)` β‘ `)`, `/**.md` β‘ `/**/*.md`).
67
-
- Expanding pattern (groups, modifiers): every entry gets the pre-expansion text normalized by `expandedRouteId()`, so the `/admin` entry of `/admin/:page?` never collides with a separately registered `/admin`.
- 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).
68
69
- 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).
69
70
- Removal is by registered pattern: `/x/*` does not remove `/x/:id`; `:id(\d+)` and `:x(\d+)` are distinct.
70
71
- Suffix routes: `_removeSuffix` walks back from the last segment, prunes empty trie nodes, then `wildcard.suffix`, then the wildcard (`_isEmptyNode` counts `suffix`).
-**Shape** (`RouteShape`): fixed single-segment matchers (`string` literal | `RegExp` | `NON_EMPTY` for a `:name`, which needs a value | `undefined` = any, a `*`) + a tail length range `[tailMin, tailMax]` (`*` β `[0,1]`, `**`/ `:x*` β `[0,β]`, `**:name` β `[1,β]`, none β `[0,0]`; the tail constrains count only, except `some`: a `**:name`'s one-segment tail can't be `""`) + `suffix`: matchers aligned to the path **end** for segments after `**`. Leading any-value suffix matchers fold into the tail (`/**/*/b` β‘ `/*/**/b`; a `:x` is `NON_EMPTY` and doesn't fold). 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.
9
+
-**Shape** (`RouteShape`): fixed single-segment matchers (`string` literal | `RegExp` | `NON_EMPTY` for a `:name`, which needs a value | `undefined` = any, a `*`) + a tail length range `[tailMin, tailMax]` (`*` β `[0,1]`, `**`β `[0,β]`, `:x*` β `[0,β]` with `some`, `**:name` β `[1,β]`, none β `[0,0]`; the tail constrains count only, except `some`: a `**:name`'s one-segment tail can't be `""`) + `suffix`: matchers aligned to the path **end** for segments after `**`. Leading any-value suffix matchers fold into the tail (`/**/*/b` β‘ `/*/**/b`; a `:x` is `NON_EMPTY` and doesn't fold). 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.
10
10
- 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.
11
11
-**Canonicalization:** trailing any-value matchers fold into the tail (`/a/*/*` β `["a"] [1,2]`), never into a `some` tail (it would move its first segment); 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/**` and `/a/:x?` β `/a/*` (`/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.
12
12
-**Overlap** = some concrete path matches both. Static/static and static/regex are exact; any-vs-anything and regex/regex over-approximate to overlap.
0 commit comments