@abide/abide 0.123.2 → 0.124.0

package/src/compiler/serveLanguage.ts

@@ -1,18 +1,23 @@
-import { existsSync, type FSWatcher, watch } from 'node:fs' // bun exposes no file watcher or sync existence check of its own
+import { existsSync } from 'node:fs' // bun exposes no sync existence check of its own
 import { dirname } from 'node:path' // bun exposes no path helpers of its own
 
 import { realOrAsGiven } from '#server/realOrAsGiven.ts'
 
 import { checkSource, lowerApp } from './checkApp.ts'
 import { citedClauses } from './citedClauses.ts'
-import { type AppChecker, openChecker } from './compileApp.ts'
+import { type Diagnosis, formatDiagnosis } from './Diagnostics.ts'
 import { DOCS_SITE } from './DOCS_SITE.ts'
 import { formatAbide } from './formatAbide.ts'
-import { formatDiagnosis } from './formatDiagnosis.ts'
 import { isNamedAlone } from './isNamedAlone.ts'
+import { KeptChecker } from './KeptChecker.ts'
 import { lineOf, offsetOf } from './lineOf.ts'
+import {
+    completionAt,
+    type Inspection,
+    type LoweredFile,
+    type Place,
+} from './LoweredFile.ts'
 import { nearest } from './nearest.ts'
-import type { Diagnosis, Inspection, Place } from './TypeSession.ts'
 
 // 38.11 — `abide lsp`: THE `.abide` LANGUAGE SERVER, OVER STDIO. It is `abide check` (38.3) asked
 // about one open document at a time, so the squiggle an editor draws and the line CI fails on are
@@ -21,8 +26,8 @@ import type { Diagnosis, Inspection, Place } from './TypeSession.ts'
 // WHAT IT SPEAKS is the part of the protocol a diagnostic needs: the handshake, a document opened,
 // changed and closed, and `publishDiagnostics` back. The document is synced whole (`Full`), so what
 // is checked is exactly the editor's text, saved or not. A hover, a jump to a definition, a
-// completion, the references to a name and a rename of it are asked of the program that check
-// registered (`TypeSession`), so they answer about the same text.
+// completion, the references to a name and a rename of it are asked of the lowering that check
+// registered (`LoweredFile`), so they answer about the same text.
 //
 // THE APP IS THE DOCUMENT'S. An editor starts this at the root of whatever it has open, which in a
 // monorepo is not an app at all, so each document is checked against the root of the NEAREST
@@ -64,8 +69,7 @@ export async function serveLanguage(
 ): Promise<void> {
     const documents = new Map<string, Document>()
     const timers = new Map<string, ReturnType<typeof setTimeout>>()
-    const checkers = new Map<string, AppChecker>()
-    const watchers = new Map<string, FSWatcher>()
+    const checkers = new Map<string, KeptChecker>()
     // Each app's real root, to the root the editor reached it by.
     const links = new Map<string, string>()
     let queue: Promise<void> = Promise.resolve()
@@ -133,37 +137,19 @@ export async function serveLanguage(
     const held = (path: string): string | undefined =>
         documents.get(Bun.pathToFileURL(spelled(path)).href)?.text
 
-    // An app's checker, opened on first use and kept for the session — and TOLD WHAT MOVED ON DISK,
-    // or it answers every check from the text it read when it opened: an export added to a `lib`
-    // module the page imports is "no exported member" until the editor restarts this. A project whose
-    // tsconfig or package.json moved is opened again.
-    const checkerOf = async (app: string): Promise<AppChecker> => {
+    // An app's checker, kept for the session — and TOLD WHAT MOVED ON DISK, or it answers every
+    // check from the text it read when it opened: an export added to a `lib` module the page
+    // imports is "no exported member" until the editor restarts this (`KeptChecker`).
+    const checkerOf = (app: string): KeptChecker => {
         let checker = checkers.get(app)
-        if (checker !== undefined && !checker.current()) {
-            checkers.delete(app)
-            await checker.close().catch(() => {})
-            checker = undefined
-        }
         if (checker === undefined) {
-            checker = await openChecker(app)
+            checker = new KeptChecker(app, () => {
+                // What an open page says may be decided by the file that moved.
+                for (const uri of documents.keys())
+                    if (placed(uri)?.app === app) check(uri)
+            })
             checkers.set(app, checker)
         }
-        if (!watchers.has(app))
-            watchers.set(
-                app,
-                watch(app, { recursive: true }, (_event, filename) => {
-                    checkers
-                        .get(app)
-                        ?.saw(
-                            filename === null
-                                ? undefined
-                                : `${app}/${filename}`,
-                        )
-                    // What an open page says may be decided by the file that moved.
-                    for (const uri of documents.keys())
-                        if (placed(uri)?.app === app) check(uri)
-                }),
-            )
         return checker
     }
 
@@ -172,11 +158,9 @@ export async function serveLanguage(
     // keeps one for the session. Queued behind the checks, so none is in flight when it closes.
     const closeIfUnopened = async (app: string): Promise<void> => {
         for (const uri of documents.keys()) if (placed(uri)?.app === app) return
-        watchers.get(app)?.close()
-        watchers.delete(app)
         const checker = checkers.get(app)
         checkers.delete(app)
-        await checker?.close().catch(() => {})
+        await checker?.close()
     }
 
     const run = async (uri: string): Promise<void> => {
@@ -189,17 +173,11 @@ export async function serveLanguage(
         const { app, path } = at
         let found: Diagnosis[]
         try {
-            found = await checkSource(
-                await checkerOf(app),
-                path,
-                document.text,
-                held,
+            found = await checkerOf(app).run((checker) =>
+                checkSource(checker, path, document.text, held),
             )
         } catch (thrown) {
             // The checker's own failure, not the page's: the next check opens another.
-            const failed = checkers.get(app)
-            checkers.delete(app)
-            await failed?.close().catch(() => {})
             found = [
                 {
                     path,
@@ -230,29 +208,30 @@ export async function serveLanguage(
         )
     }
 
-    // A question about a document is about the text the editor shows, so a check still settling
-    // runs now rather than after the answer; and it is answered in the queue, after that check.
     const inspect = (params: unknown): Promise<Inspection | undefined> =>
-        ask(params, (checker, path, text, offset) =>
-            checker.session.inspect(path, text, offset),
-        )
+        ask(params, (lowered, text, offset) => lowered?.inspect(text, offset))
 
     // 38.116 — asked after every page of the app is lowered, which is what a page this one never
     // imports needs to be among the references.
     const references = (params: unknown) =>
-        ask(params, async (checker, path, text, offset) => {
-            await lowerApp(checker, held)
-            return checker.session.references(path, text, offset)
-        })
+        ask(
+            params,
+            (lowered, text, offset) => lowered?.references(text, offset),
+            true,
+        )
 
+    // A QUESTION ABOUT A DOCUMENT IS ASKED OF THE LOWERING ITS CHECK REGISTERED (`LoweredFile`), of
+    // the text the editor shows: a check still settling runs now rather than after the answer, and
+    // the question is answered in the queue, after that check. A lowering of another text answers
+    // nothing at an offset into this one, save the props a tag being typed offers (38.117).
     const ask = <Answer>(
         params: unknown,
         question: (
-            checker: AppChecker,
-            path: string,
+            lowered: LoweredFile | undefined,
             text: string,
             offset: number,
-        ) => Promise<Answer | undefined>,
+        ) => Promise<Answer | undefined> | undefined,
+        everyPage = false,
     ): Promise<Answer | undefined> => {
         const { textDocument, position } = params as {
             textDocument: { uri: string }
@@ -268,9 +247,10 @@ export async function serveLanguage(
             const document = documents.get(uri)
             const at = placed(uri)
             if (document === undefined || at === undefined) return undefined
+            const checker = await checkerOf(at.app).live()
+            if (everyPage) await lowerApp(checker, held)
             return question(
-                await checkerOf(at.app),
-                at.path,
+                checker.session.lowered(at.path),
                 document.text,
                 offsetOf(document.text, position),
             )
@@ -363,8 +343,8 @@ export async function serveLanguage(
                 const trigger = (
                     params?.context as { triggerCharacter?: string } | undefined
                 )?.triggerCharacter
-                const found = await ask(params, (checker, path, text, offset) =>
-                    checker.session.complete(path, text, offset, trigger),
+                const found = await ask(params, (lowered, text, offset) =>
+                    completionAt(lowered, text, offset, trigger),
                 )
                 const items: object[] = []
                 for (const entry of found?.entries ?? [])
@@ -544,24 +524,16 @@ export async function serveLanguage(
             ) as Message
             buffer = buffer.slice(start + length)
             if (!(await handle(message))) {
-                await closeAll(checkers, watchers)
+                await closeAll(checkers)
                 return
             }
         }
     }
-    await closeAll(checkers, watchers)
+    await closeAll(checkers)
 }
 
-async function closeAll(
-    checkers: Map<string, AppChecker>,
-    watchers: Map<string, FSWatcher>,
-): Promise<void> {
-    for (const watcher of watchers.values()) watcher.close()
-    await Promise.all(
-        [...checkers.values()].map((checker) =>
-            checker.close().catch(() => {}),
-        ),
-    )
+async function closeAll(checkers: Map<string, KeptChecker>): Promise<void> {
+    await Promise.all([...checkers.values()].map((checker) => checker.close()))
 }
 
 /**

package/src/compiler/sharedModuleWrites.ts

@@ -9,7 +9,7 @@ import type {
 } from 'typescript/unstable/async'
 
 import { classifyRead, FUNCTIONS } from './classifyRead.ts'
-import type { Finding } from './Finding.ts'
+import type { Finding } from './Diagnostics.ts'
 import type { Span } from './projectShadow.ts'
 
 // 34.18 — A PLAIN `let` IN A `<script module>` THAT A `<script>` WRITES AS IT SETS UP. The block is

package/src/compiler/splitImports.ts

@@ -1,6 +1,6 @@
 import { SyntaxKind } from 'typescript/unstable/ast'
 
-import { COMPONENT_QUERY, TEXT_QUERY } from '#server/MODULE_QUERIES.ts'
+import { COMPONENT_QUERY, TEXT_SUFFIX } from '#server/MODULE_QUERIES.ts'
 
 import { isContextualKeyword, type Token, tokenize } from './tokenize.ts'
 
@@ -473,7 +473,7 @@ export function importedNames(
  */
 function facedSpecifier(specifier: string, lane: Lane): string | undefined {
     if (specifier.endsWith(SOURCE_SUFFIX))
-        return `${specifier.slice(0, -SOURCE_SUFFIX.length)}${TEXT_QUERY}`
+        return `${specifier.slice(0, -SOURCE_SUFFIX.length)}${TEXT_SUFFIX}`
     if (lane === 'component' && specifier.endsWith('.abide'))
         return `${specifier}${COMPONENT_QUERY}`
     return undefined

package/src/compiler/templateWarnings.ts

@@ -1,8 +1,8 @@
 import type { CheckerAnswer } from './CheckerAnswer.ts'
 import type { Read } from './classifyRead.ts'
 import { isComponentTag } from './classifyTemplate.ts'
+import { type Diagnosis, diagnosisAt } from './Diagnostics.ts'
 import { isNamedAlone } from './isNamedAlone.ts'
-import { diagnosisAt } from './lineOf.ts'
 import { Lowering } from './Lowering.ts'
 import type { AbideFile } from './parseAbide.ts'
 import {
@@ -12,7 +12,6 @@ import {
     type TemplateNode,
     visitBodies,
 } from './TemplateNode.ts'
-import type { Diagnosis } from './TypeSession.ts'
 
 // 32.14 — A `{#for}` WITH NO KEY OVER A BODY THAT HOLDS STATE. Unkeyed, a row is matched to the
 // item at its index, so a reorder hands one row's state — a component's own values, a field's text,

package/src/compiler/trackingWarnings.ts

@@ -16,7 +16,7 @@ import {
 } from 'typescript/unstable/ast/is'
 
 import { FUNCTIONS, TRANSPARENT } from './classifyRead.ts'
-import type { Finding } from './Finding.ts'
+import type { Finding } from './Diagnostics.ts'
 import type { PositionKind, PositionTable } from './PositionTable.ts'
 
 // 14.14, 14.15, 14.16 — WHERE A READ STANDS IN A BODY THAT TRACKS, and the three ways it can stand

package/src/server/CLIENT_BUILD.ts

@@ -1,13 +1,9 @@
-// WHERE THE BROWSER BUNDLE LANDS, named once for the commands that have to agree about it:
-// `abide build` writes it, `abide start` answers it, and `abide dev` builds it into memory
-// (38.16, 38.20). A leaf, with no imports of its own, for the reason every constant crossing a
-// seam is one — the build is in `bin/` and the server is in `src/server/`, and a string spelled out
-// in both is a build that silently serves nothing. The addresses it is answered at are
+// WHAT THE BROWSER BUNDLE IS NAMED, once for the seams that have to agree about it: the compiler
+// writes the entry, `abide build` precompresses every file, and the server answers both (38.5,
+// 38.20). A leaf, with no imports of its own, for the reason every constant crossing a seam is one.
+// Where the bundle lands in a build is `appBuild.ts`'s; the addresses it is answered at are
 // `#shared/ADDRESSES.ts`.
 
-/** The directory the bundle lands in, below the build's own output directory. */
-export const CLIENT_DIRECTORY = 'client'
-
 /**
  * The module that mounts the app — the one bundle file whose name the shell writes out.
  *
@@ -19,21 +15,6 @@ export const CLIENT_DIRECTORY = 'client'
  */
 export const CLIENT_ENTRY = 'entry'
 
-/**
- * The manifest file `abide build` writes beside the client directory.
- *
- * 38.5 — the manifest `manifestOf` reads off the bundle, below the build's own output directory
- * and BESIDE the client directory rather than in it: everything in there is answered under
- * `CLIENT_ADDRESS` (38.20), and the manifest is the server's, not the browser's.
- */
-export const MANIFEST = 'manifest.json'
-
-/**
- * The compilation `abide build` keeps beside the client directory: every `.abide` compiled, and
- * the build's own tables (`Compilation`), which `abide start` serves without the compiler.
- */
-export const COMPILATION = 'compilation.json'
-
 /**
  * The encodings a response can be compressed in, each with its precompressed file's suffix.
  *
@@ -43,12 +24,3 @@ export const COMPILATION = 'compilation.json'
  * a build that precompresses into files nothing ever serves.
  */
 export const ENCODING_SUFFIX = { br: '.br', gzip: '.gz' } as const
-
-/**
- * Where `abide build` copies every `public` directory, each file at its address, below its own
- * output directory. The source's own name for one is `#shared/RESERVED_DIRECTORIES.ts`'s.
- *
- * 38.18 — a directory rather than the source tree: `abide start` boots what the build produced and
- * reaches for nothing an app might have moved since.
- */
-export const PUBLIC_DIRECTORY = 'public'

package/src/server/DesktopSession.ts

@@ -0,0 +1,213 @@
+// 38.71-38.75 — WHAT THE DESKTOP WINDOW SHOWS, apart from the window: the app booted here, one
+// connected to elsewhere, or neither — and what the launcher did last, kept across launches.
+
+import { mkdir } from 'node:fs/promises' // bun exposes no directory creation of its own
+
+import { isFailed } from '#shared/Failed.ts'
+
+import { configuredMount } from './config.ts'
+import type { App } from './createApp.ts'
+import { reportUnexpected } from './hooks.ts'
+import type { Launcher } from './launcherOptions.ts'
+import type { Launch } from './launcherPage.ts'
+import { LISTENING } from './requestScope.ts'
+
+/** What the launcher did last, and what its forms held, kept across launches. 38.73. */
+type Remembered = {
+    last: { start: Record<string, string> } | { connect: string } | null
+    values: Record<string, string>
+    url: string
+    port: number
+}
+
+type Failure = NonNullable<Launch['failure']>
+
+const LOOPBACK = '127.0.0.1'
+const CONNECT_TIMEOUT_MILLISECONDS = 5000
+
+/**
+ * The launcher's state machine: start an app here, connect to one elsewhere, disconnect, and
+ * remember which in `desktop.json` under `directory`.
+ *
+ * `boot` boots the app a start serves — `bootEntered` in the executable, anything an `App` in a test.
+ */
+export class DesktopSession {
+    private readonly stateFile: string
+    private readonly directory: string
+    private readonly boot: () => Promise<App>
+    readonly remembered: Remembered
+    /** What the window shows: the app served here, one elsewhere, or neither. */
+    private current: { url: string; app: App | undefined } | undefined
+    /** The last start or connect that was refused, until the page shows it. */
+    private failure: Failure | undefined
+
+    private constructor(
+        directory: string,
+        boot: () => Promise<App>,
+        remembered: Remembered,
+    ) {
+        this.directory = directory
+        this.stateFile = `${directory}/desktop.json`
+        this.boot = boot
+        this.remembered = remembered
+        this.current = undefined
+        this.failure = undefined
+    }
+
+    /** The session `directory`'s `desktop.json` remembers, or a fresh one where there is none. */
+    static async open(
+        directory: string,
+        boot: () => Promise<App>,
+    ): Promise<DesktopSession> {
+        const remembered: Remembered = {
+            last: null,
+            values: {},
+            url: '',
+            port: 0,
+            ...(await Bun.file(`${directory}/desktop.json`)
+                .json()
+                .catch(() => ({}))),
+        }
+        return new DesktopSession(directory, boot, remembered)
+    }
+
+    /** The address the window shows, `undefined` where it shows the launcher. */
+    get shown(): string | undefined {
+        return this.current?.url
+    }
+
+    /** The refusal the page has yet to show, handed over once. */
+    takeFailure(): Failure | undefined {
+        const shown = this.failure
+        this.failure = undefined
+        return shown
+    }
+
+    // 38.72 — the form's values are the environment the app is booted under, so 27.8 coerces them
+    // and 27.7's schema refuses them as it would any other.
+    async start(values: Record<string, string>): Promise<Failure | undefined> {
+        await this.disconnect()
+        this.remembered.values = values
+        for (const [name, value] of Object.entries(values))
+            if (value === '') delete process.env[name]
+            else process.env[name] = value
+        let app: App
+        try {
+            app = await this.boot()
+        } catch (thrown) {
+            return this.refuse(refused('start', thrown))
+        }
+        try {
+            await app
+                // 38.75.
+                .listen({ hostname: LOOPBACK, port: this.remembered.port })
+                // The port the last launch served on, so the app's origin — and its storage with
+                // it — is the one it had; any free one where that is taken.
+                .catch(() => app.listen({ hostname: LOOPBACK, port: 0 }))
+        } catch (thrown) {
+            await app.stop().catch(reportUnexpected)
+            return this.refuse(refused('start', thrown))
+        }
+        const server = LISTENING.server as Bun.Server<unknown>
+        this.remembered.port = server.port ?? 0
+        this.remembered.last = { start: values }
+        this.current = {
+            url: `${server.url.origin}${configuredMount()}/`,
+            app,
+        }
+        await this.remember()
+        return undefined
+    }
+
+    async connect(given: string): Promise<Failure | undefined> {
+        const text = given.trim()
+        this.remembered.url = text
+        const url = URL.parse(
+            /^[a-z][a-z0-9+.-]*:/i.test(text) ? text : `https://${text}`,
+        )
+        if (
+            url === null ||
+            (url.protocol !== 'http:' && url.protocol !== 'https:')
+        )
+            return this.refuse({
+                form: 'connect',
+                message: `${text} is not an address.`,
+                issues: {},
+            })
+        try {
+            await fetch(url, {
+                method: 'HEAD',
+                redirect: 'manual',
+                signal: AbortSignal.timeout(CONNECT_TIMEOUT_MILLISECONDS),
+            })
+        } catch {
+            return this.refuse({
+                form: 'connect',
+                message: `Nothing answered at ${url.origin}.`,
+                issues: {},
+            })
+        }
+        await this.disconnect()
+        this.remembered.last = { connect: url.href }
+        this.current = { url: url.href, app: undefined }
+        await this.remember()
+        return undefined
+    }
+
+    /** Stops the app served here, if one is, and shows neither. */
+    async disconnect(): Promise<void> {
+        const leaving = this.current
+        this.current = undefined
+        if (leaving?.app !== undefined)
+            await leaving.app.stop().catch(reportUnexpected)
+    }
+
+    /** 38.74 — disconnects, and forgets what was done last so the next launch does not redo it. */
+    async forget(): Promise<void> {
+        this.remembered.last = null
+        await Promise.all([this.remember(), this.disconnect()])
+    }
+
+    /** 38.73 — WHAT IT DID LAST, done again, where the launcher still offers it. */
+    async resume(options: Launcher): Promise<void> {
+        const last = this.remembered.last
+        if (options.start && last !== null && 'start' in last)
+            await this.start(last.start)
+        else if (options.connect && last !== null && 'connect' in last)
+            await this.connect(last.connect)
+    }
+
+    private refuse(failure: Failure): Failure {
+        this.failure = failure
+        return failure
+    }
+
+    private async remember(): Promise<void> {
+        await mkdir(this.directory, { recursive: true })
+        await Bun.write(
+            this.stateFile,
+            JSON.stringify(this.remembered, null, 4),
+        )
+    }
+}
+
+/** A refusal as the form it came back to: 27.7's issues by field, or the error's message. */
+function refused(form: 'start' | 'connect', thrown: unknown): Failure {
+    if (
+        isFailed(thrown) &&
+        thrown.data !== null &&
+        typeof thrown.data === 'object'
+    )
+        return {
+            form,
+            message: 'The configuration was refused.',
+            issues: Array.isArray(thrown.data)
+                ? { '': thrown.data as string[] }
+                : (thrown.data as Record<string, string[]>),
+        }
+    return {
+        form,
+        message: thrown instanceof Error ? thrown.message : String(thrown),
+        issues: {},
+    }
+}