@abide/abide 0.101.0 → 0.103.0

package/src/compiler/scaffold.ts

@@ -1,5 +1,6 @@
 // 38.1 — `abide scaffold <name>`: THE LAYOUT EVERY ABIDE APP HAS, written into `<name>`. There is
-// nothing to choose, because what is scaffolded is the three seams and the files the commands read.
+// nothing to choose, because what is scaffolded is a root layout and a page — the files the commands
+// read — and the test preload.
 // A file that is already there is left as it is and reported skipped, so a scaffold run over a
 // half-made project finishes it rather than overwriting it.
 
@@ -7,8 +8,8 @@ import { withoutTrailingSlash } from '#server/withoutTrailingSlash.ts'
 import abidePackage from '../../package.json' with { type: 'json' }
 import { COMPILER_OPTIONS } from './writeDefaultProject.ts'
 
-// THE STARTER'S OWN FILES, as files: a real document, a real page and a real module, copied as they
-// stand. What depends on the name — the manifests — is written here.
+// THE STARTER'S OWN FILES, as files: a real document, a real page and the agent notes, copied as
+// they stand. What depends on the name, or what a packer drops (`filesFor`), is written here.
 const STARTER = Bun.fileURLToPath(new URL('../../scaffold/', import.meta.url))
 
 // THE ABIDE THAT WROTE THE PROJECT is the one it depends on. Installed from a registry, that is its
@@ -21,28 +22,44 @@ const ABIDE_DEPENDENCY = PACKAGE_ROOT.includes('/node_modules/')
     ? `^${abidePackage.version}`
     : `file:${PACKAGE_ROOT}`
 
+// The `#src` alias, written as the package's `imports` and again as the checker's `paths`.
+const SOURCE_ALIAS = { '#src/*': ['./src/*', './src/*.ts'] }
+
+/**
+ * 38.109 — the starter's `bunfig.toml`: a test imports the app's `.abide` files as modules, with
+ * nothing booted first.
+ */
+export const TEST_PRELOAD =
+    '# 38.109 — a test imports the app\'s `.abide` files as modules, with nothing booted first.\n[test]\npreload = ["@abide/abide/test"]\n'
+
+// WRITTEN, NOT COPIED, beside the manifests: a packer drops a `bunfig.toml` or a `.gitignore` from
+// the tarball (`bun pm pack` both, `npm pack` the second), so neither survives as a starter file.
 function filesFor(name: string): Record<string, string> {
     return {
+        'bunfig.toml': TEST_PRELOAD,
+        '.gitignore': 'node_modules\n.abide\n',
         'package.json': `${JSON.stringify(
             {
                 name,
                 private: true,
                 type: 'module',
                 scripts: {
+                    // 38.103 — the checker over `.abide`, which `tsc` does not read.
+                    check: 'abide check',
                     dev: 'abide dev',
                     build: 'abide build',
                     start: 'abide start',
+                    // 38.108 — every address, and the file answering it.
+                    routes: 'abide routes',
                 },
-                // TWO TARGETS A SEAM, because an extensionless specifier is how the seams are
-                // written and only bun probes for the extension: TypeScript takes an `imports`
-                // target as the exact file, so `#server/database` alone left every name it
-                // imports `any` and the checker could not type one of them (31.3). The first
-                // target is what bun resolves, and the one a `.ts` or `.abide` specifier needs.
-                imports: {
-                    '#ui/*': ['./src/ui/*', './src/ui/*.ts'],
-                    '#server/*': ['./src/server/*', './src/server/*.ts'],
-                    '#shared/*': ['./src/shared/*', './src/shared/*.ts'],
-                },
+                // ONE ALIAS FOR THE SOURCE, and two targets for it, because an extensionless
+                // specifier is how an import is written and only bun probes for the extension:
+                // TypeScript takes an `imports` target as the exact file, so `#src/media/server/db`
+                // alone left every name it imports `any` and the checker could not type one of
+                // them (31.3). The first target is what bun resolves, and the one a `.ts` or
+                // `.abide` specifier needs. Which side a module is on is its directory's to say
+                // (36.10), not its alias's.
+                imports: SOURCE_ALIAS,
                 dependencies: { '@abide/abide': ABIDE_DEPENDENCY },
                 // `Bun`, `bun:sqlite` and the rest of the runtime a server module reaches for are
                 // typed by these, and `abide check` reports every one untyped without them.
@@ -53,8 +70,14 @@ function filesFor(name: string): Record<string, string> {
         )}\n`,
         'tsconfig.json': `${JSON.stringify(
             // TypeScript 7 includes no `@types` package it is not named, so the runtime's is named.
+            // 34.21 — the alias as a path too: the checker resolves a text import's declaration
+            // beside the file a path names, and takes an `imports` target as the exact file.
             {
-                compilerOptions: { ...COMPILER_OPTIONS, types: ['bun'] },
+                compilerOptions: {
+                    ...COMPILER_OPTIONS,
+                    types: ['bun'],
+                    paths: SOURCE_ALIAS,
+                },
                 include: ['src'],
             },
             null,
@@ -81,7 +104,6 @@ export async function scaffold(
     const written: string[] = []
     const skipped: string[] = []
     const files: [string, string | Blob][] = Object.entries(filesFor(name))
-    // The seam both sides import from is there from the first commit, `.gitkeep` and all.
     for (const path of new Bun.Glob('**/*').scanSync({
         cwd: STARTER,
         dot: true,

package/src/compiler/serveLanguage.ts

@@ -1,10 +1,12 @@
-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 { existsSync, type FSWatcher, watch } from 'node:fs' // bun exposes no file watcher or 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 } from './checkApp.ts'
 import { type AppChecker, openChecker } from './compileApp.ts'
+import { nearest } from './nearest.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
+// 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
 // one finding rather than two implementations that agree most of the time.
 //
@@ -15,10 +17,14 @@ import type { Diagnosis, Inspection, Place } from './TypeSession.ts'
 // 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.
+// monorepo is not an app at all, so each document is checked against the root of the NEAREST
+// package above it (`appRootOf`) — with one checker per app, kept for the session.
 // `--root` pins every document to one.
 //
+// THE EDITOR'S SPELLING STOPS HERE. An app opened through a link (`/tmp` is one on macOS) is
+// checked at its real path, the one bun resolves every import to (`openChecker`), so a path is
+// made real on its way in (`placed`) and spelled under the link again on its way out (`spelled`).
+//
 // 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.
 
@@ -52,8 +58,33 @@ export async function serveLanguage(
     const timers = new Map<string, ReturnType<typeof setTimeout>>()
     const checkers = new Map<string, AppChecker>()
     const watchers = new Map<string, FSWatcher>()
+    // 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()
 
+    // The document at `uri`, in its app's real spelling; `undefined` where no app holds it.
+    const placed = (uri: string): { app: string; path: string } | undefined => {
+        const path = Bun.fileURLToPath(uri)
+        const given = root ?? appRootOf(path)
+        if (given === undefined) return undefined
+        const app = realOrAsGiven(given)
+        if (app !== given) links.set(app, given)
+        return {
+            app,
+            path: path.startsWith(`${given}/`)
+                ? `${app}${path.slice(given.length)}`
+                : path,
+        }
+    }
+
+    // `path`, real, under the root the editor reached its app by.
+    const spelled = (path: string): string => {
+        for (const [app, given] of links)
+            if (path.startsWith(`${app}/`))
+                return `${given}${path.slice(app.length)}`
+        return path
+    }
+
     const send = (message: object): void => {
         const body = ENCODER.encode(
             JSON.stringify({ jsonrpc: '2.0', ...message }),
@@ -118,8 +149,7 @@ export async function serveLanguage(
                         )
                     // 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)
+                        if (placed(uri)?.app === app) check(uri)
                 }),
             )
         return checker
@@ -129,18 +159,18 @@ export async function serveLanguage(
         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
+        const at = placed(uri)
+        if (at === undefined) return
+        const { app, path } = at
         let found: Diagnosis[]
         try {
             found = await checkSource(
                 await checkerOf(app),
-                app,
                 path,
                 document.text,
-                (held) => documents.get(Bun.pathToFileURL(held).href)?.text,
+                (held) =>
+                    documents.get(Bun.pathToFileURL(spelled(held)).href)?.text,
             )
         } catch (thrown) {
             // The checker's own failure, not the page's: the next check opens another.
@@ -179,7 +209,20 @@ 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> => {
+    const inspect = (params: unknown): Promise<Inspection | undefined> =>
+        ask(params, (session, path, text, offset) =>
+            session.inspect(path, text, offset),
+        )
+
+    const ask = <Answer>(
+        params: unknown,
+        question: (
+            session: AppChecker['session'],
+            path: string,
+            text: string,
+            offset: number,
+        ) => Promise<Answer | undefined>,
+    ): Promise<Answer | undefined> => {
         const { textDocument, position } = params as {
             textDocument: { uri: string }
             position: { line: number; character: number }
@@ -192,12 +235,11 @@ export async function serveLanguage(
         }
         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,
+            const at = placed(uri)
+            if (document === undefined || at === undefined) return undefined
+            return question(
+                (await checkerOf(at.app)).session,
+                at.path,
                 document.text,
                 offsetOf(document.text, position),
             )
@@ -220,6 +262,7 @@ export async function serveLanguage(
                             textDocumentSync: 1,
                             hoverProvider: true,
                             definitionProvider: true,
+                            completionProvider: { triggerCharacters: ['.'] },
                         },
                         serverInfo: { name: 'abide' },
                     },
@@ -279,11 +322,39 @@ export async function serveLanguage(
                 })
                 return true
             }
+            // 38.98 — the protocol's `CompletionItemKind` is the checker's own numbering.
+            case 'textDocument/completion': {
+                const trigger = (
+                    params?.context as { triggerCharacter?: string } | undefined
+                )?.triggerCharacter
+                const found = await ask(params, (session, path, text, offset) =>
+                    session.complete(path, text, offset, trigger),
+                )
+                const items: object[] = []
+                for (const entry of found?.entries ?? [])
+                    items.push({
+                        label: entry.name,
+                        kind: entry.kind,
+                        sortText: entry.sortText,
+                        filterText: entry.filterText,
+                        insertText: entry.insertText,
+                        detail: entry.detail,
+                        labelDetails: entry.labelDetails,
+                    })
+                send({
+                    id: message.id,
+                    result:
+                        found === undefined
+                            ? null
+                            : { isIncomplete: found.isIncomplete, items },
+                })
+                return true
+            }
             case 'textDocument/definition': {
                 const found = await inspect(params)
                 const locations: object[] = []
                 for (const place of found?.definitions ?? [])
-                    locations.push(locationOf(place))
+                    locations.push(locationOf(spelled(place.path), place))
                 send({ id: message.id, result: locations })
                 return true
             }
@@ -348,20 +419,16 @@ async function closeAll(
 }
 
 /**
- * The app a file at `path` belongs to: the directory above its outermost `ui/`.
+ * The app a file at `path` belongs to: the root 38.25 finds from the nearest package above it.
  *
- * 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.
+ * That package's `src` where it has one, and the package itself where it does not — the same root
+ * `abide dev` run in that package would find. `undefined` where no package lies above the file.
  */
 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
-    }
+    const manifest = nearest(dirname(path), 'package.json')
+    if (manifest === undefined) return undefined
+    const at = dirname(manifest)
+    return existsSync(`${at}/src`) ? `${at}/src` : at
 }
 
 /**
@@ -390,10 +457,10 @@ function offsetOf(
     return at + position.character
 }
 
-/** A `Place`, lines and columns from 1, as the protocol's `Location`, from 0. */
-function locationOf(place: Place): object {
+/** A `Place` at `path`, lines and columns from 1, as the protocol's `Location`, from 0. */
+function locationOf(path: string, place: Place): object {
     return {
-        uri: Bun.pathToFileURL(place.path).href,
+        uri: Bun.pathToFileURL(path).href,
         range: {
             start: {
                 line: place.start.line - 1,

package/src/compiler/sharedModuleWrites.ts

@@ -11,7 +11,7 @@ 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
+// 34.18 — 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
@@ -74,7 +74,7 @@ export async function sharedModuleWrites(
             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.`,
+                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.18.`,
             })
         }
     }

package/src/compiler/sourceMapOf.ts

@@ -0,0 +1,193 @@
+// 38.97 — WHERE A COMPILED MODULE'S LINES CAME FROM IN ITS `.abide`. The emitters build a module
+// as text around what `Lowering` hands them, so a chunk is placed by FINDING it in what they wrote
+// rather than by threading offsets through every template string that assembles one:
+//
+// - a script block is many lines and lands whole, its imports each left as a `;` on as many lines
+//   (`splitImports`), so it is anchored by its longest line found once in the module and then read
+//   line for line;
+// - a template expression is one line and may land more than once — a client module writes a slot
+//   in its markup and again in the effect that updates it — and every landing is the same source.
+//
+// What no chunk covers is the framework's own scaffolding, and maps to nothing.
+
+import { encodeMappings, type Segment } from '#server/sourceMappings.ts'
+import type { LoweredChunk } from './Lowering.ts'
+import type { Origin } from './projectShadow.ts'
+import { mapBack } from './ShadowMap.ts'
+
+/** The module's `mappings`, into the `.abide` whose text is `source`. */
+export function sourceMapOf(
+    output: string,
+    chunks: readonly LoweredChunk[],
+    projected: readonly Origin[],
+    source: string,
+): string {
+    const sourceStarts = lineStarts(source)
+    const outputLines = output.split('\n')
+    const outputStarts = lineStarts(output)
+    const lines: Segment[][] = []
+    for (let index = 0; index < outputLines.length; index += 1) lines.push([])
+    // Where a projection offset is in the `.abide`, as a line and a column.
+    const place = (line: number, column: number, offset: number): void => {
+        const at = mapBack(projected, offset)
+        const sourceLine = lineAt(sourceStarts, at)
+        ;(lines[line] as Segment[]).push([
+            column,
+            0,
+            sourceLine,
+            at - (sourceStarts[sourceLine] as number),
+        ])
+    }
+    const claimed = new Set<number>()
+
+    const multiline: LoweredChunk[] = []
+    const single: LoweredChunk[] = []
+    for (const chunk of chunks)
+        (chunk.text.includes('\n') ? multiline : single).push(chunk)
+    multiline.sort((one, two) => two.text.length - one.text.length)
+
+    for (const chunk of multiline) {
+        const chunkLines = chunk.text.split('\n')
+        const first = anchor(chunkLines, outputLines, outputStarts, output)
+        if (first === undefined) continue
+        const chunkStarts = lineStarts(chunk.text)
+        for (let index = 0; index < chunkLines.length; index += 1) {
+            const line = first + index
+            const written = outputLines[line]
+            const lowered = chunkLines[index] as string
+            if (written === undefined || claimed.has(line)) continue
+            if (written.trim() !== lowered.trim() || lowered.trim() === '')
+                continue
+            claimed.add(line)
+            const start = chunkStarts[index] as number
+            const end = start + lowered.length
+            // Lines the emitter re-indented keep their text, and move by the margin it added.
+            const shift = written.length - lowered.length
+            for (const origin of chunk.origins) {
+                const runEnd = origin.at + Math.max(origin.length, 1)
+                if (origin.at >= end || runEnd <= start) continue
+                const from = Math.max(origin.at, start)
+                place(
+                    line,
+                    from - start + shift,
+                    origin.source + (from - origin.at),
+                )
+            }
+        }
+    }
+
+    // LONGEST FIRST, each landing claimed: `count() + 1` is found again inside the handler
+    // `() => { count.set(count() + 1) }` was lowered from, and is that handler's there.
+    single.sort((one, two) => two.text.trim().length - one.text.trim().length)
+    const taken: [number, number][] = []
+    const seen = new Set<string>()
+    for (const chunk of single) {
+        const text = chunk.text.trim()
+        if (text.length < 2) continue
+        // An expression an emitter asked for twice is one chunk.
+        const key = `${chunk.origins[0]?.source}:${text}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        const lead = chunk.text.indexOf(text)
+        for (
+            let found = output.indexOf(text);
+            found !== -1;
+            found = output.indexOf(text, found + text.length)
+        ) {
+            const end = found + text.length
+            if (!standsAlone(output, found, end)) continue
+            const line = lineAt(outputStarts, found)
+            if (claimed.has(line)) continue
+            if (taken.some(([from, to]) => found < to && end > from)) continue
+            taken.push([found, end])
+            const column = found - (outputStarts[line] as number)
+            for (const origin of chunk.origins) {
+                const at = origin.at - lead
+                if (at < 0 || at > text.length) continue
+                place(line, column + at, origin.source)
+            }
+        }
+    }
+
+    // Two runs placed at one column — a pin and the copy after it — keep the later, which is the
+    // author's own text.
+    for (const segments of lines) {
+        segments.sort((one, two) => one[0] - two[0])
+        for (let at = segments.length - 1; at > 0; at -= 1)
+            if (
+                (segments[at - 1] as Segment)[0] ===
+                (segments[at] as Segment)[0]
+            )
+                segments.splice(at - 1, 1)
+    }
+    return encodeMappings(lines)
+}
+
+/**
+ * The module line `chunkLines` starts on: its longest line found exactly once, standing where the
+ * rest of the chunk agrees — or `undefined` where no line places it.
+ */
+function anchor(
+    chunkLines: readonly string[],
+    outputLines: readonly string[],
+    outputStarts: readonly number[],
+    output: string,
+): number | undefined {
+    const order: number[] = []
+    for (let index = 0; index < chunkLines.length; index += 1) order.push(index)
+    order.sort(
+        (one, two) =>
+            (chunkLines[two] as string).trim().length -
+            (chunkLines[one] as string).trim().length,
+    )
+    for (const index of order) {
+        const text = (chunkLines[index] as string).trim()
+        if (text.length < 8) return undefined
+        const found = output.indexOf(text)
+        if (found === -1 || output.indexOf(text, found + 1) !== -1) continue
+        const first = lineAt(outputStarts, found) - index
+        if (first < 0) continue
+        let agreeing = 0
+        let written = 0
+        for (let at = 0; at < chunkLines.length; at += 1) {
+            const lowered = (chunkLines[at] as string).trim()
+            if (lowered === '') continue
+            written += 1
+            if (outputLines[first + at]?.trim() === lowered) agreeing += 1
+        }
+        if (agreeing * 2 >= written) return first
+    }
+    return undefined
+}
+
+const NAME = /[\w$.]/
+
+// Not the middle of a longer name, or a member of one: `count()` inside `__count()` is not it.
+function standsAlone(output: string, start: number, end: number): boolean {
+    return (
+        !NAME.test(output[start - 1] ?? ' ') &&
+        !/[\w$]/.test(output[end] ?? ' ')
+    )
+}
+
+function lineStarts(text: string): number[] {
+    const starts = [0]
+    for (
+        let at = text.indexOf('\n');
+        at !== -1;
+        at = text.indexOf('\n', at + 1)
+    )
+        starts.push(at + 1)
+    return starts
+}
+
+function lineAt(starts: readonly number[], offset: number): number {
+    let low = 0
+    let high = starts.length - 1
+    while (low < high) {
+        const middle = (low + high + 1) >>> 1
+        if ((starts[middle] as number) <= offset) low = middle
+        else high = middle - 1
+    }
+    return low
+}