lambder 7.3.1 → 8.1.1

package/dist/build/ContractTypePrinter.js

@@ -0,0 +1,402 @@
+const INDENT = "    ";
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** How long a union may run on one line before each member goes on a line of its own. */
+const UNION_LINE_WIDTH = 80;
+const atom = (text) => ({ text, compound: false });
+const indentFollowingLines = (text, indent) => text.replace(/\n/g, `\n${indent}`);
+/** Code-unit order, so the output never depends on the locale it is generated under. */
+const byCodeUnits = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+/**
+ * Properties in the order they are written in the source: the file, then the
+ * position, then the name for those declared together (a Record's keys) or
+ * not at all. The compiler's own order is not used, because the properties of
+ * a mapped type (every zod inference) follow a union of their keys, and a
+ * union is ordered by when each key's type was first created, which moves
+ * whenever unrelated code is checked in another order.
+ */
+const bySourceOrder = (a, b) => {
+    const first = a.declarations?.[0];
+    const second = b.declarations?.[0];
+    if (first && second) {
+        const byFile = byCodeUnits(first.getSourceFile().fileName, second.getSourceFile().fileName);
+        if (byFile)
+            return byFile;
+        if (first.pos !== second.pos)
+            return first.pos - second.pos;
+    }
+    else if (first || second) {
+        return first ? -1 : 1;
+    }
+    return byCodeUnits(a.name, b.name);
+};
+/** Union members in a stable order, with null and undefined last as they are usually written. */
+const unionMemberRank = (text) => text === "null" ? 1 : text === "undefined" ? 2 : 0;
+export class ContractTypePrinter {
+    ts;
+    program;
+    checker;
+    style;
+    failures = [];
+    /** Every named declaration by the type it stands for; its text is null while it is being printed. */
+    declarations = new Map();
+    /** Names a declaration may not take: the default library's, and the contract's own. */
+    takenNames = new Set();
+    /** The anonymous types being printed: meeting one again inside itself is recursion, and it needs a name. */
+    inProgress = new Set();
+    /** Under exactOptionalPropertyTypes an optional member's type carries the compiler's own "missing" undefined, which its source never wrote. */
+    exactOptionalProperties;
+    constructor(ts, program, checker, style, contractName) {
+        this.ts = ts;
+        this.program = program;
+        this.checker = checker;
+        this.style = style;
+        this.takenNames.add(contractName);
+        this.exactOptionalProperties = !!program.getCompilerOptions().exactOptionalPropertyTypes;
+        // A declaration named after a global the printed text refers to by
+        // name (Date) would shadow it.
+        for (const sourceFile of program.getSourceFiles()) {
+            if (!program.isSourceFileDefaultLibrary(sourceFile))
+                continue;
+            for (const statement of sourceFile.statements) {
+                if ((ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isModuleDeclaration(statement))
+                    && statement.name && ts.isIdentifier(statement.name))
+                    this.takenNames.add(statement.name.text);
+            }
+        }
+    }
+    /** Prints each member of the contract type, sorted by name, and every declaration they refer to. */
+    printContract(contract) {
+        const entries = this.checker.getPropertiesOfType(contract)
+            .map((entry) => ({ name: entry.name, text: this.print(this.checker.getTypeOfSymbol(entry), this.keyOf(entry.name)).text }))
+            .sort((a, b) => byCodeUnits(a.name, b.name));
+        const declarations = [...this.declarations.values()]
+            .map(({ name, text }) => ({ name, text: text ?? "never" }))
+            .sort((a, b) => byCodeUnits(a.name, b.name));
+        return { entries, declarations, failures: this.failures };
+    }
+    /**
+     * `label value`, with a union too long for one line starting on the next
+     * line, one member per line: what a property, an index signature and a
+     * declaration all print through.
+     */
+    labeledValue(label, value) {
+        return value.startsWith("| ") ? `${label}\n${INDENT}${indentFollowingLines(value, INDENT)}` : `${label} ${value}`;
+    }
+    print(type, path) {
+        const { TypeFlags } = this.ts;
+        const flags = type.flags;
+        // The compiler's own `any` is the one a source wrote (or inferred);
+        // any other is the error type a compile error leaves behind.
+        if (flags & TypeFlags.Any) {
+            return type === this.checker.getAnyType() ? atom("any") : this.fail(path, "a type the compiler could not resolve, which a compile error in the app's sources leaves behind: run its typecheck");
+        }
+        if (flags & TypeFlags.Unknown)
+            return atom("unknown");
+        if (flags & TypeFlags.Never)
+            return atom("never");
+        if (flags & TypeFlags.String)
+            return atom("string");
+        if (flags & TypeFlags.Number)
+            return atom("number");
+        if (flags & TypeFlags.BigInt)
+            return atom("bigint");
+        if (flags & TypeFlags.Boolean)
+            return atom("boolean");
+        if (flags & TypeFlags.Void)
+            return atom("void");
+        if (flags & TypeFlags.Undefined)
+            return atom("undefined");
+        if (flags & TypeFlags.Null)
+            return atom("null");
+        if (flags & TypeFlags.ESSymbol)
+            return atom("symbol");
+        if (flags & TypeFlags.NonPrimitive)
+            return atom("object");
+        // Before the literals: an enum member is a literal type as well.
+        if (flags & TypeFlags.EnumLike)
+            return this.fail(path, `${this.checker.typeToString(type)}, an enum, which only its declaration can name`);
+        if (flags & TypeFlags.StringLiteral)
+            return atom(this.quoted(type.value));
+        if (flags & TypeFlags.NumberLiteral)
+            return atom(String(type.value));
+        if (flags & TypeFlags.BigIntLiteral) {
+            const { negative, base10Value } = type.value;
+            return atom(`${negative ? "-" : ""}${base10Value}n`);
+        }
+        if (flags & TypeFlags.BooleanLiteral)
+            return atom(this.checker.typeToString(type));
+        if (flags & TypeFlags.UniqueESSymbol)
+            return this.fail(path, "a unique symbol, which only its declaration can name");
+        if (flags & TypeFlags.TemplateLiteral)
+            return this.printTemplateLiteral(type, path);
+        if (flags & TypeFlags.StringMapping) {
+            const mapping = type;
+            return atom(`${mapping.symbol.name}<${this.print(mapping.type, path).text}>`);
+        }
+        if (flags & (TypeFlags.Union | TypeFlags.Intersection | TypeFlags.Object))
+            return this.printComposite(type, path);
+        return this.fail(path, `${this.checker.typeToString(type)}, which only resolves where it was written (a type parameter, or a conditional or indexed type over one)`);
+    }
+    /** A union, an intersection or an object: printed in place, or as a reference to a declaration of its own. */
+    printComposite(type, path) {
+        const known = this.declarations.get(type);
+        if (known)
+            return atom(known.name);
+        const ownName = this.declaredNameOf(type);
+        if (ownName !== undefined) {
+            // Registered before the body is printed, so a reference to itself
+            // inside the body finds the name.
+            const declaration = { name: this.takeName(ownName), text: null };
+            this.declarations.set(type, declaration);
+            declaration.text = this.printStructure(type, path).text;
+            return atom(declaration.name);
+        }
+        if (this.inProgress.has(type)) {
+            const declaration = { name: this.takeName(this.recursiveNameOf(type)), text: null };
+            this.declarations.set(type, declaration);
+            return atom(declaration.name);
+        }
+        this.inProgress.add(type);
+        const printed = this.printStructure(type, path);
+        this.inProgress.delete(type);
+        // Named while its body was being printed: it refers to itself.
+        const recursive = this.declarations.get(type);
+        if (!recursive)
+            return printed;
+        recursive.text = printed.text;
+        return atom(recursive.name);
+    }
+    /** The name a type is declared under, when it is one to print as a declaration: non-generic, and not the default library's. */
+    declaredNameOf(type) {
+        const { ObjectFlags, TypeFlags } = this.ts;
+        if (type.aliasSymbol) {
+            return type.aliasTypeArguments?.length || this.isDefaultLibrary(type.aliasSymbol) ? undefined : this.nameOf(type.aliasSymbol);
+        }
+        if (!(type.flags & TypeFlags.Object))
+            return undefined;
+        const objectFlags = type.objectFlags;
+        if (!(objectFlags & (ObjectFlags.Interface | ObjectFlags.Class)))
+            return undefined;
+        // A class, or an interface with a base type, is a reference to itself
+        // (for its `this` type). A generic one's instances are references to
+        // it instead, and are printed in place.
+        if (objectFlags & ObjectFlags.Reference && (type.target !== type || type.typeParameters?.length))
+            return undefined;
+        return this.isDefaultLibrary(type.symbol) ? undefined : this.nameOf(type.symbol);
+    }
+    /** The name a symbol is declared under, read off its declaration, so `export default interface Customer` is Customer; undefined when it has none to print. */
+    nameOf(symbol) {
+        const declaration = symbol.declarations?.[0];
+        const declared = declaration && this.ts.getNameOfDeclaration(declaration);
+        const name = declared && this.ts.isIdentifier(declared) ? declared.text : symbol.name;
+        return IDENTIFIER.test(name) && name !== "default" && !name.startsWith("__") ? name : undefined;
+    }
+    /**
+     * A name for a type that refers to itself and has none of its own: what it
+     * instantiates followed by its arguments (a JSON mapping of a Tree is
+     * `JsonOfTree`, a `Tree<string>` is `TreeString`), or `RecursiveType`.
+     */
+    recursiveNameOf(type) {
+        const { ObjectFlags, TypeFlags } = this.ts;
+        let instantiated;
+        if (type.aliasSymbol) {
+            instantiated = { symbol: type.aliasSymbol, typeArguments: type.aliasTypeArguments ?? [] };
+        }
+        else if (type.flags & TypeFlags.Object && type.objectFlags & ObjectFlags.Reference) {
+            const { target } = type;
+            const typeArguments = this.checker.getTypeArguments(type).slice(0, target.typeParameters?.length ?? 0);
+            instantiated = { symbol: target.symbol, typeArguments };
+        }
+        const base = instantiated && this.nameOf(instantiated.symbol);
+        if (!instantiated || !base)
+            return "RecursiveType";
+        const argumentNames = instantiated.typeArguments
+            .map((argument) => (argument.aliasSymbol && this.nameOf(argument.aliasSymbol)) ?? (argument.symbol && this.nameOf(argument.symbol)) ?? this.checker.typeToString(argument))
+            .filter((name) => IDENTIFIER.test(name));
+        return `${base}${argumentNames.map((name) => name[0].toUpperCase() + name.slice(1)).join("")}`;
+    }
+    printStructure(type, path) {
+        const { TypeFlags } = this.ts;
+        if (type.flags & TypeFlags.Union)
+            return this.printUnion(type, path);
+        if (type.flags & TypeFlags.Intersection)
+            return this.printIntersection(type, path);
+        return this.printObject(type, path);
+    }
+    printUnion(type, path) {
+        return this.printUnionOf(type.types, path);
+    }
+    printUnionOf(types, path) {
+        const members = [];
+        // boolean is the union of its two literals, and a union holding it
+        // holds them flattened in: they are put back together.
+        const booleans = new Set();
+        for (const member of types) {
+            if (member.flags & this.ts.TypeFlags.BooleanLiteral)
+                booleans.add(this.checker.typeToString(member));
+            else
+                members.push(this.print(member, path).text);
+        }
+        if (booleans.size === 2)
+            members.push("boolean");
+        else
+            members.push(...booleans);
+        members.sort((a, b) => unionMemberRank(a) - unionMemberRank(b) || byCodeUnits(a, b));
+        const oneLine = members.join(" | ");
+        if (oneLine.length <= UNION_LINE_WIDTH && !oneLine.includes("\n"))
+            return { text: oneLine, compound: true };
+        return { text: members.map((member) => `| ${indentFollowingLines(member, "  ")}`).join("\n"), compound: true };
+    }
+    printIntersection(type, path) {
+        // Objects intersected are one object, and printed as the one they are.
+        if (type.types.every((member) => this.isPlainObject(member)))
+            return this.printMembers(type, path);
+        const members = type.types.map((member) => this.wrapped(this.print(member, path))).sort(byCodeUnits);
+        return { text: members.join(" & "), compound: true };
+    }
+    printObject(type, path) {
+        const { checker, ts } = this;
+        if (checker.isTupleType(type))
+            return this.printTuple(type, path);
+        if (checker.isArrayType(type)) {
+            const reference = type;
+            const element = this.print(checker.getTypeArguments(reference)[0], `${path}[]`);
+            const readonly = reference.target.symbol?.escapedName === "ReadonlyArray";
+            return { text: `${readonly ? "readonly " : ""}${this.wrapped(element)}[]`, compound: readonly };
+        }
+        if (this.isCallable(type))
+            return this.fail(path, `${checker.typeToString(type)}, a function, which is not data`);
+        if (this.isDefaultLibraryInterface(type)) {
+            const reference = type;
+            const parameterCount = type.objectFlags & ts.ObjectFlags.Reference ? reference.target.typeParameters?.length ?? 0 : 0;
+            const typeArguments = parameterCount ? checker.getTypeArguments(reference).slice(0, parameterCount) : [];
+            const name = checker.getFullyQualifiedName(type.symbol);
+            return atom(typeArguments.length ? `${name}<${typeArguments.map((argument) => this.print(argument, path).text).join(", ")}>` : name);
+        }
+        return this.printMembers(type, path);
+    }
+    printMembers(type, path) {
+        const { checker, ts } = this;
+        const lines = [];
+        for (const index of checker.getIndexInfosOfType(type)) {
+            const key = this.print(index.keyType, `${path}[key]`).text;
+            lines.push(this.labeledValue(`${index.isReadonly ? "readonly " : ""}[key: ${key}]:`, this.print(index.type, `${path}[${key}]`).text));
+        }
+        for (const property of [...checker.getPropertiesOfType(type)].sort(bySourceOrder)) {
+            const propertyPath = `${path}.${property.name}`;
+            const unprintable = this.unprintableProperty(property);
+            if (unprintable) {
+                this.fail(propertyPath, unprintable);
+                continue;
+            }
+            const optional = !!(property.flags & ts.SymbolFlags.Optional);
+            const printed = optional ? this.printOptionalMember(checker.getTypeOfSymbol(property), propertyPath) : this.print(checker.getTypeOfSymbol(property), propertyPath);
+            lines.push(this.labeledValue(`${this.keyOf(property.name)}${optional ? "?" : ""}:`, printed.text));
+        }
+        if (!lines.length)
+            return atom("{}");
+        return atom(`{\n${lines.map((line) => INDENT + indentFollowingLines(line, INDENT) + this.style.semicolon).join("\n")}\n}`);
+    }
+    /**
+     * An optional member's type as its source wrote it. Under
+     * exactOptionalPropertyTypes the compiler adds its own "missing"
+     * undefined, a different type from the `undefined` a source writes;
+     * printed as `| undefined` it would let the member be undefined, which
+     * the source does not.
+     */
+    printOptionalMember(type, path) {
+        if (!this.exactOptionalProperties || !(type.flags & this.ts.TypeFlags.Union))
+            return this.print(type, path);
+        const undefinedType = this.checker.getUndefinedType();
+        const written = type.types.filter((member) => !(member.flags & this.ts.TypeFlags.Undefined) || member === undefinedType);
+        if (written.length === type.types.length)
+            return this.print(type, path);
+        return written.length === 1 ? this.print(written[0], path) : this.printUnionOf(written, path);
+    }
+    printTuple(type, path) {
+        const { ElementFlags } = this.ts;
+        const { elementFlags, labeledElementDeclarations, readonly } = type.target;
+        const labelOf = (index) => {
+            const declaration = labeledElementDeclarations?.[index];
+            return declaration && this.ts.isIdentifier(declaration.name) ? declaration.name.text : undefined;
+        };
+        // Labels are all or nothing in a tuple.
+        const labeled = elementFlags.every((_, index) => labelOf(index) !== undefined);
+        const elements = this.checker.getTypeArguments(type).slice(0, elementFlags.length).map((element, index) => {
+            const flag = elementFlags[index];
+            const printed = this.print(element, `${path}[${index}]`);
+            const label = labeled ? `${labelOf(index)}` : "";
+            if (flag & ElementFlags.Rest)
+                return `...${label ? `${label}: ` : ""}${this.wrapped(printed)}[]`;
+            if (flag & ElementFlags.Variadic)
+                return `...${label ? `${label}: ` : ""}${printed.text}`;
+            if (flag & ElementFlags.Optional)
+                return label ? `${label}?: ${printed.text}` : `${this.wrapped(printed)}?`;
+            return label ? `${label}: ${printed.text}` : printed.text;
+        });
+        return { text: `${readonly ? "readonly " : ""}[${elements.join(", ")}]`, compound: readonly };
+    }
+    printTemplateLiteral(type, path) {
+        // A cooked text as template source: JSON's escapes, plus the two a template adds.
+        const escape = (text) => JSON.stringify(text).slice(1, -1).replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+        const spans = type.types.map((span, index) => `\${${this.print(span, path).text}}${escape(type.texts[index + 1])}`);
+        return atom(`\`${escape(type.texts[0])}${spans.join("")}\``);
+    }
+    /** Why a property cannot be printed as a plain member, or undefined when it can. */
+    unprintableProperty(property) {
+        const { ts } = this;
+        if (String(property.escapedName).startsWith("__@"))
+            return "a symbol-keyed property, which only its declaration can name";
+        if (property.name.startsWith("#"))
+            return "a private field of a class, which only its declaration can hold";
+        const hidden = property.declarations?.some((declaration) => ts.getCombinedModifierFlags(declaration) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected));
+        return hidden ? "a private or protected member of a class, which only its declaration can hold" : undefined;
+    }
+    /** An object type printed member by member: not an array, a tuple, a function or a default library interface. */
+    isPlainObject(type) {
+        return !!(type.flags & this.ts.TypeFlags.Object)
+            && !this.checker.isArrayType(type) && !this.checker.isTupleType(type)
+            && !this.isCallable(type) && !this.isDefaultLibraryInterface(type);
+    }
+    isCallable(type) {
+        const { SignatureKind } = this.ts;
+        return this.checker.getSignaturesOfType(type, SignatureKind.Call).length > 0 || this.checker.getSignaturesOfType(type, SignatureKind.Construct).length > 0;
+    }
+    isDefaultLibraryInterface(type) {
+        const { SymbolFlags } = this.ts;
+        return !!type.symbol && !!(type.symbol.flags & (SymbolFlags.Interface | SymbolFlags.Class)) && this.isDefaultLibrary(type.symbol);
+    }
+    /** Declared in the default library, even where a package augments it (as @types/node does some globals). */
+    isDefaultLibrary(symbol) {
+        return !!symbol.declarations?.some((declaration) => this.program.isSourceFileDefaultLibrary(declaration.getSourceFile()));
+    }
+    wrapped(printed) {
+        if (!printed.compound)
+            return printed.text;
+        if (printed.text.startsWith("| "))
+            return `(\n${INDENT}${indentFollowingLines(printed.text, INDENT)}\n)`;
+        return `(${printed.text})`;
+    }
+    keyOf(name) {
+        return IDENTIFIER.test(name) ? name : this.quoted(name);
+    }
+    quoted(value) {
+        const doubleQuoted = JSON.stringify(value);
+        if (this.style.quote === "\"")
+            return doubleQuoted;
+        // Every double quote inside is escaped, so each \" is a quote and
+        // never the tail of an escaped backslash.
+        return `'${doubleQuoted.slice(1, -1).replace(/\\"/g, "\"").replace(/'/g, "\\'")}'`;
+    }
+    takeName(base) {
+        let name = base;
+        for (let suffix = 2; this.takenNames.has(name); suffix++)
+            name = `${base}${suffix}`;
+        this.takenNames.add(name);
+        return name;
+    }
+    fail(path, reason) {
+        this.failures.push(`${path}: ${reason}`);
+        return atom("unknown");
+    }
+}

package/dist/build/freshProcessVerifier.d.ts

@@ -0,0 +1,13 @@
+/** What the parent asks for: which export of which module to digest, and the file to compare it with. */
+export type FreshProcessRequest = {
+    moduleUrl: string;
+    exportName: string;
+    file: string;
+};
+/** The comparison, or why none could be made. */
+export type FreshProcessVerdict = {
+    same: boolean;
+    lines: string[];
+} | {
+    failure: string;
+};

package/dist/build/freshProcessVerifier.js

@@ -0,0 +1,19 @@
+import { readFileSync } from "fs";
+import { describeSignatureChanges, readSignatureMap, VERIFY_REPORT_PREFIX } from "./writeApiSignatures.js";
+const request = JSON.parse(process.argv[2] ?? "null");
+const namespace = await import(request.moduleUrl);
+const source = namespace[request.exportName];
+let verdict;
+if (typeof source?.apiSignatureEntries !== "function") {
+    verdict = { failure: `${request.moduleUrl} has no export "${request.exportName}" that lists API signatures: name the export holding the instance in exportName` };
+}
+else {
+    const { movedLines, summary } = describeSignatureChanges(await source.apiSignatureEntries(), readSignatureMap(readFileSync(request.file, "utf8")));
+    verdict = { same: movedLines.length === 0, lines: [summary, ...movedLines] };
+}
+// Waited for: a write to a pipe can still be pending when the process exits,
+// and the parent reads the pipe.
+await new Promise((resolveWrite) => process.stdout.write(`\n${VERIFY_REPORT_PREFIX}${JSON.stringify(verdict)}\n`, () => resolveWrite()));
+// The app's module may hold the process open (a client's sockets, a timer),
+// and this process exists for the one comparison.
+process.exit(0);

package/dist/build/moduleLocation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The module a generator reads the instance from, as both of lambder/build's
+ * generators take it: a path relative to the working directory, or a file
+ * URL, as a URL (`new URL("../server/index.ts", import.meta.url)`) or as the
+ * string `import.meta.resolve()` answers.
+ */
+export type LambderModuleLocation = string | URL;
+/** The module as a file URL. A string that already is one is taken as one: resolved as a path, it would name a directory called "file:". */
+export declare const moduleUrlOf: (module: LambderModuleLocation) => string;
+/** The module as a path on disk. */
+export declare const modulePathOf: (module: LambderModuleLocation) => string;

package/dist/build/moduleLocation.js

@@ -0,0 +1,6 @@
+import { resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+/** The module as a file URL. A string that already is one is taken as one: resolved as a path, it would name a directory called "file:". */
+export const moduleUrlOf = (module) => typeof module === "string" && !/^file:/i.test(module) ? pathToFileURL(resolve(module)).href : new URL(module).href;
+/** The module as a path on disk. */
+export const modulePathOf = (module) => fileURLToPath(moduleUrlOf(module));

package/dist/build/writeApiContract.d.ts

@@ -0,0 +1,78 @@
+import { type LambderModuleLocation } from "./moduleLocation.js";
+export type LambderApiContractFileOptions = {
+    /** The module that exports the Lambder instance, usually the server's entry: a path relative to the working directory, or a file URL. */
+    module: LambderModuleLocation;
+    /** The export that holds the instance, whose ApiContract is written out. Default: "default", the module's default export. */
+    exportName?: string;
+    /** The name the written module exports the contract type under. Default: "ApiContractType". */
+    typeName?: string;
+    /** The tsconfig.json the module compiles under, whose compiler options and path aliases resolve its imports. Relative to the working directory. Default: the nearest tsconfig.json at or above the module's directory. */
+    tsconfig?: string;
+    /** The TypeScript module to write. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk is what the contract prints now. Default: false. */
+    check?: boolean;
+    /** The comment the file opens with, one `//` line per line. It should name what generates the file. Default: a note naming writeApiContract(). */
+    header?: string;
+    /** Quotes in the generated module. Default: "double". */
+    quotes?: "single" | "double";
+    /** End the generated declarations and members with semicolons. Default: true. */
+    semicolons?: boolean;
+};
+export type LambderApiContractFileResult = {
+    /** False when the contract could not be read or printed, a check found the file stale, or the printed type was not the contract's. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** How many APIs the contract holds (0 when it could not be read). */
+    count: number;
+    /** True when the file was (re)written; a file that already holds this text is left untouched. */
+    written: boolean;
+    /** APIs whose printed types differ from the file that was on disk, by name, counting the declarations each refers to. */
+    changed: string[];
+    added: string[];
+    removed: string[];
+    /** What happened, as lines to print: a summary, then one line per API that moved or per member that could not be printed. */
+    lines: string[];
+};
+/**
+ * Writes an app's API contract type to a TypeScript module as plain types,
+ * or checks the one on disk, and names the APIs whose types moved.
+ *
+ * The contract is the ApiContract property of the instance the module
+ * exports, read through the TypeScript compiler under the server's own
+ * tsconfig; nothing of the server runs. Every type in it is printed as the
+ * structure it resolves to: zod's inferences, mapped and conditional types and
+ * the server's own types become plain object types, unions and literals. The
+ * written module imports nothing, not even lambder, and exports one type
+ * alias, `typeName`. Only the default library's interfaces (Date) are printed
+ * by name. A non-generic named type is printed once, as a declaration of its
+ * own that the entries refer to.
+ *
+ * Anything with no plain form fails the call and names where it sits: a
+ * function, a symbol-keyed property, an enum, a class's private member, or a
+ * type parameter the contract leaves open. Property `readonly` modifiers are
+ * not carried over (they never decide assignability); readonly arrays and
+ * tuples are.
+ *
+ * ```ts
+ * import { writeApiContract } from "lambder/build";
+ *
+ * const result = await writeApiContract({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiContract.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * A check compares the text, so the file should be left out of formatters;
+ * each declaration carries a `// prettier-ignore` line for Prettier. A write
+ * that changes the file first compiles the new text beside the server's
+ * sources and checks every entry against the contract both ways, and writes
+ * nothing when one differs. The file is written to a temporary file renamed
+ * over the old one, so a build reading it meanwhile never sees half of it.
+ */
+export declare const writeApiContract: (options: LambderApiContractFileOptions) => Promise<LambderApiContractFileResult>;