@abide/abide 0.102.0 → 0.104.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.102.0",
+    "version": "0.104.0",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",
@@ -40,6 +40,7 @@
         "./routing": "./src/ui/routing.ts",
         "./wire": "./src/ui/wire.ts",
         "./server": "./src/server/index.ts",
+        "./test": "./src/server/preload.ts",
         "./compiler": "./src/compiler/index.ts",
         "./package.json": "./package.json"
     },

package/scaffold/AGENTS.md

@@ -22,10 +22,17 @@ before writing code, rather than guessing from Svelte, Vue or React. It installs
 
 ## Layout
 
-- Every directory under `src/` is an address: `src/invoices/page.abide` answers `/invoices`.
-  `layout.abide` wraps the pages below it, and the outermost one writes `<html>`.
-- A module under a `server` directory runs on the server only, and importing one from browser
-  code is a compile error. A file under a `public` directory is served as it is:
-  `src/blog/public/cover.png` answers `/blog/cover.png`.
-- Handlers and hooks go in a `<script server>` block of a `.abide` file.
+- A file's path below `src/` is its address. `src/invoices/index.abide` answers `/invoices`,
+  `src/invoices/[id].abide` answers `/invoices/123`, and `layout.abide` wraps the pages below it;
+  the outermost one writes `<html>`. Run `bun run routes` to see every address and the file behind it.
+- A `.ts` beside the pages is a handler: `src/invoices/getInvoice.ts` holds
+  `export default GET(…)` and answers `/invoices/getInvoice`. It is the app's public API, for pages,
+  scripts, the CLI and MCP alike.
+- A `.abide` cannot export. A `<script server>` in one holds that file's private handlers
+  (`const save = POST(…)`), callable by that file alone, and its hooks (`onStart`, `middleware`, …).
+- A directory holds addresses and four fenced directories alone: `lib/` for components and modules,
+  `tests/` for tests, `server/` for modules the browser never loads (importing one from browser code
+  is a compile error), and `public/` for files served as they are (`src/blog/public/cover.png`
+  answers `/blog/cover.png`). Anything else beside the pages is a build error.
 - Import the app's own modules as `#src/…` (see `imports` in `package.json`).
+- A test imports `.abide` files directly: `bunfig.toml` preloads `@abide/abide/test`.

package/src/compiler/TypeSession.ts

@@ -21,6 +21,7 @@ import {
     COMPONENT_MODULE,
     COMPONENT_STAND_IN,
     checkedShadow,
+    moduleConfigShadow,
 } from './checkedShadow.ts'
 import type { Finding } from './Finding.ts'
 import { CHECKED_VALUES } from './Lowering.ts'
@@ -65,12 +66,17 @@ export class TypeSession {
      */
     private shadows = new Map<string, { path: string; text: string }>()
     /**
-     * 30.26 — the route table `diagnose` last declared, and the root it walked for it: kept until
-     * `edited` hears anything move, so a check asked again and again while an editor types walks and
-     * reads nothing on disk.
+     * What `diagnose` last read off one walk of the root: the route table it declared (30.26) and the
+     * modules it read for their `onConfig` (27.13). Kept until `edited` hears anything move, so a
+     * check asked again and again while an editor types walks and reads nothing on disk.
      */
-    private routes: { within: string; declaration: string } | undefined =
-        undefined
+    private walked:
+        | {
+              within: string
+              routes: string
+              configModules: Promise<[string, string][]>
+          }
+        | undefined = undefined
     /** The checker's own key for a path: resolved, and case-folded where its host folds case. */
     private keyOf: (path: string) => string
     /**
@@ -101,7 +107,7 @@ export class TypeSession {
     /**
      * The project this session opens: the app's tsconfig, with every shadow in `outside` a root.
      *
-     * 34.29 — A DEPENDENCY'S `.abide` IS TYPED AS THE APP'S OWN, and its tsconfig's `include` never
+     * 34.25 — A DEPENDENCY'S `.abide` IS TYPED AS THE APP'S OWN, and its tsconfig's `include` never
      * reaches `node_modules` or a linked package's directory. The session opens a config of its own —
      * served from here, never written — that extends the app's, names those shadows as files, which
      * TypeScript adds to what the base config includes (a linked package's shadow, asked for through
@@ -157,7 +163,7 @@ export class TypeSession {
     /**
      * The shadow registered at `name`, or at the same file through its directory's real path.
      *
-     * 34.29 — A LINKED PACKAGE IS ASKED FOR THROUGH ITS LINK: the checker resolves `kit/x.abide` to
+     * 34.25 — A LINKED PACKAGE IS ASKED FOR THROUGH ITS LINK: the checker resolves `kit/x.abide` to
      * `node_modules/kit/x.d.abide.ts` and the re-export there to the shadow beside it, while the
      * shadow is registered where bun resolved the file — the package's real directory.
      */
@@ -180,17 +186,17 @@ export class TypeSession {
     }
 
     private standIn(name: string): string | undefined {
-        // 34.25 — a file imported as text is its text, which the projection names apart.
+        // 34.21 — a file imported as text is its text, which the projection names apart.
         if (name.endsWith(`${SOURCE_SUFFIX}.d.ts`))
             return isFile(name.slice(0, -`${SOURCE_SUFFIX}.d.ts`.length))
                 ? 'declare const text: string\nexport default text\n'
                 : undefined
-        // 34.17, 34.23 — WHAT A `.abide` EXPORTS BY NAME, to anything importing it: the checker
-        // resolves `./x.abide` by trying `./x.abide.d.ts`, and is answered with the file's own
-        // module and server blocks — its projection — beside the component its checked module
-        // declares. The wildcard declaration a plain `.ts` is typed by carries the default alone.
+        // 34.17 — WHAT A `.abide` EXPORTS, to anything importing it: the component its checked
+        // module declares, and nothing else. The checker resolves `./x.abide` by trying
+        // `./x.abide.d.ts`; the bindings the projection re-exports for the build (16.70) are not
+        // the importer's to read.
         //
-        // 34.29 — AND THROUGH A PACKAGE'S `exports`, which the checker follows to the exact file and
+        // 34.25 — AND THROUGH A PACKAGE'S `exports`, which the checker follows to the exact file and
         // so asks for the arbitrary extension's declaration, `./x.d.abide.ts`, instead.
         const abide = name.endsWith(DECLARATION_SUFFIX)
             ? name.slice(0, -'.d.ts'.length)
@@ -200,8 +206,7 @@ export class TypeSession {
         if (abide !== undefined) {
             if (!isFile(abide)) return undefined
             const own = `./${basename(abide)}`
-            return `export * from '${own}${SHADOW_SUFFIX.slice(0, -'.ts'.length)}'
-export { default } from '${own}${CHECKED_SUFFIX.slice(0, -'.ts'.length)}'
+            return `export { default } from '${own}${CHECKED_SUFFIX.slice(0, -'.ts'.length)}'
 `
         }
         // A projection not registered — a file with nothing to read, or one this session has not
@@ -353,7 +358,7 @@ export { default } from '${own}${CHECKED_SUFFIX.slice(0, -'.ts'.length)}'
      * checker is not told what was under it.
      */
     edited(paths: string[] | undefined): void {
-        this.routes = undefined
+        this.walked = undefined
         if (paths === undefined) {
             this.everything = true
             return
@@ -442,14 +447,49 @@ export { default } from '${own}${CHECKED_SUFFIX.slice(0, -'.ts'.length)}'
     }
 
     /**
-     * The project as of every edit so far, for a job to ask its questions of.
+     * 34.25, 23.19 — makes `path`, a dependency's file, a root of the opened config, telling
+     * `changed` the config moved where it was not one already.
+     */
+    private openOutside(path: string, changed: string[]): void {
+        if (this.outside.has(path)) return
+        this.outside.add(path)
+        if (!changed.includes(this.opened)) changed.push(this.opened)
+    }
+
+    /**
+     * The project, with each of `modules` outside the app's own a root of it.
      *
      * THE SNAPSHOT IS THE SESSION'S, AND A QUESTION IS ANY MODULE'S: what a handler declares
      * (`declaredExports`) is asked of the same snapshot the reads were, taken only where something
      * moved since.
+     *
+     * 23.19 — a handler file a mount places is a package's, which the app's `include` does not reach:
+     * what it exports is asked all the same (16.73), as a mounted `.abide`'s shadow is.
      */
-    project(): Promise<Project | undefined> {
-        return this.currentProject()
+    async projectWith(
+        modules: readonly string[],
+    ): Promise<Project | undefined> {
+        const changed: string[] = []
+        for (const path of modules) {
+            const canonical = this.canonical(path)
+            // The app's own is a root already: telling the config it moved reloads the project.
+            if (placeOf(this.belowRoot(canonical)) === 'dependency')
+                this.openOutside(canonical, changed)
+        }
+        const project = await this.currentProject([], changed)
+        if (project === undefined) return project
+        // A KEPT SESSION HEARS OF A FILE ONLY AS A WATCHER REPORTS IT, and one saved into a
+        // directory made since the last snapshot is reported as the directory: it is no root yet,
+        // and is told to the next snapshot as created.
+        const found = await Promise.all(
+            modules.map((path) => project.program.getSourceFile(path)),
+        )
+        const missing: string[] = []
+        for (let at = 0; at < modules.length; at += 1)
+            if (found[at] === undefined) missing.push(modules[at] as string)
+        return missing.length === 0
+            ? project
+            : this.currentProject(missing, [...missing])
     }
 
     /**
@@ -482,7 +522,7 @@ export { default } from '${own}${CHECKED_SUFFIX.slice(0, -'.ts'.length)}'
     /**
      * Where the checker holds a `.abide`'s projection, once `readsFor` has registered it.
      *
-     * 19.15 — what a `<script server>` exports is read off it as a `.ts` module's exports are.
+     * 16.70 — what a `<script server>` binds is read off it as a `.ts` module's exports are.
      */
     projectionOf(abidePath: string): string {
         return `${this.canonical(abidePath)}${SHADOW_SUFFIX}`
@@ -581,8 +621,8 @@ export { default } from '${own}${CHECKED_SUFFIX.slice(0, -'.ts'.length)}'
             const scripts = projection.text.slice(0, projection.scripts.end)
             // A TEMPLATE POSITION IS A QUESTION TOO (14.2): a file that declares nothing but
             // writes `{format(total)}` has a position only the checker can prove static. And a
-            // `<script server>` always is (19.15): what it exports is read off this shadow, a bare
-            // `export { touch } from …` included.
+            // `<script server>` always is (16.70): what it binds is read off this shadow, re-exported
+            // under `PRIVATE_EXPORT`.
             if (
                 !DECLARES.test(scripts) &&
                 projection.slots.size === 0 &&
@@ -606,13 +646,8 @@ export { default } from '${own}${CHECKED_SUFFIX.slice(0, -'.ts'.length)}'
             // AN UNCHANGED SHADOW IS NOT REPORTED, which is what a kept session saves on a save:
             // the one page that moved is re-read rather than all of them.
             this.register(map.shadowPath, projection.text, created, changed)
-            if (
-                placeOf(this.belowRoot(source.path)) === 'dependency' &&
-                !this.outside.has(map.shadowPath)
-            ) {
-                this.outside.add(map.shadowPath)
-                changed.push(this.opened)
-            }
+            if (placeOf(this.belowRoot(source.path)) === 'dependency')
+                this.openOutside(map.shadowPath, changed)
             queries.push({
                 map,
                 spans: {
@@ -819,14 +854,30 @@ export { default } from '${own}${CHECKED_SUFFIX.slice(0, -'.ts'.length)}'
             created,
             changed,
         )
+        if (this.walked?.within !== within) {
+            // A refused tree is `checkApp`'s finding (38.33), never the checker's crash.
+            const files = appFiles(within, () => {})
+            this.walked = {
+                within,
+                routes: routesDeclaration(within, files),
+                configModules: configModulesUnder(within, files),
+            }
+        }
+        // 27.13 — what a handler file defaults, beside it.
+        for (const [path, text] of await this.walked.configModules) {
+            const shadow = moduleConfigShadow(text)
+            const at = `${this.canonical(path)}${CONFIG_SUFFIX}`
+            // One that stops filing keeps its place and declares nothing, so the next snapshot is
+            // told it moved.
+            if (shadow !== undefined || this.shadows.has(this.keyOf(at)))
+                this.register(at, shadow ?? 'export {}\n', created, changed)
+        }
         // 30.26 — THE APP'S ROUTE TABLE, which `url`'s literal is held to: every page under the
         // root, declared into abide's own `Routes`. A module rather than a script, since only a
         // module augments one.
-        if (this.routes?.within !== within)
-            this.routes = { within, declaration: routesDeclaration(within) }
         this.register(
             `${this.canonical(within)}/${ROUTES_DECLARATION}`,
-            this.routes.declaration,
+            this.walked.routes,
             created,
             changed,
         )
@@ -1106,10 +1157,11 @@ const URL_SOURCE = Bun.fileURLToPath(new URL('../shared/url', import.meta.url))
  * 30.26 — every page under `root`, and every public file's address, as a key of abide's `Routes`, or
  * nothing where it has neither.
  */
-function routesDeclaration(root: string): string {
+function routesDeclaration(
+    root: string,
+    { abide, published }: ReturnType<typeof appFiles>,
+): string {
     const routes = new Set<string>()
-    // A refused tree is `checkApp`'s finding (38.33), never the checker's crash.
-    const { abide, published } = appFiles(root, () => {})
     for (const path of abide)
         if (fileKind(path) === 'page') routes.add(routeOf(path))
     // 23.19 — and every page a mount places in the app, at its position.
@@ -1272,3 +1324,24 @@ function flatten(diagnostic: {
         message += `\n  ${flatten(link as Parameters<typeof flatten>[0]).replaceAll('\n', '\n  ')}`
     return message
 }
+
+/** What a module that is no `.abide` is checked beside as, for the `Config` it files (27.13). */
+const CONFIG_SUFFIX = '.config-shadow.ts'
+
+/**
+ * Every handler file below `within` that names `onConfig`, with its text — the modules a server
+ * runs that 27.13 types `Config` off, since 37.13 refuses a hook anywhere else that is no `.abide`.
+ */
+async function configModulesUnder(
+    within: string,
+    { handlers }: ReturnType<typeof appFiles>,
+): Promise<[string, string][]> {
+    const paths: string[] = []
+    for (const name of handlers) paths.push(`${within}/${name}`)
+    const texts = await Promise.all(paths.map((path) => Bun.file(path).text()))
+    const found: [string, string][] = []
+    for (let at = 0; at < paths.length; at += 1)
+        if ((texts[at] as string).includes('onConfig'))
+            found.push([paths[at] as string, texts[at] as string])
+    return found
+}

package/src/compiler/appMap.ts

@@ -0,0 +1,91 @@
+// 38.108 — THE APP'S MAP: every address it answers, the file answering each, and where every hook is
+// filed. What `abide routes` prints, off the build's own reading of the tree — the routes and the
+// handler mounts `compileApp` answers with — so the map and what the server answers are one walk.
+//
+// THE HOOKS ARE READ, NOT RUN, as the handlers are: a call of one of abide's hook names in a server
+// block, a `<script>` or a handler file, at the route 37.1 files it at.
+
+import { readFileSync } from 'node:fs' // bun exposes no sync read of its own
+import { appFiles } from '#server/appTree.ts'
+import { scopeOf } from '#shared/routePattern.ts'
+import { compileApp } from './compileApp.ts'
+import { hooksCalled } from './hooksCalled.ts'
+import { parseAbide } from './parseAbide.ts'
+
+/** One address the app answers, and the file answering it. */
+type MappedRoute = {
+    method: string
+    address: string
+    file: string
+    kind: 'page' | 'handler' | 'private'
+}
+
+/** One hook call, the route it is filed at, and the file making it. */
+type MappedHook = { hook: string; route: string; file: string }
+
+/** Every address the app at `root` answers, and every hook it files. */
+export async function appMap(
+    root: string,
+): Promise<{ routes: MappedRoute[]; hooks: MappedHook[] }> {
+    const app = await compileApp(root)
+    const routes: MappedRoute[] = []
+    for (const route of app.routes)
+        routes.push({
+            method: 'GET',
+            address: route.pattern,
+            file: route.source,
+            kind: 'page',
+        })
+    for (const mount of app.mounts)
+        routes.push({
+            method: mount.method,
+            address: mount.address,
+            file: mount.source,
+            kind: mount.private ? 'private' : 'handler',
+        })
+    routes.sort((one, two) =>
+        one.address === two.address
+            ? one.method < two.method
+                ? -1
+                : 1
+            : one.address < two.address
+              ? -1
+              : 1,
+    )
+    const hooks: MappedHook[] = []
+    const { abide, handlers } = appFiles(root, () => {})
+    for (const file of abide) {
+        const parsed = parseAbide(readFileSync(`${root}/${file}`, 'utf8'))
+        // Block by block: one block's last token would decide how the next one's first reads.
+        for (const script of [...parsed.servers, ...parsed.scripts])
+            for (const hook of hooksCalled(script))
+                hooks.push({ hook, route: scopeOf(file), file })
+    }
+    for (const file of handlers)
+        for (const hook of hooksCalled(readFileSync(`${root}/${file}`, 'utf8')))
+            hooks.push({ hook, route: scopeOf(file), file })
+    return { routes, hooks }
+}
+
+/** The map as `abide routes` prints it: one line an address, then one a hook. */
+export function mapText(map: Awaited<ReturnType<typeof appMap>>): string {
+    const lines: string[] = []
+    const width = (values: string[]): number =>
+        values.reduce((most, value) => Math.max(most, value.length), 0)
+    const methods = width(map.routes.map((route) => route.method))
+    const addresses = width(map.routes.map((route) => route.address))
+    for (const route of map.routes)
+        lines.push(
+            `${route.method.padEnd(methods)}  ${route.address.padEnd(addresses)}  ${route.file}${route.kind === 'private' ? '  (private)' : ''}`,
+        )
+    if (map.hooks.length > 0) {
+        lines.push('', 'hooks')
+        const hooks = width(map.hooks.map((hook) => hook.hook))
+        const routes = width(map.hooks.map((hook) => hook.route))
+        for (const hook of map.hooks)
+            lines.push(
+                `  ${hook.hook.padEnd(hooks)}  ${hook.route.padEnd(routes)}  ${hook.file}`,
+            )
+    }
+    return lines.join('\n')
+}

package/src/compiler/argsSchemaOf.ts

@@ -134,7 +134,7 @@ async function objectOf(
     }
     const schema: Schema = { type: 'object', properties }
     if (required.length > 0) schema.required = required
-    // 19.19 — A MEMBER THE TYPE DOES NOT DECLARE IS REFUSED, where no index signature declares the
+    // 19.18 — A MEMBER THE TYPE DOES NOT DECLARE IS REFUSED, where no index signature declares the
     // rest: a caller outside the process sends whatever it likes, and a body writing its args to a
     // row would write that too. An author who wants the rest declares a schema of their own.
     schema.additionalProperties = false

package/src/compiler/checkApp.ts

@@ -4,12 +4,14 @@ import { placeOf } from '#shared/routePattern.ts'
 import {
     type AppChecker,
     emitApp,
+    refuseModuleHooks,
     resolverIn,
     sourcesUnder,
     withChecker,
     withDependencies,
 } from './compileApp.ts'
 import { abideImportsOf } from './componentGraph.ts'
+import { projectShadow } from './projectShadow.ts'
 import {
     parseSources,
     type ReadSource,
@@ -17,7 +19,6 @@ import {
     refusal,
 } from './readSources.ts'
 import type { Diagnosis } from './TypeSession.ts'
-import { writeTypes } from './writeTypes.ts'
 
 /**
  * Every finding `abide check` reports for the app at `appRoot`.
@@ -39,18 +40,30 @@ export async function checkApp(
     const { root, sources } = await sourcesUnder(appRoot)
     return withChecker(root, kept, async (session) => {
         const refused: Diagnosis[] = []
-        const everyOwn = parseSources(sources, refused)
-        await writeTypes(root, everyOwn, true, refused)
-        // A file whose projection was refused is found already, and every later step projects it.
-        const refusedPaths = new Set<string>()
-        for (const found of refused) refusedPaths.add(found.path)
-        const own: typeof everyOwn = []
-        for (const source of everyOwn)
-            if (!refusedPaths.has(source.path)) own.push(source)
+        const own = parseSources(sources, refused)
+        // 23.16-23.18 and 37.13 — what the build's walk would refuse of the tree, at each file it names.
+        // 38.33 — each at its file, and every one rather than the first.
+        const atFile = (relative: string, thrown: unknown): void => {
+            refused.push(refusal(`${root}/${relative}`, thrown))
+        }
+        const { handlers, modules } = appFiles(root, atFile)
+        refuseModuleHooks(root, modules, atFile)
         const resolve = resolverIn()
-        const parsed = await withDependencies(root, own, resolve, refused)
+        const { sources: everyParsed, handlers: handlerFiles } =
+            await withDependencies(root, own, handlers, resolve, refused)
+        // 38.33 — A FILE WHOSE PROJECTION IS REFUSED (34.3, 34.17) is a finding at its file, found
+        // here because every later step projects it and would throw the refusal for the whole app.
+        // AFTER THE IMPORTS ARE FOLLOWED, so a refused file another one imports is found too.
+        const parsed: typeof everyParsed = []
+        for (const source of everyParsed)
+            try {
+                projectShadow(source.file)
+                parsed.push(source)
+            } catch (thrown) {
+                refused.push(refusal(source.path, thrown))
+            }
         const { read, warnings } = await readSources(session, parsed, refused)
-        // THE APP'S OWN FILES ARE REPORTED ON: a dependency's is compiled with them (34.27), and
+        // THE APP'S OWN FILES ARE REPORTED ON: a dependency's is compiled with them (34.23), and
         // what is wrong inside a package is the package's to report.
         const reported: ReadSource[] = []
         for (const source of read)
@@ -64,15 +77,19 @@ export async function checkApp(
         const emittable: ReadSource[] = []
         for (const source of read)
             if (!loweringRefused.has(source.path)) emittable.push(source)
-        // 23.16-23.18 — what the build's walk would refuse of the tree, at each file it names.
-        appFiles(root, (path, message) => {
-            refused.push(refusal(`${root}/${path}`, message))
-        })
         if (refused.length === 0 && ambient.length === 0)
             try {
                 warnings.push(
-                    ...(await emitApp(root, session, emittable, resolve))
-                        .warnings,
+                    ...(
+                        await emitApp(
+                            root,
+                            session,
+                            emittable,
+                            resolve,
+                            handlerFiles,
+                            atFile,
+                        )
+                    ).warnings,
                 )
             } catch (thrown) {
                 refused.push(refusal(root, thrown))
@@ -127,7 +144,7 @@ export async function checkSource(
     for (const other of sources) {
         if (other.path === path || lowered.has(other.path)) continue
         const text = held(other.path) ?? other.text
-        if (FILES_CONFIG.test(text))
+        if (text.includes('onConfig') && FILES_CONFIG.test(text))
             imports.push({ path: other.path, text, quiet: true })
     }
     // A component that does not parse, or that the checker refuses, is its own file's finding and

package/src/compiler/checkedShadow.ts

@@ -1,3 +1,4 @@
+import { SERVER_SPECIFIER } from '#shared/SPECIFIERS.ts'
 import type { CheckerAnswer } from './CheckerAnswer.ts'
 import type { Finding } from './Finding.ts'
 import {
@@ -11,7 +12,6 @@ import { holdsReactive } from './PositionTable.ts'
 import type { AbideFile } from './parseAbide.ts'
 import { NO_PROPS, type Origin, type Span } from './projectShadow.ts'
 import { CHECKED_SUFFIX } from './ShadowMap.ts'
-import { SERVER_SPECIFIER } from './SPECIFIERS.ts'
 import { abideImports } from './splitImports.ts'
 
 // 38.3 — A `.abide` FILE AS THE PROGRAM IT RUNS AS, for the checker to report on. The projection
@@ -48,10 +48,11 @@ export const COMPONENT_STAND_IN = '__component'
  */
 function componentModule(props: string, generics?: string): string {
     // 34.13 — generic over what the file's `<script>` declares, so a caller's props infer it, the
-    // signature's own parameters shadowing the opaque stand-ins the body was checked against.
+    // signature's own parameters shadowing the opaque stand-ins the body was checked against. 34.16 —
+    // a component no prop is required of is called with none, as the runtime's bound face takes it.
     const parameters = generics === undefined ? '' : `<${generics}>`
     return `
-declare const ${COMPONENT_STAND_IN}: ${parameters}(record: ${props}) => import('${SERVER_SPECIFIER}').Component
+declare const ${COMPONENT_STAND_IN}: ${parameters}(...record: {} extends ${props} ? [record?: ${props}] : [record: ${props}]) => import('${SERVER_SPECIFIER}').Component
 export default ${COMPONENT_STAND_IN}
 `
 }
@@ -141,15 +142,22 @@ function propsOf(lowering: Lowering): string {
  * Nothing where the file files none.
  */
 function configDeclarations(lowering: Lowering): string {
+    const bound: string[] = []
+    for (const read of lowering.answer.reads)
+        if (read.shape === 'config')
+            bound.push(`${CHECKED_CONFIG}${read.start}`)
+    return configInterface(bound)
+}
+
+/** `Config` extended by what each of `bound` holds — the binding of one `onConfig` call each. */
+function configInterface(bound: readonly string[]): string {
+    if (bound.length === 0) return ''
     let aliases = ''
     let names = ''
-    for (const read of lowering.answer.reads) {
-        if (read.shape !== 'config') continue
-        const name = `${CHECKED_CONFIG}${read.start}`
+    for (const name of bound) {
         aliases += `type ${name}Type = typeof ${name}\n`
         names += names === '' ? `${name}Type` : `, ${name}Type`
     }
-    if (names === '') return ''
     return `declare function ${CHECKED_CONFIG_OF}<Options>(on: (defaults: never, options?: Options) => () => void): <Defaults>(defaults: ((env: import('${SERVER_SPECIFIER}').Env) => Defaults) | null, options?: Options) => [Defaults] extends [object] ? Pick<Defaults, keyof Defaults> : {}
 ${aliases}declare module '${SERVER_SPECIFIER}' {
     interface Config extends ${names} {}
@@ -157,6 +165,31 @@ ${aliases}declare module '${SERVER_SPECIFIER}' {
 `
 }
 
+// A call standing as a statement at a module's top level, as a formatted module writes one.
+const TOP_LEVEL_CONFIG = /^onConfig\s*\(/gm
+
+/**
+ * 27.13 FOR A HANDLER FILE, the one module that is no `.abide` and may call a hook (37.13): its
+ * text with each `onConfig(…)` at its top level bound as the lowering binds a server block's, and
+ * `Config` extended by each, or `undefined` where it files none.
+ *
+ * A MODULE OF ITS OWN BESIDE THE FILE, which the checker reads and nothing reports on: the file's own
+ * text is the one its diagnostics are placed in, and binding a call shifts every column after it.
+ */
+export function moduleConfigShadow(text: string): string | undefined {
+    const bound: string[] = []
+    let out = ''
+    let from = 0
+    for (const found of text.matchAll(TOP_LEVEL_CONFIG)) {
+        const name = `${CHECKED_CONFIG}${bound.length}`
+        bound.push(name)
+        out += `${text.slice(from, found.index)}const ${name} = ${CHECKED_CONFIG_OF}(onConfig)(`
+        from = found.index + found[0].length
+    }
+    if (bound.length === 0) return undefined
+    return `${out}${text.slice(from)}\n${configInterface(bound)}`
+}
+
 /**
  * Points each `.abide` import in the script blocks at its checked module, and moves `origins` to
  * match.