@abide/abide 0.117.2 → 0.118.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @abide/abide
 
+## 0.118.0
+
+### Minor Changes
+
+- 1613343: Breaking: a handler file is named <name>.handler.ts (RULEBOOK 23.14, 23.22) ([`5f64c1b`](https://github.com/briancray/abide/commit/5f64c1b02dec18c6e8574a88ee46e2f7477bee71))
+- 1613343: Breaking: a route param names a matcher in a <NAME>.param.ts, and one naming none takes no part carrying a period (RULEBOOK 23.24-23.27, 30.34-30.37, 20.23) ([`db7b00d`](https://github.com/briancray/abide/commit/db7b00d07bbb8f47bc73a757356675555b276b51))
+
+### Patch Changes
+
+- 1613343: a page answers 404 to a request that cannot display it, before its setup runs (RULEBOOK 35.19) ([`7276d7c`](https://github.com/briancray/abide/commit/7276d7c41a44b5602b9dd4a779f85b3a05aa260f))
+
 ## 0.117.2
 
 ### Patch Changes

package/docs/REGISTRY.md

@@ -264,9 +264,9 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 
 | File | Declares | Served at | Rules |
 | --- | --- | --- | --- |
-| `users/getUser.ts` | `export default GET(…)` | `/users/getUser` | 16.2, 16.73, 19.1, 19.20, 23.14 |
-| `health.ts` | `export default GET(…)` | `/health` | 16.2, 23.14 |
-| `media/[id]/save.ts` | `export default POST(…)` | `/media/[id]/save`, `id` reaching its `Args` | 16.2, 16.65, 16.66, 16.67, 16.69 |
+| `users/getUser.handler.ts` | `export default GET(…)` | `/users/getUser` | 16.2, 16.73, 19.1, 19.20, 23.14 |
+| `health.handler.ts` | `export default GET(…)` | `/health` | 16.2, 23.14 |
+| `media/[id]/save.handler.ts` | `export default POST(…)` | `/media/[id]/save`, `id` reaching its `Args` | 16.2, 16.65, 16.66, 16.67, 16.69 |
 | `media/[id]/lib/Comments.abide` | `const addComment = POST(…)` in its `<script server>` | `/__abide/handlers/media/id/lib/Comments/addComment` | 16.70, 16.71, 16.72 |
 
 ## Schemas
@@ -315,14 +315,14 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `/__abide/openapi.json` | `GET` | The generated OpenAPI document. | 19.21, 19.22, 20.5, 20.6, 20.7, 20.8, 20.11, 20.13, 20.15, 36.7 |
+| `/__abide/openapi.json` | `GET` | The generated OpenAPI document. | 19.21, 19.22, 20.5, 20.6, 20.7, 20.8, 20.11, 20.13, 20.15, 20.23, 36.7 |
 | `OpenApiDocument` | `JsonValue` | OpenAPI 3.1, whose schema dialect is `JsonSchema`. | 20.6 |
 
 ## MCP
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `/__abide/mcp` | `POST` | The streamable-http MCP endpoint. | 19.21, 19.22, 20.5, 20.7, 20.8, 20.9, 20.10, 20.12, 20.13, 20.14, 20.16, 20.17, 20.19, 20.20, 20.21, 20.22, 36.7, 16.78 |
+| `/__abide/mcp` | `POST` | The streamable-http MCP endpoint. | 19.21, 19.22, 20.5, 20.7, 20.8, 20.9, 20.10, 20.12, 20.13, 20.14, 20.16, 20.17, 20.19, 20.20, 20.21, 20.22, 20.23, 36.7, 16.78 |
 
 # Assistant
 
@@ -513,8 +513,8 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `OptionalNames<P>` | `string` | The optional segment names. | 30.4 |
 | `RestNames<P>` | `string` | The rest segment names. | 30.5 |
 | `Query` | `Record<string, unknown> \| URLSearchParams` | The query half. | 30.6, 30.28 |
-| `ParamsOf<P>` | `& { [K in RequiredNames<P>]: string \| number } & { [K in OptionalNames<P>]?: string \| number } & { [K in RestNames<P>]?: string \| number \| (string \| number)[] }` | What a route literal's segments accept. | 30.3, 30.4, 30.5 |
-| `RouteParams<P>` | `{ [K in RequiredNames<P>]: string } & { [K in OptionalNames<P>]?: string } & { [K in RestNames<P>]: string[] }` | What a page filed under `P` reads its params as. | 23.9 |
+| `ParamsOf<P>` | `& { [K in RequiredNames<P>]: string \| number } & { [K in OptionalNames<P>]?: string \| number } & { [K in RestNames<P>]?: string \| number \| (string \| number)[] }` | What a route literal's segments accept, narrowed where `abide check` declares a matcher's literals. | 30.3, 30.4, 30.5 |
+| `RouteParams<P>` | `{ [K in RequiredNames<P>]: string } & { [K in OptionalNames<P>]?: string } & { [K in RestNames<P>]: string[] }` | What a page filed under `P` reads its params as, narrowed where `abide check` declares a matcher's literals. | 23.9 |
 | `Routes` | `interface Routes {}` | The app's route literals and public file addresses, which `abide check` declares. | 30.26 |
 | `RouteLiteral` | `[keyof Routes] extends [never] ? string : Extract<keyof Routes, string>` | What `url` takes. | 30.26 |
 
@@ -619,9 +619,10 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | --- | --- | --- |
 | `<head>` | A page's, layout's or component's contribution to the document head. | 39.1, 39.2, 39.3, 39.4, 39.5, 39.6, 39.11, 39.12, 39.13, 39.14, 39.15, 39.16, 39.17 |
 | `view-transition-name` | What turns view transitions on, in the app's own stylesheet. | 39.7, 39.8, 39.9, 39.10, 39.18, 39.19 |
-| `[name]` | A required dynamic segment. | 16.65, 23.5, 30.3 |
-| `[[name]]` | An optional segment. | 23.5, 30.4 |
-| `[...name]` | A rest segment, terminal. | 23.5, 30.5 |
+| `[name]` | A required dynamic segment. | 16.65, 23.5, 30.3, 30.34, 30.36 |
+| `[[name]]` | An optional segment. | 23.5, 30.4, 30.34, 30.36 |
+| `[...name]` | A rest segment, terminal. | 23.5, 30.5, 30.34, 30.36 |
+| `[name=NAME]` · `[[name=NAME]]` · `[...name=NAME]` | A dynamic segment a param file's matcher decides. | 19.1, 23.26, 23.27, 30.19, 30.35, 30.36, 30.37 |
 | `/__abide/**` | Every endpoint abide controls. | 20.8 |
 
 ## `render`
@@ -684,9 +685,10 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `src/public/robots.txt` | The file answered at `/robots.txt`. | 36.11 |
 | `src/public/icon.png` · `src/public/icon.icns` | The files answered at `/icon.png` and `/icon.icns`, and the desktop app's icon. | 36.11, 38.79, 45.15 |
 | `src/**/` | A directory of the app's, a segment of the route of every file directly in it. | 23.14, 23.17, 23.22 |
-| `**/index.abide` | The page at its directory's route. | 19.1, 23.3, 23.4, 23.14, 23.18 |
-| `**/<name>.abide` | The page at its directory's route and then `<name>`. | 19.1, 23.3, 23.4, 23.14, 23.21 |
-| `**/<name>.ts` | A handler file: the handler its default export declares, at its directory's route and then `<name>`. | 16.2, 16.28, 16.73, 16.74, 19.1, 23.14, 23.22 |
+| `**/index.abide` | The page at its directory's route. | 19.1, 23.3, 23.4, 23.14, 23.18, 35.19 |
+| `**/<name>.abide` | The page at its directory's route and then `<name>`. | 19.1, 23.3, 23.4, 23.14, 23.21, 35.19 |
+| `**/<NAME>.param.ts` | A param file: the matcher a segment naming `NAME` matches by. | 23.22, 23.24, 23.25, 23.26 |
+| `**/<name>.handler.ts` | A handler file: the handler its default export declares, at its directory's route and then `<name>`. | 16.2, 16.28, 16.73, 16.74, 19.1, 23.14, 23.22 |
 | `**/layout.abide` | A layout, rendering every page below its route through a slot, and the hooks over that route. | 35.1, 35.12, 35.13, 37.2, 41.11, 41.19, 41.23 |
 | `src/launcher.abide` | The desktop launcher, beside the root layout: the `onLauncher` it calls, and its page in place of the launcher's own where it has markup. | 38.80, 38.82, 38.84, 38.85, 38.107 |
 | `src/layout.abide` | The root layout, whose `<script server>` is the app's own, and whose `<html>` is the document its pages are served in. | 35.15, 35.16, 35.17, 37.1, 37.3, 39.4 |
@@ -859,7 +861,7 @@ rows a runner prints, and an adapter for an abide app.
 | `abide scaffold <name>` | Writes a starter project. | 38.1, 38.42, 38.103, 38.104, 38.106, 38.112, 38.122, 38.124 |
 | `abide run <file> [args…]` | Runs a script under the abide runtime. | 38.2, 38.57 |
 | `abide check [dir…]` | The type-checker over a `.abide` tree. | 38.3, 38.31, 38.32, 38.33, 38.40, 38.105, 38.123 |
-| `abide routes [--json]` | Every address the app answers, the file answering it, and where each hook is filed. | 38.108, 38.123 |
+| `abide routes [--json]` | Every address the app answers, the file answering it, what each matcher takes, and where each hook is filed. | 38.108, 38.123 |
 | `abide dev [--port <n>]` | Watches the project and keeps the app up. | 16.23, 16.56, 37.8, 37.9, 38.4, 38.14, 38.15, 38.16, 38.17, 38.19, 38.24, 38.25, 38.26, 38.28, 38.30, 38.35, 38.36, 38.37, 38.38, 38.41, 38.43, 38.58, 38.63, 38.64, 38.65, 38.94, 38.96, 38.97, 38.123 |
 | `abide build` | Builds the client into content-hashed chunks and a manifest. | 38.43, 38.5, 38.18, 38.25, 38.26, 38.27, 38.30, 38.66, 38.94, 38.123 |
 | `abide start [--port <n>]` | Boots the built app. | 37.8, 37.10, 37.11, 37.12, 38.6, 38.100, 38.20, 38.21, 38.22, 38.23, 38.25, 38.26, 38.27, 38.28, 38.29, 38.58, 38.67, 38.68, 38.95, 38.97, 38.110, 38.123 |

package/docs/RULEBOOK.md

@@ -121,7 +121,9 @@ REGISTRY.md because none of them is a name an app author writes.
 | server file | A file named `<name>.server.<extension>`. |
 | test file | A `.test.ts` file. |
 | declaration file | A `.d.ts` file. |
-| handler file | A `.ts` of the app's own, neither a declaration file, a test file nor a server file, directly in a directory under no fence. |
+| handler file | A file of the app's own named `<name>.handler.ts`, directly in a directory under no fence. |
+| param file | A file of the app's own named `<NAME>.param.ts`, directly in a directory under no fence. |
+| matcher | What a param file declares, and what a segment naming it matches by. |
 | private handler | A handler a `<script server>` declares. |
 | chapter app | The app the documentation's story has built by the end of one chapter, kept whole so a reader can download it and run it. |
 
@@ -1266,7 +1268,7 @@ while `outbox` holds a call not yet delivered, and MUST read the value again onc
 
 19.1 A route MUST be answered for each method by one file at most, a page answering `GET` and `HEAD`
 at its own, and a second MUST be a build error naming both files, two routes differing only in
-their parameters' names being one route.
+their parameters' names or matchers being one route.
 
 19.2 A `Schema` MUST return what it accepts.
 
@@ -1405,6 +1407,10 @@ text, and MUST carry no `structuredContent`.
 20.22 A call to a tool declaring an `outputSchema` that is answered with an `image/*` body MUST be
 refused, its text naming the tool and the image's type, and MUST be logged per 20.18 as a 500.
 
+20.23 A path parameter `/__abide/openapi.json` publishes, save a rest's, and a route parameter an MCP
+tool's input declares, a rest's on each of its items, MUST carry the pattern its segment takes a part
+by, anchored, and a matcher's name MUST be no part of the path, the operation or the tool.
+
 # 21. Generated headers
 
 21.1 Every response MUST carry `x-content-type-options: nosniff`.
@@ -1517,7 +1523,8 @@ composite.
 
 23.9 In a page or a layout, `route.params()` MUST be typed by that file's own route: a required
 segment as text, an optional one as text that may be absent, a rest as a list, and in a layout any
-segment a page below it adds.
+segment a page below it adds — under `abide check`, a page's required or optional segment whose
+matcher is an alternation of literals as the union of those literals.
 
 23.10 `reachable` MUST be true where the host answered a request, whatever the status it answered.
 
@@ -1527,8 +1534,9 @@ segment a page below it adds.
 
 23.13 `reachable` MUST ask a host that names no scheme over https, and an origin as written.
 
-23.14 A route MUST be the path of its file below the app's `--root` without its extension, and an
-`index.abide`'s, a `layout.abide`'s and an `error.abide`'s MUST be its directory's.
+23.14 A route MUST be the path of its file below the app's `--root` without its extension, a handler
+file's being `.handler.ts`, and an `index.abide`'s, a `layout.abide`'s and an `error.abide`'s MUST be
+its directory's.
 
 23.15 A file under a fence MUST NOT have a route.
 
@@ -1549,12 +1557,26 @@ error naming the mount.
 `layout.abide`, an `error.abide` and the root's `launcher.abide`.
 
 23.22 A file of the app's own directly in a directory under no fence that is neither a `.abide`, a
-handler file, a test file, a bench file nor a declaration file MUST be a build error naming the file and a `lib` directory, save one
+handler file, a param file, a test file, a bench file nor a declaration file MUST be a build error naming the file and a `lib` directory, save one
 beside the `package.json` of a root that holds it, nor a `.ts`.
 
 23.23 A server file of the app's own under no `lib` directory MUST be a build error naming the file
 and a `lib` directory.
 
+23.24 A param file MUST hold one `export const`, of the name it is filed under, whose value is a
+regular expression literal carrying no flag, and anything else, an import included, MUST be a build
+error naming the file.
+
+23.25 A matcher repeating, with `*`, `+` or `{n,}`, a group that itself holds such a repetition, or
+carrying a backreference, MUST be a build error naming its file.
+
+23.26 A segment `[name=NAME]`, `[[name=NAME]]` or `[...name=NAME]` MUST name the param file `NAME.param.ts`
+in the directory holding that segment or the nearest directory above it below the root it is filed
+under, and one naming none MUST be a build error naming the segment's file and `NAME`.
+
+23.27 Two routes naming different matchers, or a matcher and none, at one parameter position after
+one static prefix MUST be a build error naming both files.
+
 # 24. Tracing
 
 24.1 `trace` MUST be built on first ask and held for the request.
@@ -1741,7 +1763,8 @@ MUST NOT consume `csp.nonce`.
 30.2 `url` MUST require a params argument where the literal carries a required segment, and MUST
 make it optional otherwise.
 
-30.3 A required segment MUST map to a required key of `ParamsOf<P>`.
+30.3 A required segment MUST map to a required key of `ParamsOf<P>`, typed under `abide check` as
+23.9 types it where its matcher is an alternation of literals.
 
 30.4 An `OptionalNames<P>` segment MUST map to an optional key, and leaving one out MUST omit that
 segment.
@@ -1783,7 +1806,8 @@ on.
 
 30.18 `navigate` MUST leave an answer other than 204 to the document.
 
-30.19 `url` MUST throw where a param, or a member of a rest param, is `.` or `..`.
+30.19 `url` MUST throw where a param, or a member of a rest param, of a segment naming no matcher
+carries a `.`, and where any param or member is `.` or `..`.
 
 30.20 A history step to an address that differs from the page shown only in its fragment MUST NOT
 pass through `middleware`, and MUST NOT remount the page.
@@ -1828,6 +1852,17 @@ MUST leave the page and the address where they stand, save where 45.12 holds.
 30.33 A history step under 30.20, and a `navigate` under 30.21, MUST move `route.url` to the address
 it steps to.
 
+30.34 A `[param]` or an `[[optional]]` segment naming no matcher MUST NOT match a part carrying a
+`.`, and such a `[...rest]` MUST NOT take one.
+
+30.35 A segment naming a matcher MUST match a part only where the whole part, percent-decoded,
+matches it, and a `[...rest]` naming one MUST take a part only where it does.
+
+30.36 No dynamic segment MUST match a part that is `.` or `..`.
+
+30.37 An address whose part a segment refuses, by its matcher or by 30.34, MUST be matched against
+the routes 30.9 ranks after that route.
+
 # 31. Reading and writing by name
 
 31.1 Inside a `.abide` file a name bound to a `Reactive` MUST be read wherever 31.3 does not hold it.
@@ -2322,6 +2357,9 @@ on any element is.
 35.18 A document an `error.abide` answers MUST NOT be hydrated as the page its address names, and a
 navigation from it MUST load the document it asks for.
 
+35.19 A page route MUST answer a request whose `sec-fetch-dest` names neither a destination fetch
+calls a navigation request's nor `empty` with a bodiless 404, and MUST NOT set up its page.
+
 # 36. Environment and files
 
 36.1 `PORT` MUST default to 3000, and a command's own port flag MUST override it by declaring it.
@@ -2729,8 +2767,9 @@ as one markdown file, in reading order.
 38.107 `onLauncher` called anywhere but `src/launcher.abide` MUST be a build error naming that file.
 
 38.108 `abide routes` MUST print every route with each method it answers and the file answering
-it, every private handler with its address and its file, and every hook with the file that filed it;
-with `--json` it MUST print the same as one JSON document.
+it, every private handler with its address and its file, every matcher a route names with the
+pattern it takes a part by, and every hook with the file that filed it; with `--json` it MUST print
+the same as one JSON document.
 
 38.109 Under `bun test` with `@abide/abide/test` preloaded, a test MUST import a `.abide` of the app as
 the module it compiles to, whether or not `createApp` has run.