@abide/abide 0.58.0 → 0.101.0

package/src/compiler/PositionTable.ts

@@ -0,0 +1,125 @@
+import type { Node } from 'typescript/unstable/ast'
+import type { Span } from './projectShadow.ts'
+
+/**
+ * What a projected span is, by where the template put it.
+ *
+ * - `slot` — a text slot, `{expr}`.
+ * - `attribute` — an element's attribute value that is neither a listener nor a `bind:`.
+ * - `condition` — an `{#if}` or `{:else if}` subject.
+ * - `subject` — a `{#for}` subject.
+ * - `key` — a `{#for}`'s `by` key.
+ * - `listener` — an element's `on…` handler (14.9).
+ * - `prop` — a value handed to a component, spread or keyed.
+ * - `elementBind` / `componentBind` — a `bind:` operand on an element and on a component (32.6).
+ * - `untyped` — a value the shadow types as `any`: an attribute 32.10 refuses on a component, or
+ *   one on a component tag no call can spell.
+ * - `setup` — a branch-local `<script>` (14.8).
+ * - `head` — an inline component's `props` statement (32.40).
+ * - `tag` — an invocation's tag (32.34).
+ */
+export type PositionKind =
+    | 'slot'
+    | 'attribute'
+    | 'condition'
+    | 'subject'
+    | 'key'
+    | 'listener'
+    | 'prop'
+    | 'elementBind'
+    | 'componentBind'
+    | 'untyped'
+    | 'setup'
+    | 'head'
+    | 'tag'
+
+/** A span of the projection copied out of the template, and what it is. */
+export type Position = Span & { kind: PositionKind }
+
+/** 31.3 — whether a position is a `bind:` operand, which holds the `Reactive` rather than reading it. */
+export function holdsReactive(position: Position | undefined): boolean {
+    const kind = position?.kind
+    return kind === 'elementBind' || kind === 'componentBind'
+}
+
+/**
+ * Every template position a projection holds, ascending, and the checker node each one is.
+ *
+ * THE KIND IS RECORDED WHERE THE SPAN IS WRITTEN, so a reader of the checker's tree asks the table
+ * what a node is rather than re-recognizing the scaffolding the projection wrapped it in — two
+ * readers doing that with different case sets disagreed about which positions there were.
+ *
+ * A NODE IS A POSITION WHEN IT IS THE WHOLE OF ONE: it starts inside the span, and its parent
+ * starts before it. By START, because a setup's last statement takes the `;` the scaffolding writes
+ * after it, and ends past its span. The spans never nest, so at most one position holds a node, and
+ * a setup's span is as many nodes as it has statements.
+ */
+export class PositionTable {
+    readonly all: readonly Position[]
+
+    constructor(all: readonly Position[]) {
+        this.all = all
+    }
+
+    /** The position `node` is the whole of, or `undefined` where it is none or only part of one. */
+    of(node: Node): Position | undefined {
+        const start = node.getStart()
+        let low = 0
+        let high = this.all.length
+        while (low < high) {
+            const middle = (low + high) >>> 1
+            if ((this.all[middle] as Position).start <= start) low = middle + 1
+            else high = middle
+        }
+        const position = this.all[low - 1]
+        if (position === undefined || start >= position.end) return undefined
+        const parent = node.parent
+        return parent === undefined || parent.getStart() < position.start
+            ? position
+            : undefined
+    }
+
+    /** Whether any position is of a kind `kinds` holds. */
+    has(kinds: ReadonlySet<PositionKind>): boolean {
+        for (const position of this.all)
+            if (kinds.has(position.kind)) return true
+        return false
+    }
+
+    /**
+     * Each node under `root` that is the whole of a position of a kind `kinds` holds, in order.
+     *
+     * One walk in source order beside a cursor into the table, so a subtree that ends before the
+     * next wanted position is never entered.
+     */
+    nodesIn(
+        root: Node,
+        kinds: ReadonlySet<PositionKind>,
+    ): { position: Position; node: Node }[] {
+        const wanted: Position[] = []
+        for (const position of this.all)
+            if (kinds.has(position.kind)) wanted.push(position)
+        const found: { position: Position; node: Node }[] = []
+        if (wanted.length === 0) return found
+        let next = 0
+        const visit = (node: Node): void => {
+            if (next === wanted.length) return
+            const start = node.getStart()
+            while (
+                next < wanted.length &&
+                (wanted[next] as Position).end <= start
+            )
+                next += 1
+            const position = wanted[next]
+            if (position === undefined || node.end <= position.start) return
+            // Entered from a parent that started before the span, so this is the whole of it.
+            if (start >= position.start) {
+                found.push({ position, node })
+                return
+            }
+            node.forEachChild(visit)
+        }
+        root.forEachChild(visit)
+        return found
+    }
+}

package/src/compiler/REACTIVE_MEMBERS.ts

@@ -0,0 +1,36 @@
+/**
+ * The members the `Reactive` type declares, taken from REGISTRY's `Reactive` section.
+ *
+ * A constants leaf, with no imports of its own.
+ *
+ * 31.5 and 31.6 turn on this list: a property access on a name bound to a `Reactive` reaches the
+ * VALUE — `regions.join(', ')` is the array's `join` — EXCEPT for a member declared on the
+ * `Reactive` itself, which reaches that. Without the list every `n.foo` reads as the API and the
+ * value's own members are unreachable, which is what `regions.join is not a function` was.
+ *
+ * 31.9 wants the same question answered from the TYPE rather than from the name, which is a
+ * checker query this does not make yet. A value whose own type declares `set` or `peek` therefore
+ * resolves to the `Reactive`'s, and 31.13 asks for a warning naming exactly that case.
+ *
+ * WHICH IS WHY A NAME THE `Reactive` DOES NOT DECLARE MUST NOT BE HERE: it takes a member the
+ * value really has and resolves it to nothing. This list is exactly `MEMBERS` in
+ * `shared/reactive/Reactive.ts`, which already declares `then`, `catch` and `finally` — `value`
+ * and `args` are fields of `Cell` and of `ReactiveOptions`, neither of which the `Reactive`
+ * exposes.
+ */
+export const REACTIVE_MEMBERS: ReadonlySet<string> = new Set([
+    'busy',
+    'error',
+    'invalidate',
+    'isError',
+    'patch',
+    'peek',
+    'ready',
+    'refresh',
+    'set',
+    'watch',
+    // A `Reactive` is thenable (1.4), and `catch`/`finally` derive from `then` (1.5).
+    'then',
+    'catch',
+    'finally',
+])

package/src/compiler/SHARED_NAMES.ts

@@ -0,0 +1,45 @@
+/**
+ * Framework names an emitted client module imports from `@abide/abide` rather than `@abide/abide/runtime`.
+ *
+ * The escaping, the url guard, `raw`, `writePath` and `listOf`, which the server's markup and a
+ * client re-rendering an arm or a row both call. A constants leaf, with no imports of its own.
+ */
+export const SHARED_NAMES: ReadonlySet<string> = new Set([
+    'escapeText',
+    'escapeAttribute',
+    'escapeStyleValue',
+    'safeUrl',
+    // 32.37 — present, absent or text: the markup's answer and a built row's.
+    'attributeMarkup',
+    'attributeText',
+    'raw',
+    // 32.30's anchored run, which the server's markup and a browser's parsed row both write.
+    'markupRun',
+    'RAW_WRITES',
+    'writePath',
+    'listOf',
+    // 32.23's abort, which only the server lane can need: a client binding is its own `watch`
+    // and gets one from 2.12. Emitted on both sides because `renderMarkup` is both sides.
+    'slotValue',
+    // 32.5, 32.8 — what a `bind:` operand holds, which the markup writes into the tag.
+    'boundValue',
+    'groupHolds',
+    // 32.6, 33.6, 33.7 — a component's `bind:`, and the cell a child writing that prop builds.
+    'boundProp',
+    'propCell',
+    'propCells',
+    // 33.20 — a default answering where the caller's accessor reads `undefined`.
+    'propOr',
+    'withoutKeys',
+    // 33.22 — a rest element handed on whole, as the values its accessors read.
+    'restValues',
+    // 32.11 — a spread's props, which an invocation passes on both sides, and its markup.
+    'spreadProps',
+    'spreadAttributes',
+    // 10.5's pair: a share scope is opened by the emitted component on both sides, and `#shared`
+    // is where the one scope chain lives.
+    'enterShare',
+    'leaveShare',
+    'currentShare',
+    'resumeShare',
+])

package/src/compiler/SPECIFIERS.ts

@@ -0,0 +1,16 @@
+// What EMITTED code resolves abide through. A leaf, and the contract between the compiler and an
+// app's module graph: emitted code is the APP's, so it reaches for the public specifiers that
+// `packages/abide` itself is forbidden to (CLAUDE.md, "seams and imports"). Holding them here is
+// also what keeps that ban checkable: an import specifier written into a template literal reads
+// to a grep exactly like an import statement, so holding all of them here is the difference between
+// a check that works and one with an exception in it.
+//
+// FIVE, BECAUSE THE ROUTER AND THE WIRE ARE NOT PART OF WHAT EVERY PAGE IMPORTS. Only the emitted
+// route table names the one and only an emitted handler wrapper the other, and an entry each is
+// what keeps them off the runtime barrel every compiled module resolves through. `ui/routing.ts`
+// records what that is and is not worth.
+export const SHARED_SPECIFIER = '@abide/abide'
+export const SERVER_SPECIFIER = '@abide/abide/server'
+export const RUNTIME_SPECIFIER = '@abide/abide/runtime'
+export const ROUTING_SPECIFIER = '@abide/abide/routing'
+export const WIRE_SPECIFIER = '@abide/abide/wire'

package/src/compiler/ShadowMap.ts

@@ -0,0 +1,144 @@
+import type { Origin, Span } from './projectShadow.ts'
+
+/** What a `.abide`'s checked module is registered with the checker as, beside the `.abide`. */
+export const CHECKED_SUFFIX = '.check.ts'
+/** What a `.abide`'s projection is registered with the checker as, beside the `.abide`. */
+const SHADOW_SUFFIX = '.shadow.ts'
+
+/**
+ * The two files the checker reads for one `.abide`, and how a position in either is one in it.
+ *
+ * TWO LAYERS, ONE OVER THE OTHER. The projection (`projectShadow`) places each run it copied in the
+ * `.abide`; the checked module (`checkedShadow`) places each of its own in the projection. A position
+ * the checker reports in the checked module goes back through both, one in the projection through
+ * the first alone — and which one a position is in is the file the checker named, so the map owns
+ * the two suffixes as well as the two `origins`.
+ *
+ * Built over the projection alone where nothing has been lowered yet (`TypeSession.classify`), and
+ * over both once it has.
+ */
+export class ShadowMap {
+    /** The canonical `.abide` path. */
+    readonly abidePath: string
+    /** The projection's path, as the checker reads it. */
+    readonly shadowPath: string
+    /** The checked module's path, as the checker reads it. */
+    readonly checkedPath: string
+    private readonly projected: readonly Origin[]
+    private readonly checked: readonly Origin[]
+
+    constructor(
+        abidePath: string,
+        projected: readonly Origin[],
+        checked: readonly Origin[] = [],
+    ) {
+        this.abidePath = abidePath
+        this.shadowPath = `${abidePath}${SHADOW_SUFFIX}`
+        this.checkedPath = `${abidePath}${CHECKED_SUFFIX}`
+        this.projected = projected
+        this.checked = checked
+    }
+
+    /** The `.abide` a file the checker reads stands for, or `undefined` where it stands for none. */
+    static fileFor(path: string): string | undefined {
+        for (const suffix of [CHECKED_SUFFIX, SHADOW_SUFFIX])
+            if (path.endsWith(`.abide${suffix}`))
+                return path.slice(0, -suffix.length)
+        return undefined
+    }
+
+    /** Whether `path` is one of the files the checker reads for the `.abide` at `abidePath`. */
+    static isShadowOf(path: string, abidePath: string): boolean {
+        return (
+            path === `${abidePath}${SHADOW_SUFFIX}` ||
+            path === `${abidePath}${CHECKED_SUFFIX}`
+        )
+    }
+
+    /**
+     * Where `position` in `path` came from in the `.abide`. A position in scaffolding is placed at
+     * the end of the run before it, which is the source the scaffolding was written for.
+     */
+    toSource(path: string, position: number): number {
+        return mapBack(
+            this.projected,
+            path === this.checkedPath
+                ? mapBack(this.checked, position)
+                : position,
+        )
+    }
+
+    /**
+     * `start` to `end` in `path`, placed in the `.abide`, or `undefined` where it starts in what the
+     * checked module added — a declaration of the lowering's own, which the author never wrote.
+     */
+    spanToSource(path: string, start: number, end: number): Span | undefined {
+        if (
+            path === this.checkedPath &&
+            copiedFrom(this.checked, start) === undefined
+        )
+            return undefined
+        return {
+            start: this.toSource(path, start),
+            end: this.toSource(path, end),
+        }
+    }
+
+    /**
+     * Where the author's `position` stands in what the checker reads: the checked module where the
+     * lowering copied it, the projection where it rewrote it, `undefined` where nothing copied it.
+     */
+    fromSource(
+        position: number,
+    ): { path: string; position: number } | undefined {
+        const projected = mapForward(this.projected, position)
+        if (projected === undefined) return undefined
+        const checked = mapForward(this.checked, projected)
+        return checked === undefined
+            ? { path: this.shadowPath, position: projected }
+            : { path: this.checkedPath, position: checked }
+    }
+}
+
+/** The start of the run holding `position`, plus how far in; scaffolding is the run before's end. */
+function mapBack(origins: readonly Origin[], position: number): number {
+    let low = 0
+    let high = origins.length
+    while (low < high) {
+        const middle = (low + high) >>> 1
+        if ((origins[middle] as Origin).at <= position) low = middle + 1
+        else high = middle
+    }
+    const origin = origins[low - 1]
+    if (origin === undefined) return 0
+    return origin.source + Math.min(position - origin.at, origin.length)
+}
+
+/** The strict `mapBack`: where the run holding `position` was copied from, or `undefined`. */
+function copiedFrom(
+    origins: readonly Origin[],
+    position: number,
+): number | undefined {
+    for (const origin of origins)
+        if (position >= origin.at && position < origin.at + origin.length)
+            return origin.source + position - origin.at
+    return undefined
+}
+
+/**
+ * Where the run copied from source `position` stands, or `undefined` where nothing copied it —
+ * markup, or a read the lowering rewrote. Runs are ascending by where they stand, not by where they
+ * came from, so this is a scan.
+ */
+function mapForward(
+    origins: readonly Origin[],
+    position: number,
+): number | undefined {
+    for (const origin of origins)
+        if (
+            position >= origin.source &&
+            position < origin.source + origin.length
+        )
+            return origin.at + position - origin.source
+    return undefined
+}

package/src/compiler/TemplateNode.ts

@@ -0,0 +1,176 @@
+// What a `.abide` template parses into. Build-time only — nothing here is reached from
+// the client's static closure, and none of it is walked per row.
+
+/**
+ * One attribute on a template element, with its name folded to lower case once.
+ *
+ * AN HTML TAG OR ATTRIBUTE NAME IS ASCII CASE-INSENSITIVE, so every comparison reads the `lower`
+ * form the parser folded once, and the author's spelling is what the emitters write. Folded at each
+ * comparison instead, every site that forgot was its own bug: `<HEAD>` never hoisted, `HREF=`
+ * skipped 32.20's check, `ONCLICK=` shipped as a live attribute, `</BR>` was emitted.
+ */
+export type Attribute = {
+    name: string
+    lowerName: string
+    /**
+     * The literal text, or the expression source where `expression` is true.
+     *
+     * A quoted value with a slot in it is a template literal whose static text is already decoded
+     * (32.27, 32.28), and on a component a static value is too (`pushQuoted`).
+     */
+    value: string
+    /**
+     * `attr={expr}` rather than `attr="text"`.
+     *
+     * The field is always present rather than added on the expression path, so the record has one
+     * shape.
+     */
+    expression: boolean
+}
+
+/**
+ * One arm of a control block.
+ *
+ * `subject` is the source between the braces — a condition for `{#if}` and `{:else if}`, and EMPTY
+ * for `{:else}`, which is what makes it the arm that always takes.
+ */
+export type Branch = Body & { subject: string }
+
+/**
+ * A `{#component Name(pattern)}…{/component}` block: its name, its props pattern and the annotation
+ * typing it, and a body shaped as a block body is, with the `<script>` and `<style>` written in it.
+ *
+ * NOT A NODE. It renders nothing where it stands, so it is never pushed into the list it is
+ * written in — the text either side of it is one run, as the browser parses it — and it is filed
+ * on the body whose scope it is in instead (32.43), or on the invocation it is passed to (32.50).
+ */
+export type InlineComponent = Body & {
+    kind: 'component'
+    name: string
+    /** Where the name starts in the source. */
+    at: number
+    /** The props pattern as written, or `''` where the parentheses are empty. */
+    pattern: string
+    patternAt: number
+    /** The pattern's type annotation as written, or `''` where it has none. */
+    type: string
+    typeAt: number
+}
+
+/**
+ * A branch-local `<script>`: setup run once each time its body is built.
+ *
+ * 14.8 — a record of its own so the projection and the lowering can key its span apart from the
+ * subject's.
+ */
+export type Setup = { text: string }
+
+/** An element, a component invocation or a `<slot>`, with what it holds. */
+export type ElementNode = {
+    kind: 'element'
+    tag: string
+    lowerTag: string
+    attributes: Attribute[]
+    children: TemplateNode[]
+    /**
+     * 32.43 — the inline components declared between an invocation's or a `<slot>`'s tags and
+     * inside an element there. An element of any other kind files its own on the body around it,
+     * and holds none.
+     */
+    components: InlineComponent[]
+    /** 32.50 — the inline components written directly between an invocation's tags. */
+    passed: InlineComponent[]
+}
+
+/**
+ * 32.13 — a `{#for}` block, which repeats its body over a list. A REGION like `{#if}`, and the body
+ * is planned once and instantiated per row, so a row's paths are the row's own.
+ */
+export type ForBlock = Body & {
+    kind: 'block'
+    block: 'for'
+    /** `{#for item, index of list by key}` — `index` and `key` are optional. */
+    item: string
+    index: string
+    subject: string
+    key: string
+}
+
+/** One node of a parsed `.abide` template: an element, text, an expression slot, or a block. */
+export type TemplateNode =
+    | ElementNode
+    | { kind: 'text'; text: string }
+    // The source between the braces, verbatim. 32.1 renders it escaped.
+    | { kind: 'expression'; source: string }
+    // 32.12 — a control block renders ONE branch. A REGION: its shape depends on a value, which
+    // makes it the one place a marker earns its bytes. `invariance.spec.ts` is why that marker
+    // has to be a comment, and `benchGrid.ts` is why there are none anywhere else.
+    | { kind: 'block'; block: 'if'; branches: Branch[] }
+    // 32.16 — a render-time boundary over a region. Two arms, the body and the catch, each carrying
+    // its own copy of the `{:finally}` markup, which stands either way; `error` is the name the catch
+    // binds, `''` where the author bound none.
+    | { kind: 'block'; block: 'try'; branches: Branch[]; error: string }
+    | ForBlock
+
+/**
+ * What every body holds: its nodes, its branch-local `<script>` and `<style>`, and the inline
+ * components it declares. A row, an arm, an inline component and the template itself are each one,
+ * and so is what an element holds, with no `<script>` or `<style>` of its own.
+ */
+export type Body = {
+    children: TemplateNode[]
+    /** 14.8 — the body's branch-local `<script>`, or `null`. */
+    setup: Setup | null
+    /** 34.11 — the body's branch-local `<style>`, or `null`. */
+    style: string | null
+    /** 32.43 — the inline components the body declares. */
+    components: InlineComponent[]
+}
+
+const NO_BODIES: readonly Body[] = []
+
+/**
+ * The bodies one level down from a node: a row, each arm of a block, what an element holds.
+ *
+ * ONE LAYOUT, READ BY EVERY WALK, so a body's setup, style and components are not each walk's own
+ * restatement of which kind carries which. An element's body declares what is filed on it, and on
+ * an invocation that is also what it is passed (32.50) — each one a body written between its tags.
+ * 34.10 refuses a `<script>` or a `<style>` in a `{#try}` arm where the file is parsed, so its arms
+ * are read as any arm is and carry none.
+ */
+export function bodiesOf(node: TemplateNode): readonly Body[] {
+    if (node.kind === 'element')
+        return [
+            {
+                children: node.children,
+                setup: null,
+                style: null,
+                components:
+                    node.passed.length === 0
+                        ? node.components
+                        : [...node.components, ...node.passed],
+            },
+        ]
+    if (node.kind !== 'block') return NO_BODIES
+    if (node.block === 'for') return [node]
+    return node.branches
+}
+
+/**
+ * Visits `body` and every body under it, in the file's order: a body, then what it declares, then
+ * the bodies its nodes hold.
+ *
+ * `visit` is handed what the visit of the body around it returned, and an inline component is
+ * handed what the body that DECLARES it returned — it is that body's (32.45), wherever it renders.
+ */
+export function visitBodies<Around>(
+    body: Body,
+    around: Around,
+    visit: (body: Body, around: Around) => Around,
+): void {
+    const inner = visit(body, around)
+    for (const component of body.components)
+        visitBodies(component, inner, visit)
+    for (const node of body.children)
+        for (const child of bodiesOf(node)) visitBodies(child, inner, visit)
+}