@abide/abide 0.104.0 → 0.105.0

package/src/compiler/hookCalls.ts

@@ -0,0 +1,152 @@
+import { SHARED_SPECIFIER } from '#shared/SPECIFIERS.ts'
+import { importStatements } from './splitImports.ts'
+import { type Token, tokenize } from './tokenize.ts'
+
+// WHICH OF ABIDE'S HOOKS A MODULE CALLS, read off its tokens and its imports — not run. What `abide
+// routes` lists (38.108), what the build refuses where a call is never read (37.13, 38.107), and
+// which files the checker types `Config` off (27.13) all ask this one question.
+
+/** Every hook abide exports, by name. */
+export const HOOK_NAMES: ReadonlySet<string> = new Set([
+    'middleware',
+    'onStart',
+    'onStop',
+    'onError',
+    'onConfig',
+    'onHealth',
+    'onPrincipal',
+    'onLauncher',
+    'onMenu',
+])
+
+/** One call of one of abide's hooks. */
+export type HookCall = {
+    hook: string
+    /** Where the callee starts — the hook's name, or the namespace it is a member of. */
+    at: number
+    /** Where the callee ends: the `(` follows. */
+    end: number
+    /** Whether the call stands as a statement at the module's top level. */
+    topLevel: boolean
+}
+
+/**
+ * What `scripts`' imports from abide bind: each local name, a value's, to the name it imports — `*`
+ * for a namespace. Every script of one file, since a `<script module>`'s import reaches the blocks
+ * below it.
+ */
+export function abideBindings(
+    scripts: readonly string[],
+): ReadonlyMap<string, string> {
+    const bound = new Map<string, string>()
+    for (const script of scripts) {
+        if (!script.includes(SHARED_SPECIFIER)) continue
+        for (const statement of importStatements(script))
+            if (isAbideSpecifier(statement.specifier))
+                for (const binding of statement.bindings)
+                    if (!binding.typeOnly)
+                        bound.set(binding.local, binding.imported)
+    }
+    return bound
+}
+
+/**
+ * Each of abide's hooks `scripts` call — every script of one file — in the order written. Block by
+ * block: one block's last token would decide how the next one's first reads.
+ */
+export function hooksIn(scripts: readonly string[]): string[] {
+    const bindings = abideBindings(scripts)
+    const hooks: string[] = []
+    for (const script of scripts)
+        for (const call of hookCalls(script, bindings)) hooks.push(call.hook)
+    return hooks
+}
+
+/**
+ * Each of abide's hooks `source` calls, in the order written.
+ *
+ * A HOOK IS WHAT ABIDE HANDED THE MODULE: a name `bindings` imports from abide, under whatever local
+ * name, or a member of a namespace it does — `server.onStart(…)` is the hook, and `emitter.onError(…)`
+ * in a module importing abide for `reactive` is not.
+ */
+export function hookCalls(
+    source: string,
+    bindings: ReadonlyMap<string, string> = abideBindings([source]),
+): HookCall[] {
+    const calls: HookCall[] = []
+    // Untokenized where no name a hook is bound to — itself, or the namespace holding it — is in it.
+    let mentioned = false
+    for (const [local, imported] of bindings)
+        if (
+            (imported === '*' || HOOK_NAMES.has(imported)) &&
+            source.includes(local)
+        ) {
+            mentioned = true
+            break
+        }
+    if (!mentioned) return calls
+    const tokens = tokenize(source)
+    let depth = 0
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index] as Token
+        const text = token.text
+        if (text === '(' || text === '[' || text === '{') depth += 1
+        else if (text === ')' || text === ']' || text === '}') depth -= 1
+        if (tokens[index + 1]?.text !== '(') continue
+        const previous = tokens[index - 1]
+        let hook: string | undefined
+        let first = index
+        if (previous?.text === '.') {
+            const owner = tokens[index - 2]
+            if (
+                HOOK_NAMES.has(text) &&
+                owner !== undefined &&
+                bindings.get(owner.text) === '*' &&
+                tokens[index - 3]?.text !== '.'
+            ) {
+                hook = text
+                first = index - 2
+            }
+        } else if (previous?.text !== 'function') {
+            const imported = bindings.get(text)
+            if (imported !== undefined && HOOK_NAMES.has(imported))
+                hook = imported
+        }
+        if (hook === undefined) continue
+        const callee = tokens[first] as Token
+        calls.push({
+            hook,
+            at: callee.start,
+            end: token.end,
+            topLevel: depth === 0 && opensStatement(source, tokens, first),
+        })
+    }
+    return calls
+}
+
+// Whether the token at `index` begins a statement: the first, after a `;` or a `}`, or on a line of
+// its own after one that ended an expression — where a formatted module writes one.
+function opensStatement(
+    source: string,
+    tokens: readonly Token[],
+    index: number,
+): boolean {
+    const previous = tokens[index - 1]
+    if (previous === undefined) return true
+    if (previous.text === ';' || previous.text === '}') return true
+    return (
+        source
+            .slice(previous.end, (tokens[index] as Token).start)
+            .includes('\n') && ENDS_EXPRESSION.test(previous.text)
+    )
+}
+
+const ENDS_EXPRESSION = /^(?:[\w$]+|[)\]]|['"`].*)$/s
+
+/** `@abide/abide` or one of its subpaths. */
+export function isAbideSpecifier(specifier: string): boolean {
+    return (
+        specifier === SHARED_SPECIFIER ||
+        specifier.startsWith(`${SHARED_SPECIFIER}/`)
+    )
+}

package/src/compiler/mountsOf.ts

@@ -6,15 +6,16 @@
 //
 // A FILE KEEPS ITS PATH AND GAINS A POSITION. It is compiled, served and keyed by where it lies, as
 // any dependency's is (34.23); its POSITION — the path it would have below the root — is what
-// `placeOf`, `fileKind` and `routeOf` read, so a mounted page is a page by the same test as the app's.
+// `placement` reads, so a mounted page is a page by the same test as the app's.
 
-import { readFileSync, realpathSync, statSync } from 'node:fs' // bun exposes no sync read, stat or realpath of its own
+import { realpathSync, statSync } from 'node:fs' // bun exposes no sync stat or realpath of its own
 import { dirname, relative, resolve } from 'node:path' // bun exposes no path helpers of its own
 import { appFiles } from '#server/appTree.ts'
-import { placeOf } from '#shared/routePattern.ts'
+import { placeOf } from '#server/placement.ts'
 import { nearest } from './nearest.ts'
-import { type AbideFile, parseAbide, scriptBodies } from './parseAbide.ts'
-import { attributedImports, IMPORT_ATTRIBUTES } from './splitImports.ts'
+import { type AbideFile, scriptBodies } from './parseAbide.ts'
+import { Refusals } from './Refusals.ts'
+import { attributedImports } from './splitImports.ts'
 
 /** A `.abide` on disk, and the position it takes in the app. */
 type Placed = { path: string; position: string }
@@ -33,8 +34,8 @@ type DirectoryMount = {
 }
 
 /**
- * Every directory the file at `path` mounts, its position in the app being `position` — or the
- * refusal naming what one of them cannot be.
+ * Every directory the file at `path` mounts, its position in the app being `position` — or none,
+ * where one of them cannot be mounted and `refusals` is told what.
  *
  * `root` is the app's, real: a directory under it is the app's own already, with a position of its
  * own, and mounting it would give its files a second (23.20).
@@ -44,7 +45,8 @@ export function mountsOf(
     path: string,
     position: string,
     file: AbideFile,
-): DirectoryMount[] | string {
+    refusals: Refusals,
+): DirectoryMount[] {
     const mounts: DirectoryMount[] = []
     const at = position.includes('/')
         ? `${position.slice(0, position.lastIndexOf('/'))}/`
@@ -52,12 +54,27 @@ export function mountsOf(
     for (const script of scriptBodies(file))
         for (const { specifier } of attributedImports(script, 'routes')) {
             const directory = mountedDirectory(specifier, dirname(path))
-            if (directory === undefined)
-                return `abide: ${position} mounts ${specifier}, and no directory answers to it. RULEBOOK 23.19.`
-            if (ownDirectory(root, directory))
-                return `abide: ${position} mounts ${specifier}, which is the app's own directory already. RULEBOOK 23.20.`
+            // A file that mounts what it may not mounts nothing.
+            if (directory === undefined) {
+                refusals.at(
+                    path,
+                    new Error(
+                        `abide: ${position} mounts ${specifier}, and no directory answers to it. RULEBOOK 23.19.`,
+                    ),
+                )
+                return []
+            }
+            if (ownDirectory(root, directory)) {
+                refusals.at(
+                    path,
+                    new Error(
+                        `abide: ${position} mounts ${specifier}, which is the app's own directory already. RULEBOOK 23.20.`,
+                    ),
+                )
+                return []
+            }
             // The package's tree is the package's to refuse; a mount places what it finds.
-            const found = appFiles(directory, () => {})
+            const found = appFiles(directory, new Refusals(directory, true))
             const placed = (below: string): Placed => ({
                 path: `${directory}/${below}`,
                 position: `${at}${below}`,
@@ -73,51 +90,11 @@ export function mountsOf(
     return mounts
 }
 
-/**
- * Every file mounted under the app at `root` whose own `.abide` are `relatives`, and every one those
- * mount in turn, at its position — read for nothing but its mounts, and refusing nothing: the
- * build is what refuses a mount (`withDependencies`).
- *
- * THE CHECKER'S `Routes` (30.26) asks this on every check, so a file is parsed only where its text
- * names a mount at all.
- */
-export function mountedUnder(
-    root: string,
-    relatives: readonly string[],
-): Placed[] {
-    const queue: Placed[] = []
-    for (const relative of relatives)
-        queue.push({ path: `${root}/${relative}`, position: relative })
-    const found: Placed[] = []
-    const seen = new Set<string>()
-    for (let at = 0; at < queue.length; at += 1) {
-        const { path, position } = queue[at] as Placed
-        const text = readFileSync(path, 'utf8')
-        if (!IMPORT_ATTRIBUTES.routes.test(text)) continue
-        let file: AbideFile
-        try {
-            file = parseAbide(text)
-        } catch {
-            continue
-        }
-        const mounts = mountsOf(root, path, position, file)
-        if (typeof mounts === 'string') continue
-        for (const mount of mounts)
-            for (const placed of mount.files) {
-                if (seen.has(placed.path)) continue
-                seen.add(placed.path)
-                found.push(placed)
-                queue.push(placed)
-            }
-    }
-    return found
-}
-
 // Under the root and not a dependency's there: one of the app's own, with positions of its own.
 function ownDirectory(root: string, directory: string): boolean {
     if (directory === root) return true
     const below = relative(root, directory)
-    return !below.startsWith('..') && placeOf(`${below}/-`) !== 'dependency'
+    return !below.startsWith('..') && placeOf(`${below}/`) !== 'dependency'
 }
 
 /**

package/src/compiler/readSources.ts

@@ -1,11 +1,12 @@
 import { type CheckerAnswer, UNCHECKED } from './CheckerAnswer.ts'
-import { diagnosisAt } from './lineOf.ts'
 import { type AbideFile, parseAbide } from './parseAbide.ts'
+import type { Refusals } from './Refusals.ts'
 import type { Diagnosis, TypeSession } from './TypeSession.ts'
 
 // EVERY COMPILE OF A `.abide` STARTS THE SAME WAY: the text parsed, then every file read by the
 // checker in one snapshot. `abide build`, `abide check` and an editor's one file differ only in
-// what a refusal does — the build stops at it, and a check reports it and goes on with the rest.
+// what a refusal does (`Refusals`) — the build stops at it, and a check reports it and goes on with
+// the rest.
 
 /** One `.abide`, parsed. `quiet` is read for its props alone and reported on by nobody (33.4). */
 export type ParsedSource = {
@@ -13,27 +14,21 @@ export type ParsedSource = {
     text: string
     file: AbideFile
     quiet: boolean
-    /** 23.19 — where a mounted package's file stands in the app; `undefined` for one at its own path. */
-    position: string | undefined
 }
 
 /** One `.abide` as the emitters and the checked lowering take it: parsed, and answered. */
-export type ReadSource = ParsedSource & { answer: CheckerAnswer }
+export type ReadSource<Source extends ParsedSource = ParsedSource> = Source & {
+    answer: CheckerAnswer
+}
 
-/**
- * Each source parsed.
- *
- * WITH `refused`, A SOURCE THE PARSER REFUSES IS A FINDING, at its first line, and the rest are
- * parsed around it — a quiet one's is nobody's. Without it the refusal is thrown, as a build stops.
- */
+/** Each source parsed, around a source the parser refuses — a quiet one's refusal is nobody's. */
 export function parseSources(
     sources: readonly {
         path: string
         text: string
         quiet?: boolean
-        position?: string
     }[],
-    refused?: Diagnosis[],
+    refusals: Refusals,
 ): ParsedSource[] {
     const parsed: ParsedSource[] = []
     for (const source of sources) {
@@ -42,8 +37,7 @@ export function parseSources(
         try {
             file = parseAbide(source.text)
         } catch (thrown) {
-            if (refused === undefined) throw thrown
-            if (!quiet) refused.push(refusal(source.path, thrown))
+            if (!quiet) refusals.at(source.path, thrown)
             continue
         }
         parsed.push({
@@ -51,7 +45,6 @@ export function parseSources(
             text: source.text,
             file,
             quiet,
-            position: source.position,
         })
     }
     return parsed
@@ -60,22 +53,25 @@ export function parseSources(
 /**
  * Each parsed source with the checker's answer, and the compiler's warnings — in one snapshot.
  *
- * ONE SNAPSHOT FOR THE LOT, which is the whole of the compiler's build time (`readsFor`). WITH
- * `refused`, a batch that refuses is asked again a file at a time, so which file it was is known
- * and the others still answer; without it the refusal is thrown.
+ * ONE SNAPSHOT FOR THE LOT, which is the whole of the compiler's build time (`readsFor`). Where
+ * `refusals` collects, a batch that refuses is asked again a file at a time, so which file it was is
+ * known and the others still answer; where it throws, so does the batch.
  */
-export async function readSources(
+export async function readSources<Source extends ParsedSource>(
     session: TypeSession,
-    parsed: readonly ParsedSource[],
-    refused?: Diagnosis[],
-): Promise<{ read: ReadSource[]; warnings: Diagnosis[] }> {
+    parsed: readonly Source[],
+    refusals: Refusals,
+): Promise<{
+    read: ReadSource<Source>[]
+    warnings: Diagnosis[]
+}> {
     try {
         const { answers, warnings } = await session.readsFor(parsed)
         return { read: answered(parsed, answers), warnings }
     } catch (thrown) {
-        if (refused === undefined) throw thrown
+        if (!refusals.collecting) throw thrown
     }
-    const read: ReadSource[] = []
+    const read: ReadSource<Source>[] = []
     const warnings: Diagnosis[] = []
     for (const source of parsed)
         try {
@@ -83,31 +79,20 @@ export async function readSources(
             read.push(...answered([source], alone.answers))
             warnings.push(...alone.warnings)
         } catch (thrown) {
-            if (!source.quiet) refused.push(refusal(source.path, thrown))
+            if (!source.quiet) refusals.at(source.path, thrown)
         }
     return { read, warnings }
 }
 
-function answered(
-    parsed: readonly ParsedSource[],
+function answered<Source extends ParsedSource>(
+    parsed: readonly Source[],
     answers: readonly CheckerAnswer[],
-): ReadSource[] {
-    const read: ReadSource[] = []
+): ReadSource<Source>[] {
+    const read: ReadSource<Source>[] = []
     for (let at = 0; at < parsed.length; at += 1)
         read.push({
-            ...(parsed[at] as ParsedSource),
+            ...(parsed[at] as Source),
             answer: answers[at] ?? UNCHECKED,
         })
     return read
 }
-
-/** A refusal as a finding at the first line of the file it was refused in. */
-export function refusal(path: string, thrown: unknown): Diagnosis {
-    return diagnosisAt(
-        path,
-        undefined,
-        0,
-        'error',
-        thrown instanceof Error ? thrown.message : String(thrown),
-    )
-}

package/src/compiler/readsIn.ts

@@ -30,7 +30,6 @@ import {
     type Type,
     TypeFlags,
 } from 'typescript/unstable/async'
-import { fileKind, routeOf } from '#shared/routePattern.ts'
 import { aliasedSymbol } from './aliasedSymbol.ts'
 import { CheckerAnswer } from './CheckerAnswer.ts'
 import {
@@ -125,8 +124,6 @@ export async function readsIn(
     sourceFile: SourceFile,
     shadowPath: string,
     spans: ShadowSpans,
-    // The file below the app's root, which its route is read off (23.14).
-    routedPath: string,
     file: AbideFile,
 ): Promise<{ answer: CheckerAnswer; warnings: Finding[] }> {
     // A destructuring pattern binds names this does not see, and that is 31.12's case.
@@ -188,7 +185,7 @@ export async function readsIn(
     // Awaited after the round trips below, so a 33.14 refusal would reject with nothing
     // listening and be reported unhandled; `await props` still throws it.
     props.catch(() => {})
-    const params = routeReads(checker, abide, sourceFile, routedPath, reads)
+    const params = routeReads(checker, abide, sourceFile, reads)
     const configs = configReads(
         checker,
         abide,
@@ -693,21 +690,17 @@ const ROUTE_MEMBERS = new Set(['url', 'params', 'name', 'navigating'])
  * READ AS A CALL RATHER THAN THROUGH THE CHECKER'S VALUES RECORD (`local`): the record is keyed by
  * 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].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.
+ * 23.9 — AND `route.params` IS MARKED, for a checked lowering of a page or a layout to type by what
+ * the file's own route promises (`Lowering`): the file is the route, and the running module reads
+ * the one `route` every page shares.
  */
 async function routeReads(
     checker: Checker,
     abide: Abide,
     sourceFile: Node,
-    routedPath: string,
     reads: Read[],
 ): Promise<void> {
     if (abide.route === undefined) return
-    const routed = fileKind(routedPath)
-    const kind = routed === 'page' || routed === 'layout' ? routed : undefined
     const accesses: Node[] = []
     const owners: Node[] = []
     const visit = (node: Node): void => {
@@ -725,7 +718,6 @@ async function routeReads(
     sourceFile.forEachChild(visit)
     if (owners.length === 0) return
     const symbols = await checker.getSymbolAtLocation(owners)
-    const pattern = routeOf(routedPath)
     for (let at = 0; at < accesses.length; at += 1) {
         const symbol = symbols[at]
         if (symbol === undefined) continue
@@ -735,11 +727,8 @@ async function routeReads(
         const read = classifyRead(access)
         if (read === undefined) continue
         read.local = true
-        if (
-            kind !== undefined &&
+        read.routeParams =
             (access as { name?: { text: string } }).name?.text === 'params'
-        )
-            read.routeParams = [pattern, kind]
         reads.push(read)
     }
 }

package/src/compiler/resolverIn.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from 'node:fs' // bun exposes no sync existence check or read of its own
+import { dirname, posix } from 'node:path' // bun exposes no path helpers of its own
+import { resolvedFile } from '#server/abideModules.ts'
+import { nearest } from './nearest.ts'
+
+/**
+ * Resolves a specifier from a directory as bun does, or `undefined` where it does not resolve.
+ *
+ * A COMPONENT IMPORT RESOLVES THE WAY THE APP'S OWN IMPORTS DO — its import map, from the file
+ * that wrote it. One that does not resolve is left as written, and the bundle names it. THE
+ * ANSWER IS A REAL PATH, as every root handed to the compiler is.
+ */
+export function resolverIn(): (
+    specifier: string,
+    from: string,
+) => string | undefined {
+    // ONE ANSWER PER SPECIFIER AND DIRECTORY for as long as the resolver lives: a compile resolves
+    // every import once for its dependencies and again for its graph, and hands both one resolver.
+    const answered = new Map<string, string | undefined>()
+    return (specifier, from) => {
+        const key = `${from}\0${specifier}`
+        if (answered.has(key)) return answered.get(key)
+        const found = resolveFrom(specifier, from)
+        answered.set(key, found)
+        return found
+    }
+}
+
+function resolveFrom(specifier: string, from: string): string | undefined {
+    try {
+        return resolvedFile(specifier, from)
+    } catch {
+        // 38.65 — BUN KEEPS A DIRECTORY'S LISTING FOR THE LIFE OF THE PROCESS, and looks a `#` specifier up
+        // in it with no second look — where a relative one that misses reads the directory again.
+        // `abide dev` compiles in one process for its whole session, so a component created since
+        // its directory was listed never resolved, and was read as uninvoked. The `imports` map is
+        // read here instead, and the file it names looked for on disk.
+        return specifier.startsWith('#')
+            ? throughImports(specifier, from)
+            : undefined
+    }
+}
+
+/** A `#` specifier resolved through the nearest `package.json`'s `imports`, to a file that exists. */
+function throughImports(specifier: string, from: string): string | undefined {
+    const manifest = nearest(from, 'package.json')
+    if (manifest === undefined) return undefined
+    const imports = (
+        JSON.parse(readFileSync(manifest, 'utf8')) as {
+            imports?: Record<string, unknown>
+        }
+    ).imports
+    if (imports === undefined) return undefined
+    const base = dirname(manifest)
+    for (const [key, targets] of Object.entries(imports)) {
+        const star = key.indexOf('*')
+        let matched: string | undefined
+        if (star === -1) matched = key === specifier ? '' : undefined
+        else if (
+            specifier.startsWith(key.slice(0, star)) &&
+            specifier.endsWith(key.slice(star + 1)) &&
+            specifier.length >= key.length - 1
+        )
+            matched = specifier.slice(
+                star,
+                specifier.length - (key.length - star - 1),
+            )
+        if (matched === undefined) continue
+        // A conditions object names no path of its own, and is passed over.
+        for (const target of [targets].flat()) {
+            if (typeof target !== 'string') continue
+            const path = posix.join(base, target.replace('*', matched))
+            if (existsSync(path)) return path
+        }
+    }
+    return undefined
+}