@abide/abide 0.123.2 → 0.123.3

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @abide/abide
 
+## 0.123.3
+
+### Patch Changes
+
+- abfff21: Router's doc names the LevelChain that stops a page's scope ([`00c3d2d`](https://github.com/briancray/abide/commit/00c3d2d8038c673e5a067b01402b0d270fa485b8))
+- abfff21: a spread writes through setAttribute's compare-then-write (writeAttribute) ([`017a6ff`](https://github.com/briancray/abide/commit/017a6ff26a1e9ba460973b63b2c8ffc5f9e2f863))
+- abfff21: the routed mount argument comment names LevelChain.mountFrom ([`0942e6e`](https://github.com/briancray/abide/commit/0942e6e9d6545dd24d41579fd5ec28e9478892d9))
+- abfff21: a patch-log release run twice leaves a log a later follower opened ([`206d8df`](https://github.com/briancray/abide/commit/206d8dfde626592eb5ca885567f30afeed6b0b6e))
+- abfff21: one patch log for followed values, and patch marks behind functions ([`3cdda11`](https://github.com/briancray/abide/commit/3cdda118d9a8ed4cbd32834c8cd7823c26f0b5fb))
+- abfff21: one args contract for every way a handler is called ([`4e2dcab`](https://github.com/briancray/abide/commit/4e2dcab0bddaf555404fc22687e2efd41d28b500))
+- abfff21: the {#try} ambient is Scope's private, set only through underBoundary; TryRegion swaps through ArmRegion's fills/armOf ([`54e6a91`](https://github.com/briancray/abide/commit/54e6a9158bd9fe167578479a3ce4669d13797457))
+- abfff21: a file the layout has not seen is checked as painting only where it paints ([`587597f`](https://github.com/briancray/abide/commit/587597f23cdeb331816049ff0670b99eebcb1cd8))
+- abfff21: one diagnostics sink owns the finding type, its placement, abide-ignore, order and printing for build, dev, check, format and the language server ([`6d11f57`](https://github.com/briancray/abide/commit/6d11f57adc226b45bd0ddf1b4a305ee6d7a7a000))
+- abfff21: socketWire and outboxQueue each reset in one call (resetSocketWire, resetOutbox); tests stop reaching into Mux internals and draining the outbox by timing ([`721774f`](https://github.com/briancray/abide/commit/721774f93df6040e20015f03755879c4cf534a38))
+- abfff21: a mounted handler is held to the schema its row derived, so a bundled executable coerces and validates its args (RULEBOOK 19.9) ([`76c92a5`](https://github.com/briancray/abide/commit/76c92a51f0b3f49ee95e95d8088c320d7a896341))
+- abfff21: an editor shows the findings abide check has for a file — lints, handler warnings and the emit's refusals included (RULEBOOK 38.11) ([`9824535`](https://github.com/briancray/abide/commit/9824535e191b0f9748edaafadc0bc8ecc08f75d0))
+- abfff21: simplify pass — one placedSource, packageDirectory in appTree, derivedArgs probes once, manifest read beside the table, PatchLog followers always a set, pairingStatus yields the code alone, KeptChecker's heard takes nothing ([`9a6e663`](https://github.com/briancray/abide/commit/9a6e66361364b841cb53362ace080eb1e7d0372f))
+- abfff21: ServerRoute and ServerError stay private to answerRequest ([`9c51de6`](https://github.com/briancray/abide/commit/9c51de674db98e4c2793fa8f496ebe54924c087f))
+- abfff21: the build on disk is one module, and booting from a compilation is one ordering ([`a3a5349`](https://github.com/briancray/abide/commit/a3a5349baa9c55c9a931f00d635a57743ddf1cdc))
+  
+  An app with no `src/` — its root is its package — now keeps its default `.abide` build and its `bun test` build cache inside the package rather than in the directory above it, as RULEBOOK 38.27 has a build sit beside its app; an app with a `src/` is unchanged.
+- abfff21: a LevelChain owns the routed levels and their head bracketing; Router takes a popped history step through one entry and keeps its step bookkeeping private ([`a4d9641`](https://github.com/briancray/abide/commit/a4d9641105f9d1f9958b9bb6fcf90323c07cd6a8))
+- abfff21: a kept checker reopens a stale project, drops one that threw and owns its watchers, for dev and the language server alike ([`c733d7e`](https://github.com/briancray/abide/commit/c733d7ea7b648a02ed366ffe172aa3b996c7e0de))
+- abfff21: a handler file's mount row is built once, for the compiler and the in-memory test app ([`c7db045`](https://github.com/briancray/abide/commit/c7db0459e89ba4ea74918f29d7823c87a9e01d47))
+- abfff21: format the try and wire changes ([`c85913a`](https://github.com/briancray/abide/commit/c85913a0a36bc8e828885b795ba31340057a22ff))
+- abfff21: the bridge relay writes its own frames and hears sign-ins rather than being told ([`ed69e87`](https://github.com/briancray/abide/commit/ed69e87be6e92f9980cb4f9b66edc59f56f7a88f))
+
 ## 0.123.2
 
 ### Patch Changes

package/bin/abide.ts

@@ -16,8 +16,8 @@ import {
     type CompiledApp,
 } from '#compiler/compileApp.ts'
 import { compiledEntry } from '#compiler/compiledEntry.ts'
+import { type Diagnosis, printDiagnoses } from '#compiler/Diagnostics.ts'
 import { formatAbide } from '#compiler/formatAbide.ts'
-import { formatDiagnosis } from '#compiler/formatDiagnosis.ts'
 import { parseAbide } from '#compiler/parseAbide.ts'
 import { scaffold } from '#compiler/scaffold.ts'
 import { serveLanguage } from '#compiler/serveLanguage.ts'
@@ -26,15 +26,17 @@ import {
     type Compilation,
     serverMapsOf,
 } from '#server/abideModules.ts'
-import { banner } from '#server/banner.ts'
-import { buildDirectory } from '#server/buildDirectory.ts'
 import {
-    CLIENT_DIRECTORY,
-    COMPILATION,
-    ENCODING_SUFFIX,
-    MANIFEST,
-    PUBLIC_DIRECTORY,
-} from '#server/CLIENT_BUILD.ts'
+    buildDirectory,
+    type BuildFiles,
+    buildFiles,
+    builtFiles,
+    markBuild,
+    unmarkedBuild,
+    writeWhole,
+} from '#server/appBuild.ts'
+import { banner } from '#server/banner.ts'
+import { ENCODING_SUFFIX } from '#server/CLIENT_BUILD.ts'
 import { type ClientBundle, clientBundle } from '#server/clientBundle.ts'
 import { type Given, type Host, runCommands } from '#server/commands.ts'
 import { type AppPackage, packageUnder } from '#server/config.ts'
@@ -45,7 +47,6 @@ import { namesUnder } from '#server/namesUnder.ts'
 import { skipped } from '#server/placement.ts'
 import { DEFAULT_DOCUMENT, intoHead } from '#server/render.ts'
 import { runtimeRefusal } from '#server/runtimeRefusal.ts'
-import { pathsUnder, serveBuild } from '#server/serveBuild.ts'
 import { serveDev } from '#server/serveDev.ts'
 import { escapeText } from '#shared/escapeText.ts'
 import { ICON_ADDRESSES, LAUNCHER_PAGE } from '#shared/LAUNCHER_FILES.ts'
@@ -72,12 +73,8 @@ const DISK: Host = {
     // 38.100 — built in this process rather than a child, where nobody built it, and said on
     // stderr: the command's stdout is its own — `openapi`'s document, `mcp`'s messages.
     app: ({ values }) => {
-        const handle = appOnDisk(directoriesOf(values), async (root, out) =>
-            (await serveBuild(root, out, (root, out) =>
-                writeBuild({ root, out }, console.error),
-            ))
-                ? out
-                : undefined,
+        const handle = appOnDisk(directoriesOf(values), (root, out) =>
+            writeBuild({ root, out }, console.error),
         )
         return RUNTIME_REFUSAL === undefined
             ? handle
@@ -116,15 +113,12 @@ async function writeBuild(
     process.env.NODE_ENV ??= 'production'
     // 38.66 — what this build may remove is only what was written before it began.
     const began = Date.now()
-    // 38.100 — a build that fails leaves no build: the previous one's marker goes before anything
-    // can fail, so `abide start` builds again and says why rather than booting what is left.
-    const marker = `${out}/${COMPILATION}`
-    await rm(marker, { force: true })
+    // 38.100 — before anything can fail, so a build that fails leaves no build.
+    const files = await unmarkedBuild(out)
     // `--out` is a real flag rather than a constant because two test files each building into
     // one `.abide/` is the contention CLAUDE.md's "checks" section already records once.
     const app = await compileApp(root)
-    for (const warning of app.warnings)
-        console.warn(formatDiagnosis(warning, process.cwd()))
+    printDiagnoses(app.warnings, console.warn)
     if (
         Object.keys(app.files).length === 0 &&
         Object.keys(app.handlers).length === 0
@@ -138,14 +132,13 @@ async function writeBuild(
     // 36.11 — the directories above `public` and the path below it ARE the address.
     // `src/public/favicon.ico` answers at `/favicon.ico`, and nothing declares that anywhere.
     await writeClient(
-        out,
+        files,
         await clientBundle(root, compilation, app.published, 'build'),
         began,
     )
     // An app's static files are its own whether or not it has a page yet.
-    const copied = await copyPublic(root, out, app.published, began)
-    // LAST, because its presence is what `serveBuild` reads as a finished build (38.100).
-    await writeWhole(marker, JSON.stringify(compilation))
+    const copied = await copyPublic(root, files, app.published, began)
+    await markBuild(files, compilation)
     say(
         `abide build: ${app.sources} source(s), ${copied} public file(s) -> ${out}`,
     )
@@ -299,9 +292,7 @@ async function writtenEntry(
             root,
             sourceMaps: serverMapsOf(app, root),
             package: packageUnder(root),
-            manifest: await Bun.file(`${out}/${MANIFEST}`).json(),
-            client: pathsUnder(`${out}/${CLIENT_DIRECTORY}`),
-            published: pathsUnder(`${out}/${PUBLIC_DIRECTORY}`),
+            ...(await builtFiles(out)),
         }),
     )
     return { entry, compilation: app }
@@ -443,7 +434,7 @@ async function writeIcon(root: string, resources: string): Promise<boolean> {
 
 /** 38.79 — the public file the app's icon is drawn from: `/icon.icns`, else `/icon.png`. */
 async function publishedIcon(root: string): Promise<string | undefined> {
-    const published = `${buildDirectory(root)}/${PUBLIC_DIRECTORY}`
+    const { published } = buildFiles(buildDirectory(root))
     for (const address of [ICON_ADDRESSES.icns, ICON_ADDRESSES.png])
         if (await Bun.file(`${published}${address}`).exists())
             return `${published}${address}`
@@ -517,7 +508,7 @@ ${body}</dict>
  */
 async function copyPublic(
     root: string,
-    out: string,
+    files: BuildFiles,
     published: Map<string, string>,
     began: number,
 ): Promise<number> {
@@ -528,35 +519,35 @@ async function copyPublic(
         produced.add(address.slice(1))
         copies.push(
             writeWhole(
-                `${out}/${PUBLIC_DIRECTORY}${address}`,
+                `${files.published}${address}`,
                 Bun.file(`${root}/${source}`),
             ),
         )
     }
     await Promise.all(copies)
     // 38.66 — a public file the app no longer has is no longer answered.
-    await pruneStale(`${out}/${PUBLIC_DIRECTORY}`, produced, began)
+    await pruneStale(files.published, produced, began)
     return published.size
 }
 
 /**
- * Writes the client bundle (`clientBundle`) into `out`, with its manifest and precompressed copies.
+ * Writes the client bundle (`clientBundle`) into the build, with its manifest and precompressed copies.
  *
  * 38.5 — the manifest beside the bundle, and every file in each encoding (`precompressed`). AN APP
  * OF HANDLERS ALONE is written no client, and its manifest anyway, so `abide start` reads one shape
  * whatever the app holds.
  */
 async function writeClient(
-    out: string,
+    files: BuildFiles,
     bundle: ClientBundle,
     began: number,
 ): Promise<void> {
-    const client = `${out}/${CLIENT_DIRECTORY}`
+    const { client } = files
     // 38.66 — STAGED, THEN MOVED IN FILE BY FILE. A second build into the same `out` — or `abide
     // start` serving it — read a chunk half written, and emptying `client/` first took the one it
     // was serving away. Every name but the manifest's is a hash of what it holds, so two builds of
     // one tree move in the same bytes under the same names.
-    const staging = `${out}/.staging-${crypto.randomUUID()}`
+    const staging = `${dirname(client)}/.staging-${crypto.randomUUID()}`
     try {
         const written: Promise<void>[] = []
         for (const [name, { bytes }] of bundle.files)
@@ -574,7 +565,7 @@ async function writeClient(
         }
         await Promise.all(moves)
         await pruneStale(client, produced, began)
-        await writeWhole(`${out}/${MANIFEST}`, JSON.stringify(bundle.manifest))
+        await writeWhole(files.manifest, JSON.stringify(bundle.manifest))
     } finally {
         await rm(staging, { recursive: true, force: true })
     }
@@ -642,17 +633,6 @@ async function pruneStale(
     await Promise.all(stale)
 }
 
-/**
- * Writes `path` whole: to a name of its own beside it, then renamed over it.
- *
- * 38.66 — a reader, or a second build, finds the last complete file there and never a partial one.
- */
-async function writeWhole(path: string, content: string | Blob): Promise<void> {
-    const partial = `${path}.${crypto.randomUUID()}.partial`
-    await Bun.write(partial, content)
-    await rename(partial, path)
-}
-
 /**
  * Wraps a command body with the app's absolute root and build directory, or fails with no app.
  *
@@ -741,24 +721,18 @@ async function check(
     { positionals }: Given,
 ): Promise<number> {
     const within = namedDirectories(positionals)
-    const found = await checkApp(root)
-    let errors = 0
-    let warnings = 0
-    for (const diagnosis of found) {
+    const found: Diagnosis[] = []
+    for (const diagnosis of await checkApp(root))
         if (
-            within.length > 0 &&
-            !within.some(
+            within.length === 0 ||
+            within.some(
                 (directory) =>
                     diagnosis.path === directory ||
                     diagnosis.path.startsWith(`${directory}/`),
             )
         )
-            continue
-        if (diagnosis.category === 'error') errors += 1
-        else if (diagnosis.category === 'warning') warnings += 1
-        else continue
-        console.log(formatDiagnosis(diagnosis, process.cwd()))
-    }
+            found.push(diagnosis)
+    const { errors, warnings } = printDiagnoses(found, console.log)
     console.log(
         `abide check: ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}`,
     )
@@ -802,10 +776,7 @@ async function format(within: string[], { values }: Given): Promise<number> {
             next += 1
             const text = await Bun.file(path).text()
             const formatted = await formatAbide(path, text)
-            for (const finding of formatted.findings) {
-                errors += 1
-                console.log(formatDiagnosis(finding, process.cwd()))
-            }
+            errors += printDiagnoses(formatted.findings, console.log).errors
             if (formatted.text === text) continue
             changed += 1
             if (values.check)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.123.2",
+    "version": "0.123.3",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",

package/src/compiler/Diagnostics.ts

@@ -0,0 +1,198 @@
+import { relative, resolve } from 'node:path' // bun exposes no path helpers of its own
+
+import { isIgnored } from './isIgnored.ts'
+import { lineOf } from './lineOf.ts'
+import { PositionedRefusal } from './PositionedRefusal.ts'
+
+// EVERYTHING THE COMPILER HAS TO SAY, IN ONE PLACE: what a finding is, where it lands on the line an
+// author wrote, which an author silenced, the order the lot is reported in, and the one line each is
+// printed as. `abide build`, `abide dev`, `abide check`, `abide format` and `abide lsp` all read
+// findings off this, so none of them decides for itself what a refusal does or how a warning reads.
+
+/**
+ * One thing the checker said, placed in the file the author wrote.
+ *
+ * 38.3 — line and column from 1.
+ */
+export type Diagnosis = {
+    path: string
+    line: number
+    column: number
+    code: number
+    category: 'error' | 'warning' | 'suggestion' | 'message'
+    message: string
+}
+
+/** A warning or a refusal at a projection offset. */
+export type Finding = { at: number; message: string }
+
+/**
+ * Where everything a compile finds goes, each at the file it was found in.
+ *
+ * TWO MODES AND ONE CALL for a refusal: a build stops at one, so a throwing sink throws it; `abide
+ * check` reports every one at its file and goes on (38.33), so a collecting sink keeps each as a
+ * finding at the file's first line. A warning is kept either way — it does not stop a build — and so
+ * is what the checker says (`checked`). Every stage takes this and nothing else, so no stage decides
+ * for itself what a refusal does, and none spells a path its own way: a file is named relative to
+ * `root` or absolutely, and kept absolute.
+ */
+export class Diagnostics {
+    /** Every refusal kept, in the order met; empty in a throwing sink. */
+    readonly refused: Diagnosis[] = []
+    /** Every warning the compiler raised, in the order met (14, 32.14, 11.30, 18.15). */
+    readonly warnings: Diagnosis[] = []
+    /** What the checker said of each file (38.3). */
+    readonly checked: Diagnosis[] = []
+    /** What a file below the root is named relative to. */
+    readonly root: string
+    /** Whether a refusal is kept and the compile goes on, rather than thrown. */
+    readonly collecting: boolean
+
+    constructor(root: string, collecting: boolean) {
+        this.root = root
+        this.collecting = collecting
+    }
+
+    /** Every finding, in the order reported: the refusals, the warnings, then the checker's. */
+    get findings(): Diagnosis[] {
+        return [...this.refused, ...this.warnings, ...this.checked]
+    }
+
+    /**
+     * Refuses at `file`, below the root or absolute: `thrown` is thrown, or kept. Handed the file's
+     * `text`, a `PositionedRefusal` is placed on its line and column, and thrown as that line.
+     */
+    at(file: string, thrown: unknown, text?: string): void {
+        const positioned =
+            text !== undefined && thrown instanceof PositionedRefusal
+        if (!this.collecting && !positioned) throw thrown
+        const diagnosis = diagnosisAt(
+            resolve(this.root, file),
+            positioned ? text : undefined,
+            positioned ? thrown.offset : 0,
+            'error',
+            thrown instanceof Error ? thrown.message : String(thrown),
+        )
+        if (!this.collecting)
+            throw new Error(formatDiagnosis(diagnosis, process.cwd()))
+        this.refused.push(diagnosis)
+    }
+
+    /**
+     * What another stage kept, as this one takes it: every one kept, or every one thrown as one
+     * error, each at its file — a build that stops names all it found rather than a first one and a
+     * second run (11.37).
+     */
+    adopt(found: readonly Diagnosis[]): void {
+        if (found.length === 0) return
+        if (this.collecting) {
+            this.refused.push(...found)
+            return
+        }
+        const lines: string[] = []
+        for (const one of found) lines.push(formatDiagnosis(one, process.cwd()))
+        throw new Error(lines.join('\n'))
+    }
+
+    /** Keeps `found` as warnings: the build goes on. */
+    warn(found: readonly Diagnosis[]): void {
+        this.warnings.push(...found)
+    }
+
+    /** Keeps what the checker said. */
+    check(found: readonly Diagnosis[]): void {
+        this.checked.push(...found)
+    }
+}
+
+/** 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,
+    }
+}
+
+/**
+ * Each of `findings`, at an offset `place` maps into the file at `path` the author wrote, as a
+ * finding on its line — or on line 0 where the text was not handed in.
+ *
+ * 14.19 — `reads`: they are warnings on reactive reads, and one the line above silences with
+ * `abide-ignore` and its clause is left out. No other finding is silenced so.
+ */
+export function placedFindings(
+    path: string,
+    text: string | undefined,
+    findings: readonly Finding[],
+    place: (at: number) => number,
+    category: Diagnosis['category'],
+    reads = false,
+): Diagnosis[] {
+    const placed: Diagnosis[] = []
+    for (const finding of findings) {
+        const offset = place(finding.at)
+        if (
+            reads &&
+            text !== undefined &&
+            isIgnored(text, offset, finding.message)
+        )
+            continue
+        placed.push(diagnosisAt(path, text, offset, category, finding.message))
+    }
+    return placed
+}
+
+/** Orders findings by file, then line, then column. */
+export function byPlace(one: Diagnosis, two: Diagnosis): number {
+    return (
+        one.path.localeCompare(two.path) ||
+        one.line - two.line ||
+        one.column - two.column
+    )
+}
+
+/**
+ * One finding as one `tsc`-style line.
+ *
+ * ONE LINE A FINDING, in the shape `tsc` and every editor's problem matcher already read:
+ * `file:line:column - error TS2322: …`, the path relative to `from`. A finding with no line — a
+ * whole-file or whole-app refusal — names the file alone.
+ */
+export function formatDiagnosis(diagnosis: Diagnosis, from: string): string {
+    const path = relative(from, diagnosis.path) || diagnosis.path
+    const where =
+        diagnosis.line === 0
+            ? path
+            : `${path}:${diagnosis.line}:${diagnosis.column}`
+    const code = diagnosis.code === 0 ? '' : ` TS${diagnosis.code}`
+    return `${where} - ${diagnosis.category}${code}: ${diagnosis.message}`
+}
+
+/**
+ * Writes each error and warning in `found` as its line, relative to where the command was run, and
+ * answers how many of each — what every command that reports findings prints. A suggestion or a
+ * message is neither, and is not written.
+ */
+export function printDiagnoses(
+    found: readonly Diagnosis[],
+    write: (line: string) => void,
+): { errors: number; warnings: number } {
+    let errors = 0
+    let warnings = 0
+    for (const diagnosis of found) {
+        if (diagnosis.category === 'error') errors += 1
+        else if (diagnosis.category === 'warning') warnings += 1
+        else continue
+        write(formatDiagnosis(diagnosis, process.cwd()))
+    }
+    return { errors, warnings }
+}

package/src/compiler/KeptChecker.ts

@@ -0,0 +1,97 @@
+import { type FSWatcher, watch } from 'node:fs' // bun exposes no file watcher of its own
+
+import { type AppChecker, openChecker } from './compileApp.ts'
+
+/**
+ * An app's checker kept for as long as a server runs, opened when first asked for and told what its
+ * watchers see move.
+ *
+ * `abide dev` and `abide lsp` keep one each, because spawning a checker is most of what a compile
+ * costs. WHAT KEEPING ONE TAKES is here rather than in either: one whose project moved
+ * (`AppChecker.current`) is closed and another opened, and one a question threw from is dropped —
+ * the checker's own process dying is a throw too, and a session nobody can tell apart from a dead
+ * one is not one to keep. `heard` is told every move after the checker is, so what it schedules
+ * reads a checker that already knows.
+ */
+export class KeptChecker {
+    readonly root: string
+    private readonly heard: () => void
+    private readonly watchers: FSWatcher[] = []
+    private readonly watched = new Set<string>()
+    private checker: Promise<AppChecker> | undefined
+    private readonly open: (root: string) => Promise<AppChecker>
+
+    constructor(
+        root: string,
+        heard: () => void,
+        open: (root: string) => Promise<AppChecker> = openChecker,
+    ) {
+        this.root = root
+        this.heard = heard
+        this.open = open
+        this.watch(root, true)
+    }
+
+    /** A checker on the project as it stands: the one kept where it still is, or a fresh one. */
+    async live(): Promise<AppChecker> {
+        const kept = this.checker
+        if (kept !== undefined) {
+            const checker = await kept.catch(() => undefined)
+            if (checker?.current()) return checker
+            if (this.checker === kept) await this.drop()
+        }
+        this.checker ??= this.open(this.root)
+        return this.checker
+    }
+
+    /** `question` asked of a live checker; a throw drops it, so the next question opens another. */
+    async run<Answer>(
+        question: (checker: AppChecker) => Promise<Answer>,
+    ): Promise<Answer> {
+        try {
+            return await question(await this.live())
+        } catch (thrown) {
+            await this.drop()
+            throw thrown
+        }
+    }
+
+    /** Watches `directory` too — a linked package's, outside the root — once for the session. */
+    watch(directory: string, recursive = false): void {
+        if (this.watched.has(directory)) return
+        this.watched.add(directory)
+        this.watchers.push(
+            watch(directory, { recursive }, (_event, filename) =>
+                this.saw(
+                    filename === null ? undefined : `${directory}/${filename}`,
+                ),
+            ),
+        )
+    }
+
+    /** Records a move at `path`, or one nobody could place, then tells `heard`. */
+    saw(path: string | undefined): void {
+        void this.checker?.then(
+            (checker) => checker.saw(path),
+            () => {},
+        )
+        this.heard()
+    }
+
+    /** Stops watching and closes the checker. */
+    async close(): Promise<void> {
+        for (const watcher of this.watchers) watcher.close()
+        this.watchers.length = 0
+        await this.drop()
+    }
+
+    private async drop(): Promise<void> {
+        const dropped = this.checker
+        this.checker = undefined
+        try {
+            await (await dropped)?.close()
+        } catch {
+            // Already gone, which is what closing it was for.
+        }
+    }
+}

package/src/compiler/Lowering.ts

@@ -3,7 +3,7 @@ import { SyntaxKind } from 'typescript/unstable/ast'
 import type { CheckerAnswer } from './CheckerAnswer.ts'
 import type { Read } from './classifyRead.ts'
 import { holdsSlot } from './classifyTemplate.ts'
-import type { Finding } from './Finding.ts'
+import type { Finding } from './Diagnostics.ts'
 import { type AbideFile, scriptBodies } from './parseAbide.ts'
 import {
     type Origin,

package/src/compiler/PositionedRefusal.ts

@@ -1,6 +1,6 @@
 /**
  * A refusal that knows WHERE in the file's text it stands, so a sink handed the text reports it on
- * the line and column the author typed rather than at the file (`Refusals.at`).
+ * the line and column the author typed rather than at the file (`Diagnostics.at`).
  */
 export class PositionedRefusal extends Error {
     /** The offset into the file's text the refusal stands at. */