@abide/abide 0.102.0 → 0.103.0

package/src/compiler/projectShadow.ts

@@ -24,7 +24,7 @@ import type {
     Setup,
     TemplateNode,
 } from './TemplateNode.ts'
-import { tokenize } from './tokenize.ts'
+import { nesting, tokenize } from './tokenize.ts'
 
 export type Span = { start: number; end: number }
 
@@ -45,7 +45,7 @@ export type Span = { start: number; end: number }
 export type Projection = {
     text: string
     modules: Span
-    /** 34.20 — the `<script server>` bodies, module scope like `modules` and the server's alone. */
+    /** 34.19 — the `<script server>` bodies, module scope like `modules` and the server's alone. */
     servers: Span
     scripts: Span
     /** Every template position, ascending, each with its kind — what the checker's tree is asked. */
@@ -95,7 +95,7 @@ export function projectShadow(file: AbideFile): Projection {
 
 type ImportStatement = ReturnType<typeof importStatements>[number]
 
-/** 34.26 — a binding as two blocks importing the same thing agree on it. */
+/** 34.22 — a binding as two blocks importing the same thing agree on it. */
 function bindingKey(
     statement: ImportStatement,
     binding: ImportBinding,
@@ -104,7 +104,7 @@ function bindingKey(
 }
 
 /**
- * 34.26 — what is left of an import once the bindings `drops` answers for are taken out:
+ * 34.22 — what is left of an import once the bindings `drops` answers for are taken out:
  * `undefined` where none is, `''` where every one is, and the statement over the rest otherwise,
  * spelled from its tokens.
  */
@@ -163,10 +163,10 @@ function project(file: AbideFile): Projection {
         }
         return { start, end: text.length }
     }
-    // 34.25 — a block copied as written, save that a `.abide` imported as text names the module
+    // 34.21 — a block copied as written, save that a `.abide` imported as text names the module
     // holding its text, and loses the attribute bun would otherwise read that module as text by.
     //
-    // 34.26 — and a binding a `<script server>` and the file's `<script module>` or `<script>` both
+    // 34.22 — and a binding a `<script server>` and the file's `<script module>` or `<script>` both
     // import is written once: the server's module holds the other blocks' imports too, and written
     // twice it was a duplicate binding. `drops` says which copy goes. A blank line per line it
     // spanned keeps the block line for line with the file.
@@ -215,7 +215,7 @@ function project(file: AbideFile): Projection {
             origin === undefined ? undefined : origin + from,
         )
     }
-    // 34.26 — per binding the blocks both sides run import, whether one of them imports a value;
+    // 34.22 — per binding the blocks both sides run import, whether one of them imports a value;
     // and the bindings the server block imports as values.
     const shared = new Map<string, boolean>()
     for (const body of [...file.modules, ...file.scripts])
@@ -568,11 +568,19 @@ function project(file: AbideFile): Projection {
     // 34.3 — BOTH BLOCKS. A `<script>` is a function body on both sides, where an `await` at its top
     // does not parse; a `<script module>` is module scope, where it would, and holds the import of
     // every file that reaches it until it settles — the render waiting on it in all but name.
-    refuseTopLevelAwait(file.modules.join('\n'), '<script module>')
-    refuseTopLevelAwait(file.servers.join('\n'), '<script server>')
+    const modulesText = file.modules.join('\n')
+    const serversText = file.servers.join('\n')
+    refuseTopLevelAwait(modulesText, '<script module>')
+    refuseTopLevelAwait(serversText, '<script server>')
     refuseTopLevelAwait(scriptsText, '<script>')
-    refuseInstanceExport(scriptsText)
-    refuseServerDefault(file.servers.join('\n'))
+    // A kind at a time: a token at the end of one kind's text would decide how the next one's first
+    // reads.
+    refuseExport(modulesText)
+    refuseExport(serversText)
+    refuseExport(scriptsText)
+    // 16.70 — what the server block binds, re-exported under a name no author writes, so the
+    // checker reads each one's declaring call as it reads a handler file's default.
+    text += privateExports(serversText)
     return {
         text,
         modules,
@@ -699,6 +707,7 @@ declare function ${ROWS_OF}<T>(subject: Iterable<T> | AsyncIterable<T> | null |
  */
 function refuseTopLevelAwait(source: string, block: string): void {
     if (!source.includes(AWAIT)) return
+    // Brackets alone, not `nesting`: a template's substitution is still the top level here.
     let depth = 0
     for (const token of tokenize(source)) {
         const text = token.text
@@ -712,35 +721,72 @@ function refuseTopLevelAwait(source: string, block: string): void {
 }
 
 /**
- * Throws where a `<script>` exports.
+ * Throws where a script block exports.
  *
- * 34.18 — AN EXPORT IS THE MODULE'S, and a `<script>` runs once per instance: there is no one
- * instance an importer could be reading from. Refused rather than emitted, as 34.3's `await` is —
- * the block is a function body on both sides, and the bundler's own error names neither the page
- * nor the fix.
+ * 34.17 — A `.abide`'S ONE EXPORT IS ITS COMPONENT. A handler another file calls is a handler file
+ * (16.2), a value two files share is a module under a lib directory, and what the framework reads
+ * off a file is a hook it calls (37.1). Refused rather than emitted, as 34.3's `await` is: the
+ * bundler's own error names neither the file nor the fix.
  */
-function refuseInstanceExport(source: string): void {
+function refuseExport(source: string): void {
     if (!source.includes(EXPORT)) return
     let depth = 0
     let previous = ''
     for (const token of tokenize(source)) {
         const text = token.text
-        if (text === '{' || text === '(' || text === '[') depth += 1
-        else if (text === '}' || text === ')' || text === ']') depth -= 1
+        const moved = nesting(token.kind)
+        if (moved !== 0) depth += moved
         else if (depth === 0 && text === EXPORT && previous !== '.')
             throw new Error(
-                "abide: a <script> cannot export — it runs once per instance, and an export is the module's. Move the declaration to <script module>. RULEBOOK 34.18.",
+                'abide: a .abide cannot export — its component is its one export. A handler another file calls is a handler file (a .ts beside the page, `export default GET(…)`); a value files share is a module under a lib directory. RULEBOOK 34.17.',
             )
         previous = text
     }
 }
 
+/** The prefix a server block's bindings are re-exported under, for the build alone (16.70). */
+export const PRIVATE_EXPORT = '__handler_'
+
+/**
+ * 16.70 — the `export { … }` re-exporting each name the server blocks bind under `PRIVATE_EXPORT`,
+ * or `''` where they bind none. One spelling for the checker's view and the emitted module, which
+ * the build's handler table reads a private handler out of by the same name.
+ */
+export function privateExports(servers: string): string {
+    const listed: string[] = []
+    for (const name of serverBindings(servers))
+        listed.push(`${name} as ${PRIVATE_EXPORT}${name}`)
+    return listed.length === 0 ? '' : `export { ${listed.join(', ')} }\n`
+}
+
 /**
- * 34.22 — a `<script server>` exporting `default`, refused: the module's default is its component,
- * and a handler is addressed by its name (16.2).
+ * The names a `<script server>` binds with `const`, `let` or `var` at its top level, a
+ * destructuring's aside: a handler is a call bound to one name.
  */
+function serverBindings(source: string): string[] {
+    const names: string[] = []
+    if (source === '') return names
+    let depth = 0
+    let declaring = false
+    for (const token of tokenize(source)) {
+        const text = token.text
+        const moved = nesting(token.kind)
+        if (moved !== 0) {
+            depth += moved
+            declaring = false
+        } else if (depth !== 0) continue
+        else if (text === 'const' || text === 'let' || text === 'var')
+            declaring = true
+        else if (declaring && token.kind === SyntaxKind.Identifier) {
+            names.push(text)
+            declaring = false
+        } else declaring = false
+    }
+    return names
+}
+
 /**
- * 34.26 — throws where the binding both blocks import is a `.abide`'s default or namespace: the
+ * 34.22 — throws where the binding both blocks import is a `.abide`'s default or namespace: the
  * server block's is the function binding its props (34.16) and the other block's is the module it
  * compiles to (32.17), and one name in one module scope cannot hold both.
  */
@@ -754,29 +800,8 @@ function refuseTwoFaces(
         (binding.imported === 'default' || binding.imported === '*')
     )
         throw new Error(
-            `abide: <script server> imports ${binding.local} from '${statement.specifier}' as another script block of its file does — a server block's .abide is the function binding its props (34.16), the other block's is its module (32.17), and one name cannot be both. Import it under another name in the <script server>. RULEBOOK 34.26.`,
-        )
-}
-
-function refuseServerDefault(source: string): void {
-    if (!source.includes(EXPORT)) return
-    let depth = 0
-    let previous = ''
-    for (const token of tokenize(source)) {
-        const text = token.text
-        if (text === '{' || text === '(' || text === '[') depth += 1
-        else if (text === '}' || text === ')' || text === ']') depth -= 1
-        // `export { x as default }` names it too.
-        else if (
-            text === 'default' &&
-            ((depth === 0 && previous === EXPORT) ||
-                (depth === 1 && previous === 'as'))
+            `abide: <script server> imports ${binding.local} from '${statement.specifier}' as another script block of its file does — a server block's .abide is the function binding its props (34.16), the other block's is its module (32.17), and one name cannot be both. Import it under another name in the <script server>. RULEBOOK 34.22.`,
         )
-            throw new Error(
-                "abide: a <script server> cannot export `default` — the module's default is its component. Export the handler under a name; the name is its address's last segment. RULEBOOK 34.22.",
-            )
-        previous = text
-    }
 }
 
 /**

package/src/compiler/readsIn.ts

@@ -282,7 +282,7 @@ export async function readsIn(
     await proveSlots(checker, expressions, reads, statics)
     reads.sort(byPosition)
     const warnings = await warningsFor(checker, located, spans.positions)
-    // 34.19.
+    // 34.18.
     for (const warning of await sharedModuleWrites(
         checker,
         shadowPath,
@@ -694,7 +694,7 @@ const ROUTE_MEMBERS = new Set(['url', 'params', 'name', 'navigating'])
  * a name, and this read is spelled as a member.
  *
  * 23.9 — AND `route.params` IN A PAGE OR A LAYOUT IS WHAT THAT FILE'S OWN ROUTE PROMISES. The file
- * is the route: `media/[id]/page.abide` only ever renders where `id` matched, so its
+ * is the route: `media/[id].abide` only ever renders where `id` matched, so its
  * `route.params` has an `id`, and a layout's has its own segments and whatever a page below adds.
  * Only the checker reads that — the running module reads the one `route` every page shares.
  */

package/src/compiler/scaffold.ts

@@ -1,6 +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 a route, the shell and the hooks — 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.
 
@@ -8,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
@@ -22,23 +22,35 @@ 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',
-                // 34.24 — `prepare` runs on `bun install`, so a `.ts` importing a `.abide` is typed
-                // before any other abide command has run; and never fails it, as it would where
-                // `package.json` is installed before `src` is there to sync (38.26).
                 scripts: {
-                    prepare: 'abide sync || true',
                     // 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',
                 },
                 // 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:
@@ -47,9 +59,7 @@ function filesFor(name: string): Record<string, string> {
                 // 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: {
-                    '#src/*': ['./src/*', './src/*.ts'],
-                },
+                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.
@@ -60,20 +70,13 @@ 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.24 — `rootDirs` and the `#src/*` path reach what abide writes to `.abide/types`,
-            // where a `.ts` importing a `.abide` finds the names it exports.
+            // 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'],
-                    rootDirs: ['.', '.abide/types'],
-                    paths: {
-                        '#src/*': [
-                            './src/*',
-                            './src/*.ts',
-                            './.abide/types/src/*',
-                        ],
-                    },
+                    paths: SOURCE_ALIAS,
                 },
                 include: ['src'],
             },

package/src/compiler/serveLanguage.ts

@@ -4,10 +4,7 @@ import { realOrAsGiven } from '#server/realOrAsGiven.ts'
 import { checkSource } from './checkApp.ts'
 import { type AppChecker, openChecker } from './compileApp.ts'
 import { nearest } from './nearest.ts'
-import { parseAbide } from './parseAbide.ts'
-import { syncTypes } from './syncTypes.ts'
 import type { Diagnosis, Inspection, Place } from './TypeSession.ts'
-import { writeTypes } from './writeTypes.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
@@ -197,27 +194,6 @@ export async function serveLanguage(
         // 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)
-        await typesFor(app, path, document.text)
-    }
-
-    // 34.24 — THE TYPES A PLAIN `.ts` READS AN OPEN FILE BY, as the editor holds it: the whole app's
-    // the first time an app is seen, and the one file as it is edited after that.
-    const synced = new Set<string>()
-    const typesFor = async (
-        app: string,
-        path: string,
-        text: string,
-    ): Promise<void> => {
-        try {
-            if (synced.has(app))
-                await writeTypes(app, [{ path, file: parseAbide(text) }], false)
-            else {
-                synced.add(app)
-                await syncTypes(app, new Map([[path, text]]))
-            }
-        } catch {
-            // A file that does not parse keeps the types it last had; its check already says why.
-        }
     }
 
     const check = (uri: string): void => {

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/splitImports.ts

@@ -263,7 +263,7 @@ export function abideImports(
     for (const span of importSpans(script))
         if (
             span.specifier.endsWith('.abide') &&
-            // 34.25 — a `.abide` imported as text is its text, and no component edge.
+            // 34.21 — a `.abide` imported as text is its text, and no component edge.
             (span.dynamic ||
                 !IMPORT_ATTRIBUTES.text.test(
                     script.slice(span.literalEnd, span.end),
@@ -386,7 +386,7 @@ export function importStatements(script: string): {
     return found
 }
 
-// The attribute a static import is read by: as text (34.25), or as a mount of routes (23.19).
+// The attribute a static import is read by: as text (34.21), or as a mount of routes (23.19).
 export const IMPORT_ATTRIBUTES = {
     text: /\btype\s*:\s*['"]text['"]/,
     routes: /\btype\s*:\s*['"]routes['"]/,
@@ -396,7 +396,7 @@ export const IMPORT_ATTRIBUTES = {
  * Every static import a script makes `with { type }`: the specifier, where the statement and its
  * literal begin, and where the attributes end.
  *
- * 34.25 — a text import's literal-to-end span is what the projection writes over with the specifier
+ * 34.21 — a text import's literal-to-end span is what the projection writes over with the specifier
  * the checker types a `string` (`SOURCE_SUFFIX`), and the emitters ask for as text
  * (`facedSpecifier`). 23.19 — a routes import's whole statement is what the projection blanks: a
  * mount is read by the build off the file, and neither bun nor the checker has a module to give it.
@@ -466,7 +466,7 @@ export function importedNames(
  * own path, so bun resolves a relative, a `#` or a bare specifier from the file that wrote it.
  *
  * 32.17 — a component block's `.abide` import is of the module that file compiles to; a server
- * block's stays bare, for the face a module abide did not compile gets (34.16). 34.25 — a file the
+ * block's stays bare, for the face a module abide did not compile gets (34.16). 34.21 — a file the
  * projection marked as text is asked for as its text.
  */
 function facedSpecifier(specifier: string, lane: Lane): string | undefined {

package/src/compiler/writeDefaultProject.ts

@@ -10,6 +10,8 @@
 
 import { mkdtemp, rm } from 'node:fs/promises' // bun exposes no temporary-directory creation or recursive removal of its own
 import { tmpdir } from 'node:os' // bun exposes no temporary-directory path of its own
+import { dirname, resolve } from 'node:path' // bun exposes no path helpers of its own
+import { nearest } from './nearest.ts'
 
 /** What every abide app in the docs and the scaffold is written against. */
 export const COMPILER_OPTIONS = {
@@ -31,7 +33,7 @@ export async function writeDefaultProject(
     await Bun.write(
         tsconfig,
         JSON.stringify({
-            compilerOptions: COMPILER_OPTIONS,
+            compilerOptions: { ...COMPILER_OPTIONS, paths: await aliasPaths(root) },
             include: [`${root}/**/*`],
         }),
     )
@@ -40,3 +42,28 @@ export async function writeDefaultProject(
         remove: () => rm(directory, { recursive: true, force: true }),
     }
 }
+
+/**
+ * The app's `imports` aliases as `paths`, each target absolute.
+ *
+ * 34.21 — the checker resolves a text import's declaration beside the file a path names, and takes
+ * an `imports` target as the exact file, so `#src/x.abide` imported as text is found through these.
+ */
+async function aliasPaths(root: string): Promise<Record<string, string[]>> {
+    const paths: Record<string, string[]> = {}
+    const manifest = nearest(root, 'package.json')
+    if (manifest === undefined) return paths
+    const imports = (
+        (await Bun.file(manifest).json()) as {
+            imports?: Record<string, unknown>
+        }
+    ).imports
+    const base = dirname(manifest)
+    for (const [key, targets] of Object.entries(imports ?? {})) {
+        const resolved: string[] = []
+        for (const target of [targets].flat())
+            if (typeof target === 'string') resolved.push(resolve(base, target))
+        if (resolved.length > 0) paths[key] = resolved
+    }
+    return paths
+}

package/src/server/MODULE_QUERIES.ts

@@ -1,5 +1,5 @@
-// WHAT AN IMPORT OF A `.abide` ASKS FOR, spelled on the specifier: bun hands a plugin no import
-// attributes, so the compiler writes the face it wants where the plugin can read it
+// WHAT AN IMPORT OF A `.abide` OR A HANDLER FILE ASKS FOR, spelled on the specifier: bun hands a
+// plugin no import attributes, so the compiler writes the face it wants where the plugin can read it
 // (`abideModules`). A `.abide` named with none is the face a module abide did not compile gets.
 
 /** The module the file compiles to, as a compiled module imports it. 32.17. */
@@ -8,7 +8,7 @@ export const COMPONENT_QUERY = '?component'
 /** The file's scoped stylesheet, which its browser module imports. 34.4. */
 export const STYLE_QUERY = '?style'
 
-/** The file's text. 34.25. */
+/** The file's text. 34.21. */
 export const TEXT_QUERY = '?text'
 
 /**
@@ -16,3 +16,12 @@ export const TEXT_QUERY = '?text'
  * under a DOM in `bun test`. Its own `.abide` imports are browser modules too.
  */
 export const CLIENT_QUERY = '?client'
+
+/**
+ * What a handler file is imported as: its own path with this after it, so the plugin can serve it
+ * between the calls that file its hooks (37.1) and a browser its wrapper (16.74). A stack frame names
+ * the file without it (38.97).
+ */
+export const HANDLER_SUFFIX = '.abide-handler'
+/** A path that is a handler file's face. */
+export const HANDLER_FACE = new RegExp(`${RegExp.escape(HANDLER_SUFFIX)}$`)