@abide/abide 0.123.2 → 0.124.0

package/src/compiler/compileApp.ts

@@ -6,9 +6,9 @@ import {
     type CompiledFile,
     resolvedFile,
 } from '#server/abideModules.ts'
-import type { Mount } from '#server/answerRpc.ts'
 import { CLIENT_ENTRY } from '#server/CLIENT_BUILD.ts'
 import { COMPONENT_QUERY } from '#server/MODULE_QUERIES.ts'
+import type { Mount } from '#server/mountHandlers.ts'
 import { ROUTES_TABLE, SERVER_TABLE } from '#server/TABLES.ts'
 import { VIRTUAL_DIRECTORY } from '#server/VIRTUAL_DIRECTORY.ts'
 import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
@@ -22,15 +22,19 @@ import {
     type PlacedSource,
     shapeOf,
 } from './appLayout.ts'
+import { type Diagnosis, Diagnostics } from './Diagnostics.ts'
 import { emitSource } from './emitSource.ts'
 import { handlersUnder } from './handlersUnder.ts'
 import { isAbideSpecifier } from './hookCalls.ts'
 import { nearest } from './nearest.ts'
 import { projectShadow } from './projectShadow.ts'
-import { type ReadSource, readSources } from './readSources.ts'
-import { Refusals } from './Refusals.ts'
+import {
+    type ParsedSource,
+    type ReadSource,
+    readSources,
+} from './readSources.ts'
 import { respecified } from './splitImports.ts'
-import { type Diagnosis, TypeSession } from './TypeSession.ts'
+import { TypeSession } from './TypeSession.ts'
 import { writeDefaultProject } from './writeDefaultProject.ts'
 
 // AN APP'S `.abide` SOURCES, COMPILED — every file keyed by its path below the root, and loaded
@@ -80,7 +84,7 @@ export type AppChecker = {
      * The same nearest tsconfig and package.json, neither touched since. Asked rather than heard,
      * because either can sit above the watched root — the dogfood's do — and either changes what
      * every file resolves to. Where it is, the session is told every move `saw` held
-     * (`TypeSession.edited`); where it is not, the caller opens another.
+     * (`ShadowHost.edited`); where it is not, `KeptChecker` opens another.
      */
     current: () => boolean
     close: () => Promise<void>
@@ -102,8 +106,7 @@ export async function openChecker(appRoot: string): Promise<AppChecker> {
         found === undefined
             ? await writeDefaultProject(root)
             : { tsconfig: found, remove: async (): Promise<void> => {} }
-    const session = await TypeSession.open(project.tsconfig)
-    session.root = root
+    const session = await TypeSession.open(project.tsconfig, root)
     const moved = new Set<string>()
     let movedSomewhere = false
     let layout: Promise<AppLayout> | undefined
@@ -193,7 +196,7 @@ export async function compileApp(
 
 /**
  * The app at `appRoot` compiled — THE ONE PIPELINE `abide build` and `abide check` both run, the
- * layout, the reads, the lints and the emit, differing only in what a refusal does (`Refusals`) and
+ * layout, the reads, the lints and the emit, differing only in what a refusal does (`Diagnostics`) and
  * in what is checked beside: a build stops at the first refusal, and a check (`checking`) reports
  * every one at its file with what the checker says of each file (38.3), and goes on checking
  * whatever a refusal does not stop (38.33).
@@ -204,11 +207,11 @@ export async function compiled(
     checking: boolean,
 ): Promise<{ app: CompiledApp; findings: Diagnosis[] }> {
     const root = realpathSync(appRoot)
-    const refusals = new Refusals(root, checking)
+    const diagnostics = new Diagnostics(root, checking)
     // ONE LAYOUT for the sources, the handler files and the public files, and what the tree refuses
     // is met before the checker is asked anything.
     const layout = await (kept?.layout() ?? appLayout(root))
-    refusals.adopt([...layout.unparsed, ...layout.refused])
+    diagnostics.adopt([...layout.unparsed, ...layout.refused])
     const app: CompiledApp = {
         files: {},
         tables: {},
@@ -216,7 +219,7 @@ export async function compiled(
         routes: [],
         mounts: [],
         sources: layout.own,
-        warnings: [],
+        warnings: diagnostics.warnings,
         published: layout.published,
     }
     // 16.2 — an app of handler files alone is still an app; one of neither has nothing to build, and
@@ -231,62 +234,94 @@ export async function compiled(
     // One session for the whole compile: opening it spawns the checker, and the cost is paid once
     // rather than per file.
     return withChecker(root, kept, async (session) => {
-        // 38.33 — A FILE WHOSE PROJECTION IS REFUSED (34.3, 34.17) is refused at its file, found here
-        // because every later step projects it and would refuse it for the whole app.
-        const projected: PlacedSource[] = []
-        for (const source of layout.sources)
-            try {
-                projectShadow(source.file)
-                projected.push(source)
-            } catch (thrown) {
-                refusals.at(source.path, thrown)
-            }
-        const { read, warnings } = await readSources(
+        const emitted = await compiledSources(
+            layout,
             session,
-            projected,
-            refusals,
+            layout.sources,
+            [],
+            diagnostics,
+            checking,
+            true,
         )
-        let found: Diagnosis[] = []
-        let emittable = read
-        if (checking) {
-            // THE APP'S OWN FILES ARE REPORTED ON: a dependency's is compiled with them (34.23), and
-            // what is wrong inside a package is the package's to report.
-            const reported: typeof read = []
-            for (const source of read)
-                if (!source.dependency) reported.push(source)
-            const diagnosed = await session.diagnose(reported, layout)
-            found = diagnosed.diagnoses
-            // A FILE WHOSE LOWERING REFUSED is `found` already, at its line, and is not emitted.
-            emittable = []
-            for (const source of read)
-                if (!diagnosed.refused.has(source.path)) emittable.push(source)
-        }
-        const { ambient, unkeyed } = await session.lints(root, projected)
-        // 11.37 — a build error, every read named.
-        refusals.adopt(ambient)
-        // What the emit throws with no one file to name is refused at the root; a refusal of a file
-        // is refused at it.
-        let emitWarnings: Diagnosis[] = []
+        if (emitted !== undefined) Object.assign(app, emitted)
+        return { app, findings: diagnostics.findings }
+    })
+}
+
+/**
+ * What the compile makes of `own`, everything it finds in it kept in `diagnostics` — THE ONE STEP
+ * `abide check` runs over the app and an editor over the one file it holds (38.11), so the squiggle
+ * and the line CI fails on are one finding: the projection, the reads, the checker's diagnoses
+ * (`checking`), the lints and the emit.
+ *
+ * `beside` is lowered quietly with `own`, for the types it lends (33.4) and reported on by nobody;
+ * `scripts` is whether the app's `.ts` files are checked and read for handlers too, which an editor
+ * asking about one page does not want. `undefined` where the emit threw, which `diagnostics` holds
+ * at the root.
+ */
+export async function compiledSources(
+    layout: AppLayout,
+    session: TypeSession,
+    own: readonly PlacedSource[],
+    beside: readonly ParsedSource[],
+    diagnostics: Diagnostics,
+    checking: boolean,
+    scripts: boolean,
+): Promise<Awaited<ReturnType<typeof emitApp>> | undefined> {
+    // 38.33 — A FILE WHOSE PROJECTION IS REFUSED (34.3, 34.17) is refused at its file, found here
+    // because every later step projects it and would refuse it for the whole app.
+    const projected: PlacedSource[] = []
+    for (const source of own)
         try {
-            const whole = await emitApp(layout, session, emittable, refusals)
-            Object.assign(app, whole)
-            emitWarnings = whole.warnings
+            projectShadow(source.file)
+            projected.push(source)
         } catch (thrown) {
-            refusals.at(root, thrown)
+            diagnostics.at(source.path, thrown)
         }
-        // 11.30 — warned on, and the build goes on.
-        app.warnings = [...warnings, ...unkeyed, ...emitWarnings]
-        return {
-            app,
-            findings: [
-                ...refusals.found,
-                ...unkeyed,
-                ...warnings,
-                ...emitWarnings,
-                ...found,
-            ],
-        }
-    })
+    const read = await readSources(
+        session,
+        [...projected, ...beside],
+        diagnostics,
+    )
+    const placed: ReadSource<PlacedSource>[] = []
+    for (const source of read)
+        if (!source.quiet) placed.push(source as ReadSource<PlacedSource>)
+    let emittable = placed
+    if (checking) {
+        // THE APP'S OWN FILES ARE REPORTED ON: a dependency's is compiled with them (34.23), and
+        // what is wrong inside a package is the package's to report.
+        const reported: typeof read = []
+        for (const source of read)
+            if (source.quiet || !(source as Partial<PlacedSource>).dependency)
+                reported.push(source)
+        const diagnosed = await session.diagnose(reported, layout, scripts)
+        diagnostics.check(diagnosed.diagnoses)
+        // A FILE WHOSE LOWERING REFUSED is reported already, at its line, and is not emitted.
+        emittable = []
+        for (const source of placed)
+            if (!diagnosed.refused.has(source.path)) emittable.push(source)
+    }
+    const { ambient, unkeyed } = await session.lints(
+        layout.root,
+        projected,
+        scripts,
+    )
+    // 11.37 — a build error, every read named. 11.30 — warned on, and the build goes on.
+    diagnostics.adopt(ambient)
+    diagnostics.warn(unkeyed)
+    // What the emit throws with no one file to name is refused at the root; a refusal of a file
+    // is refused at it.
+    try {
+        return await emitApp(
+            scripts ? layout : { ...layout, handlers: [] },
+            session,
+            emittable,
+            diagnostics,
+        )
+    } catch (thrown) {
+        diagnostics.at(layout.root, thrown)
+        return undefined
+    }
 }
 
 /** The emit half of `compiled`, over sources already laid out and read. */
@@ -297,12 +332,9 @@ async function emitApp(
     >,
     session: TypeSession,
     sources: readonly ReadSource<PlacedSource>[],
-    refusals: Refusals,
+    refusals: Diagnostics,
 ): Promise<
-    Pick<
-        CompiledApp,
-        'files' | 'tables' | 'handlers' | 'routes' | 'mounts' | 'warnings'
-    >
+    Pick<CompiledApp, 'files' | 'tables' | 'handlers' | 'routes' | 'mounts'>
 > {
     const { root, routes, errors } = layout
     const files: Record<string, CompiledFile> = {}
@@ -311,7 +343,7 @@ async function emitApp(
     // and the browser holds its wrapper in its place — a handler file's as that file, a private
     // handler's in the server block's place in its own file's module. Written whether or not there
     // is a page: a handler is answered over http to a caller that has none.
-    const { mounts, warnings } = await handlersUnder(
+    const mounts = await handlersUnder(
         session,
         sources,
         layout.handlers,
@@ -387,7 +419,6 @@ async function emitApp(
         handlers,
         routes,
         mounts,
-        warnings,
     }
 }
 
@@ -442,7 +473,7 @@ function tableImport(source: string): string {
 function refuseSharedRoutes(
     routes: AppRoute[],
     mounts: Mount[],
-    refusals: Refusals,
+    refusals: Diagnostics,
 ): void {
     const owners = new Map<string, string>()
     const claim = (method: string, route: string, source: string): void => {
@@ -476,7 +507,7 @@ function refuseAddressCollision(
     routes: AppRoute[],
     mounts: Mount[],
     published: Map<string, string>,
-    refusals: Refusals,
+    refusals: Diagnostics,
 ): void {
     const patterns = new Set<string>()
     for (const route of routes) patterns.add(route.pattern)

package/src/compiler/declaredExports.ts

@@ -1,4 +1,4 @@
-import type { CallExpression, Node } from 'typescript/unstable/ast'
+import type { CallExpression, Node, SourceFile } from 'typescript/unstable/ast'
 import { SyntaxKind } from 'typescript/unstable/ast'
 import {
     isArrayLiteralExpression,
@@ -27,7 +27,7 @@ import {
     type UnionOrIntersectionType,
 } from 'typescript/unstable/async'
 
-import type { Mount } from '#server/answerRpc.ts'
+import type { Mount } from '#server/mountHandlers.ts'
 import type { CopyOptions } from '#shared/CopyOptions.ts'
 import {
     type Defaults,
@@ -43,7 +43,7 @@ import {
     resultSchemaOf,
     type Walk,
 } from './argsSchemaOf.ts'
-import { diagnosisAt } from './lineOf.ts'
+import { type Diagnosis, diagnosisAt, type Diagnostics } from './Diagnostics.ts'
 import { isReactiveCall, METHODS, optionNamed } from './reactiveOptions.ts'
 import {
     abideIn,
@@ -51,8 +51,7 @@ import {
     isReactiveMember,
     valueTypeOf,
 } from './reactiveTypes.ts'
-import type { Refusals } from './Refusals.ts'
-import type { Diagnosis } from './TypeSession.ts'
+import type { ShadowHost } from './ShadowHost.ts'
 
 /**
  * Every value each module exports, with the abide method that declares it.
@@ -64,16 +63,41 @@ import type { Diagnosis } from './TypeSession.ts'
  * namespace is abide's, and an app's own function of that spelling is not. A type is not an
  * export here: it is erased, and has no address to answer at.
  *
- * `projectName` is the tsconfig the project was opened on, which a module outside it is refused by.
- * 38.33 — WHAT IS REFUSED OF A MODULE IS REFUSED AT ITS FILE, `named[at]` for `paths[at]`, every
- * export read either way: a module with a refusal is `undefined`, so nothing refuses it twice.
+ * Per module's `path`: a module `onDisk` is a file the host may not hold yet, which is made a root
+ * of the project where it has to be (`ShadowHost.ask`); a projection is one the host registered.
+ * Where the checker opened no project, every module exports nothing.
+ *
+ * 38.33 — WHAT IS REFUSED OF A MODULE IS REFUSED AT ITS `file`, every export read either way: a
+ * module with a refusal — one outside the project among them — is `undefined`, so nothing refuses
+ * it twice.
  */
 export async function declaredExports(
+    host: ShadowHost,
+    modules: readonly { path: string; file: string; onDisk: boolean }[],
+    refusals: Diagnostics,
+): Promise<Map<string, DeclaredExport[] | undefined>> {
+    const declared = new Map<string, DeclaredExport[] | undefined>()
+    if (modules.length === 0) return declared
+    const onDisk: string[] = []
+    for (const module of modules) if (module.onDisk) onDisk.push(module.path)
+    const asked = await host.ask(
+        (project) => exportsIn(host, project, modules, refusals),
+        { modules: onDisk },
+    )
+    for (let at = 0; at < modules.length; at += 1)
+        declared.set(
+            (modules[at] as (typeof modules)[number]).path,
+            asked === undefined ? [] : asked[at],
+        )
+    return declared
+}
+
+/** What each of `modules` exports in `project`, in their order (`declaredExports`). */
+async function exportsIn(
+    host: ShadowHost,
     project: Project,
-    projectName: string,
-    paths: readonly string[],
-    named: readonly string[],
-    refusals: Refusals,
+    modules: readonly { path: string; file: string }[],
+    refusals: Diagnostics,
 ): Promise<(DeclaredExport[] | undefined)[]> {
     const checker = project.checker
     // ABIDE'S FILE AS THE CHECKER NAMES IT, not as this module does: it canonicalizes a path to
@@ -83,16 +107,17 @@ export async function declaredExports(
         ?.path
     const abide = await abideIn(project)
     return allSettled(
-        paths.map(async (path, at) => {
-            const file = named[at] as string
-            const sourceFile = await project.program.getSourceFile(path)
-            if (sourceFile === undefined) {
-                refusals.at(
-                    file,
-                    new Error(
-                        `abide: ${path} is not inside the project ${projectName}, so what it exports cannot be read (RULEBOOK 16.73). Give the app a tsconfig whose include reaches it.`,
-                    ),
+        modules.map(async ({ path, file }) => {
+            let sourceFile: SourceFile
+            try {
+                sourceFile = await host.sourceFile(
+                    project,
+                    path,
+                    path,
+                    'what it exports cannot be read (RULEBOOK 16.73)',
                 )
+            } catch (thrown) {
+                refusals.at(file, thrown)
                 return undefined
             }
             const module = await checker.getSymbolAtLocation(sourceFile)

package/src/compiler/diagnoseSources.ts

@@ -0,0 +1,232 @@
+import type { AppLayout, PlacedSource } from './appLayout.ts'
+import { checkedShadow, moduleConfigShadow } from './checkedShadow.ts'
+import {
+    byPlace,
+    type Diagnosis,
+    type Finding,
+    placedFindings,
+} from './Diagnostics.ts'
+import { lineOf } from './lineOf.ts'
+import { LoweredFile } from './LoweredFile.ts'
+import { CHECKED_VALUES } from './Lowering.ts'
+import { projectShadow } from './projectShadow.ts'
+import type { ReadSource } from './readSources.ts'
+import { routesDeclaration } from './routesDeclaration.ts'
+import type { ShadowEdit, ShadowHost } from './ShadowHost.ts'
+import { ShadowMap } from './ShadowMap.ts'
+
+/** One source a diagnosis lowers: read, placed where it is a page or a layout, and maybe quiet. */
+export type DiagnosedSource = Omit<ReadSource, 'quiet'> &
+    Partial<Pick<PlacedSource, 'kind' | 'route'>> & {
+        quiet?: boolean
+    }
+
+/**
+ * The checker's diagnostics for each `.abide` source and the app's `.ts` roots, and each source's
+ * lowering.
+ *
+ * 38.3 — WHAT THE CHECKER SAYS ABOUT EACH FILE AS IT RUNS, placed on the `.abide` line. Each
+ * source is checked as its lowered program (`checkedShadow`), which is registered for the life
+ * of the host beside its shadow for the reason a shadow is; and every `.ts` root of the
+ * project under the app's root is checked as it stands, where `scripts` asks for them — an editor
+ * asking about one page does not want the whole app. `sources` carry their text, which is what
+ * a position is a line of. A `quiet` source is lowered and not reported on: a component an
+ * editor's page imports, which is there for the props the page is held to (33.4).
+ *
+ * `app` is the app the sources are checked in (`appLayout`): its route table, which `url`'s
+ * literal is held to (30.26), and its handler files, which type `Config` (27.13). A source placed
+ * as a page or a layout carries its `kind` and `route`, which its `route.params` is typed by (23.9).
+ *
+ * `refused` is the path of every source whose checked lowering refused, which `diagnoses` has
+ * reported at its line — `abide check` emits the rest of the app without them. `lowered` is each
+ * source's lowering, which the host keeps for an editor's questions about it (`LoweredFile`) —
+ * none where the checker opened no project.
+ */
+export async function diagnoseSources(
+    host: ShadowHost,
+    sources: readonly DiagnosedSource[],
+    app: Pick<AppLayout, 'root' | 'addresses' | 'handlers' | 'routes'>,
+    scripts: boolean,
+): Promise<{
+    diagnoses: Diagnosis[]
+    refused: Set<string>
+    lowered: LoweredFile[]
+}> {
+    const within = app.root
+    const edit: ShadowEdit = { created: [], changed: [] }
+    const checked: {
+        source: DiagnosedSource
+        map: ShadowMap
+        refusals: readonly Finding[]
+    }[] = []
+    for (const source of sources) {
+        const shadow = checkedShadow(
+            source.file,
+            source.answer,
+            (source.kind === 'page' || source.kind === 'layout') &&
+                source.route !== undefined
+                ? { route: source.route, kind: source.kind }
+                : undefined,
+        )
+        const map = new ShadowMap(
+            host.canonical(source.path),
+            projectShadow(source.file).origins,
+            shadow.origins,
+        )
+        host.write(map.checkedPath, shadow.text, edit)
+        // 23.19 — a package's page an editor opens is reported on, so its checked module is a
+        // root of the project as its shadow is (`reactiveReads`).
+        if (!source.quiet) host.openOutside(source.path, map.checkedPath, edit)
+        checked.push({ source, map, refusals: shadow.refusals })
+    }
+    // 34.6 — WHAT THE BUNDLER RESOLVES AND THE CHECKER CANNOT: a stylesheet imported for its
+    // effect, and (34.21) markdown imported as text into a `.ts`, which bun's own types leave
+    // out where they declare `.txt`. Declared in a file of its own at the app's root, which is
+    // a script, because a pattern module can only be declared outside a module.
+    host.write(
+        `${host.canonical(within)}/${AMBIENT}`,
+        AMBIENT_DECLARATIONS,
+        edit,
+    )
+    // 27.13 — what a handler file defaults, beside it.
+    for (const handler of app.handlers) {
+        const at = `${host.canonical(handler.path)}${CONFIG_SUFFIX}`
+        const shadow = handler.hooks.includes('onConfig')
+            ? moduleConfigShadow(handler.text)
+            : undefined
+        // One that stops filing keeps its place and declares nothing, so the next snapshot is
+        // told it moved.
+        if (shadow !== undefined || host.holds(at))
+            host.write(at, shadow ?? 'export {}\n', edit)
+    }
+    // 30.26 — THE APP'S ROUTE TABLE, which `url`'s literal is held to: every page the build
+    // routes, declared into abide's own `Routes`. A module rather than a script, since only a
+    // module augments one.
+    host.write(
+        `${host.canonical(within)}/${ROUTES_DECLARATION}`,
+        routesDeclaration(app.addresses, app.routes),
+        edit,
+    )
+    const refused = new Set<string>()
+    for (const { source, refusals } of checked)
+        if (refusals.length > 0) refused.add(source.path)
+    const answered = await host.ask(
+        async (project) => {
+            const program = project.program
+            // `path` is the file the author wrote, which for a checked module is not the file asked.
+            const report = async (
+                asked: string,
+                path: string,
+                place: (position: number) => { line: number; column: number },
+            ): Promise<Diagnosis[]> => {
+                const [syntactic, semantic] = await Promise.all([
+                    program.getSyntacticDiagnostics(asked),
+                    program.getSemanticDiagnostics(asked),
+                ])
+                const said: Diagnosis[] = []
+                for (const diagnostic of [...syntactic, ...semantic])
+                    said.push({
+                        path,
+                        ...place(diagnostic.pos),
+                        code: diagnostic.code,
+                        category: CATEGORIES[diagnostic.category] ?? 'error',
+                        // A checked module's own names are the lowering's, and read as the author's.
+                        message: flatten(diagnostic).replaceAll(
+                            `${CHECKED_VALUES}.`,
+                            '',
+                        ),
+                    })
+                return said
+            }
+            const reports: Promise<Diagnosis[]>[] = []
+            const refusing: Diagnosis[] = []
+            const lowered: LoweredFile[] = []
+            for (const { source, map, refusals } of checked) {
+                const lowering = new LoweredFile(host, source.text, map)
+                host.keep(lowering)
+                lowered.push(lowering)
+                if (source.quiet) continue
+                // A refusal is at a projection offset (`Lowering.refusals`).
+                refusing.push(
+                    ...placedFindings(
+                        source.path,
+                        source.text,
+                        refusals,
+                        (at) => map.toSource(map.shadowPath, at),
+                        'error',
+                    ),
+                )
+                reports.push(
+                    report(map.checkedPath, source.path, (position) =>
+                        lineOf(
+                            source.text,
+                            map.toSource(map.checkedPath, position),
+                        ),
+                    ),
+                )
+            }
+            const standing = scripts ? host.rootsUnder(project, within) : []
+            for (const path of standing)
+                if (!host.holds(path))
+                    reports.push(
+                        Bun.file(path)
+                            .text()
+                            .then((text) =>
+                                report(path, path, (position) =>
+                                    lineOf(text, position),
+                                ),
+                            ),
+                    )
+            const reported = [
+                ...refusing,
+                ...(await Promise.all(reports)).flat(),
+            ]
+            reported.sort(byPlace)
+            // A component's props type is checked twice — in its `props` call and in what a tag is
+            // held to (`checkedShadow`) — and both copies place a finding in it at the one place
+            // written.
+            const diagnoses: Diagnosis[] = []
+            const placed = new Set<string>()
+            for (const diagnosis of reported) {
+                const key = `${diagnosis.path}:${diagnosis.line}:${diagnosis.column}:${diagnosis.code}:${diagnosis.message}`
+                if (placed.has(key)) continue
+                placed.add(key)
+                diagnoses.push(diagnosis)
+            }
+            return { diagnoses, lowered }
+        },
+        { edit },
+    )
+    return {
+        diagnoses: answered?.diagnoses ?? [],
+        refused,
+        lowered: answered?.lowered ?? [],
+    }
+}
+
+const AMBIENT = 'abide-check.d.ts'
+const ROUTES_DECLARATION = 'abide-routes.d.ts'
+const AMBIENT_DECLARATIONS = `declare module '*.css' {}
+declare module '*.md' {
+    const text: string
+    export default text
+}
+`
+
+/** What a module that is no `.abide` is checked beside as, for the `Config` it files (27.13). */
+const CONFIG_SUFFIX = '.config-shadow.ts'
+
+/** Indexed by the API's `DiagnosticCategory`. */
+const CATEGORIES = ['warning', 'error', 'suggestion', 'message'] as const
+
+function flatten(diagnostic: {
+    text: string
+    messageChain?:
+        readonly { text: string; messageChain?: unknown }[] | undefined
+}): string {
+    let message = diagnostic.text
+    const chain = diagnostic.messageChain ?? []
+    for (const link of chain)
+        message += `\n  ${flatten(link as Parameters<typeof flatten>[0]).replaceAll('\n', '\n  ')}`
+    return message
+}

package/src/compiler/emitClient.ts

@@ -143,7 +143,7 @@ class RegionEmission {
  */
 export type SelfFill = 'none' | 'routed' | 'invoked' | 'both'
 
-// The mount's third argument, which only the router passes (`Router.mountFrom`).
+// The mount's third argument, which only the router passes (`LevelChain.mountFrom`).
 const ROUTED = '__routed'
 
 /**

package/src/compiler/formatAbide.ts

@@ -2,7 +2,8 @@ import { dirname } from 'node:path' // bun exposes no path helpers of its own
 
 import { SyntaxKind } from 'typescript/unstable/ast'
 
-import { diagnosisAt, offsetOf } from './lineOf.ts'
+import { type Diagnosis, diagnosisAt } from './Diagnostics.ts'
+import { offsetOf } from './lineOf.ts'
 import { nearest } from './nearest.ts'
 import {
     type AbideFile,
@@ -13,7 +14,6 @@ import {
 } from './parseAbide.ts'
 import { sameTemplate } from './sameTemplate.ts'
 import { isSpace, slotEnd, tokenize } from './tokenize.ts'
-import type { Diagnosis } from './TypeSession.ts'
 import { VOID_ELEMENTS } from './VOID_ELEMENTS.ts'
 
 // 38.125, 38.126 — A `.abide` IS FORMATTED AS PIECES, and `bun fmt` formats every piece that is code: a
@@ -669,12 +669,11 @@ function unwrap(entry: string, unit: string): string {
     if (inner.endsWith(';')) inner = inner.slice(0, -1)
     if (inner.endsWith(')')) inner = inner.slice(0, -1)
     if (!inner.startsWith('\n')) return inner.trimEnd()
-    inner = shiftLines(
-        inner.slice(1),
-        (line) =>
-            line.startsWith(unit) ? line.slice(unit.length) : line.trimStart(),
-        'ts',
-    ).trimEnd()
+    const outdent = (line: string): string =>
+        line.startsWith(unit) ? line.slice(unit.length) : line.trimStart()
+    // The first line opens the expression, so it is never inside a template literal — and
+    // `shiftLines` leaves it alone for that reason, which is why it is outdented here.
+    inner = outdent(shiftLines(inner.slice(1), outdent, 'ts')).trimEnd()
     return inner.endsWith(',') ? inner.slice(0, -1) : inner
 }