@abide/abide 0.101.0 → 0.102.0

package/src/server/answerRpc.ts

@@ -16,6 +16,7 @@ import type { Gated } from '#shared/reactive/argsContract.ts'
 import { deadlineOf, heldGenerationOf } from '#shared/reactive/index.ts'
 import type { Defaults } from '#shared/reactive/parameterDefaults.ts'
 import { notFound, refuse } from '#shared/refuse.ts'
+import { routeOf } from '#shared/routePattern.ts'
 import type { Method, Rpc } from '#shared/rpc.ts'
 import { argsInURL } from '#shared/rpcRequest.ts'
 import { VERSION_HEADER } from '#shared/VERSION_HEADER.ts'
@@ -30,7 +31,12 @@ import { followAsEvents } from './answerSocket.ts'
 import { answerValue, namesEtag, sseHeaders } from './answerValue.ts'
 import { argsFor } from './argsFor.ts'
 import { callerOf } from './callerOf.ts'
-import { argsDocumentOf, collapsed, type Document } from './coerceArgs.ts'
+import {
+    argsDocumentOf,
+    coerceArgs,
+    collapsed,
+    type Document,
+} from './coerceArgs.ts'
 import { positiveSetting } from './config.ts'
 import {
     allows,
@@ -38,7 +44,7 @@ import {
     crossingOrigin,
     crossingRefusal,
 } from './crossingOrigin.ts'
-import { failureOf } from './hooks.ts'
+import { type AppRung, failureOf, rungsOver } from './hooks.ts'
 import { prefers } from './prefers.ts'
 import {
     currentRequestScope,
@@ -51,7 +57,8 @@ import { type Outcome, outcomeOf, takeSeed } from './seedBuffer.ts'
 import { versionOf } from './versionOf.ts'
 
 /**
- * One row of the table the build writes to `<out>/rpc.ts`: where a handler answers, and its module.
+ * One row of the handler table the build writes into the server's table (`SERVER_TABLE`): where a
+ * handler answers, and its module.
  *
  * The module is relative to the app's root, which both commands that serve already know.
  */
@@ -62,7 +69,7 @@ export type Mount = {
     name: string
     /** Whether a browser is handed a wrapper for it. 20.4. */
     ui: boolean
-    /** Whether the command line lists it — the shell's listing and completion, never whether `call` reaches it. 20.3, 38.63. */
+    /** Whether the command line lists it — the shell's listing and completion, never whether `call` reaches it. 20.3, 38.62. */
     cli: boolean
     /**
      * Whether MCP lists it where its runtime `clients` does not say.
@@ -88,9 +95,23 @@ export type Mount = {
     args: JsonValue | undefined
 }
 
+/**
+ * A row of the table the build wrote, with the import of the module its handler is declared in —
+ * the file's server module, the one the route table loads too, so a page and a call reach one
+ * handler.
+ */
+export type MountRow = Mount & { load: () => Promise<Record<string, unknown>> }
+
 /** A handler's row, mounted: the handler imported and its args schema probed. */
 export type Mounted = Mount & {
     method: Method
+    /** The route of the file declaring it, which its hooks are filed at (37.1, 37.2). */
+    route: string
+    /**
+     * The rungs filed over `route`, read once at mount (16.14) — what an http call and a socket
+     * subscription to it both pass through (37.2, 18.26).
+     */
+    rungs: AppRung[]
     handler: Rpc<unknown, unknown> & Gated<unknown>
     /**
      * The args' JSON Schema, probed once at mount.
@@ -127,6 +148,10 @@ export function mountedOwn(
         {
             address,
             method: 'GET',
+            route: '/',
+            // The root's rungs run before routing (37.3), and nothing is filed below a route
+            // of abide's own.
+            rungs: [],
             source: '',
             name,
             ui: false,
@@ -149,20 +174,17 @@ export function environmentTimeout(): number | undefined {
 }
 
 /**
- * The table's handlers, imported and keyed by address.
+ * The table's handlers, imported and keyed by method and address.
  *
- * Imported from the SOURCE tree, so a page rendering on the server and a call over the wire reach
- * one module and so one handler. AT BOOT rather than on the first call, because a page's render
- * reaches a handler through the page's own import and has to know its address before anything has
- * called it over the wire.
+ * Imported through each row's own loader, which the route table shares, so a page rendering on the
+ * server and a call over the wire reach one module and so one handler. AT BOOT rather than on the
+ * first call, because a page's render reaches a handler through the page's own import and has to
+ * know its address before anything has called it over the wire.
  */
 export async function mountHandlers(
-    table: Mount[],
-    moduleOf: (source: string) => Promise<Record<string, unknown>>,
+    table: MountRow[],
 ): Promise<{ handlers: Map<string, Mounted> }> {
-    const modules = await Promise.all(
-        table.map((mount) => moduleOf(mount.source)),
-    )
+    const modules = await Promise.all(table.map((mount) => mount.load()))
     const handlers = new Map<string, Mounted>()
     for (let at = 0; at < table.length; at += 1) {
         const mount = table[at] as Mount
@@ -172,9 +194,14 @@ export async function mountHandlers(
         // 16.9, 16.10 — the address `rpc.url` and `rpc.raw` build on, under the mount — and what a
         // page's render turns a call it made into the browser's request by (41.20).
         handler.address = underMount(mount.address)
-        handlers.set(mount.address, {
+        // 23.19 — the route its address answers below, which is its mount's for a package's file,
+        // never the file's place on disk.
+        const route = routeOf(mount.address)
+        handlers.set(handlerKey(mount.method, mount.address), {
             ...mount,
             method: mount.method,
+            route,
+            rungs: rungsOver(route),
             handler,
             argsDocument: declared ?? (mount.args as Document | undefined),
             wireArgs: declared === undefined ? mount.args : undefined,
@@ -183,30 +210,34 @@ export async function mountHandlers(
     return { handlers }
 }
 
-/** The `Response` to a handler call made over http. */
+/** What a handler is keyed by among the mounted: its method and its route. 19.1. */
+export function handlerKey(method: string, address: string): string {
+    return `${method} ${address}`
+}
+
+/**
+ * The `Response` to a call of `found` made over http, `params` being what its route matched.
+ *
+ * `found` answers the request's method — or, for an `OPTIONS`, the method its preflight asks
+ * about: which handler a request reaches is the route table's to say (19.21).
+ */
 export async function answerRpc(
-    handlers: Map<string, Mounted>,
+    found: Mounted,
+    params: Record<string, string | string[]>,
     url: URL,
     request: Request,
     // 16.38 — what paints a refusal for a request that came as a navigation.
     pages: ErrorPages,
 ): Promise<Response> {
     const pathname = url.pathname
-    const found = handlers.get(pathname)
     const origin = request.headers.get('origin')
     // 16.24 — THE PREFLIGHT, answered by abide where the handler declared `crossOrigin`.
-    if (
-        found !== undefined &&
-        request.method === 'OPTIONS' &&
-        origin !== null &&
-        allows(found.handler.crossOrigin, origin)
-    )
-        return preflight(found, origin, request)
+    if (request.method === 'OPTIONS')
+        return origin !== null && allows(found.handler.crossOrigin, origin)
+            ? preflight(found, origin, request)
+            : answered(notFound({ path: pathname, method: request.method }))
     // 16.50 — a `HEAD` is the `GET`'s answer, which the server sends without its body.
     const head = request.method === 'HEAD'
-    // 15.7 — no handler at this address AND this method is one refusal, not two.
-    if (found === undefined || found.method !== (head ? 'GET' : request.method))
-        return answered(notFound({ path: pathname, method: request.method }))
     const handler = found.handler
     const inUrl = argsInURL(found.method)
     const form = isForm(request)
@@ -226,10 +257,12 @@ export async function answerRpc(
         return answered(overCeiling(ceiling))
     const raw = await argsOf(request, url, inUrl, form, ceiling)
     if (isFailed(raw)) return answered(raw)
+    const sent = withParameters(raw, params, inUrl || form, found)
+    if (isFailed(sent)) return answered(sent)
     let args: unknown
     try {
         // A URL's and a form's args are text, and the query tells a bare name from `name=` (19.7).
-        args = argsFor(found, raw, inUrl ? url.search : form ? '' : undefined)
+        args = argsFor(found, sent, inUrl ? url.search : form ? '' : undefined)
     } catch (refused) {
         if (isFailed(refused)) return answered(refused)
         throw refused
@@ -436,6 +469,39 @@ async function argsOf(
     return parsed
 }
 
+/**
+ * The args a request sent, with the parameters its route matched laid in.
+ *
+ * 16.65 — the path's, whatever the method. 16.66 — a parameter the query or the body names as
+ * well is refused rather than one of the two chosen. A JSON body's members are typed already, so the
+ * path's text is coerced to the declared types before it joins them (19.7); text args are coerced
+ * with the rest of the text.
+ */
+function withParameters(
+    sent: unknown,
+    params: Record<string, string | string[]>,
+    text: boolean,
+    found: Mounted,
+): unknown | Failed<'HttpError', undefined> {
+    let none = true
+    for (const name in params) {
+        none = false
+        if (isRecord(sent) && name in sent)
+            return refuse(
+                400,
+                `The parameter '${name}' is in the path and in the request as well.`,
+            )
+    }
+    if (none) return sent
+    const fromPath = text
+        ? params
+        : (coerceArgs(params, found.argsDocument, '') as Record<
+              string,
+              unknown
+          >)
+    return isRecord(sent) ? { ...sent, ...fromPath } : { ...fromPath }
+}
+
 /**
  * The request's body read up to `ceiling`, as a `Response`, or a 413 refusal past it.
  *
@@ -487,6 +553,12 @@ function preflight(found: Mounted, origin: string, request: Request): Response {
  * 16.57 — `Infinity` is never reaped, which bun spells 0; any finite bound is capped at the 255
  * seconds bun's idle timeout can hold.
  *
+ * FOUR SECONDS PAST THE TIMEOUT, NOT AT IT: a load that goes its timeout is refused at that moment,
+ * and a stream's refusal is a frame written then (16.68). bun's sockets check an idle timeout on a
+ * tick four seconds wide, so an idle timeout of the same second — or one past it — fired anywhere in
+ * the tick before it and reaped the connection ahead of the frame, one stream in two under `abide
+ * dev`. Four is the tick, so the refusal always goes out first.
+ *
  * ON THE REQUEST THE LISTENER RECEIVED, never the one being answered: under a mount, or past a
  * rung that handed `next` its own, that is a copy, and bun's `timeout` does nothing for a request
  * it was not handed itself.
@@ -496,7 +568,7 @@ export function raiseTimeout(milliseconds: number): void {
     const received = scope?.received
     if (scope === undefined || received === undefined) return
     const seconds = Number.isFinite(milliseconds)
-        ? Math.min(255, Math.ceil(milliseconds / 1000))
+        ? Math.min(255, Math.ceil(milliseconds / 1000) + 4)
         : Number.POSITIVE_INFINITY
     if (seconds <= scope.timeout) return
     scope.timeout = seconds

package/src/server/answerSocket.ts

@@ -10,18 +10,20 @@
 // built per request, since a trigger names args rather than a value. A `global` value is also fed its productions, a guarded one only to a
 // subscription its rungs admitted when it opened (18.8) — they run once, in the connection's request.
 
-import { ABIDE_ADDRESS } from '#shared/ADDRESSES.ts'
 import { type Problem, problemOf } from '#shared/Failed.ts'
 import { GLOBAL_GETS } from '#shared/GLOBAL_GETS.ts'
 import { namedLogger } from '#shared/log.ts'
+import { compose } from '#shared/Middleware.ts'
+import { unmounted } from '#shared/mount.ts'
+import type { BrowserFrame, ServerFrame } from '#shared/muxFrames.ts'
 import { FOLLOWED } from '#shared/reactive/FOLLOWED.ts'
 import { servedCellOf } from '#shared/reactive/index.ts'
 import { matchesPattern } from '#shared/reactive/matchesPattern.ts'
 import { PATCH_SINKS } from '#shared/reactive/PATCH_SINKS.ts'
 import { unowned } from '#shared/reactive/watch.ts'
 import { refuse } from '#shared/refuse.ts'
-import type { BrowserFrame, ServerFrame } from '#shared/muxFrames.ts'
-import type { Mounted } from './answerRpc.ts'
+import { rpcRequest } from '#shared/rpcRequest.ts'
+import { handlerKey, type Mounted } from './answerRpc.ts'
 import { argsFor } from './argsFor.ts'
 import { closedTo, crossingOrigin, crossingRefusal } from './crossingOrigin.ts'
 import { failureOf } from './hooks.ts'
@@ -38,7 +40,7 @@ import { patchesSince, versionOf } from './versionOf.ts'
  * The far end of one connection to the mux, which its frames are written to.
  *
  * Bun's socket under `abide start`, and under `abide dev` a stand-in that posts each frame to the
- * listener holding the real one (38.15).
+ * listener holding the real one (38.14).
  */
 export type Peer = {
     send(text: string): unknown
@@ -141,10 +143,10 @@ export function feedFromServed(
  * Only where that entry is not the one it is fed from already.
  */
 function attach(rpc: Mounted['handler'], follower: Follower): unknown {
-    const serving =
-        rpc.guarded && !follower.admitted
-            ? undefined
-            : GLOBAL_GETS.get(rpc)?.at(follower.key)
+    // 18.8, 18.26 — what its own rungs or its route's refused is sent its triggers alone.
+    const serving = !follower.admitted
+        ? undefined
+        : GLOBAL_GETS.get(rpc)?.at(follower.key)
     if (serving === follower.serving) return serving
     follower.stopFeed?.()
     // A version is one entry's count, so what it was sent of another says nothing about this one.
@@ -250,8 +252,8 @@ export class MuxConnection {
             return
         }
         const id = frame.id ?? 0
-        // THE ADDRESS FROM `/__abide` ON, which is what both tables are keyed by: a browser names
-        // it as its wrapper resolved it, which is a whole URL, or a path under the app's mount.
+        // THE ADDRESS BELOW THE MOUNT, which is what the handlers are keyed by: a browser names it
+        // as its wrapper resolved it, which is a whole URL, or a path under the app's mount.
         const address = addressIn(frame.address ?? '')
         const subscriptions = this.subscriptions
         if (frame.op === 'unsub') {
@@ -260,7 +262,9 @@ export class MuxConnection {
             return
         }
         const handler =
-            frame.op === 'sub' ? this.mux.handlers.get(address) : undefined
+            frame.op === 'sub'
+                ? this.mux.handlers.get(handlerKey('GET', address))
+                : undefined
         const followed = handler?.ui ? handler : undefined
         if (followed === undefined) {
             send(this.peer, {
@@ -295,16 +299,24 @@ export class MuxConnection {
             // 18.8 — A GUARDED `GET`'s RUNGS RUN ONCE, as the subscription opens, in this
             // connection's request: one they admit is fed the value, and one they refuse is sent its
             // triggers alone.
-            let admitted = !followed.handler.guarded
+            // 18.26 — AND THE MIDDLEWARE ITS FILE'S ROUTE FILED, over the request a `GET` of it
+            // would be: one a rung answers in the handler's place is not fed, as an http call it
+            // answered would never reach the handler.
+            const routed = followed.rungs.length > 0
+            let admitted = !followed.handler.guarded && !routed
             if (!admitted) {
                 subscriptions.get(id)?.()
                 subscriptions.set(id, pending)
-                admitted = await Promise.resolve(
-                    followed.handler(args as never) as PromiseLike<unknown>,
-                ).then(
-                    () => true,
-                    () => false,
-                )
+                // No route rungs, no turn: a guarded `GET`'s rungs start in this frame's own run.
+                admitted =
+                    !routed || (await routeAdmits(this.scope, followed, args))
+                if (admitted && followed.handler.guarded)
+                    admitted = await Promise.resolve(
+                        followed.handler(args as never) as PromiseLike<unknown>,
+                    ).then(
+                        () => true,
+                        () => false,
+                    )
                 if (subscriptions.get(id) !== pending) return
             }
             follow(this, id, followed, args, frame.version, admitted)
@@ -315,6 +327,39 @@ export class MuxConnection {
     }
 }
 
+/**
+ * Whether the rungs over `mounted`'s route let a `GET` of it with `args` through, asked over the
+ * upgrade's own request at the handler's address. 18.26.
+ */
+async function routeAdmits(
+    scope: RequestScope,
+    mounted: Mounted,
+    args: unknown,
+): Promise<boolean> {
+    const upgrade = scope.request as Request
+    const asked = rpcRequest(
+        'GET',
+        mounted.address,
+        args as Record<string, unknown> | undefined,
+    )
+    const request = new Request(new URL(asked.url, upgrade.url), {
+        headers: upgrade.headers,
+        signal: upgrade.signal,
+    })
+    // REACHED BY A FLAG, not by the answer's identity: a rung that wraps or re-heads what `next`
+    // answered still let the call through, and a shared answer would carry every rung's headers.
+    let reached = false
+    try {
+        const answered = await compose(mounted.rungs, async () => {
+            reached = true
+            return new Response(null, { status: 204 })
+        })({ request })
+        return reached && answered.ok
+    } catch {
+        return false
+    }
+}
+
 /**
  * Follows a handler for `id`: its triggers always, its value where `global` and unguarded.
  *
@@ -564,8 +609,8 @@ function sendAll(serving: unknown, fed: Iterable<Follower>): void {
 }
 
 function addressIn(named: string): string {
-    const at = named.indexOf(ABIDE_ADDRESS)
-    return at === -1 ? named : named.slice(at)
+    const path = URL.parse(named)?.pathname ?? named
+    return unmounted(path) ?? path
 }
 
 /**

package/src/server/answerValue.ts

@@ -3,6 +3,8 @@
 // (16.35), a document where `page` named one (17.2), a stream — a streaming handler's chunks, or
 // `Values` a handler returned — framed one chunk per pull (16.32, 16.44–16.47).
 
+import { isFailed, problemOf } from '#shared/Failed.ts'
+import { refusalFrame } from '#shared/framing.ts'
 import { compressAnswer } from './compressAnswer.ts'
 import { prefers } from './prefers.ts'
 import {
@@ -158,7 +160,7 @@ export function linesType(request: Request): string {
         : 'application/jsonl'
 }
 
-/** A stream answered at a framing already decided — a handler's, and `log.records` (36.7). */
+/** A stream answered at a framing already decided — a handler's. */
 export function framed(
     chunks: AsyncIterator<unknown>,
     framing: Framing,
@@ -185,7 +187,7 @@ export function framed(
  * was reading in its scope.
  *
  * AN EVENT STREAM OPENS ON A COMMENT: a streamed answer's head goes out with its first byte, so a
- * stream with nothing yet to say — an empty `log.records` — held its reader's headers until it did.
+ * stream with nothing yet to say held its reader's headers until it did.
  *
  * `first` is a result already pulled — the one a framing was decided from — and is sent ahead of
  * the rest.
@@ -230,7 +232,20 @@ export function bodyOf(
                     next = await chunks.next()
                 } catch (thrown) {
                     if (ended) return
-                    controller.error(thrown)
+                    // 16.68 — A REFUSAL AFTER THE STATUS WAS SENT is the stream's last frame, so the
+                    // reader refuses with it rather than reading a dropped connection. Bytes carry no
+                    // framing to hold one, and anything else is not a refusal to send.
+                    if (framing !== 'bytes' && isFailed(thrown)) {
+                        controller.enqueue(
+                            ENCODER.encode(
+                                refusalFrame(
+                                    problemOf(thrown),
+                                    framing === 'sse' ? 'data: ' : '',
+                                ),
+                            ),
+                        )
+                        controller.close()
+                    } else controller.error(thrown)
                     release()
                     return
                 }
@@ -314,12 +329,10 @@ export function answerBlobTagged(
             })
         }
     }
-    // A RANGE DECLINED — `If-Range` naming another version, or one this does not parse. Bun.serve
-    // ranges a file-backed 200 body on its own and reads no `If-Range` when it does, so the file, or
-    // its `stream()`, would go out 206 anyway; piped, the body is no longer one it can see is a file.
-    const body =
-        range === null ? blob : blob.stream().pipeThrough(new TransformStream())
-    return new Response(body, { status, headers })
+    // A RANGE DECLINED — `If-Range` naming another version, or one this does not parse — goes out
+    // whole as the blob itself: Bun.serve ranges a file-backed body on its own, but declines exactly
+    // these, so a file still leaves from disk.
+    return new Response(blob, { status, headers })
 }
 
 /**

package/src/server/appDirectories.ts

@@ -1,7 +1,7 @@
 /**
  * The directories an app's own files stand in: `root`, and the one above it.
  *
- * `root` is the directory `ui/` sits under — `src/` — and the one above it is the package beside
+ * `root` is the app's root — `src/` — and the one above it is the package beside
  * it. The app's `package.json` and `bunfig.toml` are found in the first that has one.
  */
 export function appDirectories(root: string): string[] {

package/src/server/appPlugins.ts

@@ -3,7 +3,7 @@ import { appDirectories } from './appDirectories.ts'
 /**
  * The app's own bundler plugins, loaded from `bunfig.toml`'s `[serve.static] plugins`.
  *
- * 38.44 — declared where bun already has an app declare them, the key `bun-plugin-tailwind`
+ * 38.43 — declared where bun already has an app declare them, the key `bun-plugin-tailwind`
  * documents. `Bun.build` reads no bunfig, so both client builds read this one — in
  * `appDirectories`, as `config` finds the app's `package.json`.
  */

package/src/server/appTree.ts

@@ -0,0 +1,179 @@
+// 23.14 — WHERE AN APP'S ADDRESSES ARE, read off the tree in one walk. Every directory below the root
+// is a segment of an address, and a `page.abide`, `layout.abide` or `error.abide` in it answers there;
+// a `server` or `public` directory is never one (23.15) — the first fences a graph and the second
+// holds files answered as authored, at the path of the directories above it. So an app is organized
+// by subject (`media/[id]/page.abide`, `media/server`) and the addresses follow.
+//
+// ONE WALK for the sources and the public files `abide build` copies and `abide dev` answers, and
+// the refusals (23.16, 23.17, 23.18) — and ONE SKIP RULE, `skipped`, for every walk of the tree,
+// beside `placeOf`, which answers the same question of one path.
+//
+// A WALK RATHER THAN A GLOB: a glob descends `node_modules` and the build output before a filter
+// can drop them.
+
+import { type Dirent, readdirSync } from 'node:fs' // bun has no directory listing of its own
+import { ABIDE_ADDRESS } from '#shared/ADDRESSES.ts'
+import {
+    PUBLIC_DIRECTORY,
+    RESERVED_DIRECTORIES,
+} from '#shared/RESERVED_DIRECTORIES.ts'
+import { fileKind, routeOf, skipped } from '#shared/routePattern.ts'
+
+/** What one walk of the app finds, every path relative to the root. */
+export type AppFiles = {
+    /** Every `.abide`, in path order. */
+    abide: string[]
+    /** Every file under a `public` directory, to the address it is answered at below the mount. */
+    published: Map<string, string>
+}
+
+/** Told of each thing the tree refuses, at the path relative to the root. */
+type Refuse = (path: string, message: string) => void
+
+const THROW: Refuse = (_path, message) => {
+    throw new Error(message)
+}
+
+/**
+ * The app's `.abide` sources and public files, refusing a tree 23.16, 23.17 or 23.18 forbids.
+ *
+ * `refuse` throws by default, which is the build's answer; `abide check` collects instead (38.33),
+ * and the checker's route table ignores them, since a refused tree is the build's to report.
+ *
+ * A missing root is an app with nothing in it, not a fault.
+ */
+export function appFiles(root: string, refuse: Refuse = THROW): AppFiles {
+    const files: AppFiles = { abide: [], published: new Map() }
+    walk(root, '', undefined, files, refuse)
+    files.abide.sort()
+    return files
+}
+
+// `reserved` is the nearest reserved directory above `relative` — its path and its name — or
+// `undefined` where none is.
+function walk(
+    directory: string,
+    relative: string,
+    reserved: { path: string; name: string } | undefined,
+    files: AppFiles,
+    refuse: Refuse,
+): void {
+    let entries: Dirent[]
+    try {
+        entries = readdirSync(directory, { withFileTypes: true })
+    } catch (thrown) {
+        if ((thrown as { code?: unknown }).code === 'ENOENT') return
+        throw thrown
+    }
+    for (const entry of entries) {
+        if (skipped(entry.name)) continue
+        const path = `${relative}${entry.name}`
+        if (entry.isDirectory()) {
+            let within = reserved
+            if (RESERVED_DIRECTORIES.has(entry.name)) {
+                if (reserved !== undefined)
+                    refuse(
+                        path,
+                        `abide: ${path} is a ${entry.name} directory under the ${reserved.name} directory ${reserved.path}. RULEBOOK 23.16.`,
+                    )
+                within = { path, name: entry.name }
+            }
+            walk(
+                `${directory}/${entry.name}`,
+                `${path}/`,
+                within,
+                files,
+                refuse,
+            )
+            continue
+        }
+        if (path.endsWith('.abide')) files.abide.push(path)
+        if (reserved === undefined) {
+            // 23.17 — anything that could answer here would answer in abide's own namespace.
+            if (path.endsWith('.abide'))
+                refuseFrameworkRoute(routeOf(path), path, refuse)
+        } else if (fileKind(entry.name) !== 'component')
+            refuse(
+                path,
+                `abide: ${path} is a ${entry.name} under the ${reserved.name} directory ${reserved.path}, where nothing has an address. RULEBOOK 23.18.`,
+            )
+        else if (reserved.name === PUBLIC_DIRECTORY)
+            files.published.set(path, publicAddress(path, reserved.path))
+    }
+}
+
+/** Refuses `source` where `route` lies in the framework's own namespace. 23.17. */
+export function refuseFrameworkRoute(
+    route: string,
+    source: string,
+    refuse: Refuse = THROW,
+): void {
+    if (route === ABIDE_ADDRESS || route.startsWith(`${ABIDE_ADDRESS}/`))
+        refuse(
+            source,
+            `abide: ${source} answers at ${route}, which is under ${ABIDE_ADDRESS}, where abide's own addresses are. RULEBOOK 23.17.`,
+        )
+}
+
+// 36.11 — the directories above `public`, then the file's own path below it.
+function publicAddress(path: string, directory: string): string {
+    const above = directory.slice(0, -PUBLIC_DIRECTORY.length)
+    return `/${above}${path.slice(directory.length + 1)}`
+}
+
+/**
+ * The public files as the server reads them: each address, without its leading `/`, to the file.
+ *
+ * 38.19 — out of the source tree, where `abide dev` answers them.
+ */
+export function publishedUnder(
+    root: string,
+    published: Map<string, string>,
+): Map<string, string> {
+    const paths = new Map<string, string>()
+    for (const [source, address] of published)
+        paths.set(address.slice(1), `${root}/${source}`)
+    return paths
+}
+
+/**
+ * Every `.abide` under `root`, relative to it, in path order — the app's own, and none a
+ * dependency ships.
+ *
+ * Refuses nothing: the language server lists them on every check, and a tree 23.16 forbids is the
+ * build's to refuse (`appFiles`).
+ */
+export function abideUnder(root: string): string[] {
+    const found: string[] = []
+    for (const path of abideFilesUnder(root, '')) found.push(path)
+    return found.sort()
+}
+
+/**
+ * Whether a `.abide` lies anywhere under `root` — stopping at the first.
+ *
+ * 38.26's question, asked of a root before anything is built from it, so asking it of a large tree
+ * is as cheap as the tree allows.
+ */
+export function holdsAbide(root: string): boolean {
+    return !abideFilesUnder(root, '').next().done
+}
+
+function* abideFilesUnder(
+    directory: string,
+    relative: string,
+): Generator<string> {
+    let entries: Dirent[]
+    try {
+        entries = readdirSync(directory, { withFileTypes: true })
+    } catch {
+        return
+    }
+    for (const entry of entries) {
+        if (skipped(entry.name)) continue
+        const path = `${relative}${entry.name}`
+        if (entry.isDirectory())
+            yield* abideFilesUnder(`${directory}/${entry.name}`, `${path}/`)
+        else if (path.endsWith('.abide')) yield path
+    }
+}