@abide/abide 0.100.0 → 0.102.0

package/src/compiler/handlersUnder.ts

@@ -1,73 +1,83 @@
-// 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` answering at the path alone.
+// 16.2 AND 19.15 — EVERY HANDLER AN APP DECLARES, AND WHERE IT IS ANSWERED. A handler is an export
+// of a `<script server>` in a `.abide` of the app's own, and its address is that file's
+// route — its directory's (23.14) — and then the export's name. A directory's handlers may sit in as
+// many of its files as an author likes; two of them exporting one name is 19.1's refusal.
 //
-// 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 blocks SAY rather than by importing them,
+// so a build never runs server code: a server block 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
+// the file's projection 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.
 
 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 { parseRoutePattern, placeOf, routeOf } from '#shared/routePattern.ts'
 import { declaredExports } from './declaredExports.ts'
+import type { AbideFile } from './parseAbide.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 `.abide` the build read, by its path and its path below the app's root. */
+type Source = {
+    path: string
+    relative: string
+    /** 23.19 — the path it answers by: its own, or the one its mount gives it. */
+    position: string
+    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.
- */
-export function declaresHandlers(root: string): boolean {
-    return modulesUnder(root).length > 0
-}
+const TRANSPILER = new Bun.Transpiler({ loader: 'ts' })
+
+// 19.22 — as the transpiler prints it, one statement to a line; `export * as name` names its export.
+const STAR_EXPORT = /^export \* from /m
 
 /**
  * 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[],
 ): Promise<{ mounts: Mount[]; warnings: Diagnosis[] }> {
-    const modules = modulesUnder(root)
-    const paths: string[] = []
-    for (const { source } of modules) paths.push(`${root}/${source}`)
+    // 34.31 — a dependency's server block has no address of its own: what it declares is mounted
+    // where a file of the app's re-exports it, and as that file's.
+    const serving: Source[] = []
+    for (const source of sources) {
+        if (source.file.servers.length === 0) continue
+        if (
+            STAR_EXPORT.test(
+                TRANSPILER.transformSync(source.file.servers.join('\n')),
+            )
+        )
+            throw new Error(
+                `abide: ${source.relative} re-exports with \`export *\` from its <script server>, whose names the build cannot read without running it. Name each handler it re-exports. RULEBOOK 19.22.`,
+            )
+        if (placeOf(source.position) !== 'dependency') serving.push(source)
+    }
     const project = await session.project()
     const declared =
-        project === undefined
+        project === undefined || serving.length === 0
             ? []
-            : await declaredExports(project, session.tsconfig, paths)
+            : await declaredExports(
+                  project,
+                  session.tsconfig,
+                  serving.map((source) => session.projectionOf(source.path)),
+              )
     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
+    const names = new Map<string, string>()
+    for (let at = 0; at < serving.length; at += 1) {
+        const { relative, position, file } = serving[at] as Source
+        const route = routeOf(position)
+        // 19.15 — what THE SERVER BLOCK exports, out of everything the file's module does: its
+        // component and its `<script module>`'s names are the module's own.
+        const exported = new Set(
+            TRANSPILER.scan(file.servers.join('\n')).exports,
+        )
         for (const {
-            name: exported,
+            name,
             method,
             ui,
             cli,
@@ -78,22 +88,27 @@ export async function handlersUnder(
             args,
             unread,
         } of declared[at] ?? []) {
+            if (!exported.has(name)) continue
             if (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} exports \`${name}\` from its <script server>, which is not declared as a handler. A server block exports handlers alone, each declared by abide's \`GET(…)\` (or POST, PUT, PATCH, DELETE); anything else belongs in a module of its own. RULEBOOK 19.15.`,
                 )
-            const address = `${RPC_ADDRESS}/${path}${exported === 'default' ? '' : `/${exported}`}`
-            const owner = owners.get(address)
-            if (owner !== undefined)
+            const address = `${route === '/' ? '' : route}/${name}`
+            refuseFrameworkRoute(address, relative)
+            refuseUndeclaredParameters(address, args, relative, name)
+            // 20.13 — one name per handler on every generated surface.
+            const surface = surfaceName(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,
+                source: relative,
+                name,
                 ui,
                 cli,
                 mcp,
@@ -107,3 +122,38 @@ export async function handlersUnder(
     }
     return { mounts, warnings }
 }
+
+/**
+ * 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,
+    exported: 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}'s \`${exported}\` answers at ${address}, and its args do not declare \`${segment.name}\`. RULEBOOK 16.67.`,
+        )
+    }
+}

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,138 @@
+// 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` 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.27); 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 { abideUnder } 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` under it at the position it takes in the app. */
+export type Mounted = {
+    specifier: string
+    directory: string
+    files: 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,
+): Mounted[] | string {
+    const mounts: Mounted[] = []
+    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.`
+            const files: Placed[] = []
+            for (const below of abideUnder(directory))
+                files.push({
+                    path: `${directory}/${below}`,
+                    position: `${at}${below}`,
+                })
+            mounts.push({ specifier, directory, files })
+        }
+    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
+    }
+}