@abide/abide 0.123.2 → 0.124.0

package/src/compiler/handlersUnder.ts

@@ -9,8 +9,9 @@
 // each module exports and which call declares each (16.73) — which is also what makes an export
 // that is not a handler a refusal here rather than an address that silently never answers.
 
-import type { Mount } from '#server/answerRpc.ts'
 import { frameworkRouteRefusal } from '#server/appTree.ts'
+import { handlerFileMount } from '#server/handlerFileMount.ts'
+import type { Mount } from '#server/mountHandlers.ts'
 import { PRIVATE_EXPORT } from '#server/PRIVATE_EXPORT.ts'
 import { surfaceName } from '#server/surfaceOf.ts'
 import { PRIVATE_HANDLERS_ADDRESS } from '#shared/ADDRESSES.ts'
@@ -18,8 +19,8 @@ import { parseRoutePattern } from '#shared/routePattern.ts'
 
 import type { PlacedHandler, PlacedSource } from './appLayout.ts'
 import { declaredExports } from './declaredExports.ts'
-import type { Refusals } from './Refusals.ts'
-import type { Diagnosis, TypeSession } from './TypeSession.ts'
+import type { Diagnostics } from './Diagnostics.ts'
+import type { TypeSession } from './TypeSession.ts'
 
 /** A handler file, by its path and its path below the app's root. */
 export type HandlerFile = {
@@ -36,7 +37,7 @@ type Source = Pick<
 >
 
 /**
- * The app's handler mounts, with the warnings the build raised reading them.
+ * The app's handler mounts, the warnings the build raised reading them kept in `diagnostics`.
  *
  * Off one read of the checker. 18.15 — with what the build could not read of a copy's options.
  * 19.1's one owner per route and method is `compileApp`'s, which holds the pages as well.
@@ -48,46 +49,27 @@ export async function handlersUnder(
         PlacedHandler,
         'path' | 'relative' | 'route' | 'scope' | 'matchers'
     >[],
-    refusals: Refusals,
-): Promise<{ mounts: Mount[]; warnings: Diagnosis[] }> {
+    diagnostics: Diagnostics,
+): Promise<Mount[]> {
     const serving: Source[] = []
     for (const source of sources)
         if (source.file.servers.length > 0) serving.push(source)
-    const paths: string[] = []
-    const named: string[] = []
-    for (const file of files) {
-        paths.push(file.path)
-        named.push(file.relative)
-    }
-    // The project is asked of below, so the session keeps its snapshot until then.
-    using _held = session.hold()
-    const project = await session.projectWith(paths)
-    for (const source of serving) {
-        paths.push(session.projectionOf(source.path))
-        named.push(source.path)
-    }
+    const host = session.host
+    const modules: { path: string; file: string; onDisk: boolean }[] = []
+    for (const file of files)
+        modules.push({ path: file.path, file: file.relative, onDisk: true })
+    for (const source of serving)
+        modules.push({
+            path: host.projectionOf(source.path),
+            file: source.path,
+            onDisk: false,
+        })
     // A module whose read was refused is `undefined`, refused at its file already.
-    const declared =
-        project === undefined || paths.length === 0
-            ? paths.map(() => [])
-            : await declaredExports(
-                  project,
-                  session.tsconfig,
-                  paths,
-                  named,
-                  refusals,
-              )
+    const declared = await declaredExports(host, modules, diagnostics)
     const mounts: Mount[] = []
-    const warnings: Diagnosis[] = []
     const names = new Map<string, string>()
-    for (let at = 0; at < files.length; at += 1) {
-        const {
-            relative,
-            route: address,
-            scope,
-            matchers,
-        } = files[at] as (typeof files)[number]
-        const exported = declared[at]
+    for (const { path, relative, route: address, scope, matchers } of files) {
+        const exported = declared.get(path)
         if (exported === undefined) continue
         try {
             const handler = exported.find((each) => each.name === 'default')
@@ -114,35 +96,22 @@ export async function handlersUnder(
                     `abide: ${named} and ${relative} are both named ${surface} on the generated surfaces. RULEBOOK 20.13.`,
                 )
             names.set(surface, relative)
-            mounts.push({
-                address,
-                method: handler.method,
-                source: relative,
-                name: address.slice(address.lastIndexOf('/') + 1),
-                export: 'default',
-                scope,
-                matchers,
-                private: false,
-                ui: handler.ui,
-                cli: handler.cli,
-                mcp: handler.mcp,
-                description: handler.description,
-                copy: handler.copy,
-                defaults: handler.defaults,
-                args: handler.args,
-                result: handler.result,
-            })
-            warnings.push(...handler.unread)
+            mounts.push(
+                handlerFileMount(
+                    { address, source: relative, scope, matchers },
+                    { ...handler, method: handler.method },
+                ),
+            )
+            diagnostics.warn(handler.unread)
         } catch (thrown) {
-            refusals.at(relative, thrown)
+            diagnostics.at(relative, thrown)
         }
     }
-    for (let at = 0; at < serving.length; at += 1) {
-        const { relative, position, place, scope } = serving[at] as Source
+    for (const { path, relative, position, place, scope } of serving) {
         // 34.24 — a dependency's file answers where a mount places it, and its handlers below the
         // path it has there.
         const below = place === 'dependency' ? relative : position
-        for (const each of declared[files.length + at] ?? []) {
+        for (const each of declared.get(host.projectionOf(path)) ?? []) {
             if (each.method === undefined) continue
             if (!each.name.startsWith(PRIVATE_EXPORT)) continue
             const name = each.name.slice(PRIVATE_EXPORT.length)
@@ -164,10 +133,10 @@ export async function handlersUnder(
                 args: each.args,
                 result: each.result,
             })
-            warnings.push(...each.unread)
+            diagnostics.warn(each.unread)
         }
     }
-    return { mounts, warnings }
+    return mounts
 }
 
 /**

package/src/compiler/lineOf.ts

@@ -1,5 +1,3 @@
-import type { Diagnosis } from './TypeSession.ts'
-
 /**
  * An offset into a file's text as the line and column an editor shows, both from 1.
  *
@@ -36,20 +34,3 @@ export function offsetOf(
     }
     return at + position.character
 }
-
-/** abide's own finding at `offset` into `text`, or at line 0 where the text was not handed in. */
-export function diagnosisAt(
-    path: string,
-    text: string | undefined,
-    offset: number,
-    category: Diagnosis['category'],
-    message: string,
-): Diagnosis {
-    return {
-        path,
-        ...(text === undefined ? { line: 0, column: 0 } : lineOf(text, offset)),
-        code: 0,
-        category,
-        message,
-    }
-}

package/src/compiler/matchersOf.ts

@@ -10,8 +10,8 @@
 
 import { parseRoutePattern } from '#shared/routePattern.ts'
 
+import type { Diagnostics } from './Diagnostics.ts'
 import { matcherOf } from './paramFile.ts'
-import type { Refusals } from './Refusals.ts'
 
 /** A directory a file mounts (23.19), where it mounts, and the param files under it, by path. */
 export type MountedTree = { directory: string; at: string; params: string[] }
@@ -28,7 +28,7 @@ type Routed = {
  * Each routed file's matchers, by its path: every name its route's segments give, to the anchored
  * source of the param file it resolves to — empty where its route names none.
  *
- * `params` is every param file of the app's own, by path. Refusals land at the file the fault is in:
+ * `params` is every param file of the app's own, by path. Diagnostics land at the file the fault is in:
  * a param file that declares no matcher at itself, a name that resolves to none at the segment's file.
  */
 export async function matchersOf(
@@ -36,7 +36,7 @@ export async function matchersOf(
     routed: readonly Routed[],
     params: readonly string[],
     trees: readonly MountedTree[],
-    refusals: Refusals,
+    refusals: Diagnostics,
 ): Promise<Map<string, Record<string, string>>> {
     // Every param file's matcher, read once whichever routes name it; `undefined` where 23.24 or
     // 23.25 refused the file, so a segment naming it refuses nothing more.

package/src/compiler/mountsOf.ts

@@ -14,9 +14,9 @@ import { dirname, relative, resolve } from 'node:path' // bun exposes no path he
 import { appFiles } from '#server/appTree.ts'
 import { placeOf } from '#server/placement.ts'
 
+import { Diagnostics } from './Diagnostics.ts'
 import { nearest } from './nearest.ts'
 import { type AbideFile, scriptBodies } from './parseAbide.ts'
-import { Refusals } from './Refusals.ts'
 import { attributedImports } from './splitImports.ts'
 
 /** A `.abide` on disk, and the position it takes in the app. */
@@ -49,7 +49,7 @@ export function mountsOf(
     path: string,
     position: string,
     file: AbideFile,
-    refusals: Refusals,
+    refusals: Diagnostics,
 ): DirectoryMount[] {
     const mounts: DirectoryMount[] = []
     const at = position.includes('/')
@@ -78,7 +78,7 @@ export function mountsOf(
                 return []
             }
             // The package's tree is the package's to refuse; a mount places what it finds.
-            const found = appFiles(directory, new Refusals(directory, true))
+            const found = appFiles(directory, new Diagnostics(directory, true))
             const placed = (below: string): Placed => ({
                 path: `${directory}/${below}`,
                 position: `${at}${below}`,

package/src/compiler/reactiveReads.ts

@@ -0,0 +1,235 @@
+import { getTouchingPropertyName } from 'typescript/unstable/ast'
+import type { Project } from 'typescript/unstable/async'
+
+import { checkedShadow } from './checkedShadow.ts'
+import { type CheckerAnswer, UNCHECKED } from './CheckerAnswer.ts'
+import { byPlace, type Diagnosis, placedFindings } from './Diagnostics.ts'
+import { type Projection, projectShadow } from './projectShadow.ts'
+import { type Abide, abideIn, isReactiveSymbol } from './reactiveTypes.ts'
+import { readsIn } from './readsIn.ts'
+import type { ParsedSource } from './readSources.ts'
+import type { ShadowEdit, ShadowHost } from './ShadowHost.ts'
+import { mapForward, ShadowMap } from './ShadowMap.ts'
+import { templateWarnings } from './templateWarnings.ts'
+
+/** Whether a script can bind a name at all — a file that cannot is never handed to the checker. */
+const DECLARES = /\b(?:const|let|var|import)\b/
+
+/**
+ * Reads and compiler warnings for every file, in one checker snapshot.
+ *
+ * 31.3 — THE READS IN EACH FILE: every occurrence of a name bound to a `Reactive`, classified, in
+ * its projection (`projectShadow`). Everything else is left exactly as written. What each file's
+ * shadow is asked is `readsIn`'s; the rounds a binding typed from a read takes are this module's.
+ *
+ * EVERY FILE IN ONE SNAPSHOT, which is the whole of the compiler's build time. Measured at
+ * 19.7 ms a file taking a snapshot each against 0.8 ms a file sharing one — 25x, because
+ * adding a file to the project's root set is what costs, not asking about it.
+ *
+ * WHAT IT HAS TO SAY THAT IS NOT A TYPE ERROR comes back beside the reads: the compiler's own
+ * warnings (14.14 to 14.17, 32.14), each on the `.abide` line where the source's text
+ * was handed in.
+ */
+export async function reactiveReads(
+    host: ShadowHost,
+    sources: readonly (Pick<ParsedSource, 'path' | 'file'> & {
+        text?: string
+    })[],
+): Promise<{ answers: CheckerAnswer[]; warnings: Diagnosis[] }> {
+    // Per source, its shadow and what is asked of it, or `undefined` where nothing is declared.
+    const queries: ({ map: ShadowMap; projection: Projection } | undefined)[] =
+        []
+    const edit: ShadowEdit = { created: [], changed: [] }
+
+    // EVERY SOURCE PROJECTS BEFORE ANY SHADOW IS REGISTERED. A projection refuses (a top-level
+    // `await`), and a shadow registered ahead of the refusal was in the host with the edit that
+    // would have reported it dropped — so the retry found nothing moved, and the checker answered
+    // from the old shadow at the new one's offsets, or never had the file at all.
+    const projected = sources.map((source) => ({
+        source,
+        projection: projectShadow(source.file),
+    }))
+    for (const { source, projection } of projected) {
+        // 34.2 — A `<script module>` DECLARES NAMES TOO, and the `<script>` under it is inside
+        // that scope on both sides. The projection holds both from offset 0.
+        const scripts = projection.text.slice(0, projection.scripts.end)
+        // A TEMPLATE POSITION IS A QUESTION TOO (14.2): a file that declares nothing but
+        // writes `{format(total)}` has a position only the checker can prove static. And a
+        // `<script server>` always is (16.70): what it binds is read off this shadow, re-exported
+        // under `PRIVATE_EXPORT`.
+        if (
+            !DECLARES.test(scripts) &&
+            projection.slots.size === 0 &&
+            source.file.servers.length === 0
+        ) {
+            queries.push(undefined)
+            continue
+        }
+        // CANONICAL AT THE KEY, not at the comparison. A doubled separator or a relative
+        // path is the same file and a raw string is not the same string — registered as it
+        // arrived, the shadow appeared in nobody's directory listing AND named a file the
+        // checker could not open, and the refusal blamed the app's tsconfig for it.
+        const map = new ShadowMap(
+            host.canonical(source.path),
+            projection.origins,
+        )
+        // AN UNCHANGED SHADOW IS NOT REPORTED, which is what a kept session saves on a save:
+        // the one page that moved is re-read rather than all of them.
+        host.write(map.shadowPath, projection.text, edit)
+        host.openOutside(source.path, map.shadowPath, edit)
+        queries.push({ map, projection })
+    }
+
+    const answered = queries.some((query) => query !== undefined)
+        ? await host.ask(
+              (project) => fixedPoint(host, project, sources, queries),
+              { edit },
+          )
+        : undefined
+    const answers = answered?.answers ?? sources.map(() => UNCHECKED)
+    const warnings = answered?.warnings ?? []
+    for (let at = 0; at < sources.length; at += 1) {
+        const source = sources[at] as (typeof sources)[number]
+        if (source.text !== undefined)
+            warnings.push(
+                ...templateWarnings(
+                    source.path,
+                    source.text,
+                    source.file,
+                    answers[at] ?? UNCHECKED,
+                ),
+            )
+    }
+    warnings.sort(byPlace)
+    return { answers, warnings }
+}
+
+/**
+ * Each query's answer, round after round, and the warnings each file's last answer earned — a
+ * source with no query answered `UNCHECKED`.
+ *
+ * 31.1 — A BINDING THE PROJECTION TYPED FROM A `Reactive` IS ASKED OF THE PROGRAM IT RUNS AS: each
+ * file holding one is lowered with what it has answered so far, and a binding that is a `Reactive`
+ * there is one in the projection too. A binding typed from one that just turned out to be a
+ * `Reactive` is asked again, until a round turns none. Nothing is asked, and no second snapshot
+ * taken, where no file holds one (`readsIn`'s `suspects`).
+ */
+async function fixedPoint(
+    host: ShadowHost,
+    first: Project,
+    sources: readonly (Pick<ParsedSource, 'path' | 'file'> & {
+        text?: string
+    })[],
+    queries: readonly (
+        { map: ShadowMap; projection: Projection } | undefined
+    )[],
+): Promise<{ answers: CheckerAnswer[]; warnings: Diagnosis[] }> {
+    const answers = sources.map(() => UNCHECKED)
+    // Per source, its compiler warnings, the bindings the projection could not type, and those the
+    // lowered program proved a `Reactive`.
+    const warned: Diagnosis[][] = sources.map(() => [])
+    const suspects: number[][] = sources.map(() => [])
+    const held: Set<number>[] = sources.map(() => new Set())
+    const answer = async (
+        asked: Project,
+        abide: Abide,
+        at: number,
+    ): Promise<void> => {
+        const query = queries[at]
+        if (query === undefined) return
+        const source = sources[at] as (typeof sources)[number]
+        const sourceFile = await host.sourceFile(
+            asked,
+            query.map.shadowPath,
+            source.path,
+            'no name in it can be typed (RULEBOOK 31.3)',
+        )
+        const read = await readsIn(
+            asked.checker,
+            abide,
+            sourceFile,
+            query.map.shadowPath,
+            query.projection,
+            source.file,
+            held[at] as Set<number>,
+        )
+        answers[at] = read.answer
+        suspects[at] = read.suspects
+        warned[at] = placedFindings(
+            source.path,
+            source.text,
+            read.warnings,
+            (offset) => query.map.toSource(query.map.shadowPath, offset),
+            'warning',
+            true,
+        )
+    }
+    const every = queries.map((_, at) => at)
+    const firstAbide = await abideIn(first)
+    await Promise.all(every.map((at) => answer(first, firstAbide, at)))
+    for (;;) {
+        const asking = every.filter(
+            (at) => (suspects[at] as number[]).length > 0,
+        )
+        if (asking.length === 0) break
+        const edit: ShadowEdit = { created: [], changed: [] }
+        const lowered = asking.map((at) => {
+            const source = sources[at] as (typeof sources)[number]
+            const query = queries[at] as { map: ShadowMap }
+            const shadow = checkedShadow(
+                source.file,
+                answers[at] as CheckerAnswer,
+            )
+            host.write(query.map.checkedPath, shadow.text, edit)
+            host.openOutside(source.path, query.map.checkedPath, edit)
+            return { at, path: query.map.checkedPath, origins: shadow.origins }
+        })
+        const turned = await host.ask(
+            async (asked) => {
+                const abide = await abideIn(asked)
+                const turning = new Set<number>()
+                await Promise.all(
+                    lowered.map(async ({ at, path, origins }) => {
+                        const sourceFile =
+                            await asked.program.getSourceFile(path)
+                        if (sourceFile === undefined) return
+                        for (const start of suspects[at] as number[]) {
+                            const position = mapForward(origins, start)
+                            if (position === undefined) continue
+                            const symbol =
+                                await asked.checker.getSymbolAtLocation(
+                                    getTouchingPropertyName(
+                                        sourceFile,
+                                        position,
+                                    ),
+                                )
+                            if (
+                                symbol !== undefined &&
+                                (await isReactiveSymbol(
+                                    asked.checker,
+                                    abide,
+                                    symbol,
+                                ))
+                            ) {
+                                ;(held[at] as Set<number>).add(start)
+                                turning.add(at)
+                            }
+                        }
+                    }),
+                )
+                if (turning.size > 0)
+                    await Promise.all(
+                        [...turning].map((at) => answer(asked, abide, at)),
+                    )
+                return turning
+            },
+            { edit },
+        )
+        // A snapshot the checker opened no project in answers nothing further, and no warning of
+        // an earlier round is reported.
+        if (turned === undefined) return { answers, warnings: [] }
+        if (turned.size === 0) break
+        for (const at of asking) if (!turned.has(at)) suspects[at] = []
+    }
+    return { answers, warnings: warned.flat() }
+}

package/src/compiler/reactiveTypes.ts

@@ -182,6 +182,19 @@ export async function isReactiveType(
     )
 }
 
+/**
+ * Whether the value `symbol` names is a `Reactive` (31.3) — the one question a binding is asked,
+ * whether of its projection or of the program it lowers to.
+ */
+export async function isReactiveSymbol(
+    checker: Checker,
+    abide: Abide,
+    symbol: CheckedSymbol,
+): Promise<boolean> {
+    const type = await checker.getTypeOfSymbol(symbol)
+    return type !== undefined && isReactiveType(checker, abide, type, false)
+}
+
 /**
  * Whether a type is abide's `Selection`, or a type parameter constrained by one.
  *

package/src/compiler/readSources.ts

@@ -1,11 +1,11 @@
 import { type CheckerAnswer, UNCHECKED } from './CheckerAnswer.ts'
+import type { Diagnostics } from './Diagnostics.ts'
 import { type AbideFile, parseAbide } from './parseAbide.ts'
-import type { Refusals } from './Refusals.ts'
-import type { Diagnosis, TypeSession } from './TypeSession.ts'
+import type { TypeSession } from './TypeSession.ts'
 
 // EVERY COMPILE OF A `.abide` STARTS THE SAME WAY: the text parsed, then every file read by the
 // checker in one snapshot. `abide build`, `abide check` and an editor's one file differ only in
-// what a refusal does (`Refusals`) — the build stops at it, and a check reports it and goes on with
+// what a refusal does (`Diagnostics`) — the build stops at it, and a check reports it and goes on with
 // the rest.
 
 /** One `.abide`, parsed. `quiet` is read for its props alone and reported on by nobody (33.4). */
@@ -28,7 +28,7 @@ export function parseSources(
         text: string
         quiet?: boolean
     }[],
-    refusals: Refusals,
+    refusals: Diagnostics,
 ): ParsedSource[] {
     const parsed: ParsedSource[] = []
     for (const source of sources) {
@@ -51,37 +51,35 @@ export function parseSources(
 }
 
 /**
- * Each parsed source with the checker's answer, and the compiler's warnings — in one snapshot.
+ * Each parsed source with the checker's answer — in one snapshot — the compiler's warnings kept in
+ * `diagnostics`.
  *
  * ONE SNAPSHOT FOR THE LOT, which is the whole of the compiler's build time (`readsFor`). Where
- * `refusals` collects, a batch that refuses is asked again a file at a time, so which file it was is
- * known and the others still answer; where it throws, so does the batch.
+ * `diagnostics` collects, a batch that refuses is asked again a file at a time, so which file it was
+ * is known and the others still answer; where it throws, so does the batch.
  */
 export async function readSources<Source extends ParsedSource>(
     session: TypeSession,
     parsed: readonly Source[],
-    refusals: Refusals,
-): Promise<{
-    read: ReadSource<Source>[]
-    warnings: Diagnosis[]
-}> {
+    diagnostics: Diagnostics,
+): Promise<ReadSource<Source>[]> {
     try {
         const { answers, warnings } = await session.readsFor(parsed)
-        return { read: answered(parsed, answers), warnings }
+        diagnostics.warn(warnings)
+        return answered(parsed, answers)
     } catch (thrown) {
-        if (!refusals.collecting) throw thrown
+        if (!diagnostics.collecting) throw thrown
     }
     const read: ReadSource<Source>[] = []
-    const warnings: Diagnosis[] = []
     for (const source of parsed)
         try {
             const alone = await session.readsFor([source])
             read.push(...answered([source], alone.answers))
-            warnings.push(...alone.warnings)
+            diagnostics.warn(alone.warnings)
         } catch (thrown) {
-            if (!source.quiet) refusals.at(source.path, thrown)
+            if (!source.quiet) diagnostics.at(source.path, thrown)
         }
-    return { read, warnings }
+    return read
 }
 
 function answered<Source extends ParsedSource>(