lambder 7.3.1 → 8.1.1

package/dist/build/writeApiContract.js

@@ -0,0 +1,302 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { ContractTypePrinter } from "./ContractTypePrinter.js";
+import { modulePathOf } from "./moduleLocation.js";
+import { writeFileAtomically } from "./writeFileAtomically.js";
+const DEFAULT_HEADER = [
+    "Generated by writeApiContract() from lambder/build. Do not edit.",
+    "",
+    "The server's API contract written out as plain types, so a client compiles",
+    "the contract without compiling the server's schemas and code.",
+].join("\n");
+const INDENT = "    ";
+/** How many compiler diagnostics a failure prints before it stops. */
+const DIAGNOSTIC_LIMIT = 20;
+/**
+ * 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 const writeApiContract = async (options) => {
+    const ts = await loadTypeScript();
+    const file = resolve(options.file);
+    const modulePath = modulePathOf(options.module);
+    const exportName = options.exportName ?? "default";
+    const typeName = options.typeName ?? "ApiContractType";
+    const style = { quote: options.quotes === "single" ? "'" : "\"", semicolon: options.semicolons === false ? "" : ";" };
+    let count = 0;
+    const result = (ok, written, lines, moved) => ({ ok, file, count, written, changed: moved?.changed ?? [], added: moved?.added ?? [], removed: moved?.removed ?? [], lines });
+    const project = readProject(ts, options.tsconfig, modulePath);
+    if ("failure" in project)
+        return result(false, false, [`✗ ${options.module}: ${project.failure}`, ...(project.details ?? [])]);
+    // The program is used for the printing alone, and dropped before the
+    // verification builds its own: only the parsed files carry over.
+    const printing = printContractFile(ts, project, modulePath, exportName, typeName, style, options.header);
+    if ("failure" in printing)
+        return result(false, false, [`✗ ${options.module}: ${printing.failure}`, ...(printing.details ?? [])]);
+    count = printing.count;
+    const { text, parsedFiles } = printing;
+    const previous = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const moved = describeContractChanges(ts, typeName, previous, text);
+    const unchanged = previous !== null && previous.replace(/\r\n/g, "\n") === text;
+    const movedSummary = moved.lines.length ? [`  ${moved.summary}`, ...moved.lines] : [];
+    if (options.check) {
+        if (unchanged)
+            return result(true, false, [`✓ ${options.file} matches the ${count} APIs of ${typeName}`], moved);
+        return result(false, false, [`✗ ${options.file} is stale: regenerate it`, ...(movedSummary.length ? movedSummary : ["  no API's types changed; the header or layout did"])], moved);
+    }
+    if (unchanged)
+        return result(true, false, [`✓ ${options.file} is up to date (${count} APIs)`], moved);
+    const mismatches = verifyPrintedContract(ts, project, parsedFiles, { modulePath, exportName }, { file, text, typeName });
+    if (mismatches.length)
+        return result(false, false, [`✗ the printed ${typeName} is not the contract of ${exportName} in ${options.module}, so ${options.file} was not written:`, ...mismatches.map((line) => `  ${line}`)], moved);
+    writeFileAtomically(file, text, previous !== null);
+    return result(true, true, [`✓ Wrote ${options.file} (${count} APIs)`, ...(movedSummary.length ? movedSummary : ["  no API's types changed; the header or layout did"])], moved);
+};
+/** The compiler API writeApiContract reads with. TypeScript 7 ships none, so its package answers the import without one. */
+const loadTypeScript = async () => {
+    const requirement = "writeApiContract reads the contract through the TypeScript compiler API (typescript 5.4 to 6.x): install one beside lambder, such as in the generator's own package when the app is on TypeScript 7";
+    let ts;
+    try {
+        ts = (await import("typescript")).default;
+    }
+    catch (err) {
+        throw new Error(requirement, { cause: err });
+    }
+    if (typeof ts?.createProgram !== "function")
+        throw new Error(`${requirement}; the typescript installed (${ts?.version ?? "unknown"}) has no compiler API`);
+    return ts;
+};
+/** The server's compiler options, and the root files a program over the module needs: the module, and the project's own declaration files, which may declare globals the module relies on. */
+const readProject = (ts, tsconfig, modulePath) => {
+    const configPath = tsconfig ? resolve(tsconfig) : ts.findConfigFile(dirname(modulePath), ts.sys.fileExists);
+    if (!configPath)
+        return { failure: "no tsconfig.json in its directory or above it; name the server's in tsconfig" };
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error)
+        return { failure: `${configPath} could not be read`, details: formatDiagnostics(ts, [read.error]) };
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(configPath), undefined, configPath);
+    if (parsed.errors.length)
+        return { failure: `${configPath} has errors`, details: formatDiagnostics(ts, parsed.errors) };
+    return {
+        // Nothing is emitted, and a composite project's rule that every file be
+        // listed in it does not hold for a program rooted at one module.
+        options: { ...parsed.options, noEmit: true, composite: false, incremental: false, declaration: false },
+        rootNames: [modulePath, ...parsed.fileNames.filter((fileName) => fileName.endsWith(".d.ts"))],
+    };
+};
+/** An export of a module, followed through a re-export or an `export default` of a name. */
+const readExport = (ts, program, checker, modulePath, exportName) => {
+    const sourceFile = program.getSourceFile(modulePath);
+    if (!sourceFile)
+        return { failure: "the module was not found" };
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    const exported = moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.name === exportName);
+    if (!exported)
+        return { failure: `the module has no export named "${exportName}"` };
+    return exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+};
+/** The ApiContract of the instance a module exports, from a module that compiles. */
+const readInstanceContract = (ts, program, checker, modulePath, exportName) => {
+    const sourceFile = program.getSourceFile(modulePath);
+    if (!sourceFile)
+        return { failure: "the module was not found" };
+    // A module with errors can infer `any` where the contract meant a type,
+    // and `any` prints and verifies as itself.
+    const diagnostics = [...program.getSyntacticDiagnostics(sourceFile), ...program.getSemanticDiagnostics(sourceFile)];
+    if (diagnostics.length)
+        return { failure: "the module does not compile", details: formatDiagnostics(ts, diagnostics) };
+    const instance = readExport(ts, program, checker, modulePath, exportName);
+    if ("failure" in instance)
+        return { failure: `${instance.failure}; name the export that holds the Lambder instance in exportName` };
+    const contract = checker.getPropertyOfType(checker.getTypeOfSymbol(instance), "ApiContract");
+    if (!contract)
+        return { failure: `"${exportName}" is not a Lambder instance: it has no ApiContract` };
+    return checker.getTypeOfSymbol(contract);
+};
+/** The contract type a printed module exports. */
+const readPrintedContract = (ts, program, checker, file, typeName) => {
+    const exported = readExport(ts, program, checker, file, typeName);
+    if ("failure" in exported)
+        return exported;
+    if (!(exported.flags & ts.SymbolFlags.Type))
+        return { failure: `${typeName} is not a type` };
+    return checker.getDeclaredTypeOfSymbol(exported);
+};
+const printContractFile = (ts, project, modulePath, exportName, typeName, style, header) => {
+    const program = ts.createProgram({ rootNames: project.rootNames, options: project.options });
+    const checker = program.getTypeChecker();
+    const contract = readInstanceContract(ts, program, checker, modulePath, exportName);
+    if ("failure" in contract)
+        return contract;
+    const printer = new ContractTypePrinter(ts, program, checker, style, typeName);
+    const printed = printer.printContract(contract);
+    if (printed.failures.length) {
+        return { failure: `${typeName} holds types with no plain form, which only the server's sources could name:`, details: printed.failures.map((line) => `  ${line}`) };
+    }
+    return {
+        text: renderContractFile(printer, printed, typeName, style, header),
+        count: printed.entries.length,
+        parsedFiles: new Map(program.getSourceFiles().map((sourceFile) => [sourceFile.fileName, sourceFile])),
+    };
+};
+const renderContractFile = (printer, printed, typeName, style, header = DEFAULT_HEADER) => {
+    const indented = (text) => INDENT + text.replace(/\n/g, `\n${INDENT}`);
+    const entries = printed.entries.map(({ name, text }) => indented(printer.labeledValue(`${printer.keyOf(name)}:`, text)) + style.semicolon);
+    return [
+        ...header.split("\n").map((line) => line ? `// ${line}` : "//"),
+        "",
+        // Kept as written by a formatter that honours it: a check compares
+        // the text.
+        "// prettier-ignore",
+        entries.length ? [`export type ${typeName} = {`, ...entries, `}${style.semicolon}`].join("\n") : `export type ${typeName} = {}${style.semicolon}`,
+        ...printed.declarations.flatMap(({ name, text }) => ["", "// prettier-ignore", printer.labeledValue(`type ${name} =`, text) + style.semicolon]),
+        "",
+    ].join("\n");
+};
+/**
+ * Compiles the printed text beside the server's sources, from the files the
+ * printing parsed, and checks each entry against the contract's in both
+ * directions. Answers the entries that differ, or the diagnostics of a text
+ * that does not compile; nothing when the two are the same type.
+ */
+const verifyPrintedContract = (ts, project, parsedFiles, { modulePath, exportName }, { file, text, typeName }) => {
+    const canonical = (fileName) => {
+        const slashed = fileName.replace(/\\/g, "/");
+        return ts.sys.useCaseSensitiveFileNames ? slashed : slashed.toLowerCase();
+    };
+    const printedFile = canonical(file);
+    const isPrinted = (fileName) => canonical(fileName) === printedFile;
+    const host = ts.createCompilerHost(project.options, true);
+    const { getSourceFile, fileExists, readFile } = host;
+    host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => isPrinted(fileName)
+        ? ts.createSourceFile(fileName, text, languageVersion, true)
+        : parsedFiles.get(fileName) ?? getSourceFile.call(host, fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    host.fileExists = (fileName) => isPrinted(fileName) || fileExists.call(host, fileName);
+    host.readFile = (fileName) => isPrinted(fileName) ? text : readFile.call(host, fileName);
+    const program = ts.createProgram({ rootNames: [...project.rootNames, file], options: project.options, host });
+    const printedSource = program.getSourceFile(file);
+    const diagnostics = [...program.getSyntacticDiagnostics(printedSource), ...program.getSemanticDiagnostics(printedSource)];
+    if (diagnostics.length)
+        return ["the printed text does not compile:", ...formatDiagnostics(ts, diagnostics)];
+    const checker = program.getTypeChecker();
+    const contract = readInstanceContract(ts, program, checker, modulePath, exportName);
+    const reprinted = readPrintedContract(ts, program, checker, file, typeName);
+    if ("failure" in contract)
+        return [contract.failure];
+    if ("failure" in reprinted)
+        return [`the printed text: ${reprinted.failure}`];
+    const mismatches = [];
+    for (const entry of checker.getPropertiesOfType(contract)) {
+        const counterpart = checker.getPropertyOfType(reprinted, entry.name);
+        if (!counterpart) {
+            mismatches.push(`${entry.name}: missing from the printed type`);
+            continue;
+        }
+        const original = checker.getTypeOfSymbol(entry);
+        const copy = checker.getTypeOfSymbol(counterpart);
+        if (!checker.isTypeAssignableTo(original, copy))
+            mismatches.push(`${entry.name}: the contract's type is not assignable to the printed one`);
+        if (!checker.isTypeAssignableTo(copy, original))
+            mismatches.push(`${entry.name}: the printed type is not assignable to the contract's`);
+    }
+    for (const entry of checker.getPropertiesOfType(reprinted)) {
+        if (!checker.getPropertyOfType(contract, entry.name))
+            mismatches.push(`${entry.name}: in the printed type, not in the contract`);
+    }
+    return mismatches;
+};
+/**
+ * Which entries a file's text and the new text print differently, counting
+ * the declarations each entry refers to, directly or through another one: a
+ * change to a shared named type moves every entry that uses it.
+ */
+const describeContractChanges = (ts, typeName, previous, text) => {
+    const before = previous === null ? new Map() : entryClosures(ts, typeName, previous);
+    const after = entryClosures(ts, typeName, text);
+    const changed = [...after.keys()].filter((name) => before.has(name) && before.get(name) !== after.get(name));
+    const added = [...after.keys()].filter((name) => !before.has(name));
+    const removed = [...before.keys()].filter((name) => !after.has(name));
+    return {
+        changed, added, removed,
+        lines: [...changed.map((name) => `  ~ ${name}`), ...added.map((name) => `  + ${name}`), ...removed.map((name) => `  - ${name}`)],
+        summary: `${changed.length} changed, ${added.length} added, ${removed.length} removed (${after.size - changed.length - added.length} unchanged)`,
+    };
+};
+/** Each entry of the contract type in a printed module, as its own text followed by every declaration it reaches. Empty when the text holds no such type. */
+const entryClosures = (ts, typeName, text) => {
+    const sourceFile = ts.createSourceFile("contract.ts", text, ts.ScriptTarget.Latest, true);
+    const declared = new Map();
+    let contract;
+    for (const statement of sourceFile.statements) {
+        if (!ts.isTypeAliasDeclaration(statement))
+            continue;
+        if (statement.name.text === typeName && ts.isTypeLiteralNode(statement.type))
+            contract = statement.type;
+        else
+            declared.set(statement.name.text, statement.type);
+    }
+    const closures = new Map();
+    for (const member of contract?.members ?? []) {
+        if (!ts.isPropertySignature(member) || !member.type || !(ts.isIdentifier(member.name) || ts.isStringLiteral(member.name)))
+            continue;
+        const reached = new Set();
+        const visit = (node) => {
+            if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+                const name = node.typeName.text;
+                const body = declared.get(name);
+                if (body && !reached.has(name)) {
+                    reached.add(name);
+                    visit(body);
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(member.type);
+        closures.set(member.name.text, [member.type.getText(sourceFile), ...[...reached].sort().map((name) => `type ${name} = ${declared.get(name).getText(sourceFile)}`)].join("\n"));
+    }
+    return closures;
+};
+const formatDiagnostics = (ts, diagnostics) => {
+    const shown = ts.formatDiagnostics(diagnostics.slice(0, DIAGNOSTIC_LIMIT), {
+        getCanonicalFileName: (fileName) => fileName,
+        getCurrentDirectory: () => process.cwd(),
+        getNewLine: () => "\n",
+    }).trim().split("\n").map((line) => `  ${line}`);
+    return diagnostics.length > DIAGNOSTIC_LIMIT ? [...shown, `  ... and ${diagnostics.length - DIAGNOSTIC_LIMIT} more`] : shown;
+};

package/dist/build/writeApiSignatures.d.ts

@@ -0,0 +1,114 @@
+import type { LambderApiSignatureEntry } from "../api/LambderApiSignature.js";
+import { type LambderModuleLocation } from "./moduleLocation.js";
+/**
+ * How the fresh process reports its comparison: one line on stdout starting
+ * with this, then the verdict as JSON. The line, not the exit status, is the
+ * answer: the app's module prints what it likes while it loads, and a
+ * process that fails before the line never compared anything.
+ */
+export declare const VERIFY_REPORT_PREFIX = "lambder-api-signatures-verified:";
+/** This process's execArgv, less the flags only it may run with (see PARENT_ONLY_FLAG). */
+export declare const freshProcessNodeFlags: (execArgv: readonly string[]) => string[];
+/** What writeApiSignatures reads the signatures from: a Lambder instance, or anything else that lists them the same way. */
+export type LambderApiSignatureSource = {
+    apiSignatureEntries(): Promise<LambderApiSignatureEntry[]>;
+};
+export type LambderApiSignatureFileOptions = {
+    /**
+     * The module that exports the instance, usually the server's entry: a
+     * path relative to the working directory, or a file URL. It is imported
+     * in this process, so a TypeScript module needs the process's loader
+     * (`tsx`, `node --import tsx`), as the generator script itself does.
+     */
+    module: LambderModuleLocation;
+    /** The export that holds the instance. Default: "default", the module's default export. */
+    exportName?: string;
+    /** The TypeScript module to write, exporting `apiSignatures`. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk is what the registrations produce 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 writeApiSignatures(). */
+    header?: string;
+    /** Quotes in the generated module. Default: "double". */
+    quotes?: "single" | "double";
+    /** End the generated statements with semicolons. Default: true. */
+    semicolons?: boolean;
+    /**
+     * After writing, or after a check that found the file current, load the
+     * module again in a fresh Node process and check the file against what
+     * it digests there. A schema built from the clock or a random source
+     * digests differently in every process; this catches it by endpoint name
+     * instead of letting signatures change on every build. Only the module is
+     * loaded there, never the calling script, so nothing the script does runs
+     * twice; the module's own top-level code does run again. The fresh
+     * process gets this process's Node flags (`--import`, `--require`,
+     * `--loader`, `--conditions`) less the inspector, watch mode, the test
+     * runner and the eval flags (`-e`, `-p`, `--input-type`), so a TypeScript
+     * module loads there as it did here when its loader is on the command
+     * line or in NODE_OPTIONS. Default: true.
+     */
+    verifyInFreshProcess?: boolean;
+};
+export type LambderApiSignatureFileResult = {
+    /** False when a check found the file stale, or a fresh process digested different signatures or never compared them. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** How many APIs the file holds. */
+    count: number;
+    /** True when the file was (re)written; a file that already holds these signatures is left untouched, however it is formatted. */
+    written: boolean;
+    /** Endpoints whose signature differs from the file that was on disk, by name. */
+    changed: string[];
+    added: string[];
+    /** Endpoints the file held and the registrations no longer have. Named by key only: a key is a one-way hash of a name that is gone. */
+    removedKeys: string[];
+    /** What happened, as lines to print: a summary, then one line per endpoint that moved. */
+    lines: string[];
+};
+/**
+ * The map a generated file holds, read back by its hex pairs. Either quote
+ * style parses, and so does a key without quotes: a formatter that quotes
+ * properties only as needed (Prettier's default, Biome's, ESLint's
+ * quote-props) unquotes every key that starts with a letter.
+ */
+export declare const readSignatureMap: (contents: string) => Record<string, string>;
+/** How the registrations differ from a map read off a file, by endpoint, as the lines both this process and a fresh one print. */
+export declare const describeSignatureChanges: (entries: LambderApiSignatureEntry[], previousMap: Record<string, string>) => {
+    changed: string[];
+    added: string[];
+    removedKeys: string[];
+    movedLines: string[];
+    summary: string;
+};
+/**
+ * Writes the signature map both sides ship (see Lambder.apiSignatures()) to
+ * a TypeScript module, or checks the one on disk, and says which endpoints
+ * moved: every changed signature is a forced reload for the tabs calling
+ * that endpoint, so this is the line that says how wide a deploy's reload
+ * will be.
+ *
+ * Call it from a generator script, naming the module that exports the app's
+ * instance, as writeApiContract takes it:
+ *
+ * ```ts
+ * import { writeApiSignatures } from "lambder/build";
+ *
+ * const result = await writeApiSignatures({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiSignatures.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * Signatures are compared as the map the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it or unquoted
+ * its keys is neither stale nor rewritten. The file, written or found
+ * current, is then checked again against the module loaded in a fresh
+ * process (see `verifyInFreshProcess`). A module that does not load, or an
+ * export that is not an instance, throws.
+ */
+export declare const writeApiSignatures: (options: LambderApiSignatureFileOptions) => Promise<LambderApiSignatureFileResult>;

package/dist/build/writeApiSignatures.js

@@ -0,0 +1,217 @@
+import { spawnSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { moduleUrlOf } from "./moduleLocation.js";
+import { writeFileAtomically } from "./writeFileAtomically.js";
+/*
+ * The signature file every app with apiSignatures needs, written and checked
+ * by the framework that defines it.
+ *
+ * The digests are computed once, by the generator, into this file, and both
+ * sides read the file: the frontend hands it to LambderCaller and the server
+ * hands it to create(), so the two can never disagree. What can still go wrong is the file itself (stale against the
+ * registrations, or different in every process because a schema reads the
+ * clock), and both are checked here.
+ */
+/**
+ * How the fresh process reports its comparison: one line on stdout starting
+ * with this, then the verdict as JSON. The line, not the exit status, is the
+ * answer: the app's module prints what it likes while it loads, and a
+ * process that fails before the line never compared anything.
+ */
+export const VERIFY_REPORT_PREFIX = "lambder-api-signatures-verified:";
+/** How long a fresh-process verification may run before it counts as failed. */
+const VERIFY_TIMEOUT_MS = 5 * 60 * 1000;
+/** What a fresh process may print before its verdict line: a chatty module must not fill the pipe and fail the check. */
+const VERIFY_OUTPUT_BYTES = 64 * 1024 * 1024;
+/** The fresh process's entry, beside this module in the build. */
+const FRESH_PROCESS_ENTRY = new URL("./freshProcessVerifier.js", import.meta.url);
+/**
+ * This process's own Node flags that the fresh process must not inherit,
+ * because they make it something other than a plain run of the verifier: the
+ * inspector (`--inspect-brk` waits for a debugger forever, and a fixed port
+ * collides with this process's), watch mode (a watched process never exits),
+ * the test runner (`--test` runs the entry as a test file), and the eval
+ * flags: `-e`, `-p` and a cluster of them such as `-pe` (which run their code
+ * in place of the entry), and `--input-type` (which Node refuses beside an
+ * entry file). Everything else, `--import`, `--require`, `--loader`,
+ * `--conditions` and the rest, is how this process loads the app's modules,
+ * and the fresh one needs it to load the same way.
+ */
+const PARENT_ONLY_FLAG = /^(--(inspect|debug-port|watch|test)([-=].*)?|--(eval|print|input-type)(=.*)?|-[a-z]*[ep][a-z]*)$/;
+/** This process's execArgv, less the flags only it may run with (see PARENT_ONLY_FLAG). */
+export const freshProcessNodeFlags = (execArgv) => {
+    const kept = [];
+    for (let index = 0; index < execArgv.length; index++) {
+        const flag = execArgv[index];
+        if (!PARENT_ONLY_FLAG.test(flag)) {
+            kept.push(flag);
+            continue;
+        }
+        // execArgv holds only Node's own options (the script and its
+        // arguments are argv), so an element that is not a flag is the value
+        // of the flag before it, and goes with it.
+        const next = execArgv[index + 1];
+        if (!flag.includes("=") && next !== undefined && !next.startsWith("-"))
+            index++;
+    }
+    return kept;
+};
+const DEFAULT_HEADER = [
+    "Generated by writeApiSignatures() from lambder/build. Do not edit.",
+    "",
+    "Every API the server registers, keyed by the hash of its name, with the",
+    "digest of its client-facing shape. The client sends the value with every",
+    "call and the server compares it with its own copy of this file, so a",
+    "deploy reloads only the tabs that call an endpoint whose shape changed.",
+].join("\n");
+/**
+ * The map a generated file holds, read back by its hex pairs. Either quote
+ * style parses, and so does a key without quotes: a formatter that quotes
+ * properties only as needed (Prettier's default, Biome's, ESLint's
+ * quote-props) unquotes every key that starts with a letter.
+ */
+export const readSignatureMap = (contents) => {
+    const map = {};
+    for (const match of contents.matchAll(/(?<![\w$])(['"]?)([0-9a-f]+)\1\s*:\s*['"]([0-9a-f]+)['"]/g))
+        map[match[2]] = match[3];
+    return map;
+};
+/** How the registrations differ from a map read off a file, by endpoint, as the lines both this process and a fresh one print. */
+export const describeSignatureChanges = (entries, previousMap) => {
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    const changed = entries.filter(({ key, signature }) => key in previousMap && previousMap[key] !== signature).sort(byName).map(({ name }) => name);
+    const added = entries.filter(({ key }) => !(key in previousMap)).sort(byName).map(({ name }) => name);
+    const keys = new Set(entries.map(({ key }) => key));
+    const removedKeys = Object.keys(previousMap).filter((key) => !keys.has(key));
+    const movedLines = [
+        ...changed.map((name) => `  ~ ${name}`),
+        ...added.map((name) => `  + ${name}`),
+        ...removedKeys.map((key) => `  - ${key} (removed: a key cannot be resolved back to its name)`),
+    ];
+    const summary = `${changed.length} changed, ${added.length} added, ${removedKeys.length} removed (${entries.length - changed.length - added.length} unchanged)`;
+    return { changed, added, removedKeys, movedLines, summary };
+};
+const renderSignatureFile = (entries, options) => {
+    const quote = options.quotes === "single" ? "'" : "\"";
+    const semicolon = options.semicolons === false ? "" : ";";
+    const header = (options.header ?? DEFAULT_HEADER).split("\n").map((line) => line ? `// ${line}` : "//");
+    // Keys and signatures are hex, so swapping the quote character touches nothing inside them.
+    const map = JSON.stringify(Object.fromEntries(entries.map(({ key, signature }) => [key, signature])), null, 4).replace(/"/g, quote);
+    return [
+        ...header,
+        `import type { LambderApiSignatureMap } from ${quote}lambder/client${quote}${semicolon}`,
+        "",
+        // Kept as written by a formatter that honours it, so a format pass
+        // after every generation has nothing to change. One that does not
+        // honour it changes the text only: the map reads back the same.
+        "// prettier-ignore",
+        `export const apiSignatures: LambderApiSignatureMap = ${map}${semicolon}`,
+        "",
+    ].join("\n");
+};
+/**
+ * Writes the signature map both sides ship (see Lambder.apiSignatures()) to
+ * a TypeScript module, or checks the one on disk, and says which endpoints
+ * moved: every changed signature is a forced reload for the tabs calling
+ * that endpoint, so this is the line that says how wide a deploy's reload
+ * will be.
+ *
+ * Call it from a generator script, naming the module that exports the app's
+ * instance, as writeApiContract takes it:
+ *
+ * ```ts
+ * import { writeApiSignatures } from "lambder/build";
+ *
+ * const result = await writeApiSignatures({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiSignatures.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * Signatures are compared as the map the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it or unquoted
+ * its keys is neither stale nor rewritten. The file, written or found
+ * current, is then checked again against the module loaded in a fresh
+ * process (see `verifyInFreshProcess`). A module that does not load, or an
+ * export that is not an instance, throws.
+ */
+export const writeApiSignatures = async (options) => {
+    const file = resolve(options.file);
+    const moduleUrl = moduleUrlOf(options.module);
+    const exportName = options.exportName ?? "default";
+    let namespace;
+    try {
+        namespace = await import(moduleUrl);
+    }
+    catch (err) {
+        throw new Error(`writeApiSignatures could not load ${moduleUrl}`, { cause: err });
+    }
+    const source = namespace[exportName];
+    if (typeof source?.apiSignatureEntries !== "function") {
+        throw new Error(`${moduleUrl} has no export "${exportName}" that lists API signatures: name the export holding the instance in exportName`);
+    }
+    const entries = await source.apiSignatureEntries();
+    const previous = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const { changed, added, removedKeys, movedLines, summary } = describeSignatureChanges(entries, previous === null ? {} : readSignatureMap(previous));
+    const unchanged = previous !== null && movedLines.length === 0;
+    const result = (ok, written, lines) => ({ ok, file, count: entries.length, written, changed, added, removedKeys, lines });
+    // A stale file is the answer by itself: a fresh process could only find
+    // it stale again. A current one goes on to the verification, as a write
+    // does.
+    let written = false;
+    let lines;
+    if (options.check) {
+        if (!unchanged)
+            return result(false, false, [`✗ ${options.file} is stale: regenerate it`, `  ${summary}`, ...movedLines]);
+        lines = [`✓ ${options.file} matches the ${entries.length} registered APIs`];
+    }
+    else {
+        // A file that already holds this map is left as it is, however it is
+        // formatted, so a watcher or an incremental build sees no change
+        // where there is none, and a formatter's or a checkout's version of
+        // the file is not rewritten back on every run. A change of header,
+        // quotes or semicolons shows the next time the map changes.
+        written = !unchanged;
+        if (written)
+            writeFileAtomically(file, renderSignatureFile(entries, options), previous !== null);
+        lines = [
+            written ? `✓ Wrote ${options.file} (${entries.length} APIs)` : `✓ ${options.file} is up to date (${entries.length} APIs)`,
+            ...(movedLines.length ? [`  ${summary}`, ...movedLines] : ["  no signatures changed: this build forces no reloads"]),
+        ];
+    }
+    if (options.verifyInFreshProcess === false)
+        return result(true, written, lines);
+    const request = { moduleUrl, exportName, file };
+    const child = spawnSync(process.execPath, [...freshProcessNodeFlags(process.execArgv), fileURLToPath(FRESH_PROCESS_ENTRY), JSON.stringify(request)], {
+        encoding: "utf8",
+        timeout: VERIFY_TIMEOUT_MS,
+        maxBuffer: VERIFY_OUTPUT_BYTES,
+    });
+    const reportLine = (child.stdout ?? "").split("\n").findLast((line) => line.startsWith(VERIFY_REPORT_PREFIX));
+    if (reportLine === undefined) {
+        const stderrTail = (child.stderr ?? "").trim().split("\n").slice(-20).filter(Boolean);
+        return result(false, written, [
+            ...lines,
+            child.error
+                ? `✗ the fresh process that verifies ${options.file} could not finish: ${child.error.message}`
+                : `✗ the fresh process that verifies ${options.file} never compared it: loading ${request.moduleUrl} failed (exit status ${child.status ?? "none"})`,
+            ...stderrTail.map((line) => `  ${line}`),
+        ]);
+    }
+    const verdict = JSON.parse(reportLine.slice(VERIFY_REPORT_PREFIX.length));
+    if ("failure" in verdict)
+        return result(false, written, [...lines, `✗ the fresh process that verifies ${options.file} never compared it: ${verdict.failure}`]);
+    if (verdict.same)
+        return result(true, written, [...lines, "✓ a fresh process digests the same signatures"]);
+    return result(false, written, [
+        ...lines,
+        `✗ a fresh process digests different signatures for ${options.file}: a schema reads the clock or a random source`,
+        ...verdict.lines.map((line) => `  ${line}`),
+    ]);
+};

package/dist/build/writeFileAtomically.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Writes a generated file so that a build reading it meanwhile sees the old
+ * contents or the new, never half of either: the text goes to a file beside
+ * the target and is renamed over it. A symlink is followed to the file it
+ * names, since renamed over, the link itself would become the new file and
+ * its target would keep the old contents.
+ */
+export declare const writeFileAtomically: (file: string, contents: string, exists: boolean) => void;

package/dist/build/writeFileAtomically.js

@@ -0,0 +1,22 @@
+import { mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "fs";
+import { dirname } from "path";
+/**
+ * Writes a generated file so that a build reading it meanwhile sees the old
+ * contents or the new, never half of either: the text goes to a file beside
+ * the target and is renamed over it. A symlink is followed to the file it
+ * names, since renamed over, the link itself would become the new file and
+ * its target would keep the old contents.
+ */
+export const writeFileAtomically = (file, contents, exists) => {
+    const target = exists ? realpathSync(file) : file;
+    mkdirSync(dirname(target), { recursive: true });
+    const partial = `${target}.${process.pid}.tmp`;
+    try {
+        writeFileSync(partial, contents);
+        renameSync(partial, target);
+    }
+    catch (err) {
+        rmSync(partial, { force: true });
+        throw err;
+    }
+};