@abide/abide 0.49.0 → 0.50.1

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

@@ -0,0 +1,193 @@
+import ts from 'typescript'
+import { declaredNames } from './declaredNames.ts'
+import { expressionIsPrefixEvaluable } from './expressionIsPrefixEvaluable.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* One hoistable await: the node whose promise-start moves to the SSR prefix, and the
+   `$flightN` const name that holds the in-flight promise. */
+export type HoistedFlight = {
+    node: Extract<TemplateNode, { kind: 'await' }>
+    name: string
+}
+
+/*
+ADR-0034 — the SSR-only pass that picks which `await` blocks may start their promise in the
+synchronous render prefix so independent flights overlap instead of serializing. An await is
+HOISTABLE iff its promise is evaluable at prefix time and its content is unconditionally rendered:
+
+  1. Its promise's referenced identifiers avoid every enclosing TEMPLATE-LOCAL binder (a `{#for}`
+     item/index, a `{:then}`/`{:catch}`/`then v` value, a snippet param, a nested `<script>`
+     local) — those don't exist in the prefix — AND every ASYNC-CELL name (`cellReadNames`, still
+     pending at prefix time).
+  2. It is not inside a CONDITIONALLY-rendered branch (`{#if}`/`{#switch}`/`{#try}`, a snippet/slot
+     body, or another await's pending/then/catch branch) — starting its flight eagerly would fetch
+     for a branch that may never render, or surface an error prematurely.
+  3. It is STATICALLY-SINGLE: on the top-level spine, or inside a single-element-literal
+     `{#for k of [expr] by k}` whose body renders exactly once (so one hoisted flight == one row).
+
+Fail-closed: identifiers are over-collected and any doubt blocks the hoist, so a mis-classified
+row-local flight can never collapse a multi-row `{#for}` to one shared value. Server-only — the
+returned nodes are rewired only in `generateSSR`; the client build and the wire are untouched.
+*/
+export function hoistableAwaits(
+    nodes: TemplateNode[],
+    cellReadNames: ReadonlySet<string>,
+): HoistedFlight[] {
+    const flights: HoistedFlight[] = []
+    const counter = { next: 0 }
+    walkList(nodes, new Set<string>(), false, false, cellReadNames, flights, counter)
+    return flights
+}
+
+/* Walk a sibling list left-to-right so a nested `<script>`'s declared locals extend the binder
+   set for the siblings that follow it (they are in that script's lexical scope). */
+function walkList(
+    list: TemplateNode[],
+    binders: ReadonlySet<string>,
+    conditional: boolean,
+    multiRow: boolean,
+    cellReadNames: ReadonlySet<string>,
+    flights: HoistedFlight[],
+    counter: { next: number },
+): void {
+    /* A running binder set for this list: a `<script>` sibling adds its top-level declarations,
+       so a later sibling's await that reads one is (conservatively) not hoistable. */
+    let listBinders = binders
+    for (const node of list) {
+        if (node.kind === 'script') {
+            listBinders = union(listBinders, declaredNames(node.code))
+            continue
+        }
+        walkNode(node, listBinders, conditional, multiRow, cellReadNames, flights, counter)
+    }
+}
+
+function walkNode(
+    node: TemplateNode,
+    binders: ReadonlySet<string>,
+    conditional: boolean,
+    multiRow: boolean,
+    cellReadNames: ReadonlySet<string>,
+    flights: HoistedFlight[],
+    counter: { next: number },
+): void {
+    if (node.kind === 'await') {
+        /* Hoistability is judged in the INCOMING context — the block's promise starts when the
+           block mounts (its pending branch always renders), so it is not gated by its own
+           branches, only by an enclosing conditional/multi-row. */
+        if (
+            !conditional &&
+            !multiRow &&
+            promiseIsPrefixEvaluable(node.promise, binders, cellReadNames)
+        ) {
+            flights.push({ node, name: `$flight${counter.next++}` })
+        }
+        /* The resolved/catch/pending branches are conditionally shown and bind the resolved value
+           (`node.as` for `{#await p then v}`; a `{:then v}`/`{:catch e}` branch binds via its own
+           `as`, added when that branch node is walked). */
+        const inner = node.as === undefined ? binders : union(binders, new Set([node.as]))
+        walkList(node.children, inner, true, multiRow, cellReadNames, flights, counter)
+        return
+    }
+    if (node.kind === 'each') {
+        /* Row/index bindings are template-local; the body is multi-row unless the source is a
+           single-element array literal (then it renders exactly once). `{#for await}` drains a
+           stream — its body is still per-frame, so treat it as multi-row. */
+        const rowBinders = new Set<string>()
+        rowBinders.add(node.as)
+        if (node.index !== undefined) {
+            rowBinders.add(node.index)
+        }
+        const rowMulti = multiRow || node.async === true || !isSingleElementLiteral(node.items)
+        walkList(
+            node.children,
+            union(binders, rowBinders),
+            conditional,
+            rowMulti,
+            cellReadNames,
+            flights,
+            counter,
+        )
+        return
+    }
+    if (
+        node.kind === 'if' ||
+        node.kind === 'switch' ||
+        node.kind === 'case' ||
+        node.kind === 'try'
+    ) {
+        /* Conditionally-rendered subtrees — never hoist a flight out of them. */
+        walkList(node.children, binders, true, multiRow, cellReadNames, flights, counter)
+        return
+    }
+    if (node.kind === 'branch') {
+        const inner = node.as === undefined ? binders : union(binders, new Set([node.as]))
+        walkList(node.children, inner, true, multiRow, cellReadNames, flights, counter)
+        return
+    }
+    if (node.kind === 'snippet') {
+        /* A snippet is a builder called conditionally; its params are locals. */
+        const params =
+            node.params === undefined
+                ? new Set<string>()
+                : declaredNames(`const [${node.params}] = []`)
+        walkList(
+            node.children,
+            union(binders, params),
+            true,
+            multiRow,
+            cellReadNames,
+            flights,
+            counter,
+        )
+        return
+    }
+    if (node.kind === 'component') {
+        /* Slot content is a fresh, lazily-built scope rendered at the child's `<slot>`. */
+        walkList(node.children, binders, true, multiRow, cellReadNames, flights, counter)
+        return
+    }
+    if (node.kind === 'element' && 'children' in node) {
+        walkList(node.children, binders, conditional, multiRow, cellReadNames, flights, counter)
+    }
+}
+
+/* True when EVERY referenced identifier of `promise` is prefix-evaluable: none is a template-local
+   binder and none is an async-cell name. Delegates to the shared `expressionIsPrefixEvaluable`. */
+function promiseIsPrefixEvaluable(
+    promise: string,
+    binders: ReadonlySet<string>,
+    cellReadNames: ReadonlySet<string>,
+): boolean {
+    return expressionIsPrefixEvaluable(promise, binders, cellReadNames)
+}
+
+/* A single-element array literal like `[remountKey]` — the only `{#for}` source that renders its
+   body exactly once, so a hoisted flight inside it maps to one row (no shared-flight hazard). */
+function isSingleElementLiteral(items: string): boolean {
+    let source: ts.SourceFile
+    try {
+        source = ts.createSourceFile('items.ts', items, ts.ScriptTarget.Latest, true)
+    } catch {
+        return false
+    }
+    const statement = source.statements[0]
+    if (
+        statement === undefined ||
+        source.statements.length !== 1 ||
+        !ts.isExpressionStatement(statement) ||
+        !ts.isArrayLiteralExpression(statement.expression)
+    ) {
+        return false
+    }
+    const elements = statement.expression.elements
+    return elements.length === 1 && !ts.isSpreadElement(elements[0] as ts.Expression)
+}
+
+function union(a: ReadonlySet<string>, b: ReadonlySet<string>): Set<string> {
+    const result = new Set(a)
+    for (const value of b) {
+        result.add(value)
+    }
+    return result
+}

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

@@ -0,0 +1,112 @@
+import { declaredNames } from './declaredNames.ts'
+import { expressionIsPrefixEvaluable } from './expressionIsPrefixEvaluable.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+type ComponentNode = Extract<TemplateNode, { kind: 'component' }>
+
+/*
+ADR-0037 Phase 2 — which `<Child/>` renders may START in the synchronous SSR prefix (as a `$$flight`
+awaited at its structural position) so sibling child renders overlap instead of serializing behind
+each other's `await Child.render(...)`. A child render is HOISTABLE iff it is on the TOP-LEVEL SPINE
+— reachable from the template root through only plain elements, so no control-flow / await-branch /
+snippet / slot binder is in scope — AND:
+
+  1. its component reference and every prop value (including a `{...spread}`) are prefix-evaluable:
+     no async-cell name (still pending at the prefix, before the barrier) and no nested-`<script>`
+     local declared earlier on the spine (those lower at their body position, not the prefix);
+  2. it carries NO slot content (`children` empty) — lazily-built slot content would need its own
+     prefix-evaluability proof; a childless card is the common parallel case;
+  3. no `bind:` prop — a two-way write-back channel that must wire at its structural position.
+
+Off-spine components (inside `{#if}`/`{#for}`/`{#await}`, a snippet, or another component's slot) stay
+sequential: conservatively excluded rather than proven row/branch-safe. Fail-closed throughout — any
+doubt leaves the render sequential, never wrong. Server-only; the client build is untouched.
+*/
+export function hoistableChildRenders(
+    nodes: TemplateNode[],
+    cellReadNames: ReadonlySet<string>,
+): Set<ComponentNode> {
+    const hoistable = new Set<ComponentNode>()
+    /* Every `{#snippet name}` in the component is a hoisted builder that may itself render an
+       async cell / await; a prop passing one to a child (`<List item={row}/>`) must therefore NOT
+       hoist — calling `row()` early, in the prefix, would render it out of order. Seed the binder set
+       with all snippet names (collected tree-wide, since a snippet is in scope for the whole
+       component) so any prop referencing one fails the prefix-evaluability check. */
+    const binders = new Set<string>()
+    collectSnippetNames(nodes, binders)
+    walkSpine(nodes, binders, cellReadNames, hoistable)
+    return hoistable
+}
+
+/* Recursively collect every `{#snippet name}` name in the subtree into `into`. */
+function collectSnippetNames(list: TemplateNode[], into: Set<string>): void {
+    for (const node of list) {
+        if (node.kind === 'snippet') {
+            into.add(node.name)
+        }
+        if ('children' in node && Array.isArray(node.children)) {
+            collectSnippetNames(node.children, into)
+        }
+    }
+}
+
+/* Walk a spine sibling list left-to-right: a `<script>` sibling's locals bind the siblings that
+   follow it; a component is judged in the running binder context; a plain element descends (still on
+   the spine). Every other node kind leaves the spine and is not descended — its components stay
+   sequential. */
+function walkSpine(
+    list: TemplateNode[],
+    binders: ReadonlySet<string>,
+    cellReadNames: ReadonlySet<string>,
+    hoistable: Set<ComponentNode>,
+): void {
+    let running = binders
+    for (const node of list) {
+        if (node.kind === 'script') {
+            running = union(running, declaredNames(node.code))
+            continue
+        }
+        if (node.kind === 'component') {
+            if (componentIsHoistable(node, running, cellReadNames)) {
+                hoistable.add(node)
+            }
+            /* Slot children are off-spine (built lazily inside the child) — not descended. */
+            continue
+        }
+        if (node.kind === 'element' && 'children' in node) {
+            walkSpine(node.children, running, cellReadNames, hoistable)
+        }
+        /* if / switch / each / await / try / snippet / branch: off the spine, skip. */
+    }
+}
+
+/* Childless, bind-free, with a prefix-evaluable tag and every prop value prefix-evaluable. */
+function componentIsHoistable(
+    node: ComponentNode,
+    binders: ReadonlySet<string>,
+    cellReadNames: ReadonlySet<string>,
+): boolean {
+    if (node.children.length > 0) {
+        return false
+    }
+    if (!expressionIsPrefixEvaluable(node.name, binders, cellReadNames)) {
+        return false
+    }
+    for (const prop of node.props) {
+        if (prop.bind === true) {
+            return false
+        }
+        if (!expressionIsPrefixEvaluable(prop.code, binders, cellReadNames)) {
+            return false
+        }
+    }
+    return true
+}
+
+function union(a: ReadonlySet<string>, b: ReadonlySet<string>): Set<string> {
+    const result = new Set(a)
+    for (const value of b) {
+        result.add(value)
+    }
+    return result
+}

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

@@ -16,9 +16,11 @@ prop value can't diverge on the concatenation. Always yields a string, so an
 interpolated attribute is always present.
 */
 export function interpolatedTemplateLiteral(parts: TextPart[]): string {
+    /* A dynamic slot coerces nullish to empty so `attr="a {v} b"` with a pending/undefined
+       `v` yields `"a  b"`, never `"a undefined b"` (ADR-0032 D3). */
     const body = parts
         .map((part) =>
-            part.kind === 'static' ? escapeTemplateChunk(part.value) : `\${${part.code}}`,
+            part.kind === 'static' ? escapeTemplateChunk(part.value) : `\${(${part.code}) ?? ''}`,
         )
         .join('')
     return `\`${body}\``

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

@@ -0,0 +1,37 @@
+import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
+import { shadowInterpolationClassifier } from './shadowInterpolationClassifier.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
+
+/*
+Builds the type-directed interpolation classifier for one `.abide` file, backed by
+a WARM shadow program kept once per project root (ADR-0019, Stage B). The shadow
+program (checker + every component's source→shadow `mappings`) is expensive to
+build, so it is created lazily on first request for a root and reused for every
+component in that root — the coupling that makes type-directed lowering affordable.
+The incremental `createShadowLanguageService` does not expose the checker, shadow
+`ts.SourceFile`, or per-file mappings publicly, so v1 uses the one-shot
+`createShadowProgram` (reused per root) rather than the LS overlay path.
+
+FAIL-OPEN throughout: if the program can't be built, or the file has no shadow, the
+classifier is absent (→ today's plain-value binding); and the returned closure wraps
+its whole body so ANY throw (resolution failure, missing node, checker hiccup) returns
+`'sync'`. A type-resolution problem degrades to today's behavior, never breaks the build.
+*/
+export function interpolationClassifierForRoot(
+    cache: Map<string, ShadowProgram | undefined>,
+    root: string,
+    abidePath: string,
+): InterpolationClassifier | undefined {
+    if (!cache.has(root)) {
+        try {
+            cache.set(root, createShadowProgram(root))
+        } catch {
+            cache.set(root, undefined)
+        }
+    }
+    const shadowProgram = cache.get(root)
+    if (shadowProgram === undefined) {
+        return undefined
+    }
+    return shadowInterpolationClassifier(shadowProgram.program, shadowProgram.shadows, abidePath)
+}

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

@@ -0,0 +1,174 @@
+import ts from 'typescript'
+import { classifyInterpolationType } from './classifyInterpolationType.ts'
+
+/* The two TypeScript diagnostics a bare async read (ADR-0032) raises spuriously in a template.
+   2339 — a property "missing" on the un-awaited `Promise`/`AsyncIterable`; 2801 — a condition the
+   raw promise makes "always defined". Both are correct against the raw type but wrong against the
+   runtime PEEK (the resolved value, `undefined` while pending), which the shadow can't see. */
+const PROPERTY_DOES_NOT_EXIST = 2339
+const CONDITION_ALWAYS_DEFINED = 2801
+
+/*
+Whether a shadow diagnostic is one the ADR-0032 bare-async-read peek makes spurious. The runtime
+lifts a promise/iterable sub-expression to a cell that reads the RESOLVED value (`undefined` while
+pending), so `getFoo()?.name` composes on the resolved object and `{#if getFoo()}` holds while
+pending — but the type-check shadow checks the RAW expression, where the property sits on the
+un-awaited `Promise` and the promise reads as always-truthy. This recognises those two cases so the
+caller can drop them:
+
+  - 2339 (missing property): an OPTIONAL access (`?.`) on a promise/iterable-typed base whose
+    property EXISTS on the awaited (promise) or frame (iterable) type — the peek's real member.
+  - 2801 (always-defined condition): the flagged subject itself classifies as a promise/iterable —
+    the peek is genuinely nullable (pending → `undefined`), so it is not always-defined.
+
+Deliberately narrow so it never hides a real mistake: only these two codes; 2339 only via `?.`
+(a bare `.name` on a promise stays an error, nudging toward the `?.` the peek needs) and only when
+the property resolves on the awaited/frame type (a typo `?.namex` stays); 2801 only when the
+subject is actually async (a bare `{#if someFn}` — a forgotten call — stays). Callers additionally
+gate on the diagnostic mapping into the template region, so `<script>` code (where a forgotten
+`await` must surface) is never touched.
+*/
+export function isSpuriousAsyncReadDiagnostic(
+    shadowFile: ts.SourceFile,
+    checker: ts.TypeChecker,
+    code: number,
+    start: number,
+    length: number,
+): boolean {
+    if (code === PROPERTY_DOES_NOT_EXIST) {
+        return isResolvedOptionalAsyncAccess(shadowFile, checker, start, length)
+    }
+    if (code === CONDITION_ALWAYS_DEFINED) {
+        return isAsyncSubject(shadowFile, checker, start, length)
+    }
+    return false
+}
+
+/* A 2339 on the member of an optional (`?.`) access whose base is a promise/iterable and whose
+   accessed property exists on the resolved value — the ADR-0032 peek, not an error. */
+function isResolvedOptionalAsyncAccess(
+    shadowFile: ts.SourceFile,
+    checker: ts.TypeChecker,
+    start: number,
+    length: number,
+): boolean {
+    const access = enclosingOptionalAccess(deepestNodeAt(shadowFile, start, length))
+    if (access === undefined) {
+        return false
+    }
+    const resolved = resolvedAsyncType(access.expression, checker)
+    if (resolved === undefined) {
+        return false
+    }
+    const property = accessedPropertyName(access)
+    return property !== undefined && checker.getPropertyOfType(resolved, property) !== undefined
+}
+
+/* A 2801 whose flagged subject classifies as a promise/iterable — the peek reads `undefined` while
+   pending, so it is genuinely nullable, not always-defined. */
+function isAsyncSubject(
+    shadowFile: ts.SourceFile,
+    checker: ts.TypeChecker,
+    start: number,
+    length: number,
+): boolean {
+    const node = deepestNodeAt(shadowFile, start, length)
+    const kind = classifyInterpolationType(checker.getTypeAtLocation(node), node, checker)
+    return kind === 'promise' || kind === 'asyncIterable'
+}
+
+/* The resolved value an async base peeks: a promise's awaited type, an iterable's frame type,
+   `undefined` when the base isn't actually async. */
+function resolvedAsyncType(base: ts.Node, checker: ts.TypeChecker): ts.Type | undefined {
+    const baseType = checker.getTypeAtLocation(base)
+    const kind = classifyInterpolationType(baseType, base, checker)
+    if (kind === 'promise') {
+        return checker.getAwaitedType(baseType)
+    }
+    if (kind === 'asyncIterable') {
+        return asyncFrameType(baseType, base, checker)
+    }
+    return undefined
+}
+
+/* The deepest AST node whose range contains the diagnostic span. */
+function deepestNodeAt(sourceFile: ts.SourceFile, start: number, length: number): ts.Node {
+    let best: ts.Node = sourceFile
+    const end = start + length
+    const visit = (node: ts.Node): void => {
+        if (node.getStart(sourceFile) <= start && node.getEnd() >= end) {
+            best = node
+            node.forEachChild(visit)
+        }
+    }
+    visit(sourceFile)
+    return best
+}
+
+/* The optional (`?.`) property/element access that OWNS `node` as its accessed member — walking
+   up from the name identifier. `undefined` when `node` isn't the member of an optional access
+   (a bare `.name`, or the base rather than the member). */
+function enclosingOptionalAccess(
+    node: ts.Node,
+): ts.PropertyAccessExpression | ts.ElementAccessExpression | undefined {
+    const parent = node.parent
+    if (parent === undefined) {
+        return undefined
+    }
+    if (ts.isPropertyAccessExpression(parent) && parent.name === node) {
+        return parent.questionDotToken === undefined ? undefined : parent
+    }
+    if (ts.isElementAccessExpression(parent) && parent.argumentExpression === node) {
+        return parent.questionDotToken === undefined ? undefined : parent
+    }
+    return undefined
+}
+
+/* The property name an access reads — the identifier for `a?.b`, the string literal for
+   `a?.['b']`. A computed non-literal element access has no static name. */
+function accessedPropertyName(
+    access: ts.PropertyAccessExpression | ts.ElementAccessExpression,
+): string | undefined {
+    if (ts.isPropertyAccessExpression(access)) {
+        return access.name.text
+    }
+    return ts.isStringLiteralLike(access.argumentExpression)
+        ? access.argumentExpression.text
+        : undefined
+}
+
+/* The frame type of an `AsyncIterable<T>` — `T`, which is what the runtime peek reads (the latest
+   frame). The named async-iterable types (`AsyncIterable`/`AsyncGenerator`/`AsyncIterableIterator`)
+   all carry `T` as their first type argument, so read it directly; a structurally-typed iterable
+   with no type arguments falls back to resolving `[Symbol.asyncIterator]().next()`'s yielded value.
+   `location` is any node in the program, needed to resolve the iterator symbol's type. `undefined`
+   when neither yields a frame, so the caller keeps the diagnostic. */
+function asyncFrameType(
+    type: ts.Type,
+    location: ts.Node,
+    checker: ts.TypeChecker,
+): ts.Type | undefined {
+    const directArgument = checker.getTypeArguments(type as ts.TypeReference)[0]
+    if (directArgument !== undefined) {
+        return directArgument
+    }
+    /* The `Symbol.asyncIterator` member mangles to `__@asyncIterator@<id>`, so match by prefix. */
+    const iterator = checker
+        .getPropertiesOfType(type)
+        .find((property) => (property.escapedName as string).startsWith('__@asyncIterator'))
+    if (iterator === undefined) {
+        return undefined
+    }
+    const factory = checker.getTypeOfSymbolAtLocation(iterator, location).getCallSignatures()[0]
+    const next = factory && checker.getPropertyOfType(factory.getReturnType(), 'next')
+    const nextSignature =
+        next && checker.getTypeOfSymbolAtLocation(next, location).getCallSignatures()[0]
+    if (!nextSignature) {
+        return undefined
+    }
+    /* `next()` resolves to `IteratorResult<T, TReturn>`, whose first type argument is the yielded
+       `T` (its `value` PROPERTY widens to `T | TReturn` across the done/not-done union, so read the
+       argument, not the property). */
+    const result = checker.getAwaitedType(nextSignature.getReturnType())
+    return result && checker.getTypeArguments(result as ts.TypeReference)[0]
+}