@abide/abide 0.58.0 → 0.101.0

package/src/compiler/emitComponent.ts

@@ -0,0 +1,162 @@
+import { type CheckerAnswer, UNCHECKED } from './CheckerAnswer.ts'
+import { Cursor, placeTemplate } from './Cursor.ts'
+import { Lowering, PROPS } from './Lowering.ts'
+import type { AbideFile } from './parseAbide.ts'
+import {
+    concat,
+    definitions,
+    HEADS,
+    headSink,
+    renderLevel,
+    renderMarkup,
+    SERVER_LANE,
+} from './renderMarkup.ts'
+import { SERVER_SPECIFIER } from './SPECIFIERS.ts'
+import { insideShare, SETTLED_AT, shareScope } from './shareScope.ts'
+import { splitImports, withoutProps } from './splitImports.ts'
+
+// The name the body is bound to while a component's head contributions land (`HEADS`).
+const BODY = '__body'
+// A page's or a layout's deferred build (41.19).
+const BUILT = '__built'
+const BUILD = '__build'
+
+/**
+ * The server module for a parsed `.abide` file: one ESM module exporting its component.
+ *
+ * The `<script>` body is copied VERBATIM into the component function, which is the whole of 19.11
+ * at this stage: the compiler does not read the expression grammar, so anything TypeScript accepts
+ * survives.
+ *
+ * The component returns its head and its body apart. 39.3 is why the split is HERE and not in
+ * `render`: the hoist is a compile-time partition of the template, so the emitted function has
+ * two returns rather than one string a renderer has to go looking through. 35.5 is answered by
+ * `render`, which turns the two into the byte stream a document is served as.
+ *
+ * `settles` IS A PAGE OR A LAYOUT, which `render` builds a level at a time (41.19): its setup runs
+ * at the call and its markup is built on the first read of `head` or `body`, so the calls the
+ * setup started are given the turn to answer that a component built inside its caller's markup is
+ * not. Every other component builds where it is called, and pays nothing for the difference.
+ */
+export function emitComponent(
+    file: AbideFile,
+    answer: CheckerAnswer = UNCHECKED,
+    settles = false,
+    /** Where each specifier this file imports landed in the build (`splitImports`). */
+    landed: ReadonlyMap<string, string> = new Map(),
+): string {
+    // Only what the page actually uses. An emitted module carrying an import nothing calls is a
+    // name the app's own tooling reports as unused, in a file nobody wrote.
+    const lowering = new Lowering(file, answer)
+
+    const page = new Cursor()
+    page.components = file.components
+    placeTemplate(file.template, page)
+    const body = renderLevel(page.top, lowering, SERVER_LANE)
+    // 32.43 — the template's own components, declared where the body is built: they read the
+    // setup's names, and a child they invoke adds its head to the body's.
+    const declared = definitions(page, lowering)
+
+    // EMITTED AFTER THE BODY, NOT BEFORE. 39.12 merges across the whole FILE, so a second `<head>`
+    // further down the template shadows the first one's `<title>` — and rendering a node adds to
+    // `Lowering.used` (`lowering.use`), so emitting a contribution the merge then drops leaves the
+    // module importing a name nothing calls. `headSink` is the client lane's too, which is what keeps the two from drifting.
+    const head = renderMarkup(headSink(file), lowering, SERVER_LANE)
+
+    // 31.1 and 31.4 hold INSIDE a `.abide` file, not just in its template, so the script block is
+    // lowered with the same rewrite the slots get.
+    //
+    // 34.2 — A `<script module>` IS MODULE SCOPE, here as in the browser, so what it exports is the
+    // module's (34.17). What must stay per request is a `reactive`, which is by 11.32 wherever it
+    // is declared.
+    const moduleSetup = splitImports(lowering.modules(), '', landed)
+    const setup = splitImports(lowering.scripts(), '', landed)
+    const componentBody = setup.body
+
+    // A child invoked inside `<head>` pushes to the same array from the head expression.
+    const heads =
+        head.includes(HEADS) ||
+        declared.includes(HEADS) ||
+        body.some((part) => part.includes(HEADS))
+    // 10.5 — around the setup that calls `reactive.share`, and the body whose children are
+    // rendered inside it and find it on the way up.
+    const { opened, closed } = shareScope(lowering, '    ')
+
+    // THE SETUP IS NOT RE-INDENTED. Adding a margin to every line rewrites the INSIDE of a
+    // multi-line template literal, so `\`line one\nline two\`` gains four spaces it never had —
+    // a changed string constant, in a file nobody reads.
+    // 39.1 THROUGH A COMPONENT. A child contributes to the document head as a page does, and the
+    // call that renders it stands inside the BODY expression — so the heads are collected as the
+    // body is built and the body is bound to a name before the return reads them. The array is
+    // emitted only where the page invokes something: a page with no component pays nothing.
+    // `head` is read before `__heads.join` in the return, so a child in the head lands too.
+    const build = `${heads ? `    const ${HEADS} = []\n` : ''}${declared}\
+    const ${BODY} = ${concat(body)}
+    return {
+        head: ${head}${heads ? ` + ${HEADS}.join('')` : ''},
+        body: ${BODY},
+    }`
+    // 41.19 — BUILT ON THE FIRST READ, and ONCE: `render` reads `head` and then `body`, and a
+    // child the markup invokes must not be set up twice. The build resumes the share scope the
+    // setup ran in (10.5), since by the time it is read the caller's has long been left — and that
+    // scope is `scope` on the answer, so `composePage` sets the level below up inside it too.
+    const level = settles
+        ? `    const ${SETTLED_AT} = ${lowering.use('currentShare')}()
+    let ${BUILT}
+    const ${BUILD} = () => {
+        if (${BUILT} !== undefined) return ${BUILT}
+        ${insideShare(lowering, SETTLED_AT, `${BUILT} = (() => {\n${build}\n})()`)}
+        return ${BUILT}
+    }
+    return {
+        scope: ${SETTLED_AT},
+        get head() { return ${BUILD}().head },
+        get body() { return ${BUILD}().body },
+    }`
+        : build
+    return `${moduleImports(lowering, () => SERVER_SPECIFIER, [moduleSetup, setup])}
+${moduleSetup.body === '' ? '' : `${moduleSetup.body}\n`}export default function Component(${lowering.takesProps() ? `${PROPS} = {}` : ''}) {
+${opened}${componentBody}
+${level}${closed}
+}
+`
+}
+
+/**
+ * An emitted module's imports: each framework name `lowering` used, from the specifier it ships
+ * under, and the author's own from both script blocks, already pointed where they landed
+ * (`splitImports`).
+ *
+ * ASKED LAST, because `used` fills as the module is emitted.
+ */
+export function moduleImports(
+    lowering: Lowering,
+    specifierOf: (name: string) => string,
+    scripts: readonly { imports: string }[],
+): string {
+    const names = new Map<string, string[]>()
+    for (const name of [...lowering.used].sort()) {
+        const specifier = specifierOf(name)
+        names.set(specifier, [...(names.get(specifier) ?? []), name])
+    }
+    let out = ''
+    for (const specifier of [...names.keys()].sort())
+        out += `import { ${importClause(names.get(specifier) as string[])} } from '${specifier}'\n`
+    for (const script of scripts) out += withoutProps(script.imports)
+    return out
+}
+
+/**
+ * The braces of a framework import: each name bound as `name as __name`.
+ *
+ * EVERY FRAMEWORK NAME IS BOUND UNDER `__`, the namespace an author does not write in: the escaping
+ * helpers are public on `@abide/abide`, so an author may import the same name into the same `<script>` —
+ * `import { safeUrl } from './mine.ts'` beside one `<a href={u}>` was
+ * `Identifier 'safeUrl' has already been declared` — and a `<script module>` declaring `setText` at
+ * module scope collides with a runtime import made as written just the same.
+ */
+function importClause(names: string[]): string {
+    const written: string[] = []
+    for (const name of names) written.push(`${name} as __${name}`)
+    return written.join(', ')
+}

package/src/compiler/emitSource.ts

@@ -0,0 +1,91 @@
+import { fileKind } from '#shared/routePattern.ts'
+import type { CheckerAnswer } from './CheckerAnswer.ts'
+import { emitClient } from './emitClient.ts'
+import { emitComponent } from './emitComponent.ts'
+import type { AbideFile } from './parseAbide.ts'
+import {
+    markScoped,
+    namesViewTransition,
+    scopeCss,
+    scopeToken,
+} from './scopeStyles.ts'
+
+/**
+ * One `.abide`'s modules, in the mode the build compiles it in: its server module, its client
+ * module (`''` where it has none) and its scoped stylesheet.
+ *
+ * Everything that mode depends on is the path below the app root and whether another file invokes
+ * it (`componentGraph`), so a test handing over the same two facts compiles what the build would.
+ */
+export function emitSource(
+    relative: string,
+    file: AbideFile,
+    answer: CheckerAnswer,
+    invoked: boolean,
+    landed?: ReadonlyMap<string, string>,
+): {
+    server: string
+    client: string
+    sheet: string | undefined
+    /** 39.8 — whether a `<style>` names a view transition, read here rather than at run time. */
+    transitions: boolean
+} {
+    const kind = fileKind(relative)
+    // 34.4 — A COMPONENT WITH STYLES: its elements carry its token, and the styles, scoped,
+    // are a stylesheet its client module imports — which the bundle collects into the
+    // stylesheet the document links (38.24).
+    // 34.11 — each body's own `<style>`, scoped to the token its elements carry; the
+    // component's token is added only where a component-level `<style>` requires it.
+    const token = scopeToken(relative)
+    const componentStyled = file.styles.length > 0
+    const bodies = markScoped(
+        file.template,
+        token,
+        componentStyled ? [token] : [],
+        file.components,
+    )
+    let sheet: string | undefined
+    let transitions = false
+    if (componentStyled || bodies.length > 0) {
+        const styles = file.styles.join('\n')
+        sheet = scopeCss(styles, token)
+        transitions = namesViewTransition(styles)
+        for (const body of bodies) {
+            sheet += `\n${scopeCss(body.css, body.token)}`
+            transitions ||= namesViewTransition(body.css)
+        }
+    }
+    // 30.7 — A ROUTABLE PAGE CARRIES ITS OWN MARKUP for the same reason an invoked component
+    // does, and it is the same mechanism: a page the reader ARRIVED at was painted by the
+    // server and hydrates, and a page they NAVIGATED to is handed the empty anchor pair and
+    // fills it from the template in its own module. `emitClient`'s `fillEmpty` is
+    // what makes one module serve both, so "routable" joins "invoked" as a module that fills
+    // itself — and parts from it in how OFTEN it can be filled, which is what decides whether
+    // the fill is markup or a build, and in carrying a head (`SelfFill`).
+    // 35.1 — A LAYOUT CARRIES ITS OWN MARKUP for the same reason a routable page does:
+    // nothing imports it, the router is what invokes it, and a reader who navigated to a
+    // page under it may arrive with the layout already standing or with nothing at all.
+    // An `error.abide` is never navigated to — only the server holds the error table.
+    const routed = kind === 'page' || kind === 'layout'
+    // The client module is emitted only where there is something to hydrate, or where something
+    // fills or imports it by name (`emitClient` answers which). A static component nothing invokes
+    // has no `.client.ts`, so a file shipping no runtime is a fact about the build rather than a
+    // claim about the bundler.
+    const client = emitClient(
+        file,
+        answer,
+        invoked ? (routed ? 'both' : 'invoked') : routed ? 'routed' : 'none',
+        landed,
+    )
+    const name = relative.slice(relative.lastIndexOf('/') + 1)
+    return {
+        // 41.19 — a page and a layout are built a level at a time by `render`.
+        server: emitComponent(file, answer, kind !== 'component', landed),
+        client:
+            client !== '' && sheet !== undefined
+                ? `import './${name.replace(/\.abide$/, '.style.css')}'\n${client}`
+                : client,
+        sheet,
+        transitions,
+    }
+}

package/src/compiler/formatDiagnosis.ts

@@ -0,0 +1,19 @@
+import { relative } from 'node:path' // bun exposes no path helpers of its own
+import type { Diagnosis } from './TypeSession.ts'
+
+/**
+ * One finding as one `tsc`-style line.
+ *
+ * ONE LINE A FINDING, in the shape `tsc` and every editor's problem matcher already read:
+ * `file:line:column - error TS2322: …`, the path relative to where the command was run. A finding
+ * with no line — a whole-file or whole-app refusal — names the file alone.
+ */
+export function formatDiagnosis(diagnosis: Diagnosis, from: string): string {
+    const path = relative(from, diagnosis.path) || diagnosis.path
+    const where =
+        diagnosis.line === 0
+            ? path
+            : `${path}:${diagnosis.line}:${diagnosis.column}`
+    const code = diagnosis.code === 0 ? '' : ` TS${diagnosis.code}`
+    return `${where} - ${diagnosis.category}${code}: ${diagnosis.message}`
+}

package/src/compiler/handlersUnder.ts

@@ -0,0 +1,112 @@
+// 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.
+//
+// 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.
+
+import type { Mount } from '#server/answerRpc.ts'
+import { namesUnder } from '#server/namesUnder.ts'
+import { RPC_ADDRESS } from '#shared/ADDRESSES.ts'
+import { declaredExports } from './declaredExports.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
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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.
+ */
+export async function handlersUnder(
+    root: string,
+    session: TypeSession,
+): Promise<{ mounts: Mount[]; warnings: Diagnosis[] }> {
+    const modules = modulesUnder(root)
+    const paths: string[] = []
+    for (const { source } of modules) paths.push(`${root}/${source}`)
+    const project = await session.project()
+    const declared =
+        project === undefined
+            ? []
+            : 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)
+                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.`,
+                )
+            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)
+                throw new Error(
+                    `abide: ${owner} and ${source} both declare a handler at ${address}. RULEBOOK 19.1.`,
+                )
+            owners.set(address, source)
+            mounts.push({
+                address,
+                method,
+                source,
+                name: exported,
+                ui,
+                cli,
+                mcp,
+                description,
+                copy,
+                defaults,
+                args,
+            })
+            warnings.push(...unread)
+        }
+    }
+    return { mounts, warnings }
+}

package/src/compiler/index.ts

@@ -0,0 +1,15 @@
+// The compiler — `.abide` source in, ESM modules out. Build time only, and resolvable by a build
+// as `@abide/abide/compiler`.
+//
+// It is its own seam rather than a folder under #server, and the distinction survives being
+// public: `@abide/abide/server` is what an app's REQUEST PATH imports, so a compiler reachable from it
+// is one `export *` away from putting a bundler in an app's server graph. A separate entry is
+// 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.
+
+export { componentGraph } from './componentGraph.ts'
+export { emitClient, type SelfFill } from './emitClient.ts'
+export { emitComponent } from './emitComponent.ts'
+export { type AbideFile, parseAbide } from './parseAbide.ts'
+export type { Attribute, TemplateNode } from './TemplateNode.ts'
+export { TypeSession } from './TypeSession.ts'

package/src/compiler/invocationProps.ts

@@ -0,0 +1,67 @@
+// 32.17 — WHAT A COMPONENT INVOCATION HANDS ITS CHILD, as the entries of the props record both lanes
+// write: one accessor per prop (33.4). Written once, because the server calls the child with this
+// record and the browser mounts it with the same one, and two copies are two answers to what a tag
+// passes.
+//
+// 32.11, 33.12, 33.13 — SPREADS FIRST, IN SOURCE ORDER, then every explicit prop: an explicit prop
+// beats a spread whatever the order the author wrote them in, and two spreads resolve as written.
+// 32.6 — `bind:prop` passes the caller's own `Reactive` behind the prop's accessor, which reads it
+// like any prop and hands the `Reactive` over to a child that writes (`boundProp`). Any prop takes
+// one, whatever the child declares (33.8).
+
+import { propKeyOf } from './classifyTemplate.ts'
+import type { Lowering } from './Lowering.ts'
+import { holdsReactive } from './PositionTable.ts'
+import type { ElementNode, InlineComponent } from './TemplateNode.ts'
+
+/** The props-record entries a component tag hands its child: spreads first, then each prop. */
+export function invocationProps(
+    node: ElementNode,
+    lowering: Lowering,
+): string[] {
+    const spreads: string[] = []
+    const explicit: string[] = []
+    for (const attribute of node.attributes) {
+        if (attribute.name === '...') {
+            spreads.push(
+                `...${lowering.use('spreadProps')}(() => (${lowering.expression(attribute)}))`,
+            )
+            continue
+        }
+        const key = propKeyOf(attribute)
+        if (key === undefined)
+            throw new Error(
+                `abide: ${attribute.name} on <${node.tag}> is not a prop a component takes — \`bind:\` hands over the \`Reactive\` in its braces (32.6), and \`class:\` and \`style:\` set an element's own class and style. RULEBOOK 32.10.`,
+            )
+        // A STATIC PROP IS STILL AN ACCESSOR. One shape per prop whatever the call site spelled
+        // (33.10), so the child reads every key the same way and a literal is not a second case.
+        if (holdsReactive(lowering.projection.slots.get(attribute))) {
+            explicit.push(
+                `${JSON.stringify(key)}: ${lowering.use('boundProp')}(() => (${lowering.reference(attribute)}))`,
+            )
+            continue
+        }
+        const value = attribute.expression
+            ? lowering.expression(attribute)
+            : JSON.stringify(attribute.value)
+        explicit.push(`${JSON.stringify(key)}: () => (${value})`)
+    }
+    // 32.50 — a component written between the tags is the prop of its name, the one each lane's
+    // region declares under `passedName`, so every read of the accessor is the same function (32.35).
+    for (const passed of node.passed)
+        explicit.push(
+            `${JSON.stringify(passed.name)}: () => ${passedName(passed)}`,
+        )
+    return [...spreads, ...explicit]
+}
+
+/**
+ * What a region declares an inline component passed to an invocation under (32.50).
+ *
+ * Not its own name, which is in scope nowhere around the invocation (32.51): numbered by where it
+ * is written, which is unique in its file. Its own name is the function expression's, so its body
+ * still invokes itself (32.44).
+ */
+export function passedName(component: InlineComponent): string {
+    return `__passed${component.at}`
+}

package/src/compiler/isNamedAlone.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether `subject` is one identifier and nothing else.
+ *
+ * The case 32.32 keys by the value's own `by`, and a component tag a call can spell
+ * (`projectShadow`).
+ */
+export function isNamedAlone(subject: string): boolean {
+    return /^[\p{ID_Start}$_][\p{ID_Continue}$\u200c\u200d]*$/u.test(subject)
+}

package/src/compiler/lineOf.ts

@@ -0,0 +1,38 @@
+import type { Diagnosis } from './TypeSession.ts'
+
+/**
+ * An offset into a file's text as the line and column an editor shows, both from 1.
+ *
+ * 38.3.
+ */
+export function lineOf(
+    text: string,
+    offset: number,
+): { line: number; column: number } {
+    let line = 1
+    let lineStart = 0
+    const end = Math.min(offset, text.length)
+    for (let at = 0; at < end; at += 1)
+        if (text.charCodeAt(at) === 10) {
+            line += 1
+            lineStart = at + 1
+        }
+    return { line, column: end - lineStart + 1 }
+}
+
+/** abide's own finding at `offset` into `text`, or at line 0 where the text was not handed in. */
+export function diagnosisAt(
+    path: string,
+    text: string | undefined,
+    offset: number,
+    category: Diagnosis['category'],
+    message: string,
+): Diagnosis {
+    return {
+        path,
+        ...(text === undefined ? { line: 0, column: 0 } : lineOf(text, offset)),
+        code: 0,
+        category,
+        message,
+    }
+}