@abide/abide 0.101.0 → 0.103.0

package/src/compiler/handlersUnder.ts

@@ -1,112 +1,200 @@
-// 16.2 AND 19.1 — EVERY HANDLER AN APP DECLARES, AND WHERE IT IS ANSWERED. A handler is an export of
-// a module under `server/rpc`, and its address is the module's path below that directory and then
-// the export's name — `default`, or an export named as its file, answering at the path alone.
+// 16.2 AND 16.70 — EVERY HANDLER AN APP DECLARES, AND WHERE IT IS ANSWERED. A handler file's default
+// export answers at that file's route (23.14), and is the app's public surface; a handler a
+// `<script server>` declares is its file's alone, answered below `/__abide/handlers/` at the file's
+// path and its binding's name, and listed nowhere (16.71).
 //
-// READ, NOT RUN. The build finds handlers by what their modules SAY rather than by importing them,
-// so a build never runs server code: an app's module may open a database at import, and nothing
-// about building a browser bundle is a reason to. The checker the build already holds lists what a
-// module exports and which call declares each (19.15) — which is also what makes an export that is
-// not a handler a refusal here rather than an address that silently never answers.
+// READ, NOT RUN. The build finds handlers by what their files SAY rather than by importing them,
+// so a build never runs server code: a handler file may open a database at import, and nothing
+// about building a browser bundle is a reason to. The checker the build already holds lists what
+// each module exports and which call declares each (16.73) — which is also what makes an export
+// that is not a handler a refusal here rather than an address that silently never answers.
 
 import type { Mount } from '#server/answerRpc.ts'
-import { namesUnder } from '#server/namesUnder.ts'
-import { RPC_ADDRESS } from '#shared/ADDRESSES.ts'
+import { refuseFrameworkRoute } from '#server/appTree.ts'
+import { surfaceName } from '#server/surfaceOf.ts'
+import { PRIVATE_HANDLERS_ADDRESS } from '#shared/ADDRESSES.ts'
+import {
+    parseRoutePattern,
+    placeOf,
+    routeOf,
+    scopeOf,
+} from '#shared/routePattern.ts'
 import { declaredExports } from './declaredExports.ts'
+import type { AbideFile } from './parseAbide.ts'
+import { PRIVATE_EXPORT } from './projectShadow.ts'
 import type { Diagnosis, TypeSession } from './TypeSession.ts'
 
-const HANDLER_DIRECTORY = 'server/rpc'
-
-// One module under the tree: where it is from the root, and its address path below the tree.
-type HandlerModule = { source: string; path: string }
-
-/** Every module under `server/rpc`. */
-function modulesUnder(root: string): HandlerModule[] {
-    const modules: HandlerModule[] = []
-    for (const name of namesUnder(
-        `${root}/${HANDLER_DIRECTORY}`,
-        '**/*.ts',
-    ).sort())
-        modules.push({
-            source: `${HANDLER_DIRECTORY}/${name}`,
-            path: name.replace(/\.ts$/, ''),
-        })
-    return modules
+/** A handler file, by its path and its path below the app's root. */
+export type HandlerFile = {
+    path: string
+    relative: string
+    /** 23.19 — the path it answers by: its own, or the one its mount gives it. */
+    position: string
 }
 
+/** A `.abide` the build read. */
+type Source = HandlerFile & { file: AbideFile }
+
 /**
- * Whether the app has any module under `server/rpc`.
- *
- * Asked before a checker is opened to read it: an app of handlers alone has no `.abide` to say it
- * is an app.
+ * Told of each thing the emit refuses, at the file below the root it names. The build's throws;
+ * `abide check` collects every one at its file (38.33).
  */
-export function declaresHandlers(root: string): boolean {
-    return modulesUnder(root).length > 0
+export type Refuse = (relative: string, thrown: unknown) => void
+
+/** The build's answer to a refusal: the first one stops it. */
+export const THROW: Refuse = (_relative, thrown) => {
+    throw thrown
 }
 
 /**
  * The app's handler mounts, with the warnings the build raised reading them.
  *
- * Off one read of the checker. 19.1 — one owner per address, and the error names both files. 18.15 —
- * with what the build could not read of a copy's options.
+ * Off one read of the checker. 18.15 — with what the build could not read of a copy's options.
+ * 19.1's one owner per route and method is `compileApp`'s, which holds the pages as well.
  */
 export async function handlersUnder(
-    root: string,
     session: TypeSession,
+    sources: readonly Source[],
+    files: readonly HandlerFile[],
+    refuse: Refuse = THROW,
 ): Promise<{ mounts: Mount[]; warnings: Diagnosis[] }> {
-    const modules = modulesUnder(root)
+    const serving: Source[] = []
+    for (const source of sources)
+        if (source.file.servers.length > 0) serving.push(source)
     const paths: string[] = []
-    for (const { source } of modules) paths.push(`${root}/${source}`)
-    const project = await session.project()
+    for (const file of files) paths.push(file.path)
+    const project = await session.projectWith(paths)
+    for (const source of serving) paths.push(session.projectionOf(source.path))
     const declared =
-        project === undefined
+        project === undefined || paths.length === 0
             ? []
             : await declaredExports(project, session.tsconfig, paths)
     const mounts: Mount[] = []
     const warnings: Diagnosis[] = []
-    const owners = new Map<string, string>()
-    for (let at = 0; at < modules.length; at += 1) {
-        const { source, path } = modules[at] as HandlerModule
-        for (const {
-            name: exported,
-            method,
-            ui,
-            cli,
-            mcp,
-            description,
-            copy,
-            defaults,
-            args,
-            unread,
-        } of declared[at] ?? []) {
-            if (method === undefined)
+    const names = new Map<string, string>()
+    for (let at = 0; at < files.length; at += 1) {
+        const { relative, position } = files[at] as HandlerFile
+        try {
+            const address = routeOf(position)
+            const exported = declared[at] ?? []
+            const handler = exported.find((each) => each.name === 'default')
+            // 16.73 — the default and nothing else, declared by one of the five methods.
+            for (const each of exported)
+                if (each.name !== 'default' || each.method === undefined)
+                    throw new Error(
+                        each.name === 'default'
+                            ? `abide: ${relative}'s default export is not declared as a handler. A handler file's default is declared by abide's \`GET(…)\` (or POST, PUT, PATCH, DELETE); anything else belongs under a lib directory. RULEBOOK 16.73.`
+                            : `abide: ${relative} exports \`${each.name}\`, and a handler file exports its handler as its default and nothing else. Move \`${each.name}\` into a module under a lib or a server directory. RULEBOOK 16.73.`,
+                    )
+            if (handler?.method === undefined)
                 throw new Error(
-                    `abide: ${source} exports \`${exported}\`, which is not declared as a handler. A module under ${HANDLER_DIRECTORY} exports handlers alone, each declared by abide's \`GET(…)\` (or POST, PUT, PATCH, DELETE); anything else belongs beside it. RULEBOOK 19.15.`,
+                    `abide: ${relative} is a handler file — a .ts directly in an address directory — and exports no handler as its default. Export one (\`export default GET(…)\`), or move the file into a lib directory. RULEBOOK 16.73, 23.22.`,
                 )
-            const atPath =
-                exported === 'default' ||
-                exported === path.slice(path.lastIndexOf('/') + 1)
-            const address = `${RPC_ADDRESS}/${path}${atPath ? '' : `/${exported}`}`
-            const owner = owners.get(address)
-            if (owner !== undefined)
+            refuseFrameworkRoute(address, relative)
+            refuseUndeclaredParameters(address, handler.args, relative)
+            // 20.13 — one name per handler on every generated surface.
+            const surface = surfaceName(handler.method, address)
+            const named = names.get(surface)
+            if (named !== undefined)
                 throw new Error(
-                    `abide: ${owner} and ${source} both declare a handler at ${address}. RULEBOOK 19.1.`,
+                    `abide: ${named} and ${relative} are both named ${surface} on the generated surfaces. RULEBOOK 20.13.`,
                 )
-            owners.set(address, source)
+            names.set(surface, relative)
             mounts.push({
                 address,
-                method,
-                source,
-                name: exported,
-                ui,
-                cli,
-                mcp,
-                description,
-                copy,
-                defaults,
-                args,
+                method: handler.method,
+                source: relative,
+                name: address.slice(address.lastIndexOf('/') + 1),
+                export: 'default',
+                scope: scopeOf(position),
+                private: false,
+                ui: handler.ui,
+                cli: handler.cli,
+                mcp: handler.mcp,
+                description: handler.description,
+                copy: handler.copy,
+                defaults: handler.defaults,
+                args: handler.args,
             })
-            warnings.push(...unread)
+            warnings.push(...handler.unread)
+        } catch (thrown) {
+            refuse(relative, thrown)
+        }
+    }
+    for (let at = 0; at < serving.length; at += 1) {
+        const { relative, position } = serving[at] as Source
+        // 34.24 — a dependency's file answers where a mount places it, and its handlers below the
+        // path it has there.
+        const below = placeOf(position) === 'dependency' ? relative : position
+        for (const each of declared[files.length + at] ?? []) {
+            if (each.method === undefined) continue
+            if (!each.name.startsWith(PRIVATE_EXPORT)) continue
+            const name = each.name.slice(PRIVATE_EXPORT.length)
+            mounts.push({
+                address: privateAddress(below, name),
+                method: each.method,
+                source: relative,
+                name,
+                export: each.name,
+                scope: scopeOf(position),
+                private: true,
+                ui: each.ui,
+                cli: false,
+                mcp: false,
+                description: each.description,
+                copy: each.copy,
+                defaults: each.defaults,
+                args: each.args,
+            })
+            warnings.push(...each.unread)
         }
     }
     return { mounts, warnings }
 }
+
+/**
+ * The address of the private handler `name` the `.abide` at `path` declares: below
+ * `PRIVATE_HANDLERS_ADDRESS`, the file's path without its extension, each segment's brackets and
+ * dots dropped so nothing in it reads as a parameter, then its name (16.70).
+ */
+export function privateAddress(path: string, name: string): string {
+    const segments: string[] = []
+    for (const segment of path.replace(/\.abide$/, '').split('/'))
+        if (segment !== '' && segment !== '..')
+            segments.push(segment.replace(/[[\].]/g, ''))
+    return `${PRIVATE_HANDLERS_ADDRESS}/${segments.join('/')}/${name}`
+}
+
+/**
+ * Throws where a handler's `Args` does not declare a parameter its route carries.
+ *
+ * 16.67 — read off the JSON Schema its annotation derives, which is what the wire holds the args
+ * to: a parameter the schema does not name would reach the handler as a key it never typed.
+ */
+function refuseUndeclaredParameters(
+    address: string,
+    args: unknown,
+    source: string,
+): void {
+    const schema = args as
+        | {
+              properties?: Record<string, unknown>
+              additionalProperties?: unknown
+          }
+        | undefined
+    // A record type — an index signature — declares every key.
+    const open =
+        schema?.additionalProperties !== undefined &&
+        schema.additionalProperties !== false
+    for (const segment of parseRoutePattern(address)) {
+        if (segment.kind === 'static' || open) continue
+        if (
+            schema?.properties !== undefined &&
+            segment.name in schema.properties
+        )
+            continue
+        throw new Error(
+            `abide: ${source} answers at ${address}, and its handler's args do not declare \`${segment.name}\`. RULEBOOK 16.67.`,
+        )
+    }
+}

package/src/compiler/hooksCalled.ts

@@ -0,0 +1,35 @@
+import { tokenize } from './tokenize.ts'
+
+/** Every hook abide exports, by name. */
+export const HOOK_NAMES: ReadonlySet<string> = new Set([
+    'middleware',
+    'onStart',
+    'onStop',
+    'onError',
+    'onConfig',
+    'onHealth',
+    'onPrincipal',
+    'onLauncher',
+    'onMenu',
+])
+
+/**
+ * Each of abide's hook names called in `source`, in the order written: the name, then `(`, and not
+ * a declaration — a member call included, since `server.onStart(…)` is abide's hook all the same.
+ * Read, not run — what `abide routes` lists and the build's refusals of a hook called where it is
+ * never read (38.107) go by.
+ */
+export function hooksCalled(source: string): string[] {
+    const called: string[] = []
+    let previous = ''
+    let named: string | undefined
+    for (const token of tokenize(source)) {
+        if (named !== undefined && token.text === '(') called.push(named)
+        named =
+            HOOK_NAMES.has(token.text) && previous !== 'function'
+                ? token.text
+                : undefined
+        previous = token.text
+    }
+    return called
+}

package/src/compiler/index.ts

@@ -7,6 +7,13 @@
 // reached only by something already doing a build. Nothing here is in any client bundle, and
 // `compiler.test.ts` holds the two apart by asserting what `@abide/abide/server` exports.
 
+// 34.14 — what serves what this compiles, to a bundle or to the runtime (`abideModules`).
+export {
+    abideModules,
+    type Compilation,
+    type CompiledFile,
+    serveCompilation,
+} from '#server/abideModules.ts'
 export { componentGraph } from './componentGraph.ts'
 export { emitClient, type SelfFill } from './emitClient.ts'
 export { emitComponent } from './emitComponent.ts'

package/src/compiler/mountsOf.ts

@@ -0,0 +1,150 @@
+// 23.19 — A PACKAGE'S DIRECTORY, MOUNTED WHERE THE APP SAYS.
+// `import 'kit/admin' with { type: 'routes' }` in a file of the app's places every `.abide` and
+// handler file under the package's `admin` directory at the importing file's directory, so its
+// pages, layouts, error pages and handlers answer below it — and the app, not the package, decides
+// where: the mount is a line in a file the app writes, at the position the app gave it.
+//
+// A FILE KEEPS ITS PATH AND GAINS A POSITION. It is compiled, served and keyed by where it lies, as
+// any dependency's is (34.23); its POSITION — the path it would have below the root — is what
+// `placeOf`, `fileKind` and `routeOf` read, so a mounted page is a page by the same test as the app's.
+
+import { readFileSync, realpathSync, statSync } from 'node:fs' // bun exposes no sync read, stat or realpath of its own
+import { dirname, relative, resolve } from 'node:path' // bun exposes no path helpers of its own
+import { appFiles } from '#server/appTree.ts'
+import { placeOf } from '#shared/routePattern.ts'
+import { nearest } from './nearest.ts'
+import { type AbideFile, parseAbide, scriptBodies } from './parseAbide.ts'
+import { attributedImports, IMPORT_ATTRIBUTES } from './splitImports.ts'
+
+/** A `.abide` on disk, and the position it takes in the app. */
+type Placed = { path: string; position: string }
+
+/**
+ * One directory a file mounts, and each `.abide` and each handler file under it at the position it
+ * takes in the app.
+ */
+type DirectoryMount = {
+    specifier: string
+    directory: string
+    /** The position its files take below the root: the mounting file's directory, `/`-ended. */
+    at: string
+    files: Placed[]
+    handlers: Placed[]
+}
+
+/**
+ * Every directory the file at `path` mounts, its position in the app being `position` — or the
+ * refusal naming what one of them cannot be.
+ *
+ * `root` is the app's, real: a directory under it is the app's own already, with a position of its
+ * own, and mounting it would give its files a second (23.20).
+ */
+export function mountsOf(
+    root: string,
+    path: string,
+    position: string,
+    file: AbideFile,
+): DirectoryMount[] | string {
+    const mounts: DirectoryMount[] = []
+    const at = position.includes('/')
+        ? `${position.slice(0, position.lastIndexOf('/'))}/`
+        : ''
+    for (const script of scriptBodies(file))
+        for (const { specifier } of attributedImports(script, 'routes')) {
+            const directory = mountedDirectory(specifier, dirname(path))
+            if (directory === undefined)
+                return `abide: ${position} mounts ${specifier}, and no directory answers to it. RULEBOOK 23.19.`
+            if (ownDirectory(root, directory))
+                return `abide: ${position} mounts ${specifier}, which is the app's own directory already. RULEBOOK 23.20.`
+            // The package's tree is the package's to refuse; a mount places what it finds.
+            const found = appFiles(directory, () => {})
+            const placed = (below: string): Placed => ({
+                path: `${directory}/${below}`,
+                position: `${at}${below}`,
+            })
+            mounts.push({
+                specifier,
+                directory,
+                at,
+                files: found.abide.map(placed),
+                handlers: found.handlers.map(placed),
+            })
+        }
+    return mounts
+}
+
+/**
+ * Every file mounted under the app at `root` whose own `.abide` are `relatives`, and every one those
+ * mount in turn, at its position — read for nothing but its mounts, and refusing nothing: the
+ * build is what refuses a mount (`withDependencies`).
+ *
+ * THE CHECKER'S `Routes` (30.26) asks this on every check, so a file is parsed only where its text
+ * names a mount at all.
+ */
+export function mountedUnder(
+    root: string,
+    relatives: readonly string[],
+): Placed[] {
+    const queue: Placed[] = []
+    for (const relative of relatives)
+        queue.push({ path: `${root}/${relative}`, position: relative })
+    const found: Placed[] = []
+    const seen = new Set<string>()
+    for (let at = 0; at < queue.length; at += 1) {
+        const { path, position } = queue[at] as Placed
+        const text = readFileSync(path, 'utf8')
+        if (!IMPORT_ATTRIBUTES.routes.test(text)) continue
+        let file: AbideFile
+        try {
+            file = parseAbide(text)
+        } catch {
+            continue
+        }
+        const mounts = mountsOf(root, path, position, file)
+        if (typeof mounts === 'string') continue
+        for (const mount of mounts)
+            for (const placed of mount.files) {
+                if (seen.has(placed.path)) continue
+                seen.add(placed.path)
+                found.push(placed)
+                queue.push(placed)
+            }
+    }
+    return found
+}
+
+// Under the root and not a dependency's there: one of the app's own, with positions of its own.
+function ownDirectory(root: string, directory: string): boolean {
+    if (directory === root) return true
+    const below = relative(root, directory)
+    return !below.startsWith('..') && placeOf(`${below}/-`) !== 'dependency'
+}
+
+/**
+ * The real directory `specifier` names from `from`: a relative path as written, and a bare one as a
+ * package and the path into it, found in the nearest `node_modules` above.
+ *
+ * A DIRECTORY, NOT A MODULE: a package's `exports` names its modules, and a mount asks for none of
+ * them, so its directory is found as bun would find the package and then walked.
+ */
+function mountedDirectory(specifier: string, from: string): string | undefined {
+    let candidate: string | undefined
+    if (specifier.startsWith('./') || specifier.startsWith('../'))
+        candidate = resolve(from, specifier)
+    else {
+        const parts = specifier.split('/')
+        const nameLength = specifier.startsWith('@') ? 2 : 1
+        const name = parts.slice(0, nameLength).join('/')
+        const inside = parts.slice(nameLength).join('/')
+        const found = nearest(from, `node_modules/${name}`)
+        if (found === undefined) return undefined
+        candidate = inside === '' ? found : `${found}/${inside}`
+    }
+    try {
+        return statSync(candidate).isDirectory()
+            ? realpathSync(candidate)
+            : undefined
+    } catch {
+        return undefined
+    }
+}

package/src/compiler/nearest.ts

@@ -0,0 +1,14 @@
+import { existsSync } from 'node:fs' // bun exposes no sync existence check of its own
+import { dirname } from 'node:path' // bun exposes no path helpers of its own
+
+/** The nearest file or directory at `name` at or above `from`, or `undefined`. */
+export function nearest(from: string, name: string): string | undefined {
+    let at = from
+    while (true) {
+        const candidate = `${at}/${name}`
+        if (existsSync(candidate)) return candidate
+        const up = dirname(at)
+        if (up === at) return undefined
+        at = up
+    }
+}