@abide/abide 0.58.0 → 0.101.0

package/src/lib/ui/compile/assertTranspiles.ts

@@ -1,19 +0,0 @@
-/*
-Fail-loud guard for generated code. The compile passes build modules as strings and
-AST — a corruption (an un-handled rewrite position, a generator bug, a stale lowering)
-otherwise ships as a broken bundle that fails opaquely at load. Transpiling the output
-turns it into a compile-time error naming the stage and showing the offending source.
-`context` labels which stage produced it. Compile-time only; never on the hot path.
-*/
-
-const transpiler = new Bun.Transpiler({ loader: 'ts' })
-
-export function assertTranspiles(code: string, context: string): void {
-    try {
-        transpiler.transformSync(code)
-    } catch (error) {
-        throw new Error(
-            `[abide] ${context} produced invalid syntax — please report this with the component source. Output:\n${code}\n\n${String(error)}`,
-        )
-    }
-}

package/src/lib/ui/compile/assetModulesFile.ts

@@ -1,32 +0,0 @@
-import { resolve } from 'node:path'
-
-/*
-A single virtual ambient-declaration file injected into the shadow world so the
-type-checker resolves bundler-handled asset imports instead of erroring "cannot
-find module". Bun bundles a stylesheet import for its side effect and resolves a
-static asset to its URL string; these declarations mirror that. One shared file
-(not a per-component preamble) keeps the wildcard module patterns declared once,
-which TypeScript requires. Used by both the check Program and the LSP service so
-the editor and CLI agree.
-*/
-export function assetModulesFile(cwd: string): { path: string; content: string } {
-    return {
-        path: resolve(cwd, '__abide_assets__.d.ts'),
-        content: [
-            "declare module '*.css' {}",
-            "declare module '*.scss' {}",
-            "declare module '*.sass' {}",
-            "declare module '*.less' {}",
-            "declare module '*.svg' { const src: string; export default src }",
-            "declare module '*.png' { const src: string; export default src }",
-            "declare module '*.jpg' { const src: string; export default src }",
-            "declare module '*.jpeg' { const src: string; export default src }",
-            "declare module '*.gif' { const src: string; export default src }",
-            "declare module '*.webp' { const src: string; export default src }",
-            "declare module '*.avif' { const src: string; export default src }",
-            "declare module '*.woff' { const src: string; export default src }",
-            "declare module '*.woff2' { const src: string; export default src }",
-            '',
-        ].join('\n'),
-    }
-}

package/src/lib/ui/compile/assignmentTargetNames.ts

@@ -1,54 +0,0 @@
-import ts from 'typescript'
-
-/*
-Collects every identifier NAME that is written somewhere in `source` — the target of
-an assignment (`x = …`, `x += …`, and every compound form) or the operand of a `++`/`--`
-update. A write to a member (`x.foo = …`, `x[i]++`) counts as a write to its root object
-identifier (`x`), since mutating the object the prop holds still needs a writable cell.
-Reads never count. Used to decide which props a component actually writes, so only those
-are upgraded from a read-only derive to a writable cell (`bindableProp`).
-
-Accumulates into `into` so several fragments (the script, each template expression) can
-feed one set. Best-effort and syntactic — it does not resolve scope, so a shadowing local
-of the same name is conservatively treated as a write to the prop; that only ever upgrades
-a prop needlessly, never drops a real write.
-*/
-export function assignmentTargetNames(source: ts.SourceFile, into: Set<string>): void {
-    const rootIdentifier = (node: ts.Expression): string | undefined => {
-        let current: ts.Expression = node
-        /* Peel member/element access and parens down to the base object identifier — every
-           one of these node kinds exposes the inner expression as `.expression`. */
-        while (
-            ts.isPropertyAccessExpression(current) ||
-            ts.isElementAccessExpression(current) ||
-            ts.isParenthesizedExpression(current) ||
-            ts.isNonNullExpression(current)
-        ) {
-            current = current.expression
-        }
-        return ts.isIdentifier(current) ? current.text : undefined
-    }
-    const visit = (node: ts.Node): void => {
-        if (
-            ts.isBinaryExpression(node) &&
-            node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
-            node.operatorToken.kind <= ts.SyntaxKind.LastAssignment
-        ) {
-            const name = rootIdentifier(node.left)
-            if (name !== undefined) {
-                into.add(name)
-            }
-        } else if (
-            (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
-            (node.operator === ts.SyntaxKind.PlusPlusToken ||
-                node.operator === ts.SyntaxKind.MinusMinusToken)
-        ) {
-            const name = rootIdentifier(node.operand as ts.Expression)
-            if (name !== undefined) {
-                into.add(name)
-            }
-        }
-        ts.forEachChild(node, visit)
-    }
-    visit(source)
-}

package/src/lib/ui/compile/asyncInterpolationFields.ts

@@ -1,152 +0,0 @@
-import { attrLiftPosition } from './attrLiftPosition.ts'
-import type { AsyncInterpolationField } from './types/AsyncInterpolationField.ts'
-import type { TemplateNode } from './types/TemplateNode.ts'
-
-/* No control-flow subject to record — the writeback for a content/attribute field. */
-const NO_OP = (): void => {}
-
-/*
-Enumerates the async-liftable interpolation fields of ONE template node — content text parts,
-value-position attributes (`attrLiftPosition`), and the control-flow subjects — as the single shared
-reading both compile front-ends lower from. It mirrors `ifPlan`/`awaitPlan` (a per-node structural
-plan the two back-ends read), applied to interpolations: the runtime lifts each field to an injected
-`computed` cell and `write`s the rewritten `__vN` reference back — marking `setAsyncSubject` when a
-whole subject collapsed to one bare cell — while the shadow reads the same `code`/`loc`/`position` to
-peek-wrap its value-typed projection. Neither can disagree on WHICH interpolations are async or their
-position.
-
-Fields are yielded in source order (text parts / attributes before the control-flow subject) so the
-runtime's global `__vN` cell numbering stays deterministic. The node's children are NOT descended —
-each front-end recurses on its own. A `{#for await}` source is the sanctioned `AsyncIterable`, drained
-unchanged, so it is never lifted (excluded); `await` / `component` / `snippet` / `try` carry no lifted
-field (an `await`'s promise and a component's props route through their own lowerings).
-*/
-export function asyncInterpolationFields(node: TemplateNode): AsyncInterpolationField[] {
-    const fields: AsyncInterpolationField[] = []
-    switch (node.kind) {
-        case 'text':
-            for (const part of node.parts) {
-                if (part.kind === 'expression' && part.loc !== undefined) {
-                    fields.push({
-                        code: part.code,
-                        loc: part.loc,
-                        position: 'content',
-                        subject: false,
-                        write: (code) => {
-                            part.code = code
-                        },
-                        setAsyncSubject: NO_OP,
-                    })
-                }
-            }
-            return fields
-        case 'element':
-            for (const attr of node.attrs) {
-                if (attr.kind === 'interpolated') {
-                    for (const part of attr.parts) {
-                        if (part.kind === 'expression' && part.loc !== undefined) {
-                            fields.push({
-                                code: part.code,
-                                loc: part.loc,
-                                position: 'attribute',
-                                subject: false,
-                                write: (code) => {
-                                    part.code = code
-                                },
-                                setAsyncSubject: NO_OP,
-                            })
-                        }
-                    }
-                    continue
-                }
-                /* Only `expression` attributes lift (directives evaluate to a handler/lvalue, not a
-                   rendered value) — `attrLiftPosition` is the shared gate. */
-                const position = attrLiftPosition(attr)
-                if (
-                    position !== undefined &&
-                    attr.kind === 'expression' &&
-                    attr.loc !== undefined
-                ) {
-                    fields.push({
-                        code: attr.code,
-                        loc: attr.loc,
-                        position,
-                        subject: false,
-                        write: (code) => {
-                            attr.code = code
-                        },
-                        setAsyncSubject: NO_OP,
-                    })
-                }
-            }
-            return fields
-        case 'if':
-            if (node.loc !== undefined) {
-                fields.push({
-                    code: node.condition,
-                    loc: node.loc,
-                    position: 'if',
-                    subject: true,
-                    write: (code) => {
-                        node.condition = code
-                    },
-                    setAsyncSubject: (asyncSubject) => {
-                        node.asyncSubject = asyncSubject
-                    },
-                })
-            }
-            return fields
-        case 'switch':
-            if (node.loc !== undefined) {
-                fields.push({
-                    code: node.subject,
-                    loc: node.loc,
-                    position: 'switch',
-                    subject: true,
-                    write: (code) => {
-                        node.subject = code
-                    },
-                    setAsyncSubject: (asyncSubject) => {
-                        node.asyncSubject = asyncSubject
-                    },
-                })
-            }
-            return fields
-        case 'case':
-            /* An `{:elseif}` condition — a truthy-tested control-flow subject, lifted like an
-               `{#if}` head so a bare async `{:elseif}` holds the cond-chain while it loads. */
-            if (node.condition !== undefined && node.loc !== undefined) {
-                fields.push({
-                    code: node.condition,
-                    loc: node.loc,
-                    position: 'if',
-                    subject: true,
-                    write: (code) => {
-                        node.condition = code
-                    },
-                    setAsyncSubject: (asyncSubject) => {
-                        node.asyncSubject = asyncSubject
-                    },
-                })
-            }
-            return fields
-        case 'each':
-            /* A plain `{#for}` source lifts (a promise-of-iterable → empty while pending); a
-               `{#for await}` source is the sanctioned `AsyncIterable`, never lifted. */
-            if (node.loc !== undefined && !node.async) {
-                fields.push({
-                    code: node.items,
-                    loc: node.loc,
-                    position: 'each',
-                    subject: false,
-                    write: (code) => {
-                        node.items = code
-                    },
-                    setAsyncSubject: NO_OP,
-                })
-            }
-            return fields
-        default:
-            return fields
-    }
-}

package/src/lib/ui/compile/asyncValuePositionError.ts

@@ -1,21 +0,0 @@
-import type { InterpolationKind } from './types/InterpolationKind.ts'
-import type { ValuePositionInterpolation } from './types/ValuePositionInterpolation.ts'
-
-/*
-The narrowed value-position guard (ADR-0032): a promise/`AsyncIterable` (sub)expression now LIFTS
-to a peek-cell in every position — an attribute, an `{#if}`/`{#switch}` subject, a plain `{#for}`
-source — reading `undefined` while pending. The ONE remaining error is a raw `AsyncIterable`
-driving a PLAIN `{#for}`: a frame is not a collection, so iterate its frames with `{#for await}`
-(the `for await` position is exempt). Everything else (promises everywhere, streams in attribute/
-`{#if}`/`{#switch}`/content) is allowed. Shared by the build front-end (`liftAsyncSubExpressions`
-throws the same message) and `abide check` (`collectAbideDiagnostics`).
-*/
-export function asyncValuePositionError(
-    kind: InterpolationKind,
-    position: ValuePositionInterpolation['position'],
-): string | undefined {
-    if (kind !== 'asyncIterable' || position !== 'each') {
-        return undefined
-    }
-    return "[abide] an `AsyncIterable` can't drive a plain `{#for}` — iterate its frames with `{#for await}`."
-}

package/src/lib/ui/compile/asyncValuePositionInterpolations.ts

@@ -1,64 +0,0 @@
-import type { TemplateNode } from './types/TemplateNode.ts'
-import type { ValuePositionInterpolation } from './types/ValuePositionInterpolation.ts'
-
-/*
-Collects every interpolation sitting in a NON-content value position across a parsed
-template — the positions Stage E guards (ADR-0019): an attribute value, an `{#if}` /
-`{#switch}` head, and a `{#each}`/`{#for}` iterable. Text-child positions are NOT
-collected: promise/asyncIterable text interpolations lower to a streaming await /
-stream cell (Stages C+D), so they render fine. A `{#for await}` iterable is included
-but tagged `for await` so the caller allows an `AsyncIterable` there.
-
-Shared by both guard sites: the build front-end (`lowerAsyncInterpolations`, which
-classifies each and throws) and `abide check` (`collectAbideDiagnostics`, which
-classifies each and pushes a diagnostic). Only positions the parser tracked an offset
-for are collected — an untracked span (`loc === undefined`) has no classifier key.
-*/
-export function asyncValuePositionInterpolations(
-    nodes: TemplateNode[],
-): ValuePositionInterpolation[] {
-    const found: ValuePositionInterpolation[] = []
-    collect(nodes, found)
-    return found
-}
-
-/* Recursive walk: pushes each node's value-position interpolations, then descends
-   into its children so nested elements and blocks are reached. */
-function collect(nodes: TemplateNode[], found: ValuePositionInterpolation[]): void {
-    for (const node of nodes) {
-        if (node === undefined) {
-            continue
-        }
-        if (node.kind === 'element') {
-            for (const attr of node.attrs) {
-                /* `name={expr}` — a plain reactive value bind. */
-                if (attr.kind === 'expression' && attr.loc !== undefined) {
-                    found.push({ loc: attr.loc, code: attr.code, position: 'attribute' })
-                    continue
-                }
-                /* `name="… {expr} …"` — each interpolated part stringifies into the value. */
-                if (attr.kind === 'interpolated') {
-                    for (const part of attr.parts) {
-                        if (part.kind === 'expression' && part.loc !== undefined) {
-                            found.push({ loc: part.loc, code: part.code, position: 'attribute' })
-                        }
-                    }
-                }
-            }
-        } else if (node.kind === 'if' && node.loc !== undefined) {
-            found.push({ loc: node.loc, code: node.condition, position: 'if' })
-        } else if (node.kind === 'switch' && node.loc !== undefined) {
-            found.push({ loc: node.loc, code: node.subject, position: 'switch' })
-        } else if (node.kind === 'each' && node.loc !== undefined) {
-            /* `{#for await}` is the sanctioned async iterable; a sync `{#each}` is not. */
-            found.push({
-                loc: node.loc,
-                code: node.items,
-                position: node.async ? 'for await' : 'each',
-            })
-        }
-        if ('children' in node) {
-            collect(node.children, found)
-        }
-    }
-}

package/src/lib/ui/compile/attrLiftPosition.ts

@@ -1,18 +0,0 @@
-import type { LiftPosition } from './liftAsyncSubExpressions.ts'
-import type { TemplateAttr } from './types/TemplateAttr.ts'
-
-/* The value position an attribute's authored expression occupies for async lowering, or undefined
-   when the attribute carries no async-liftable expression. Only `name={code}` (`expression`) and
-   `name="… {code} …"` (`interpolated`) bind a rendered value a promise/stream sub-expression may sit
-   in and lift to a peek-cell — every element value position is `'attribute'`. The directive
-   attributes (`on*` event, `bind:`, `class:`, `style:`, `attach`, `{...}` spread) evaluate to a
-   handler / lvalue / attachment / spread object, not a rendered value, so their expressions are NOT
-   lifted; a `static` literal carries no expression at all. Both compile front-ends read this so the
-   runtime's injected cells and the shadow's peek-wrap cover the SAME attribute set — the two can
-   never silently disagree on which attribute expressions are async. */
-export function attrLiftPosition(attr: TemplateAttr): LiftPosition | undefined {
-    if (attr.kind === 'expression' || attr.kind === 'interpolated') {
-        return 'attribute'
-    }
-    return undefined
-}

package/src/lib/ui/compile/awaitPlan.ts

@@ -1,60 +0,0 @@
-import { catchBinding } from './catchBinding.ts'
-import { resolveBranches } from './resolveBranches.ts'
-import type { Binding } from './types/Binding.ts'
-import type { TemplateNode } from './types/TemplateNode.ts'
-
-/* The structural shape of an `await` block, resolved ONCE from the node so the build and
-   SSR back-ends share one reading of it and only own emission. Both previously recomputed
-   branch resolution, the `finallyChildren` default, the blocking-vs-streaming split of the
-   resolved content/binding, and the surface-the-rejection rule — the parts that can silently
-   diverge. Same single-source-of-truth model the positional walks already use. */
-export type AwaitPlan = {
-    /* `then` on the tag → blocking: no pending branch, the children ARE the resolved content
-       (settled before first flush). Absent → streaming: pending flushes, `then` resolves later. */
-    blocking: boolean
-    /* The pending content (streaming) — `[]` when blocking. */
-    pending: TemplateNode[]
-    /* The resolved content + its bound name: the children-minus-branch bound to `node.as`
-       when blocking, the `then` branch bound to its `as` when streaming. `_value` default. */
-    resolvedChildren: TemplateNode[]
-    resolvedAs: string
-    /* The catch content + its bound name (`_error` default); empty when no catch branch. */
-    catchChildren: TemplateNode[]
-    catchAs: string
-    finallyChildren: TemplateNode[]
-    /* Neither catch nor finally → a rejection must surface (re-throw / `undefined` catch thunk)
-       instead of rendering an empty branch. */
-    surfaceRejection: boolean
-    /* The resolved branch's binding (`resolvedAs`, `reactive` — a `.value` cell on the
-       client, a re-settle updates it in place). One element. */
-    resolvedBindings: Binding[]
-    /* The catch branch's binding (`catchAs`, `plain`); empty when no catch branch. The
-       `finally` branch binds nothing, so it registers no binding. */
-    catchBindings: Binding[]
-}
-
-/* Resolves an `await` node's branches into the shared structural plan. */
-export function awaitPlan(node: Extract<TemplateNode, { kind: 'await' }>): AwaitPlan {
-    const [thenBranch, catchBranch, finallyBranch] = resolveBranches(
-        node,
-        'then',
-        'catch',
-        'finally',
-    )
-    const finallyChildren = finallyBranch?.children ?? []
-    const nonBranch = node.children.filter((child) => child.kind !== 'branch')
-    const resolvedAs = (node.blocking ? node.as : thenBranch?.as) ?? '_value'
-    const catchAs = catchBranch?.as ?? '_error'
-    return {
-        blocking: node.blocking,
-        pending: node.blocking ? [] : nonBranch,
-        resolvedChildren: node.blocking ? nonBranch : (thenBranch?.children ?? []),
-        resolvedAs,
-        catchChildren: catchBranch?.children ?? [],
-        catchAs,
-        finallyChildren,
-        surfaceRejection: catchBranch === undefined && finallyChildren.length === 0,
-        resolvedBindings: [{ name: resolvedAs, classification: 'reactive' }],
-        catchBindings: catchBinding(catchAs, catchBranch !== undefined),
-    }
-}

package/src/lib/ui/compile/awaitSubjectExpr.ts

@@ -1,23 +0,0 @@
-/*
-The lowered `{#await X}` subject, normalised so a cell subject AWAITS its resolution
-(ADR-0047): a BARE async-cell reference is passed RAW (not peeked to `$$readCell(cell)`)
-and wrapped in `$$awaitSubject(...)`, which resolves a cell to a promise-of-its-value —
-so `{#await rates}` (a cell) shows pending then the value; any other subject lowers
-unchanged, so `{#await getFoo()}` (a plain promise) is byte-identical. A name currently
-SHADOWED by a block binding (`{#for rates of …}` / `{:then rates}` over a component cell
-`rates`) is the binder's local, not the cell — it lowers through `lowerExpression` like any
-other subject, matching how every other reference site honours the shadow stack. ONE
-decision site shared by both back-ends (the client `awaitBlock` emit and SSR's blocking /
-streaming / flight-hoist emits), so the bare-cell classification can't drift between them.
-*/
-export function awaitSubjectExpr(
-    promiseCode: string,
-    cellReadNames: ReadonlySet<string>,
-    isShadowed: (name: string) => boolean,
-    lowerExpression: (code: string) => string,
-): string {
-    const bare = promiseCode.trim()
-    return cellReadNames.has(bare) && !isShadowed(bare)
-        ? `$$awaitSubject(${bare})`
-        : lowerExpression(promiseCode)
-}

package/src/lib/ui/compile/bindListenEvent.ts

@@ -1,18 +0,0 @@
-/*
-The DOM event a generic two-way `bind:<property>` listens on to write the bound
-path back. Most form fields report edits via `input`, but a few properties are
-driven by their own event and never fire `input` — `<details open>` fires
-`toggle` and a checkbox/radio `checked` fires `change`. `<select value>` is NOT
-handled here: generateBuild intercepts it before this function and routes it to
-`bindSelectValue` (a MutationObserver-based helper that re-applies on late
-options), so this function never sees that case.
-*/
-export function bindListenEvent(property: string): string {
-    if (property === 'open') {
-        return 'toggle'
-    }
-    if (property === 'checked') {
-        return 'change'
-    }
-    return 'input'
-}

package/src/lib/ui/compile/cachedShadowProgram.ts

@@ -1,39 +0,0 @@
-import { messageFromError } from '../../shared/messageFromError.ts'
-import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
-
-/*
-Get-or-build the warm shadow program for a project root, cached once per root and shared by
-the interpolation and seed classifiers (whichever is requested first for a root warms it; the
-other reuses it). The shadow program is what makes type-directed async detection possible —
-resolving whether `{getFoo()}` is a promise/stream and lifting it to a streaming/blocking cell.
-
-On a build FAILURE the program is cached as `undefined` and the classifiers degrade to today's
-plain-value / syntactic behavior — the build never breaks. But the failure is WARNED once per
-root: a silent `undefined` disables type-directed async detection for EVERY component in the
-root, so a broken tsconfig would otherwise ship a bare `{getFoo()}` as the literal
-`[object Promise]` text with no signal at all. The warn fires once (guarded by `cache.has`), so
-the two classifiers sharing a cache never double-report.
-
-`build` is injectable so the warn-once path is testable without a broken project on disk;
-callers pass nothing and get `createShadowProgram`.
-*/
-export function cachedShadowProgram(
-    cache: Map<string, ShadowProgram | undefined>,
-    root: string,
-    build: (root: string) => ShadowProgram = createShadowProgram,
-): ShadowProgram | undefined {
-    if (!cache.has(root)) {
-        try {
-            cache.set(root, build(root))
-        } catch (error) {
-            cache.set(root, undefined)
-            const detail = messageFromError(error)
-            console.warn(
-                `[abide] couldn't build the type program for ${root}: ${detail}\n` +
-                    '  type-directed async detection is disabled for this project — a bare promise/stream\n' +
-                    '  read like {getFoo()} renders as text instead of streaming. Check the tsconfig.',
-            )
-        }
-    }
-    return cache.get(root)
-}

package/src/lib/ui/compile/cachedSourceFile.ts

@@ -1,40 +0,0 @@
-import ts from 'typescript'
-
-/*
-One parsed `ts.SourceFile` per (fileName, exact text, options signature), shared across
-every `ts.Program` this process builds. `ts.createProgram` re-parses all ~90 default
-`lib.*.d.ts` files (~3MB) plus every resolved dependency on each call — negligible for the
-one-shot `abide check` CLI, but the LSP rebuilds a program per edit and the test suite builds
-dozens over identical inputs. A `SourceFile` is a pure function of its text and the
-parse/bind-affecting compiler options, so reuse is safe — the same reuse TS performs for the
-source files it carries forward from an incremental `oldProgram`. Keying on the EXACT text
-means any content change re-parses (never a stale AST); the `signature` keeps two projects
-with different targets/libs from sharing a file; one entry per fileName bounds the cache to a
-single program's footprint.
-*/
-
-type CacheEntry = { text: string; signature: string; sourceFile: ts.SourceFile }
-
-const CACHE = new Map<string, CacheEntry>()
-
-export function cachedSourceFile(
-    fileName: string,
-    text: string,
-    languageVersionOrOptions: ts.ScriptTarget | ts.CreateSourceFileOptions,
-    signature: string,
-    scriptKind?: ts.ScriptKind,
-): ts.SourceFile {
-    const existing = CACHE.get(fileName)
-    if (existing && existing.text === text && existing.signature === signature) {
-        return existing.sourceFile
-    }
-    const sourceFile = ts.createSourceFile(
-        fileName,
-        text,
-        languageVersionOrOptions,
-        true,
-        scriptKind,
-    )
-    CACHE.set(fileName, { text, signature, sourceFile })
-    return sourceFile
-}

package/src/lib/ui/compile/catchBinding.ts

@@ -1,10 +0,0 @@
-import type { Binding } from './types/Binding.ts'
-
-/* A block's `catch` branch binding — the error name, or none when the block has no catch
-   branch. Shared by the await/each/try plans so the one catch-binding shape stays
-   single-source. `reactive` binds the error as a `.value` cell the runtime can update in
-   place (the reactive `{#try}` — a catch→catch error swaps in place, no rebuild); the
-   await/each catches leave it `plain` (they pass the error by value). */
-export function catchBinding(catchAs: string, hasCatch: boolean, reactive = false): Binding[] {
-    return hasCatch ? [{ name: catchAs, classification: reactive ? 'reactive' : 'plain' }] : []
-}