@abide/abide 0.117.1 → 0.118.0

package/src/server/generatedSurfaces.ts

@@ -18,7 +18,7 @@ import { essenceOf } from '#shared/framing.ts'
 import { namedLogger } from '#shared/log.ts'
 import { mounted } from '#shared/mount.ts'
 import { type Reactive, reactive } from '#shared/reactive/index.ts'
-import { parseRoutePattern } from '#shared/routePattern.ts'
+import { parseRoutePattern, type Segment } from '#shared/routePattern.ts'
 import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
 import { answered } from './answerFailure.ts'
 import { bodyWithin, type Mounted } from './answerRpc.ts'
@@ -134,13 +134,19 @@ function openApiOf(handlers: Map<string, Mounted>): {
         for (const segment of parseRoutePattern(each.address)) {
             if (segment.kind === 'static') continue
             inPath.add(segment.name)
+            const declared = schema?.properties?.[segment.name] ?? {
+                type: 'string',
+            }
+            // 20.23 — and what the segment takes, save a rest's: its value is the parts joined,
+            // which one part's pattern does not describe.
             const parameter: Record<string, unknown> = {
                 name: segment.name,
                 in: 'path',
                 required: true,
-                schema: schema?.properties?.[segment.name] ?? {
-                    type: 'string',
-                },
+                schema:
+                    segment.kind === 'rest'
+                        ? declared
+                        : patterned(declared, patternOf(segment, each.matchers)),
             }
             if (segment.kind === 'optional')
                 parameter.description = 'May be left out, with its segment.'
@@ -172,8 +178,11 @@ function openApiOf(handlers: Map<string, Mounted>): {
                     },
                 },
             }
-        // OpenAPI spells a parameter `{id}` where a route spells it `[id]`.
-        const path = each.address.replace(/\[+(?:\.\.\.)?([^\]]+)\]+/g, '{$1}')
+        // OpenAPI spells a parameter `{id}` where a route spells it `[id]`, and names no matcher.
+        const path = each.address.replace(
+            /\[+(?:\.\.\.)?([^\]=]+)(?:=[^\]]*)?\]+/g,
+            '{$1}',
+        )
         paths[path] ??= {}
         ;(paths[path] as Record<string, unknown>)[each.method.toLowerCase()] =
             operation
@@ -291,7 +300,9 @@ export class McpSurface {
             listing.push({
                 name: tool.name,
                 description: tool.description ?? '',
-                inputSchema: toolInput(tool.schema),
+                inputSchema: toolInput(
+                    withPathPatterns(tool.schema, tool.address, tool.matchers),
+                ),
                 // 20.14 — what the method promises: a `GET` is safe, and a `GET`, a `PUT` and a
                 // `DELETE` idempotent. Any other write may destroy, and nothing says it does not.
                 annotations: {
@@ -454,6 +465,63 @@ function logCall(
     )
 }
 
+/** 20.23 — the anchored pattern a segment takes a part by: its matcher's, or 30.34's default. */
+function patternOf(segment: Segment, matchers: Record<string, string>): string {
+    return segment.matcher === undefined
+        ? PERIODLESS_PATTERN
+        : (matchers[segment.matcher] ?? PERIODLESS_PATTERN)
+}
+
+const PERIODLESS_PATTERN = '^[^.]+$'
+
+/** `declared` constrained to `pattern` too: beside a pattern it declares itself, not over it. */
+function patterned(declared: unknown, pattern: string): unknown {
+    if (declared === null || typeof declared !== 'object') return { pattern }
+    return 'pattern' in declared
+        ? { allOf: [declared, { pattern }] }
+        : { ...declared, pattern }
+}
+
+/**
+ * 20.23 — `schema` with each route parameter it declares constrained to what its segment takes, a
+ * rest's on each of its items; `schema` itself where the route has no parameter it declares.
+ */
+function withPathPatterns(
+    schema: unknown,
+    address: string,
+    matchers: Record<string, string>,
+): unknown {
+    if (schema === null || typeof schema !== 'object') return schema
+    const properties = (schema as { properties?: Record<string, unknown> })
+        .properties
+    if (properties === undefined) return schema
+    const constrained: Record<string, unknown> = { ...properties }
+    let changed = false
+    for (const segment of parseRoutePattern(address)) {
+        if (segment.kind === 'static') continue
+        const declared = properties[segment.name]
+        if (declared === undefined) continue
+        const pattern = patternOf(segment, matchers)
+        constrained[segment.name] =
+            segment.kind === 'rest' &&
+            declared !== null &&
+            typeof declared === 'object' &&
+            'items' in declared
+                ? {
+                      ...declared,
+                      items: patterned(
+                          (declared as { items: unknown }).items,
+                          pattern,
+                      ),
+                  }
+                : segment.kind === 'rest'
+                  ? declared
+                  : patterned(declared, pattern)
+        changed = true
+    }
+    return changed ? { ...schema, properties: constrained } : schema
+}
+
 /**
  * `schema` as a tool's `inputSchema`, its top-level `type` `object` whatever it declared there, or
  * `undefined` where no value it admits is an object. 20.19, 20.20.

package/src/server/placement.ts

@@ -104,6 +104,16 @@ export function isServerFile(path: string): boolean {
 
 const SERVER_FILE = /[^/]\.server\.[^./]+$/
 
+/** 16.2 — whether `path` names a handler file, `<name>.handler.ts`, whose default export answers at its route. */
+export function isHandlerFile(path: string): boolean {
+    return path.endsWith('.handler.ts')
+}
+
+/** 23.24 — whether `path` names a param file, `<NAME>.param.ts`, declaring the matcher `NAME`. */
+export function isParamFile(path: string): boolean {
+    return path.endsWith('.param.ts')
+}
+
 /** Whether `path` names a test file, which is never an address nor a module the app runs. */
 export function isTestFile(path: string): boolean {
     return path.endsWith('.test.ts')
@@ -127,7 +137,7 @@ export function skipped(name: string): boolean {
 /**
  * The route a file answers at — its path below the root without its extension.
  *
- * 23.14 — `media/[id].abide` and `media/getGrid.ts` are `/media/[id]` and `/media/getGrid`; an
+ * 23.14 — `media/[id].abide` and `media/getGrid.handler.ts` are `/media/[id]` and `/media/getGrid`; an
  * `index.abide`, a `layout.abide` and an `error.abide` are their directory's.
  */
 export function routeOf(path: string): string {
@@ -138,7 +148,7 @@ export function routeOf(path: string): string {
     return `/${parts.filter((part) => part !== '').join('/')}`
 }
 
-const EXTENSION = /\.(?:abide|ts)$/
+const EXTENSION = /\.(?:abide|handler\.ts)$/
 
 /** 23.14, 23.18 — the names whose route is their directory's, and so a route's wherever they stand. */
 export const DIRECTORY_FILES = new Set([

package/src/server/remote.ts

@@ -115,11 +115,15 @@ function handlerAt(
     address: string,
     method: string | undefined,
 ): Mount | undefined {
-    const rows: { pattern: string; mount: Mount }[] = []
+    const rows: {
+        pattern: string
+        matchers: Record<string, string>
+        mount: Mount
+    }[] = []
     for (const mount of handlers) {
         if (method !== undefined && mount.method !== method) continue
         if (mount.address === address) return mount
-        rows.push({ pattern: mount.address, mount })
+        rows.push({ pattern: mount.address, matchers: mount.matchers, mount })
     }
     return firstMatch(rankRoutes(rows), partsOf(address) ?? [])?.route.mount
 }

package/src/server/surfaceOf.ts

@@ -17,6 +17,8 @@ export type Listed = {
     schema: unknown
     /** What it answers, as JSON Schema, where its type says. 19.21. */
     result: unknown
+    /** 23.26 — each matcher its address names, to its anchored source. */
+    matchers: Record<string, string>
 }
 
 /**
@@ -50,6 +52,7 @@ export function surfaceOf(
             live === undefined ? mount.description : live.handler.description,
         schema: live === undefined ? mount.args : live.argsDocument,
         result: mount.result,
+        matchers: mount.matchers,
     }
 }
 
@@ -60,7 +63,8 @@ export function surfaceOf(
  * and dots dropped, so `/media/[id]` reads `media_id` rather than `media__id_`.
  */
 export function surfaceName(method: Method, route: string): string {
-    return `${method.toLowerCase()}${route === '/' ? '' : route.replace(/[[\].]/g, '')}`.replace(
+    // 19.1 — a matcher is no part of what a route is, so none of its name: `=NAME` goes first.
+    return `${method.toLowerCase()}${route === '/' ? '' : route.replace(/=[^\]]*/g, '').replace(/[[\].]/g, '')}`.replace(
         /[^a-zA-Z0-9-]/g,
         '_',
     )

package/src/shared/filledPath.ts

@@ -42,32 +42,38 @@ export function filledSegments(
         }
         if (segment.kind === 'rest' && Array.isArray(value)) {
             for (const each of value)
-                address += `/${encodedSegment(spelled, segment.name, each, refused)}`
+                address += `/${encodedSegment(spelled, segment, each, refused)}`
             continue
         }
-        address += `/${encodedSegment(spelled, segment.name, value, refused)}`
+        address += `/${encodedSegment(spelled, segment, value, refused)}`
     }
     return address === '' ? '/' : address
 }
 
 /**
- * A param value encoded as one path segment; `.` and `..` are refused.
+ * A param value encoded as one path segment, refused where no address can carry it.
  *
- * 30.19 — A VALUE OF `.` OR `..` HAS NO SPELLING AS A SEGMENT: the URL parser collapses it as a
- * dot-segment, and `%2E` / `%2E%2E` with it, so the address would land on another route. Refused
- * rather than written, as a missing required segment is (30.3).
+ * 30.19 — A VALUE NO SEGMENT TAKES HAS NO SPELLING: one carrying a period, where the segment names no
+ * matcher to lift the default (30.34), and `.` or `..` whatever it names (30.36), which the URL
+ * parser collapses as a dot-segment, `%2E` / `%2E%2E` with it. Refused rather than written, as a
+ * missing required segment is (30.3). A named matcher is not run here: the literal says a matcher
+ * is named, and only a route table holds the regex (23.26).
  */
 function encodedSegment(
     spelled: string,
-    name: string,
+    segment: Segment,
     value: unknown,
     refused: (name: string, message: string) => unknown,
 ): string {
     const text = String(value)
-    if (text === '.' || text === '..')
+    const carried =
+        segment.matcher === undefined
+            ? !text.includes('.')
+            : text !== '.' && text !== '..'
+    if (!carried)
         throw refused(
-            name,
-            `abide: ${spelled} was given '${text}' for '${name}', and no address carries it as a segment — the URL parser resolves it to another route. RULEBOOK 30.19.`,
+            segment.name,
+            `abide: ${spelled} was given '${text}' for '${segment.name}', and no address carries ${segment.matcher === undefined ? 'a period in a param naming no matcher' : 'a dot-segment'}. RULEBOOK 30.19.`,
         )
     return encodeURIComponent(text)
 }

package/src/shared/matchRoute.ts

@@ -56,9 +56,16 @@ function walk(
         return prefix || at === parts.length ? {} : null
     const segment = segments[index] as Segment
     // 30.5 — A REST TAKES THE MOST THE SEGMENTS AFTER IT LEAVE, nothing included, so a handler's
-    // name after one (`/docs/[...path]/save`) is reached rather than spent on the rest.
+    // name after one (`/docs/[...path]/save`) is reached rather than spent on the rest — and 30.35,
+    // never past a part it does not accept.
     if (segment.kind === 'rest') {
-        for (let end = parts.length; end >= at; end -= 1) {
+        let furthest = at
+        while (
+            furthest < parts.length &&
+            segment.accepts.test(parts[furthest] as string)
+        )
+            furthest += 1
+        for (let end = furthest; end >= at; end -= 1) {
             const params = walk(segments, index + 1, parts, end, prefix)
             if (params !== null) {
                 params[segment.name] = parts.slice(at, end)
@@ -68,8 +75,12 @@ function walk(
         return null
     }
     const part = parts[at]
+    // 30.34, 30.35 — A PARAM TAKES A PART ITS SEGMENT ACCEPTS: the matcher it names, or, naming
+    // none, no part carrying a period, which is how a file is named — the `/favicon.ico` a browser
+    // asks every site for is no `[param]` page's to answer.
+    const takeable = part !== undefined && segment.accepts.test(part)
     if (segment.kind === 'optional') {
-        if (part !== undefined) {
+        if (takeable) {
             const taken = walk(segments, index + 1, parts, at + 1, prefix)
             if (taken !== null) {
                 taken[segment.name] = part
@@ -79,7 +90,8 @@ function walk(
         return walk(segments, index + 1, parts, at, prefix)
     }
     if (part === undefined) return null
-    if (segment.kind === 'static' && part !== segment.name) return null
+    if (segment.kind === 'static' ? part !== segment.name : !takeable)
+        return null
     const params = walk(segments, index + 1, parts, at + 1, prefix)
     if (params !== null && segment.kind === 'required')
         params[segment.name] = part

package/src/shared/reactive/Reactive.ts

@@ -2219,6 +2219,10 @@ function mirror(cell: Cell, inner: Cell): void {
     // 7.13 through the adoption: the re-settle a rerun of the adopter makes reaches a reload the
     // adopted value owes, rather than finding it unservable and giving up.
     if (inner.owes !== OWES_NOTHING) settleOwed(inner)
+    // 13.7 THROUGH THE ADOPTION TOO: a sweep's mark on a value nothing read is `DIRTY`, and an
+    // adoption is that value's next read. A mirror reached through a rerun finds it resolved
+    // already; the first one `adopt` runs does not, and copied the held value over the mark.
+    if (inner.state !== CLEAN) resolve(inner)
     const adopted = inner.stream
     if (adopted !== null) {
         forwardStream(cell, inner, adopted)

package/src/shared/routePattern.ts

@@ -17,29 +17,78 @@ export type Segment = {
     kind: SegmentKind
     /** The literal text for a static segment, the param name for the other three. */
     name: string
+    /** 23.26 — the matcher a dynamic segment names after `=`, or `undefined` where it names none. */
+    matcher: string | undefined
+    /** 30.34, 30.35 — what a part must match to be taken: the matcher's, or the period default. */
+    accepts: RegExp
 }
 
+/** 30.34, 30.36 — what a segment naming no matcher takes: a part carrying no period. */
+const PERIODLESS = /^[^.]+$/
+
+// A segment naming a matcher, parsed with no table to resolve it in, takes nothing: only a route
+// table's own rows say which regex a name stands for (23.26), and a reader that only builds an
+// address or compares shapes never walks one.
+const UNRESOLVED = /(?!)/
+
 /**
  * A route literal split into its segments, each classified by kind.
  *
- * `[...rest]`, `[[optional]]`, `[required]`, or a literal. Ordered longest-first: `[[a]]` is a
- * `[a]` with another bracket round it, so testing the short form first matches both.
+ * `[...rest]`, `[[optional]]`, `[required]`, or a literal, each dynamic one optionally naming a
+ * matcher after `=`, compiled from `matchers` — each name's anchored source, as the build wrote it
+ * into the row (23.26) — where a route table hands its row's. Ordered
+ * longest-first: `[[a]]` is a `[a]` with another bracket round it, so testing the short form first
+ * matches both.
  */
-export function parseRoutePattern(pattern: string): Segment[] {
+export function parseRoutePattern(
+    pattern: string,
+    matchers?: Record<string, string>,
+): Segment[] {
     const out: Segment[] = []
     for (const raw of pattern.split('/')) {
         if (raw === '') continue
-        if (raw.startsWith('[[') && raw.endsWith(']]'))
-            out.push({ kind: 'optional', name: raw.slice(2, -2) })
-        else if (raw.startsWith('[...') && raw.endsWith(']'))
-            out.push({ kind: 'rest', name: raw.slice(4, -1) })
-        else if (raw.startsWith('[') && raw.endsWith(']'))
-            out.push({ kind: 'required', name: raw.slice(1, -1) })
-        else out.push({ kind: 'static', name: raw })
+        let kind: SegmentKind = 'static'
+        let body = raw
+        if (raw.startsWith('[[') && raw.endsWith(']]')) {
+            kind = 'optional'
+            body = raw.slice(2, -2)
+        } else if (raw.startsWith('[...') && raw.endsWith(']')) {
+            kind = 'rest'
+            body = raw.slice(4, -1)
+        } else if (raw.startsWith('[') && raw.endsWith(']')) {
+            kind = 'required'
+            body = raw.slice(1, -1)
+        }
+        const split = kind === 'static' ? -1 : body.indexOf('=')
+        const matcher = split === -1 ? undefined : body.slice(split + 1)
+        out.push({
+            kind,
+            name: split === -1 ? body : body.slice(0, split),
+            matcher,
+            accepts:
+                matcher === undefined
+                    ? PERIODLESS
+                    : matchers === undefined
+                      ? UNRESOLVED
+                      : resolvedIn(matchers, matcher, pattern),
+        })
     }
     return out
 }
 
+function resolvedIn(
+    matchers: Record<string, string>,
+    matcher: string,
+    pattern: string,
+): RegExp {
+    const source = matchers[matcher]
+    if (source === undefined)
+        throw new Error(
+            `abide: the route table's row for ${pattern} carries no matcher ${matcher}, which the build writes beside every segment naming one. RULEBOOK 23.26.`,
+        )
+    return new RegExp(source)
+}
+
 /**
  * A `sort` comparator over two parsed patterns: negative where `a` is the more specific.
  *
@@ -99,12 +148,15 @@ export function coversRoute(outer: Segment[], route: Segment[]): boolean {
  * which page an address resolves to, so it is here with `compareRoutes` rather than written out
  * beside each table: the server's boot and the client router's start compile through one call.
  */
-export function rankRoutes<T extends { pattern: string }>(
-    rows: T[],
-): (T & { segments: Segment[] })[] {
+export function rankRoutes<
+    T extends { pattern: string; matchers?: Record<string, string> },
+>(rows: T[]): (T & { segments: Segment[] })[] {
     const ranked: (T & { segments: Segment[] })[] = []
     for (const row of rows)
-        ranked.push({ ...row, segments: parseRoutePattern(row.pattern) })
+        ranked.push({
+            ...row,
+            segments: parseRoutePattern(row.pattern, row.matchers ?? {}),
+        })
     ranked.sort((a, b) => compareRoutes(a.segments, b.segments))
     return ranked
 }

package/src/shared/url.ts

@@ -12,26 +12,31 @@ type Parts<P extends string> = P extends `${infer Head}/${infer Tail}`
     ? Head | Parts<Tail>
     : P
 
+// 23.26 — a segment's param is named before any `=`: `[symbol=TICKER]` is `symbol`.
+type ParamName<Body extends string> = Body extends `${infer Name}=${string}`
+    ? Name
+    : Body
+
 export type RequiredNames<P extends string> =
     Parts<P> extends infer Part
         ? Part extends `[${infer Name}]`
             ? Name extends `[${string}` | `...${string}`
                 ? never
-                : Name
+                : ParamName<Name>
             : never
         : never
 
 export type OptionalNames<P extends string> =
     Parts<P> extends infer Part
         ? Part extends `[[${infer Name}]]`
-            ? Name
+            ? ParamName<Name>
             : never
         : never
 
 export type RestNames<P extends string> =
     Parts<P> extends infer Part
         ? Part extends `[...${infer Name}]`
-            ? Name
+            ? ParamName<Name>
             : never
         : never
 
@@ -51,18 +56,28 @@ export type HasSegments<P extends string> = [
 
 export type Query = Record<string, unknown> | URLSearchParams
 
-/** The params a route literal takes, by segment kind. */
+/** The params a route literal takes, by segment kind, and 30.3 — narrowed where `abide check` says. */
 export type ParamsOf<P extends string> = {
     [K in RequiredNames<P>]: string | number
 } & { [K in OptionalNames<P>]?: string | number } & {
     [K in RestNames<P>]?: string | number | (string | number)[]
-}
+} & Narrowed<P>
+
+/**
+ * 23.9, 30.3 — the params `abide check` declared for `P` beside its key: each whose matcher is an
+ * alternation of literals, as their union. Nothing where it declared none, or nothing at all.
+ */
+type Narrowed<P extends string> = P extends keyof Routes
+    ? Routes[P] extends true
+        ? unknown
+        : Routes[P]
+    : unknown
 
 /**
  * 30.26 — the route literals an app files its pages under, which `abide check` declares for the app
  * it checks. Where nothing declared them any literal is taken, so a plain `tsc` still compiles.
  */
-// biome-ignore lint/suspicious/noEmptyInterface: filled by declaration merging, per app
+// biome-ignore lint/suspicious/noEmptyInterface: filled by declaration merging, per app — each literal to `true`, or to the params it narrows (23.9)
 export interface Routes {}
 
 /** 30.26 — what `url` takes: one of the app's route literals, or any where none were declared. */
@@ -76,7 +91,9 @@ export type RouteLiteral = [keyof Routes] extends [never]
  */
 export type RouteParams<P extends string> = {
     [K in RequiredNames<P>]: string
-} & { [K in OptionalNames<P>]?: string } & { [K in RestNames<P>]: string[] }
+} & { [K in OptionalNames<P>]?: string } & {
+    [K in RestNames<P>]: string[]
+} & Narrowed<P>
 
 /**
  * An address from a route literal and its params, resolved against the mount, with an optional