@abide/abide 0.58.0 → 0.100.0

package/src/compiler/VOID_ELEMENTS.ts

@@ -0,0 +1,22 @@
+/**
+ * Elements that never have children and never take a close tag.
+ *
+ * A constants leaf, with no imports of its own: the PARSER must not push one onto its
+ * open-element stack and the EMITTER must not write a close tag for one, and two copies of the
+ * list is one list that goes stale.
+ */
+export const VOID_ELEMENTS: ReadonlySet<string> = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'source',
+    'track',
+    'wbr',
+])

package/src/compiler/aliasedSymbol.ts

@@ -0,0 +1,15 @@
+import {
+    type Symbol as CheckedSymbol,
+    type Checker,
+    SymbolFlags,
+} from 'typescript/unstable/async'
+
+/** The symbol an import or a re-export names, or the symbol itself where it is not an alias. */
+export function aliasedSymbol(
+    checker: Checker,
+    symbol: CheckedSymbol,
+): Promise<CheckedSymbol> {
+    return (symbol.flags & SymbolFlags.Alias) === 0
+        ? Promise.resolve(symbol)
+        : checker.getAliasedSymbol(symbol)
+}

package/src/compiler/ambientReadsIn.ts

@@ -0,0 +1,152 @@
+import {
+    type CallExpression,
+    type Node,
+    SyntaxKind,
+} from 'typescript/unstable/ast'
+import {
+    isCallExpression,
+    isIdentifier,
+    isPropertyAccessExpression,
+    isPropertyAssignment,
+} from 'typescript/unstable/ast/is'
+import type { Checker } from 'typescript/unstable/async'
+import { aliasedSymbol } from './aliasedSymbol.ts'
+import {
+    isWrittenInPlace,
+    optionNamed,
+    reactiveOptions,
+} from './reactiveOptions.ts'
+
+// 11.37 — A `global` VALUE'S BODY READING WHAT ONLY A REQUEST HAS. A `global` value is one for the
+// whole process (11.34), so a body reading the request it happened to be built in answers every
+// later request with the first one's `principal`, `cookies` or `route` — the one failure a page
+// served to one person at a time never shows.
+//
+// WHAT THE BODY READS ITSELF, by the checker's own symbols: an app's `route` is not abide's, and
+// abide's imported under another name is. A read reached through a function the body calls is not
+// seen, and is the same limit 14.16 has.
+
+const besideThis = (relative: string): string =>
+    Bun.fileURLToPath(new URL(relative, import.meta.url))
+
+// Where abide declares each ambient, and whether only its `.nonce` belongs to the request.
+const AMBIENTS: { path: string; name: string; nonce: boolean }[] = [
+    {
+        path: besideThis('../server/requestScope.ts'),
+        name: 'request',
+        nonce: false,
+    },
+    {
+        path: besideThis('../server/requestScope.ts'),
+        name: 'response',
+        nonce: false,
+    },
+    {
+        path: besideThis('../shared/principal.ts'),
+        name: 'principal',
+        nonce: false,
+    },
+    { path: besideThis('../shared/cookies.ts'), name: 'cookies', nonce: false },
+    { path: besideThis('../shared/csp.ts'), name: 'csp', nonce: true },
+    { path: besideThis('../shared/route.ts'), name: 'route', nonce: false },
+]
+
+/** The modules that declare abide's per-request ambients, each once. */
+export const AMBIENT_SOURCES: string[] = [
+    ...new Set(AMBIENTS.map((ambient) => ambient.path)),
+]
+
+/**
+ * Where a `global` reactive's body reads a per-request ambient, in source order.
+ *
+ * `paths` maps each of `AMBIENT_SOURCES` to the path the checker names it by (`declaredExports` has
+ * the reason: the checker folds case on a case-insensitive disk).
+ */
+export async function ambientReadsIn(
+    checker: Checker,
+    sourceFile: Node,
+    paths: Map<string, string>,
+): Promise<{ at: number; ambient: string }[]> {
+    // EVERY NAME A `global` BODY USES, whatever it is spelled: which ones are abide's ambients is
+    // the symbol's answer.
+    const candidates: Node[] = []
+    const collect = (node: Node): void => {
+        if (isIdentifier(node) && isUse(node)) candidates.push(node)
+        node.forEachChild((child) => {
+            collect(child)
+            return undefined
+        })
+    }
+    const visit = (node: Node): void => {
+        if (isCallExpression(node) && isGlobalReactive(node)) {
+            const body = node.arguments[0]
+            if (body !== undefined) collect(body)
+        }
+        node.forEachChild((child) => {
+            visit(child)
+            return undefined
+        })
+    }
+    visit(sourceFile)
+    if (candidates.length === 0) return []
+    const symbols = await checker.getSymbolAtLocation(candidates)
+    const found: { at: number; ambient: string }[] = []
+    await Promise.all(
+        candidates.map(async (node, at) => {
+            const symbol = symbols[at]
+            if (symbol === undefined) return
+            const target = await aliasedSymbol(checker, symbol)
+            const declared = target.valueDeclaration?.path
+            if (declared === undefined) return
+            for (const ambient of AMBIENTS)
+                if (
+                    ambient.name === target.name &&
+                    declared === paths.get(ambient.path) &&
+                    (!ambient.nonce || readsNonce(node))
+                )
+                    found.push({
+                        at: node.getStart(),
+                        ambient: ambient.nonce
+                            ? `${ambient.name}.nonce`
+                            : ambient.name,
+                    })
+        }),
+    )
+    found.sort((one, two) => one.at - two.at)
+    return found
+}
+
+/**
+ * Whether a call builds a `global` value over a body written in place: `reactive(() => …, { global:
+ * true })` or `GET(() => …, { global: true })`, the option a literal `true`.
+ */
+function isGlobalReactive(call: CallExpression): boolean {
+    if (!isWrittenInPlace(call.arguments[0])) return false
+    const options = reactiveOptions(call)
+    return (
+        options !== undefined &&
+        optionNamed(options, 'global')?.kind === SyntaxKind.TrueKeyword
+    )
+}
+
+/** Whether a name stands for a value, rather than a property or a key that spells one. */
+function isUse(node: Node): boolean {
+    const parent = node.parent
+    if (isPropertyAccessExpression(parent) && parent.name === node) return false
+    return !(isPropertyAssignment(parent) && parent.name === node)
+}
+
+/**
+ * Whether the name is read as `name.nonce`.
+ *
+ * `csp` is one per request only in its `nonce`.
+ */
+function readsNonce(node: Node): boolean {
+    const parent = node.parent
+    return (
+        isPropertyAccessExpression(parent) &&
+        parent.expression === node &&
+        isIdentifier(parent.name) &&
+        parent.name.text === 'nonce'
+    )
+}

package/src/compiler/argsDefaultsIn.ts

@@ -0,0 +1,173 @@
+import type {
+    CallExpression,
+    Node,
+    ObjectBindingPattern,
+    ObjectLiteralExpression,
+} from 'typescript/unstable/ast'
+import {
+    isArrowFunction,
+    isCallExpression,
+    isFunctionDeclaration,
+    isFunctionExpression,
+    isIdentifier,
+    isObjectBindingPattern,
+    isObjectLiteralExpression,
+    isPropertyAssignment,
+    isStringLiteral,
+} from 'typescript/unstable/ast/is'
+import { type Checker, SymbolFlags, type Type } from 'typescript/unstable/async'
+import type { Finding } from './Finding.ts'
+import { optionNamed, reactiveOptions } from './reactiveOptions.ts'
+
+// 11.30 — AN `args` SCHEMA DEFAULTING A MEMBER THE BODY'S PARAMETER DOES NOT. The key is taken before
+// `args` runs (11.26), so a default only the schema writes is applied after it: `{}` and `{ page: 1 }`
+// are two entries the body runs the same for. A warning rather than a refusal: the program is valid,
+// and the cost is work rather than a wrong value.
+//
+// WHAT THE SCHEMA DEFAULTS IS READ WITHOUT RUNNING IT: a `jsonSchema` document's `default` keyword
+// where the document is written at the call, and otherwise a Standard Schema's own declared types —
+// a member its input may leave out and its output always has is one it defaults. A schema that is a
+// function says neither, and is not warned on.
+
+/** The object pattern a function's first parameter destructures, or `undefined`. */
+export function parameterPattern(
+    node: Node | undefined,
+): ObjectBindingPattern | undefined {
+    if (
+        node === undefined ||
+        !(
+            isArrowFunction(node) ||
+            isFunctionExpression(node) ||
+            isFunctionDeclaration(node)
+        )
+    )
+        return undefined
+    const pattern = node.parameters[0]?.name
+    return pattern !== undefined && isObjectBindingPattern(pattern)
+        ? pattern
+        : undefined
+}
+
+/**
+ * The args members a function's parameter pattern gives a default.
+ *
+ * 19.10 — THE ARGS MEMBERS A HANDLER DEFAULTS, which its annotation still calls required: the type
+ * the `Rpc` carries is the one written, and a default lives on the pattern that destructures it.
+ */
+export function defaultedMembers(node: Node | undefined): string[] {
+    const pattern = parameterPattern(node)
+    if (pattern === undefined) return []
+    const defaulted: string[] = []
+    for (const element of pattern.elements) {
+        if (element.initializer === undefined) continue
+        const key = element.propertyName ?? element.name
+        if (key !== undefined && (isIdentifier(key) || isStringLiteral(key)))
+            defaulted.push(key.text)
+    }
+    return defaulted
+}
+
+/** Where a `reactive(…)`'s `args` defaults a member its body's parameter does not. */
+export async function argsDefaultsIn(
+    checker: Checker,
+    sourceFile: Node,
+): Promise<Finding[]> {
+    const gated: { args: Node; body: Node }[] = []
+    const visit = (node: Node): void => {
+        if (isCallExpression(node)) {
+            const args = argsOf(node)
+            const body = node.arguments[0]
+            if (args !== undefined && parameterPattern(body) !== undefined)
+                gated.push({ args, body: body as Node })
+        }
+        node.forEachChild((child) => {
+            visit(child)
+            return undefined
+        })
+    }
+    visit(sourceFile)
+    const found: Finding[] = []
+    for (const { args, body } of gated) {
+        const written = defaultedMembers(body)
+        for (const member of await schemaDefaults(checker, args))
+            if (!written.includes(member))
+                found.push({
+                    at: args.getStart(),
+                    message: `abide: \`args\` defaults \`${member}\`, and the body's parameter does not. The key is taken before \`args\` runs, so a call leaving \`${member}\` out and one writing its default are two entries the body runs the same for. Default \`${member}\` in the parameter too. RULEBOOK 11.30.`,
+                })
+    }
+    return found
+}
+
+/** The `args` option a `reactive(…)` call writes, or `undefined`. */
+function argsOf(call: CallExpression): Node | undefined {
+    const options = reactiveOptions(call)
+    return options === undefined ? undefined : optionNamed(options, 'args')
+}
+
+/** The members a schema defaults, as far as it can be read without running it. */
+async function schemaDefaults(
+    checker: Checker,
+    schema: Node,
+): Promise<string[]> {
+    const document =
+        isCallExpression(schema) &&
+        isIdentifier(schema.expression) &&
+        schema.expression.text === 'jsonSchema'
+            ? schema.arguments[0]
+            : undefined
+    if (document !== undefined && isObjectLiteralExpression(document))
+        return documentDefaults(document)
+    const type = await checker.getTypeAtLocation(schema)
+    return type === undefined ? [] : standardDefaults(checker, type)
+}
+
+/** The members a JSON Schema document written as a literal gives a `default`. */
+function documentDefaults(document: ObjectLiteralExpression): string[] {
+    const properties = optionNamed(document, 'properties')
+    if (properties === undefined || !isObjectLiteralExpression(properties))
+        return []
+    const defaulted: string[] = []
+    for (const property of properties.properties) {
+        if (!isPropertyAssignment(property)) continue
+        const key = property.name
+        if (!(isIdentifier(key) || isStringLiteral(key))) continue
+        const member = property.initializer
+        if (
+            isObjectLiteralExpression(member) &&
+            optionNamed(member, 'default') !== undefined
+        )
+            defaulted.push(key.text)
+    }
+    return defaulted
+}
+
+/** The members a Standard Schema's input may leave out and its output always has. */
+async function standardDefaults(
+    checker: Checker,
+    type: Type,
+): Promise<string[]> {
+    const standard = await memberType(checker, type, '~standard')
+    const declared = standard && (await memberType(checker, standard, 'types'))
+    const types = declared && (await checker.getNonNullableType(declared))
+    const input = types && (await memberType(checker, types, 'input'))
+    const output = types && (await memberType(checker, types, 'output'))
+    if (!input || !output) return []
+    const defaulted: string[] = []
+    for (const member of await checker.getPropertiesOfType(output)) {
+        if ((member.flags & SymbolFlags.Optional) !== 0) continue
+        const given = await checker.getPropertyOfType(input, member.name)
+        if (given === undefined || (given.flags & SymbolFlags.Optional) !== 0)
+            defaulted.push(member.name)
+    }
+    return defaulted
+}
+
+async function memberType(
+    checker: Checker,
+    type: Type,
+    name: string,
+): Promise<Type | undefined> {
+    const member = await checker.getPropertyOfType(type, name)
+    return member === undefined ? undefined : checker.getTypeOfSymbol(member)
+}

package/src/compiler/argsSchemaOf.ts

@@ -0,0 +1,230 @@
+// 19.9 — A HANDLER'S ARGS, AS THE JSON SCHEMA ITS TYPESCRIPT ANNOTATION SAYS, derived at build by
+// the checker the build already holds. A URL carries text and a caller outside the process carries
+// whatever it likes, so `({ id }: { id: number })` is a promise only the in-process call keeps; this
+// is what lets the wire keep it too — coerced (19.7), validated, and published (20.11) with no
+// schema written twice.
+//
+// 19.11 — THE DIALECT IS `validateJson`'s, and a type it cannot say is `{}` — no constraint — rather than a
+// guess: a function, a class, a generic still open. Narrower than the type is a refusal an author
+// never wrote; wider is the handler's own concern, which is where it was before.
+
+import {
+    type Checker,
+    type LiteralType,
+    SignatureKind,
+    SymbolFlags,
+    type Type,
+    TypeFlags,
+    type TypeReference,
+    type UnionOrIntersectionType,
+} from 'typescript/unstable/async'
+import type { JsonValue } from '#shared/JsonValue.ts'
+
+type Schema = { [keyword: string]: JsonValue }
+
+/**
+ * What one schema walk remembers: the object types it has answered, and how deep it is.
+ *
+ * ONE WALK'S MEMORY: each object type walked once, whatever reaches it again, and a depth past which
+ * a type is `{}`. An args record is JSON a few levels deep; a type that reaches the DOM or the lib's
+ * class graph instead is wide enough to walk for minutes, and widening it is 19.11's answer.
+ */
+export type Walk<Seen = Map<number, Schema>> = { seen: Seen; depth: number }
+/** The depth a walk stops at: an object type this deep or deeper is not walked. */
+export const DEEPEST = 8
+
+/**
+ * The JSON Schema of a handler's args record, or `undefined` where it takes no record.
+ *
+ * What the first parameter of the `Rpc`'s call takes, or `undefined` where it takes no record —
+ * with each member the handler defaults made optional (19.10).
+ */
+export async function argsSchemaOf(
+    checker: Checker,
+    handler: Type,
+    defaulted: string[],
+): Promise<Schema | undefined> {
+    const [call] = await checker.getSignaturesOfType(
+        handler,
+        SignatureKind.Call,
+    )
+    const args =
+        call === undefined ? undefined : await checker.getParameterType(call, 0)
+    if (args === undefined) return undefined
+    const schema = await schemaOf(checker, args, { seen: new Map(), depth: 0 })
+    if (schema.type !== 'object') return undefined
+    const required = schema.required as string[] | undefined
+    if (required !== undefined && defaulted.length > 0) {
+        const kept = required.filter((name) => !defaulted.includes(name))
+        if (kept.length > 0) schema.required = kept
+        else delete schema.required
+    }
+    return schema
+}
+
+async function schemaOf(
+    checker: Checker,
+    type: Type,
+    walk: Walk,
+): Promise<Schema> {
+    const flags = type.flags
+    if (flags & TypeFlags.String) return { type: 'string' }
+    if (flags & TypeFlags.Number) return { type: 'number' }
+    if (flags & TypeFlags.Boolean) return { type: 'boolean' }
+    if (flags & TypeFlags.Null) return { type: 'null' }
+    if (flags & (TypeFlags.StringLiteral | TypeFlags.NumberLiteral))
+        return literalsOf([type])
+    if (flags & TypeFlags.BooleanLiteral)
+        return {
+            type: 'boolean',
+            const: (type as LiteralType).value as boolean,
+        }
+    if (flags & TypeFlags.Union)
+        return unionOf(checker, type as UnionOrIntersectionType, walk)
+    if (!(flags & (TypeFlags.Object | TypeFlags.Intersection))) return {}
+    // A type reached again — inside itself, or from a second member — answers what it answered, and
+    // one still being walked answers `{}`: a recursive type says nothing more the second time.
+    const known = walk.seen.get(type.id)
+    if (known !== undefined) return known
+    if (walk.depth >= DEEPEST) return {}
+    const pending: Schema = {}
+    walk.seen.set(type.id, pending)
+    const inner: Walk = { seen: walk.seen, depth: walk.depth + 1 }
+    // Three questions of one type, asked together rather than one round trip after another.
+    const [array, tuple, calls] = await Promise.all([
+        checker.isArrayType(type),
+        checker.isTupleType(type),
+        checker.getSignaturesOfType(type, SignatureKind.Call),
+    ])
+    let schema: Schema
+    if (array) {
+        const [item] = await checker.getTypeArguments(type as TypeReference)
+        schema =
+            item === undefined
+                ? { type: 'array' }
+                : { type: 'array', items: await schemaOf(checker, item, inner) }
+    } else if (tuple) schema = { type: 'array' }
+    else if (calls.length > 0) schema = {}
+    else schema = await objectOf(checker, type, inner)
+    walk.seen.set(type.id, schema)
+    return schema
+}
+
+async function objectOf(
+    checker: Checker,
+    type: Type,
+    walk: Walk,
+): Promise<Schema> {
+    const properties: Schema = {}
+    const required: string[] = []
+    const members = await checker.getPropertiesOfType(type)
+    // Every member's type in one round trip.
+    const types = await checker.getTypeOfSymbol(members)
+    for (let at = 0; at < members.length; at += 1) {
+        const property = members[at] as (typeof members)[number]
+        const value = types[at]
+        if (value === undefined) continue
+        properties[property.name] = await schemaOf(checker, value, walk)
+        // A member JSON can leave out is not required, whether `?` said so or `| undefined` did.
+        if (
+            (property.flags & SymbolFlags.Optional) === 0 &&
+            !(await holdsUndefined(value))
+        )
+            required.push(property.name)
+    }
+    const schema: Schema = { type: 'object', properties }
+    if (required.length > 0) schema.required = required
+    // 19.20 — A MEMBER THE TYPE DOES NOT DECLARE IS REFUSED, where no index signature declares the
+    // rest: a caller outside the process sends whatever it likes, and a body writing its args to a
+    // row would write that too. An author who wants the rest declares a schema of their own.
+    schema.additionalProperties = false
+    for (const index of await checker.getIndexInfosOfType(type))
+        if (index.keyType.flags & TypeFlags.String)
+            schema.additionalProperties = await schemaOf(
+                checker,
+                index.valueType,
+                walk,
+            )
+    return schema
+}
+
+/**
+ * A union, with what JSON cannot carry dropped: `undefined` is an absent member rather than a value.
+ * `true | false` is `boolean`, a run of one kind's literals is an `enum` under that kind's `type` —
+ * the `type` is what 19.7 coerces text by — and bare kinds merge into one `type` list.
+ */
+async function unionOf(
+    checker: Checker,
+    union: UnionOrIntersectionType,
+    walk: Walk,
+): Promise<Schema> {
+    const all = await union.getTypes()
+    const members: Type[] = []
+    const literals: Type[] = []
+    let booleans = 0
+    for (const member of all) {
+        if (member.flags & (TypeFlags.Undefined | TypeFlags.Void)) continue
+        if (member.flags & TypeFlags.BooleanLiteral) booleans += 1
+        else if (
+            member.flags &
+            (TypeFlags.StringLiteral | TypeFlags.NumberLiteral)
+        )
+            literals.push(member)
+        else members.push(member)
+    }
+    const schemas: Schema[] = []
+    if (literals.length > 0) schemas.push(...literalGroups(literals))
+    if (booleans === 2) schemas.push({ type: 'boolean' })
+    else if (booleans === 1)
+        for (const member of all)
+            if (member.flags & TypeFlags.BooleanLiteral)
+                schemas.push({
+                    type: 'boolean',
+                    const: (member as LiteralType).value as boolean,
+                })
+    for (const member of members)
+        schemas.push(await schemaOf(checker, member, walk))
+    if (schemas.length === 1) return schemas[0] as Schema
+    const kinds: string[] = []
+    for (const schema of schemas) {
+        if (Object.keys(schema).length !== 1 || typeof schema.type !== 'string')
+            return { anyOf: schemas }
+        kinds.push(schema.type)
+    }
+    return { type: kinds }
+}
+
+/** String literals under `string`, number literals under `number`: one `enum` each. */
+function literalGroups(literals: Type[]): Schema[] {
+    const strings: Type[] = []
+    const numbers: Type[] = []
+    for (const literal of literals)
+        (literal.flags & TypeFlags.StringLiteral ? strings : numbers).push(
+            literal,
+        )
+    const groups: Schema[] = []
+    if (strings.length > 0) groups.push(literalsOf(strings))
+    if (numbers.length > 0) groups.push(literalsOf(numbers))
+    return groups
+}
+
+function literalsOf(literals: Type[]): Schema {
+    const values: JsonValue[] = []
+    for (const literal of literals)
+        values.push((literal as LiteralType).value as string | number)
+    const kind =
+        (literals[0] as Type).flags & TypeFlags.StringLiteral
+            ? 'string'
+            : 'number'
+    return values.length === 1
+        ? { type: kind, const: values[0] as JsonValue }
+        : { type: kind, enum: values }
+}
+
+async function holdsUndefined(type: Type): Promise<boolean> {
+    if (type.flags & (TypeFlags.Undefined | TypeFlags.Void)) return true
+    if (!(type.flags & TypeFlags.Union)) return false
+    for (const member of await (type as UnionOrIntersectionType).getTypes())
+        if (member.flags & (TypeFlags.Undefined | TypeFlags.Void)) return true
+    return false
+}