@abide/abide 0.58.0 → 0.100.0

package/src/compiler/serveLanguage.ts

@@ -0,0 +1,405 @@
+import { type FSWatcher, watch } from 'node:fs' // bun exposes no file watcher of its own
+import { basename, dirname } from 'node:path' // bun exposes no path helpers of its own
+import { checkSource } from './checkApp.ts'
+import { type AppChecker, openChecker } from './compileApp.ts'
+import type { Diagnosis, Inspection, Place } from './TypeSession.ts'
+
+// 38.12 — `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
+// one finding rather than two implementations that agree most of the time.
+//
+// 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 and a jump to a definition are
+// asked of the program that check registered (`TypeSession.inspect`), 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 directory above the
+// OUTERMOST `ui/` it sits in (`appRootOf`) — with one checker per app, kept for the session.
+// `--root` pins every document to one.
+//
+// ONE CHECK AT A TIME. The checker holds one snapshot, and two checks interleaving would each
+// register the other's text for a moment; a burst of keystrokes collapses onto the last one.
+
+type Message = {
+    id?: number | string
+    method?: string
+    params?: unknown
+}
+
+type Document = { uri: string; text: string; version: number }
+
+const SETTLE_MS = 150
+const HEADER_END = '\r\n\r\n'
+const ENCODER = new TextEncoder()
+
+/** The protocol's `DiagnosticSeverity`. */
+const SEVERITY: Record<Diagnosis['category'], number> = {
+    error: 1,
+    warning: 2,
+    message: 3,
+    suggestion: 4,
+}
+
+/** Answers the language server protocol read from `input` until the client exits. */
+export async function serveLanguage(
+    root: string | undefined,
+    input: ReadableStream<Uint8Array>,
+    write: (bytes: Uint8Array) => void,
+): 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>()
+    let queue: Promise<void> = Promise.resolve()
+
+    const send = (message: object): void => {
+        const body = ENCODER.encode(
+            JSON.stringify({ jsonrpc: '2.0', ...message }),
+        )
+        write(ENCODER.encode(`Content-Length: ${body.length}${HEADER_END}`))
+        write(body)
+    }
+
+    const publish = (uri: string, found: Diagnosis[], text: string): void => {
+        const diagnostics: object[] = []
+        const lines = text.split('\n')
+        for (const diagnosis of found) {
+            const line = Math.max(diagnosis.line - 1, 0)
+            const character = Math.max(diagnosis.column - 1, 0)
+            diagnostics.push({
+                range: {
+                    start: { line, character },
+                    end: {
+                        line,
+                        character:
+                            character +
+                            wordLength(lines[line] ?? '', character),
+                    },
+                },
+                severity: SEVERITY[diagnosis.category],
+                source: 'abide',
+                ...(diagnosis.code === 0 ? {} : { code: diagnosis.code }),
+                message: diagnosis.message,
+            })
+        }
+        send({
+            method: 'textDocument/publishDiagnostics',
+            params: { uri, diagnostics },
+        })
+    }
+
+    // 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 `.ts`
+    // beside the page 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> => {
+        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)
+            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 ((root ?? appRootOf(Bun.fileURLToPath(uri))) === app)
+                            check(uri)
+                }),
+            )
+        return checker
+    }
+
+    const run = async (uri: string): Promise<void> => {
+        const document = documents.get(uri)
+        if (document === undefined) return
+        const version = document.version
+        const path = Bun.fileURLToPath(uri)
+        const app = root ?? appRootOf(path)
+        // A `.abide` belonging to no app has nothing to be checked against.
+        if (app === undefined) return
+        let found: Diagnosis[]
+        try {
+            found = await checkSource(
+                await checkerOf(app),
+                app,
+                path,
+                document.text,
+                (held) => documents.get(Bun.pathToFileURL(held).href)?.text,
+            )
+        } 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,
+                    line: 1,
+                    column: 1,
+                    code: 0,
+                    category: 'error',
+                    message:
+                        thrown instanceof Error
+                            ? thrown.message
+                            : String(thrown),
+                },
+            ]
+        }
+        // A newer text has arrived while this one was checked, and will be published.
+        if (documents.get(uri)?.version !== version) return
+        publish(uri, found, document.text)
+    }
+
+    const check = (uri: string): void => {
+        clearTimeout(timers.get(uri))
+        timers.set(
+            uri,
+            setTimeout(() => {
+                timers.delete(uri)
+                queue = queue.then(() => run(uri))
+            }, SETTLE_MS),
+        )
+    }
+
+    // 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> => {
+        const { textDocument, position } = params as {
+            textDocument: { uri: string }
+            position: { line: number; character: number }
+        }
+        const uri = textDocument.uri
+        if (timers.has(uri)) {
+            clearTimeout(timers.get(uri))
+            timers.delete(uri)
+            queue = queue.then(() => run(uri))
+        }
+        const answered = queue.then(async () => {
+            const document = documents.get(uri)
+            if (document === undefined) return undefined
+            const path = Bun.fileURLToPath(uri)
+            const app = root ?? appRootOf(path)
+            if (app === undefined) return undefined
+            return (await checkerOf(app)).session.inspect(
+                path,
+                document.text,
+                offsetOf(document.text, position),
+            )
+        })
+        queue = answered.then(
+            () => {},
+            () => {},
+        )
+        return answered.catch(() => undefined)
+    }
+
+    const handle = async (message: Message): Promise<boolean> => {
+        const params = message.params as Record<string, unknown> | undefined
+        switch (message.method) {
+            case 'initialize':
+                send({
+                    id: message.id,
+                    result: {
+                        capabilities: {
+                            textDocumentSync: 1,
+                            hoverProvider: true,
+                            definitionProvider: true,
+                        },
+                        serverInfo: { name: 'abide' },
+                    },
+                })
+                return true
+            case 'shutdown':
+                await queue
+                send({ id: message.id, result: null })
+                return true
+            case 'exit':
+                return false
+            case 'textDocument/didOpen': {
+                const opened = params?.textDocument as Document
+                // A document with no file behind it — `untitled:` — belongs to no app, and has no
+                // path for one to be found from.
+                if (
+                    !opened.uri.startsWith('file:') ||
+                    !opened.uri.endsWith('.abide')
+                )
+                    return true
+                documents.set(opened.uri, {
+                    uri: opened.uri,
+                    text: opened.text,
+                    version: opened.version,
+                })
+                check(opened.uri)
+                return true
+            }
+            case 'textDocument/didChange': {
+                const changed = params?.textDocument as Document
+                const document = documents.get(changed.uri)
+                const changes = params?.contentChanges as { text: string }[]
+                const last = changes[changes.length - 1]
+                if (document === undefined || last === undefined) return true
+                document.text = last.text
+                document.version = changed.version
+                check(changed.uri)
+                return true
+            }
+            case 'textDocument/hover': {
+                const found = await inspect(params)
+                send({
+                    id: message.id,
+                    result:
+                        found === undefined
+                            ? null
+                            : {
+                                  contents: {
+                                      kind: 'markdown',
+                                      value: `\`\`\`ts\n${found.signature}\n\`\`\`${
+                                          found.documentation === ''
+                                              ? ''
+                                              : `\n\n${found.documentation}`
+                                      }`,
+                                  },
+                              },
+                })
+                return true
+            }
+            case 'textDocument/definition': {
+                const found = await inspect(params)
+                const locations: object[] = []
+                for (const place of found?.definitions ?? [])
+                    locations.push(locationOf(place))
+                send({ id: message.id, result: locations })
+                return true
+            }
+            case 'textDocument/didClose': {
+                const closed = params?.textDocument as { uri: string }
+                if (!documents.delete(closed.uri)) return true
+                clearTimeout(timers.get(closed.uri))
+                timers.delete(closed.uri)
+                publish(closed.uri, [], '')
+                return true
+            }
+        }
+        // A request this server does not answer is still answered, so the client does not wait.
+        if (message.id !== undefined && message.method !== undefined)
+            send({
+                id: message.id,
+                error: {
+                    code: -32601,
+                    message: `${message.method} is not served`,
+                },
+            })
+        return true
+    }
+
+    let buffer = new Uint8Array(0)
+    const decoder = new TextDecoder()
+    for await (const chunk of input) {
+        const joined = new Uint8Array(buffer.length + chunk.length)
+        joined.set(buffer)
+        joined.set(chunk, buffer.length)
+        buffer = joined
+        for (;;) {
+            const header = decoder.decode(buffer.subarray(0, 256))
+            const end = header.indexOf(HEADER_END)
+            if (end === -1) break
+            const length = Number(/Content-Length: (\d+)/i.exec(header)?.[1])
+            const start = end + HEADER_END.length
+            if (buffer.length < start + length) break
+            const message = JSON.parse(
+                decoder.decode(buffer.subarray(start, start + length)),
+            ) as Message
+            buffer = buffer.slice(start + length)
+            if (!(await handle(message))) {
+                await closeAll(checkers, watchers)
+                return
+            }
+        }
+    }
+    await closeAll(checkers, watchers)
+}
+
+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(() => {}),
+        ),
+    )
+}
+
+/**
+ * The app a file at `path` belongs to: the directory above its outermost `ui/`.
+ *
+ * OUTERMOST, so a component folder that happens to be called `ui` inside an app is not taken for
+ * the app. `undefined` where the file is under no `ui/` at all.
+ */
+function appRootOf(path: string): string | undefined {
+    let found: string | undefined
+    let at = dirname(path)
+    for (;;) {
+        if (basename(at) === 'ui') found = dirname(at)
+        const up = dirname(at)
+        if (up === at) return found
+        at = up
+    }
+}
+
+/**
+ * How much of a line the finding at `character` underlines: the word that starts there, or one
+ * character where none does.
+ */
+function wordLength(line: string, character: number): number {
+    const word = /^[\w$]+/.exec(line.slice(character))?.[0]
+    return word === undefined ? 1 : word.length
+}
+
+/**
+ * The protocol's `{ line, character }`, from 0, as an offset into `text`. A character is a UTF-16
+ * code unit in the protocol and in a JavaScript string alike.
+ */
+function offsetOf(
+    text: string,
+    position: { line: number; character: number },
+): number {
+    let at = 0
+    for (let line = 0; line < position.line; line += 1) {
+        const end = text.indexOf('\n', at)
+        if (end === -1) return text.length
+        at = end + 1
+    }
+    return at + position.character
+}
+
+/** A `Place`, lines and columns from 1, as the protocol's `Location`, from 0. */
+function locationOf(place: Place): object {
+    return {
+        uri: Bun.pathToFileURL(place.path).href,
+        range: {
+            start: {
+                line: place.start.line - 1,
+                character: place.start.column - 1,
+            },
+            end: { line: place.end.line - 1, character: place.end.column - 1 },
+        },
+    }
+}

package/src/compiler/shareScope.ts

@@ -0,0 +1,51 @@
+import type { Lowering } from './Lowering.ts'
+
+// Where a deferred level holds the share scope its setup ran in (41.19), for its build to resume.
+export const SETTLED_AT = '__settledAt'
+
+// The share scope an instance opens (10.5), named apart from the client's binding `Scope`: one is
+// what a component's descendants look a key up through, the other is what stops its bindings.
+const SHARED = '__shared'
+
+/**
+ * The emitted lines that open and close the instance's own share scope, or two empty strings.
+ *
+ * 10.5 — opened around everything the instance does on either side, or nothing where it shares
+ * nothing. Closed in a `finally`, so an instance that threw leaves the scope it entered.
+ */
+export function shareScope(
+    lowering: Lowering,
+    indent: string,
+): { opened: string; closed: string } {
+    if (!lowering.opensShareScope()) return { opened: '', closed: '' }
+    return {
+        opened: `${indent}const ${SHARED} = ${lowering.use('enterShare')}()\n${indent}try {\n`,
+        closed: `\n${indent}} finally { ${lowering.use('leaveShare')}(${SHARED}) }`,
+    }
+}
+
+/**
+ * The emitted statements that put the share scope held in `at` back and leave it again.
+ *
+ * 10.5 — for work that runs later than the instance it belongs to, with that instance's scope no
+ * longer current. The leave goes in a `finally`, wherever the caller's `try` is.
+ */
+export function resumedShare(
+    lowering: Lowering,
+    at: string,
+): { resume: string; leave: string } {
+    return {
+        resume: `const __back = ${lowering.use('resumeShare')}(${at})`,
+        leave: `${lowering.use('leaveShare')}(__back)`,
+    }
+}
+
+/** `body` run inside the share scope held in `at`, which it leaves in a `finally` (`resumedShare`). */
+export function insideShare(
+    lowering: Lowering,
+    at: string,
+    body: string,
+): string {
+    const { resume, leave } = resumedShare(lowering, at)
+    return `${resume}\ntry {\n${body}\n} finally { ${leave} }`
+}

package/src/compiler/sharedModuleWrites.ts

@@ -0,0 +1,88 @@
+import { type Node, NodeFlags } from 'typescript/unstable/ast'
+import {
+    isVariableDeclaration,
+    isVariableDeclarationList,
+} from 'typescript/unstable/ast/is'
+import type {
+    Symbol as CheckedSymbol,
+    Checker,
+} from 'typescript/unstable/async'
+import { classifyRead, FUNCTIONS } from './classifyRead.ts'
+import type { Finding } from './Finding.ts'
+import type { Span } from './projectShadow.ts'
+
+// 34.19 — A PLAIN `let` IN A `<script module>` THAT A `<script>` WRITES AS IT SETS UP. The block is
+// module scope (34.2), which a server shares across every request, and setup runs inside a render —
+// so the value one request leaves is the one the next request starts from, and its markup drifts
+// from what the browser builds. A `reactive` is per request wherever it is declared (11.32), which
+// is the fix the warning names. A write inside a function runs when that function is called — a
+// handler, in a browser — and is left alone: the warning is for what a render does.
+
+/**
+ * The writes a `<script>` makes, outside any function, to a plain `let` or `var` its file's
+ * `<script module>` declares.
+ *
+ * `names`, `symbols` and `reactive` are `readsIn`'s top-level names, aligned, and `reactive` holds
+ * the symbol only where the name is a `Reactive`.
+ */
+export async function sharedModuleWrites(
+    checker: Checker,
+    shadowPath: string,
+    names: readonly Node[],
+    symbols: readonly (CheckedSymbol | undefined)[],
+    reactive: readonly (CheckedSymbol | undefined)[],
+    modules: Span,
+    scripts: Span,
+): Promise<Finding[]> {
+    const shared: { name: string; symbol: CheckedSymbol }[] = []
+    for (let at = 0; at < names.length; at += 1) {
+        const name = names[at] as Node
+        const symbol = symbols[at]
+        const start = name.getStart()
+        if (
+            symbol === undefined ||
+            reactive[at] !== undefined ||
+            start < modules.start ||
+            start >= modules.end
+        )
+            continue
+        const declaration = name.parent
+        const list = declaration?.parent
+        if (
+            !isVariableDeclaration(declaration) ||
+            list === undefined ||
+            !isVariableDeclarationList(list) ||
+            (list.flags & NodeFlags.Const) !== 0
+        )
+            continue
+        shared.push({ name: (name as { text?: string }).text ?? '', symbol })
+    }
+    if (shared.length === 0) return []
+    const warnings: Finding[] = []
+    for (const { name, symbol } of shared) {
+        const references = await checker.getReferencesToSymbolInFile(
+            shadowPath,
+            symbol,
+        )
+        for (const reference of references) {
+            const node = await reference.resolve()
+            if (node === undefined) continue
+            const at = node.getStart()
+            if (at < scripts.start || at >= scripts.end) continue
+            const shape = classifyRead(node)?.shape
+            if (shape !== 'write' && shape !== 'update') continue
+            if (insideFunction(node)) continue
+            warnings.push({
+                at,
+                message: `abide: \`${name}\` is a plain \`let\` in <script module>, which a server shares across every request, and this <script> writes it while the page renders — so one request's value is where the next one starts. Declare it with \`reactive\`, which is per request wherever it stands, or move it into <script>. RULEBOOK 34.19.`,
+            })
+        }
+    }
+    return warnings
+}
+
+function insideFunction(node: Node): boolean {
+    for (let parent = node.parent; parent !== undefined; parent = parent.parent)
+        if (FUNCTIONS.has(parent.kind)) return true
+    return false
+}