@abide/abide 0.49.0 → 0.50.1

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

@@ -1,7 +1,16 @@
 import ts from 'typescript'
+import { asyncValuePositionError } from './asyncValuePositionError.ts'
+import { asyncValuePositionInterpolations } from './asyncValuePositionInterpolations.ts'
+import { classifyInterpolationType } from './classifyInterpolationType.ts'
 import type { ShadowProgram } from './createShadowProgram.ts'
+import { isSpuriousAsyncReadDiagnostic } from './isSpuriousAsyncReadDiagnostic.ts'
+import { nodeAtShadowOffset } from './nodeAtShadowOffset.ts'
+import { parseTemplateRecovering } from './parseTemplateRecovering.ts'
 import { remapShadowDiagnostic } from './remapShadowDiagnostic.ts'
+import { sourceToShadowOffset } from './sourceToShadowOffset.ts'
+import { templateStartOffset } from './templateStartOffset.ts'
 import type { AbideDiagnostic } from './types/AbideDiagnostic.ts'
+import type { ShadowMapping } from './types/CompiledShadow.ts'
 
 /*
 Runs the shadow program's type-checker over every `.abide` shadow and relocates
@@ -12,6 +21,7 @@ Shared by `abide check` (one-shot render) and the LSP (per-file publish).
 */
 export function collectAbideDiagnostics(shadow: ShadowProgram): AbideDiagnostic[] {
     const { program, shadows, parseErrors, abidePaths } = shadow
+    const checker = program.getTypeChecker()
     const diagnostics: AbideDiagnostic[] = []
     for (const abidePath of abidePaths) {
         const parseError = parseErrors.get(abidePath)
@@ -41,6 +51,15 @@ export function collectAbideDiagnostics(shadow: ShadowProgram): AbideDiagnostic[
         if (sourceFile === undefined || mappings === undefined) {
             continue
         }
+        /* The template boundary: a diagnostic mapping at/after it is a template expression, so
+           eligible for the ADR-0032 bare-async-read suppression; anything before it is `<script>`
+           code, where a forgotten `await` must still surface. If the source can't be read, DON'T
+           fall back to 0 — that treats the whole file (including `<script>`) as template and would
+           silently suppress a genuine forgotten-await error. Use +Infinity so nothing is eligible
+           for suppression and every real diagnostic surfaces (fail toward reporting). */
+        const abideSource = ts.sys.readFile(abidePath)
+        const templateStart =
+            abideSource === undefined ? Number.POSITIVE_INFINITY : templateStartOffset(abideSource)
         const raw = [
             ...program.getSyntacticDiagnostics(sourceFile),
             ...program.getSemanticDiagnostics(sourceFile),
@@ -57,6 +76,21 @@ export function collectAbideDiagnostics(shadow: ShadowProgram): AbideDiagnostic[
             if (located === undefined) {
                 continue
             }
+            /* Drop the diagnostics a bare async read (ADR-0032) provokes spuriously: the runtime
+               peeks the resolved value (`undefined` while pending), so a `?.` read of a real member
+               and an `{#if}` on the promise are valid — the raw-`Promise` shadow can't see that. */
+            if (
+                located.start >= templateStart &&
+                isSpuriousAsyncReadDiagnostic(
+                    sourceFile,
+                    checker,
+                    diagnostic.code,
+                    diagnostic.start,
+                    diagnostic.length ?? 0,
+                )
+            ) {
+                continue
+            }
             diagnostics.push({
                 file: abidePath,
                 start: located.start,
@@ -65,6 +99,68 @@ export function collectAbideDiagnostics(shadow: ShadowProgram): AbideDiagnostic[
                 category: diagnostic.category,
             })
         }
+        /* Stage E parity (ADR-0019): the build front-end (`lowerAsyncInterpolations`) throws on a
+           promise/asyncIterable in a NON-content value position; mirror it here as a diagnostic so
+           `abide check`/the LSP surface the same error. The shadow already type-checks these
+           spans, so their offsets map through the same `mappings`; classify each against the
+           checker and emit an Error for any async value the guard rejects. */
+        collectValuePositionDiagnostics(abidePath, sourceFile, mappings, checker, diagnostics)
     }
     return diagnostics
 }
+
+/* Parses the component template, walks its value-position interpolations, and pushes a diagnostic
+   for any promise/asyncIterable the Stage E guard rejects. Classifies via the shadow: map the
+   expression's source offset into shadow coordinates, find its emitted expression node, read its
+   checker type. Fail-open — an unparseable template or unmappable span contributes nothing, so a
+   type hiccup degrades to no extra diagnostic instead of throwing. */
+function collectValuePositionDiagnostics(
+    abidePath: string,
+    shadowFile: ts.SourceFile,
+    mappings: ShadowMapping[],
+    checker: ts.TypeChecker,
+    diagnostics: AbideDiagnostic[],
+): void {
+    const source = ts.sys.readFile(abidePath)
+    if (source === undefined) {
+        return
+    }
+    /* The template starts just past the leading `<script>` — the SAME base `compileShadow` parses
+       from, so each interpolation's `loc` lines up with the shadow's source→shadow `mappings`. */
+    const templateStart = templateStartOffset(source)
+    /* The recovering core never throws — it returns best-effort `nodes` PLUS every parse
+       diagnostic. Surface each with the `file` + `category` the parser can't know, so the LSP
+       reports parse errors from mid-edit source instead of fail-opening on the first throw. */
+    const parsed = parseTemplateRecovering(source.slice(templateStart), templateStart)
+    const nodes = parsed.nodes
+    for (const parseDiagnostic of parsed.diagnostics) {
+        diagnostics.push({
+            file: abidePath,
+            start: parseDiagnostic.start,
+            length: parseDiagnostic.length,
+            message: parseDiagnostic.message,
+            category: ts.DiagnosticCategory.Error,
+        })
+    }
+    for (const interpolation of asyncValuePositionInterpolations(nodes)) {
+        const shadowOffset = sourceToShadowOffset(mappings, interpolation.loc)
+        if (shadowOffset === undefined) {
+            continue
+        }
+        const node = nodeAtShadowOffset(shadowFile, shadowOffset, interpolation.code.length)
+        if (node === undefined) {
+            continue
+        }
+        const kind = classifyInterpolationType(checker.getTypeAtLocation(node), node, checker)
+        const message = asyncValuePositionError(kind, interpolation.position)
+        if (message !== undefined) {
+            diagnostics.push({
+                file: abidePath,
+                start: interpolation.loc,
+                length: interpolation.code.length,
+                message,
+                category: ts.DiagnosticCategory.Error,
+            })
+        }
+    }
+}

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

@@ -2,6 +2,8 @@ import { analyzeComponent } from './analyzeComponent.ts'
 import { generateBuild } from './generateBuild.ts'
 import { hoistCells } from './hoistCells.ts'
 import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
+import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
 
 /*
 Compiles a single-file abide component into the body of a client build function.
@@ -19,10 +21,24 @@ export function compileComponent(
     source: string,
     isLayout = false,
     scopeSeed?: string,
-    analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
+    analyzed?: AnalyzedComponent,
+    classify?: InterpolationClassifier,
+    seedClassify?: SeedTypeClassifier,
 ): string {
-    const { script, stateNames, derivedNames, computedNames, nodes } = analyzed
-    const build = generateBuild(nodes, 'host', stateNames, derivedNames, computedNames, isLayout)
+    /* `analyzed` is shared by `compileModule` (analyzed once, classifiers already applied);
+       a direct caller (tests) omits it and the front-end runs here — threading `classify` and
+       `seedClassify` so type-directed interpolation + cell lowering happen on this path too. */
+    const resolved = analyzed ?? analyzeComponent(source, scopeSeed, classify, seedClassify)
+    const { script, stateNames, derivedNames, computedNames, cellReadNames, nodes } = resolved
+    const build = generateBuild(
+        nodes,
+        'host',
+        stateNames,
+        derivedNames,
+        computedNames,
+        isLayout,
+        cellReadNames,
+    )
     /* The scoped CSS is bundled into the entry stylesheet (see `abideUiPlugin`), not
        injected at runtime; the build only needs the `data-a-…` scope attributes on
        elements, which `generateBuild` reads from each node's annotated `scopes`. */

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

@@ -1,11 +1,12 @@
 import ts from 'typescript'
 import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
 import { analyzeComponent } from './analyzeComponent.ts'
-import { assertRuntimeHelpersBound } from './assertRuntimeHelpersBound.ts'
 import { assertTranspiles } from './assertTranspiles.ts'
 import { compileComponent } from './compileComponent.ts'
 import { compileSSR } from './compileSSR.ts'
 import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
+import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
 import { UI_RUNTIME_IMPORTS } from './UI_RUNTIME_IMPORTS.ts'
 
 /*
@@ -26,52 +27,34 @@ what the `.abide` bundler loader emits.
 */
 export function compileModule(
     source: string,
-    options: { isLayout?: boolean; moduleId?: string; hot?: boolean } = {},
+    options: {
+        isLayout?: boolean
+        moduleId?: string
+        /* Type-directed interpolation lowering (ADR-0019): the warm shadow classifier the
+           bundler plugin builds per `.abide`. Optional and fail-open — absent, the module
+           compiles exactly as before (every interpolation binds as a plain value). */
+        classify?: InterpolationClassifier
+        /* Type-directed cell lowering (ADR-0023): the seed classifier the plugin builds over
+           the SAME warm shadow program. Optional and fail-open — absent, a no-marker
+           `computed(seed)` routes by the `isBareCallComputed` syntax heuristic (today's behavior). */
+        seedClassify?: SeedTypeClassifier
+    } = {},
 ): { code: string; styles: AnalyzedComponent['styles'] } {
     const isLayout = options.isLayout ?? false
     /* Run the shared front-end once and feed it to both back-ends — the analysis is
        pure over (source, moduleId), so the client and SSR builds reuse one parse
        instead of re-running it. `imports` (hoisted child-component imports) and the
-       per-element scopes both come from this single pass. */
-    const analyzed = analyzeComponent(source, options.moduleId)
+       per-element scopes both come from this single pass. The classifier (when present)
+       lowers promise-typed interpolations here, so both back-ends see one lowered tree. */
+    const analyzed = analyzeComponent(
+        source,
+        options.moduleId,
+        options.classify,
+        options.seedClassify,
+    )
     const userImports = analyzed.imports
     const body = indent(compileComponent(source, isLayout, options.moduleId, analyzed))
 
-    /* Hot module (dev component HMR): the same client build, but its runtime comes
-       from the live bundle via `window.__abide` — so it shares the one reactive graph
-       and instance registry, not fresh copies — and on load it hands the new factory
-       to `hotReplace`, which disposes + re-runs every live instance in place. No SSR /
-       hydrate / export: it is imported only to replace, never mounted fresh. Supports
-       leaf components today; one importing children falls back to a reload (the dev
-       layer decides what to hot-swap). */
-    if (options.hot) {
-        /* Bridge keys are the bare source names; bind each to its emitted local (`$$`
-           alias when set), so the hot body's `$$mountChild(...)` resolves. */
-        const names = UI_RUNTIME_IMPORTS.map((entry) =>
-            entry.alias === undefined || entry.alias === entry.name
-                ? entry.name
-                : `${entry.name}: ${entry.alias}`,
-        ).join(', ')
-        const id = JSON.stringify(options.moduleId)
-        /* Hot mode never imports the scoped CSS (it reuses the live bundle's sheet), so
-           styles are empty here regardless of the analyzed blocks. */
-        return {
-            code: `const { ${names}, hotReplace } = window.__abide
-${userImports}
-function build(host, $props) {
-${body}
-}
-function component(host, $props) {
-    return $$mount(host, build, $props)
-}
-component.build = build
-component.__abideId = ${id}
-if (!hotReplace(${id}, component)) location.reload()
-`,
-            styles: [],
-        }
-    }
-
     const ssrBody = indent(compileSSR(source, isLayout, options.moduleId, analyzed))
     const moduleBody = `function build(host, $props) {
 ${body}
@@ -95,7 +78,7 @@ component.hydrate = hydrateInto
 /* The bare build, so a parent can range-mount this as a nested child (no wrapper). */
 component.build = build
 component.hydratable = ${analyzed.hydratable}
-${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(options.moduleId)}\n`}`
+`
     /* Per-component dead-import elimination: emit only the runtime helpers this module
        references. A component using no `each`/`await`/`html` shouldn't drag those modules
        into its chunk, and the package isn't globally side-effect-free (the dev/runtime
@@ -107,13 +90,10 @@ ${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(
        string/comment/HTML literal (e.g. an `on`-attribute in static markup) no longer
        forces a spurious import, so no per-surface scoping is needed: a client-only helper
        simply doesn't appear as an identifier in the SSR body. */
-    /* Parse the generated bodies ONCE and feed the single tree to both AST passes: the
-       dead-import filter (`collectIdentifiers`) and the binding backstop
-       (`assertRuntimeHelpersBound`). The import block isn't in this tree yet — it is derived
-       from the filter's result — so the backstop is told the names that block will bind
-       (`importedHelpers`), which is exactly what it would have read from the prepended imports
-       had it re-parsed the whole module. `setParentNodes` is required by the backstop's
-       `getStart`/line lookups. */
+    /* Parse the generated bodies ONCE and feed the tree to the dead-import filter
+       (`collectIdentifiers`) and the reactive-import backstop below. The import block isn't in
+       this tree yet — it is derived from the filter's result. `setParentNodes` lets
+       `collectValueReferences` distinguish a value use from a property name. */
     const bodySource = ts.createSourceFile(
         'module.ts',
         `${userImports}\n${moduleBody}`,
@@ -161,17 +141,6 @@ ${moduleBody}`
        template shape no test exercises) otherwise ships as a broken bundle; this surfaces
        it as a located compile error for every component. */
     assertTranspiles(module, 'component module generation')
-    /* `assertTranspiles` only proves the output PARSES — a call to an un-imported helper is
-       valid syntax, so it slips through. This second guard proves the output is BOUND: every
-       runtime helper it calls is actually imported (an independent check of the dead-import
-       filter above), turning a runtime `ReferenceError` into a located compile error. It walks
-       the SAME tree the filter just parsed, with the kept helper imports supplied as the bound
-       set the prepended import block provides. */
-    assertRuntimeHelpersBound(
-        bodySource,
-        new Set(keptImports.map((entry) => entry.alias ?? entry.name)),
-        'component module generation',
-    )
     return { code: module, styles: analyzed.styles }
 }
 

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

@@ -2,6 +2,8 @@ import { analyzeComponent } from './analyzeComponent.ts'
 import { generateSSR } from './generateSSR.ts'
 import { SSR_ESCAPE } from './SSR_ESCAPE.ts'
 import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
+import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
+import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
 
 /*
 Compiles a component into the body of a server render function. Runs the shared
@@ -18,12 +20,12 @@ Effects are stripped — they are client lifecycle and emit no HTML, so the serv
 render is a snapshot of the markup before any effect runs.
 
 Defines `$$model` via the lowered script; the reactive scope is entered via `$$enterScope`
-and exited in a `finally` block. The block-id counter is
-the request-local `$ctx` (threaded into child renders), not a module global — a blocking
-`await` block awaits its promise at its structural position and renders inline, so ids
-allocate depth-first like the client; render yields at that `await`, and a shared global
-counter would interleave across concurrent requests. `$ctx` defaults to a fresh counter
-when a caller (a test, a top-level render) omits it.
+and exited in a `finally` block. The block-id counter is the request-local `$ctx` — a
+per-render-path `Map` (ADR-0037), threaded into child renders — not a module global. Each
+`await`/`try` block draws `$$blockId($ctx)` = `${render-path}:${n}`, counting per path in
+document order; namespacing by path (rather than one flat counter) keeps ids congruent with
+the client even when sibling child renders run concurrently, and isolates concurrent requests.
+`$ctx` defaults to a fresh `Map` when a caller (a test, a top-level render) omits it.
 
 The body is wrapped in an ASYNC IIFE (returns `Promise<SsrRender>`) ONLY when it contains
 an inline `await` — a blocking `{#await … then}` block, a child-component render, a `<slot>`
@@ -43,17 +45,54 @@ export function compileSSR(
     source: string,
     isLayout = false,
     scopeSeed?: string,
-    analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
+    analyzed?: AnalyzedComponent,
+    classify?: InterpolationClassifier,
+    seedClassify?: SeedTypeClassifier,
 ): string {
-    const { ssrScript: lowered, stateNames, derivedNames, computedNames, nodes } = analyzed
-    const ssr = generateSSR(nodes, stateNames, derivedNames, computedNames, isLayout)
+    /* `analyzed` is shared by `compileModule` (analyzed once, classifiers already applied);
+       a direct caller (tests) omits it and the front-end runs here — threading `classify` and
+       `seedClassify` so type-directed interpolation + cell lowering happen on this path too. */
+    const resolved = analyzed ?? analyzeComponent(source, scopeSeed, classify, seedClassify)
+    const {
+        ssrScript: lowered,
+        stateNames,
+        derivedNames,
+        computedNames,
+        cellReadNames,
+        nodes,
+    } = resolved
+    const {
+        body: ssr,
+        flightDecls,
+        hasStagedChildren,
+    } = generateSSR(nodes, stateNames, derivedNames, computedNames, isLayout, cellReadNames)
+    /* ADR-0039: a component with hoistable children declares `$childSlots` (the body walk reserves an
+       output slot per child) and, after the walk, awaits `$$finalizeStreamedChildren` — which fills
+       each slot inline (settled child, byte-identical to the old inline await) or with a streaming
+       boundary (still-pending child). Empty for a component with no hoistable child, which stays
+       synchronous. */
+    const childSlotsDecl = hasStagedChildren ? 'const $childSlots = [];\n' : ''
+    const finalizeChildren = hasStagedChildren
+        ? 'await $$finalizeStreamedChildren($childSlots, $awaits, $resume);\n'
+        : ''
+    /* The Tier-2 await-barrier (ADR-0019): between the lowered cell declarations and the
+       template, drain + await every async cell's in-flight promise so the template's
+       `$$readCell(name)` peeks the RESOLVED value and it bakes into the first-pass HTML —
+       single render pass, no client refetch. Emitted whenever the component declares a cell
+       (`cellReadNames`: every `linked` / async or bare-call `computed`); the barrier only
+       awaits promises a cell actually registered server-side (a sync/stream cell registers
+       none), so it is a cheap no-op for a component whose cells all settled synchronously. */
+    const barrier = cellReadNames.size > 0 ? 'await $$settleAsyncCells();\n' : ''
     /* No `<style>` in the markup — the scoped CSS is bundled into the entry stylesheet
        the shell links (see `abideUiPlugin`), so SSR output is styled by that sheet. The
        elements still carry their `data-a-…` scopes via `generateSSR`. */
     /* `typeof model` guards a component with no reactive state (a pure-async or
        static component declares no `model`); its snapshot is then empty. */
+    /* ADR-0034 flight declarations sit AFTER the lowered script (so their promises can read the
+       component's signals) and BEFORE the barrier (so a hoisted flight is already in-flight while
+       the barrier awaits any unrelated blocking cell). Empty when nothing hoisted. */
     const body =
-        `const $scope = $$enterScope();\ntry {\n${lowered}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\nconst $resume = {};\n${ssr}` +
+        `const $scope = $$enterScope();\ntry {\n${lowered}\n${flightDecls}${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\n${childSlotsDecl}const $resume = {};\n${barrier}${ssr}${finalizeChildren}` +
         `return { html: $out.join(''), state: (typeof $$model !== 'undefined' ? $$model.snapshot() : {}), awaits: $awaits, resume: $resume };\n` +
         `} finally { $$exitScope($scope); }`
     /* An inline `await` — a blocking await block, a child render, a slot read, or a
@@ -63,6 +102,6 @@ export function compileSSR(
        top-level `await` in a non-async function (a SyntaxError). `(?!:)` excludes the
        `<!--abide:await:N-->` boundary-marker strings; `\b` excludes `$awaits`. A false
        positive (the token in author text) only costs a needless async wrapper, never a crash. */
-    const needsAsync = /\bawait\b(?!:)/.test(`${lowered}${ssr}`)
-    return `var $ctx = $ctx || { next: 0 };\n${needsAsync ? `return (async () => {\n${body}\n})();` : body}`
+    const needsAsync = hasStagedChildren || /\bawait\b(?!:)/.test(`${lowered}${ssr}${barrier}`)
+    return `var $ctx = $ctx || new Map();\n${needsAsync ? `return (async () => {\n${body}\n})();` : body}`
 }