@abide/abide 0.101.0 → 0.103.0

package/src/compiler/appMap.ts

@@ -0,0 +1,96 @@
+// 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, modules } = 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 })
+    // 37.1 — A MODULE THAT IS NEITHER files at the root: it runs as it is imported, before the
+    // importing file's route is set.
+    for (const file of modules)
+        for (const hook of hooksCalled(readFileSync(`${root}/${file}`, 'utf8')))
+            hooks.push({ hook, route: '/', 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.20 — 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

@@ -1,13 +1,16 @@
 import { relative } from 'node:path' // bun exposes no path helpers of its own
-import { buildDirectory } from '#server/buildDirectory.ts'
+import { appFiles } from '#server/appTree.ts'
+import { placeOf } from '#shared/routePattern.ts'
 import {
     type AppChecker,
     emitApp,
     resolverIn,
     sourcesUnder,
     withChecker,
+    withDependencies,
 } from './compileApp.ts'
 import { abideImportsOf } from './componentGraph.ts'
+import { projectShadow } from './projectShadow.ts'
 import {
     parseSources,
     type ReadSource,
@@ -36,10 +39,34 @@ export async function checkApp(
     const { root, sources } = await sourcesUnder(appRoot)
     return withChecker(root, kept, async (session) => {
         const refused: Diagnosis[] = []
-        const parsed = parseSources(sources, refused)
+        const own = parseSources(sources, refused)
+        // 23.16-23.18 — what the build's walk would refuse of the tree, at each file it names.
+        const { handlers } = appFiles(root, (path, message) => {
+            refused.push(refusal(`${root}/${path}`, message))
+        })
+        const resolve = resolverIn()
+        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.23), and
+        // what is wrong inside a package is the package's to report.
+        const reported: ReadSource[] = []
+        for (const source of read)
+            if (placeOf(relative(root, source.path)) !== 'dependency')
+                reported.push(source)
         const { diagnoses: found, refused: loweringRefused } =
-            await session.diagnose(read, root)
+            await session.diagnose(reported, root)
         const { ambient, unkeyed } = await session.lints(root, parsed)
         // A FILE WHOSE LOWERING REFUSED is `found` already, at its line — emitted too, it throws the
         // same refusal at the root and takes the rest of the app's findings with it.
@@ -54,7 +81,13 @@ export async function checkApp(
                             root,
                             session,
                             emittable,
-                            relative(root, buildDirectory(root)),
+                            resolve,
+                            handlerFiles,
+                            // 38.33 — each at its file, and every one rather than the first.
+                            (relative, thrown) =>
+                                refused.push(
+                                    refusal(`${root}/${relative}`, thrown),
+                                ),
                         )
                     ).warnings,
                 )
@@ -65,10 +98,12 @@ export async function checkApp(
     })
 }
 
+const FILES_CONFIG = /^\s*onConfig\s*\(/m
+
 /**
  * The findings for one file as an editor holds it, saved or not.
  *
- * 38.12 — ONE FILE AS AN EDITOR HOLDS IT, saved or not: the same findings `checkApp` has for it, for
+ * 38.11 — ONE FILE AS AN EDITOR HOLDS IT, saved or not: the same findings `checkApp` has for it, for
  * `abide lsp` to publish. The rest of the app is read from disk, as it stands — save a file `held`
  * has, which is one the editor holds too.
  *
@@ -78,12 +113,11 @@ export async function checkApp(
  */
 export async function checkSource(
     checker: AppChecker,
-    root: string,
     path: string,
     text: string,
     held: (path: string) => string | undefined = () => undefined,
 ): Promise<Diagnosis[]> {
-    const session = checker.session
+    const { session, root } = checker
     const refused: Diagnosis[] = []
     const [page] = parseSources([{ path, text }], refused)
     if (page === undefined) return refused
@@ -91,7 +125,7 @@ export async function checkSource(
     for (const imported of abideImportsOf(
         path,
         page.file,
-        resolverIn(root),
+        resolverIn(),
     ).values())
         try {
             imports.push({
@@ -102,6 +136,17 @@ export async function checkSource(
         } catch {
             // A component that cannot be read takes anything here.
         }
+    // 27.13 — AND EVERY FILE FILING `onConfig`, quietly, so a page that only reads `config()` is
+    // typed by defaults it never imported — as `checkApp`'s whole-app program types it. The scan
+    // only names candidates (a statement opening on the call); the checker decides which file.
+    const lowered = new Set(imports.map((one) => one.path))
+    const { sources } = await checker.sources()
+    for (const other of sources) {
+        if (other.path === path || lowered.has(other.path)) continue
+        const text = held(other.path) ?? other.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
     // takes anything here: a quiet source's refusal is reported by nobody.
     const { read, warnings } = await readSources(

package/src/compiler/checkedShadow.ts

@@ -1,6 +1,13 @@
+import { SERVER_SPECIFIER } from '#shared/SPECIFIERS.ts'
 import type { CheckerAnswer } from './CheckerAnswer.ts'
 import type { Finding } from './Finding.ts'
-import { CHECKED_VALUES, CHECKED_WRITE, Lowering } from './Lowering.ts'
+import {
+    CHECKED_CONFIG,
+    CHECKED_CONFIG_OF,
+    CHECKED_VALUES,
+    CHECKED_WRITE,
+    Lowering,
+} from './Lowering.ts'
 import { holdsReactive } from './PositionTable.ts'
 import type { AbideFile } from './parseAbide.ts'
 import { NO_PROPS, type Origin, type Span } from './projectShadow.ts'
@@ -18,7 +25,7 @@ import { abideImports } from './splitImports.ts'
 //
 // A `.abide` IMPORT NAMES ITS CHECKED MODULE, so a component a page imports resolves to something
 // the checker can read rather than to a file it cannot parse. What a checked module exports as its
-// default is a component taking what its `props` call declares, so a tag is held to it (38.41).
+// default is a component taking what its `props` call declares, so a tag is held to it (38.40).
 
 /** A `.abide` lowered as the program it runs as, with its runs mapped back to the projection. */
 export type CheckedShadow = {
@@ -35,15 +42,17 @@ export type CheckedShadow = {
 export const COMPONENT_STAND_IN = '__component'
 
 /**
- * The whole of what a checked module exports, and so all a module importing one sees of it: a
- * component, called with the record its tag passes (`projectShadow`'s `invocation`).
+ * The component a checked module exports as its default: called with the record its tag passes
+ * (`projectShadow`'s `invocation`), and answering the `Component` a server module's call of it
+ * renders (34.16). What its blocks export by name is beside it.
  */
 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}) => void
+declare const ${COMPONENT_STAND_IN}: ${parameters}(...record: {} extends ${props} ? [record?: ${props}] : [record: ${props}]) => import('${SERVER_SPECIFIER}').Component
 export default ${COMPONENT_STAND_IN}
 `
 }
@@ -61,6 +70,7 @@ export function checkedShadow(
     // Every span the emitters lower, with whether it holds the `Reactive` rather than reading it.
     const units: { span: Span; holds: boolean }[] = [
         { span: projection.modules, holds: false },
+        { span: projection.servers, holds: false },
         { span: projection.scripts, holds: false },
     ]
     for (const span of projection.slots.values())
@@ -101,6 +111,7 @@ export function checkedShadow(
         }\n`
     text += `declare const ${CHECKED_VALUES}: {\n${values}}\n`
     text += `declare function ${CHECKED_WRITE}<Cell extends { (): unknown; set(value: never): unknown }, Value extends Parameters<Cell['set']>[0]>(cell: Cell, value: Value): Value extends ReturnType<Cell> ? Value : ReturnType<Cell>\n`
+    text += configDeclarations(lowering)
     return {
         ...pointAtCheckedModules(text, origins, scriptsEnd),
         refusals: lowering.refusals,
@@ -123,6 +134,62 @@ function propsOf(lowering: Lowering): string {
               .replace(/\(\s*\)$/, '')}>`
 }
 
+/**
+ * 27.13 — WHAT EACH `onConfig` DEFAULTS IS DECLARED INTO `Config`, so `config().RETRIES` is the
+ * `number` its defaults return rather than the index's `unknown`. Each call is bound by the lowering
+ * (`CHECKED_CONFIG`) and typed by `CHECKED_CONFIG_OF` as what its defaults return; an interface can
+ * only extend a name, so each is aliased, and a union is narrowed to the keys every member has.
+ * 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 name of bound) {
+        aliases += `type ${name}Type = typeof ${name}\n`
+        names += names === '' ? `${name}Type` : `, ${name}Type`
+    }
+    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} {}
+}
+`
+}
+
+// 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 MODULE THAT IS NO `.abide` — a handler file, or one under a `server` directory: 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.

package/src/compiler/classifyRead.ts

@@ -27,10 +27,11 @@ import { REACTIVE_MEMBERS } from './REACTIVE_MEMBERS.ts'
  * statement ends and whether `{ n }` is a literal are TypeScript's answers rather than a token
  * walk's guess at them. Every offset is into the file's projection (`projectShadow`).
  *
- * ONE SHAPE IS NOT A REACTIVE NAME: `raw` is the callee of a template expression's bare `raw(…)`
- * (32.25), which lowers to the framework's own `raw`; a `<script>`'s is left as written. It rides
- * this list because it is a rewrite at an occurrence, which is what the splice walks; what the
- * checker proved about a whole position is `CheckerAnswer`'s.
+ * TWO SHAPES ARE NOT A REACTIVE NAME: `raw` is the callee of a template expression's bare `raw(…)`
+ * (32.25), which lowers to the framework's own `raw`; a `<script>`'s is left as written. `config`
+ * is the callee of an `onConfig(…)` statement in a `<script server>` (27.13), which only a checked
+ * lowering rewrites. They ride this list because each is a rewrite at an occurrence, which is what
+ * the splice walks; what the checker proved about a whole position is `CheckerAnswer`'s.
  *
  * THE SHAPE IS FIXED: every field on every read, so `Lowering`'s splice sees one hidden class.
  */
@@ -69,6 +70,7 @@ export type Read = {
         | 'restMember'
         | 'restWhole'
         | 'raw'
+        | 'config'
     /** What the rewrite replaces: the name, or a whole write or update from its first token. */
     from: number
     to: number

package/src/compiler/classifyTemplate.ts

@@ -132,7 +132,7 @@ export function classifyAttributes(
             // 32.10, 32.19 — THE PLAIN `style={expr}` OR `class={expr}` BESIDE A DIRECTIVE IS LEFT
             // UNBOUND. `setAttribute` replaces the whole merged value and takes the directives'
             // halves with it, and the two bindings then overwrite each other in whichever order
-            // they re-ran.
+            // they reran.
             //
             // ALLOWED, rather than refused. The page still RENDERS right — the server writes both
             // halves into the one merged attribute — so the only thing a build error would buy is