@nifrajs/cli 4.0.2 → 5.1.0

package/dist/output-schemas.js

@@ -0,0 +1,975 @@
+/**
+ * Output schemas from a route's own return types. `loaderOutput` and `actionOutput` stay the reviewed
+ * allow-list of what reaches the browser: nothing here runs at request time, and no schema is derived
+ * implicitly. `nifra schemas` reads each loader's and action's TypeScript return type, writes a
+ * schema for review where a route has none, keeps the schemas it wrote current, and names the
+ * returned fields a hand-written schema drops. `nifra check` (NF-C033) fails on a generated schema
+ * whose route has changed what it returns since.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { isSensitiveFieldName } from "@nifrajs/web/zones";
+import { codePositionMask } from "./check-scan.js";
+import { codeUnitOrder } from "./internal/code-unit-order.js";
+import { loadProjectTypeScript, } from "./internal/typescript-import.js";
+import { exported, expressionEnd } from "./rules/data-guard.js";
+const PAIRS = [
+    ["loader", "loaderOutput"],
+    ["action", "actionOutput"],
+];
+/** The comment that marks a schema `nifra schemas` wrote, with the hash of what it wrote. */
+export const GENERATED_MARK = "nifra:generated";
+const MARKER = /^[ \t]*\/\/ nifra:generated ([0-9a-f]{8})\b/;
+const FLAG_NAMES = [
+    "Any",
+    "Unknown",
+    "Never",
+    "Undefined",
+    "Void",
+    "Null",
+    "StringLiteral",
+    "NumberLiteral",
+    "BooleanLiteral",
+    "StringLike",
+    "NumberLike",
+    "BooleanLike",
+    "BigIntLike",
+    "ESSymbolLike",
+    "Union",
+    "Intersection",
+    "Object",
+    "NonPrimitive",
+];
+const flagsFrom = (read) => {
+    const at = (name) => {
+        const value = read(name);
+        return typeof value === "number" ? value : 0;
+    };
+    return {
+        Any: at("Any"),
+        Unknown: at("Unknown"),
+        Never: at("Never"),
+        Undefined: at("Undefined"),
+        Void: at("Void"),
+        Null: at("Null"),
+        StringLiteral: at("StringLiteral"),
+        NumberLiteral: at("NumberLiteral"),
+        BooleanLiteral: at("BooleanLiteral"),
+        StringLike: at("StringLike"),
+        NumberLike: at("NumberLike"),
+        BooleanLike: at("BooleanLike"),
+        BigIntLike: at("BigIntLike"),
+        ESSymbolLike: at("ESSymbolLike"),
+        Union: at("Union"),
+        Intersection: at("Intersection"),
+        Object: at("Object"),
+        NonPrimitive: at("NonPrimitive"),
+    };
+};
+const MAX_DEPTH = 12;
+const JSON_ALIASES = new Set(["JsonValue", "JSONValue", "Json"]);
+const NOT_JSON = new Set([
+    "Map",
+    "Set",
+    "WeakMap",
+    "WeakSet",
+    "RegExp",
+    "Error",
+    "Promise",
+    "URL",
+    "URLSearchParams",
+    "Headers",
+    "Request",
+    "Response",
+    "Blob",
+    "File",
+    "FormData",
+    "ArrayBuffer",
+    "SharedArrayBuffer",
+    "DataView",
+    "ReadableStream",
+    "WritableStream",
+    "Function",
+]);
+const TYPED_ARRAY = /^(?:Big)?(?:Int|Uint|Float)(?:8|16|32|64)(?:Clamped)?Array$/;
+const sameShape = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function unionOf(input) {
+    const flat = input
+        .flatMap((member) => (member.kind === "union" ? member.members : [member]))
+        .filter((member) => member.kind !== "never");
+    const json = flat.find((member) => member.kind === "json");
+    if (json !== undefined)
+        return json;
+    const isBool = (member) => member.kind === "literal" && typeof member.value === "boolean";
+    const both = flat.some((m) => m.kind === "literal" && m.value === true) &&
+        flat.some((m) => m.kind === "literal" && m.value === false);
+    const members = [];
+    for (const member of flat) {
+        const next = both && isBool(member) ? { kind: "boolean" } : member;
+        if (!members.some((seen) => sameShape(seen, next)))
+            members.push(next);
+    }
+    if (members.length === 0)
+        return { kind: "never" };
+    if (members.length === 1 && members[0] !== undefined)
+        return members[0];
+    // TypeScript versions order union members differently; a canonical order keeps the generated text,
+    // and the hash in its marker, the same under each. `null` reads best last.
+    const rank = (shape) => `${shape.kind === "null" || shape.kind === "undefined" ? 1 : 0}${JSON.stringify(shape)}`;
+    return { kind: "union", members: members.sort((a, b) => codeUnitOrder(rank(a), rank(b))) };
+}
+function withoutUndefined(shape) {
+    if (shape.kind !== "union" || !shape.members.some((member) => member.kind === "undefined"))
+        return shape;
+    return unionOf(shape.members.filter((member) => member.kind !== "undefined"));
+}
+async function shapeOf(reader, type, seen, depth) {
+    if (depth > MAX_DEPTH)
+        return { kind: "json", reason: "nested too deep to read" };
+    const f = reader.flag;
+    const flags = reader.flags(type);
+    const is = (mask) => (flags & mask) !== 0;
+    if (is(f.Any))
+        return { kind: "json", reason: "any" };
+    if (is(f.Unknown))
+        return { kind: "json", reason: "unknown" };
+    if (is(f.Never))
+        return { kind: "never" };
+    if (is(f.Undefined | f.Void))
+        return { kind: "undefined" };
+    if (is(f.Null))
+        return { kind: "null" };
+    if (is(f.StringLiteral | f.NumberLiteral | f.BooleanLiteral)) {
+        const value = await reader.literal(type);
+        if (value !== undefined)
+            return { kind: "literal", value };
+    }
+    if (is(f.StringLike))
+        return { kind: "string" };
+    if (is(f.NumberLike))
+        return { kind: "number" };
+    // `boolean` is the union `true | false` with the Boolean flag, so this precedes the union branch.
+    if (is(f.BooleanLike))
+        return { kind: "boolean" };
+    if (is(f.BigIntLike))
+        return { kind: "opaque", what: "a bigint" };
+    if (is(f.ESSymbolLike))
+        return { kind: "opaque", what: "a symbol" };
+    const alias = await reader.aliasName(type);
+    if (alias !== undefined && JSON_ALIASES.has(alias))
+        return { kind: "json" };
+    if (is(f.Union)) {
+        const members = await reader.members(type);
+        return unionOf(await Promise.all(members.map((member) => shapeOf(reader, member, seen, depth + 1))));
+    }
+    if (seen.has(type))
+        return { kind: "json", reason: "a recursive type" };
+    if (is(f.Intersection)) {
+        // A branded primitive (`string & { __brand: "Id" }`) crosses the wire as the primitive.
+        for (const part of await reader.members(type)) {
+            if ((reader.flags(part) & (f.StringLike | f.NumberLike | f.BooleanLike)) !== 0)
+                return shapeOf(reader, part, seen, depth + 1);
+        }
+    }
+    if (!is(f.Object | f.Intersection | f.NonPrimitive))
+        return { kind: "opaque", what: await reader.text(type) };
+    const tuple = await reader.tupleElements(type);
+    if (tuple !== undefined) {
+        return {
+            kind: "tuple",
+            items: await Promise.all(tuple.map((item) => shapeOf(reader, item, seen, depth + 1))),
+        };
+    }
+    const element = await reader.arrayElement(type);
+    if (element !== undefined)
+        return { kind: "array", items: await shapeOf(reader, element, seen, depth + 1) };
+    const name = await reader.symbolName(type);
+    if (name === "Date")
+        return { kind: "date" };
+    if (name !== undefined && (NOT_JSON.has(name) || TYPED_ARRAY.test(name)))
+        return { kind: "opaque", what: `a ${name}` };
+    if (await reader.callable(type))
+        return { kind: "opaque", what: "a function" };
+    seen.add(type);
+    try {
+        const properties = await reader.properties(type);
+        // A `Response`, or nifra's own response carrier (`redirect()`, `status()`): control flow, not data.
+        if (properties.some((property) => property.name === "toResponse"))
+            return { kind: "opaque", what: "a Response" };
+        const promise = properties.find((property) => property.name === "promise");
+        if (promise !== undefined && properties.some((p) => p.name === "__nifra_deferred")) {
+            const [inner] = await reader.typeArguments(promise.type);
+            return {
+                kind: "deferred",
+                value: inner === undefined
+                    ? { kind: "json", reason: "unknown" }
+                    : await shapeOf(reader, inner, seen, depth + 1),
+            };
+        }
+        const index = await reader.stringIndex(type);
+        if (index !== undefined && properties.length === 0)
+            return { kind: "record", values: await shapeOf(reader, index, seen, depth + 1) };
+        const fields = [];
+        for (const property of properties) {
+            if (property.name.startsWith("__@") || (await reader.callable(property.type)))
+                continue;
+            const shape = await shapeOf(reader, property.type, seen, depth + 1);
+            // `key?: undefined` is how TypeScript lines up a union of object literals: a key the other
+            // members have and this one never sends.
+            if (shape.kind === "undefined" || shape.kind === "never")
+                continue;
+            const defined = withoutUndefined(shape);
+            fields.push({
+                name: property.name,
+                optional: property.optional || defined !== shape,
+                shape: defined,
+            });
+        }
+        return { kind: "object", fields };
+    }
+    finally {
+        seen.delete(type);
+    }
+}
+/** What a loader's return type sends: control-flow returns (nothing, a `Response`) carry no data. */
+function dataShape(shape) {
+    const members = shape.kind === "union" ? shape.members : [shape];
+    return unionOf(members.filter((member) => member.kind !== "undefined" && !(member.kind === "opaque" && member.what === "a Response")));
+}
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const note = (text) => text.replaceAll("*/", "* /");
+/** `shape` as `t.*` source, objects one field per line below `indent`. */
+export function schemaSource(shape, indent = "") {
+    switch (shape.kind) {
+        case "string":
+        case "number":
+        case "boolean":
+        case "null":
+        case "date":
+            return `t.${shape.kind}()`;
+        case "undefined":
+        case "never":
+            return "t.null()";
+        case "json":
+            return shape.reason === undefined
+                ? "t.json()"
+                : `t.json() /* ${note(shape.reason)} in the source type */`;
+        case "opaque":
+            return `t.json() /* ${note(shape.what)}, which is not JSON */`;
+        case "literal":
+            return `t.literal(${JSON.stringify(shape.value)})`;
+        case "array":
+            return `t.array(${schemaSource(shape.items, indent)})`;
+        case "tuple":
+            return `t.array(${schemaSource(unionOf(shape.items), indent)})`;
+        case "record":
+            return `t.record(${schemaSource(shape.values, indent)})`;
+        case "deferred":
+            return `t.deferred(${schemaSource(shape.value, indent)})`;
+        case "union":
+            return `t.union([${shape.members.map((member) => schemaSource(member, indent)).join(", ")}])`;
+        case "object": {
+            if (shape.fields.length === 0)
+                return "t.object({})";
+            const inner = `${indent}  `;
+            const lines = shape.fields.map((field) => {
+                const key = IDENTIFIER.test(field.name) ? field.name : JSON.stringify(field.name);
+                if (isSensitiveFieldName(field.name))
+                    return `${inner}// left out: ${key} - a credential-like name; declare it with t.declassified("why", ...) if it must reach the browser`;
+                if (field.shape.kind === "opaque")
+                    return `${inner}// left out: ${key} - ${note(field.shape.what)}, which is not JSON`;
+                const value = schemaSource(field.shape, inner);
+                return `${inner}${key}: ${field.optional ? `t.optional(${value})` : value},`;
+            });
+            return `t.object({\n${lines.join("\n")}\n${indent}})`;
+        }
+    }
+}
+/** The paths a draft of `shape` leaves out: credential-like names, and values that are not JSON. */
+export function omittedPaths(shape, path = "") {
+    switch (shape.kind) {
+        case "array":
+            return omittedPaths(shape.items, `${path}[]`);
+        case "tuple":
+            return omittedPaths(unionOf(shape.items), `${path}[]`);
+        case "record":
+            return omittedPaths(shape.values, `${path}{}`);
+        case "deferred":
+            return omittedPaths(shape.value, path);
+        case "union":
+            return [...new Set(shape.members.flatMap((member) => omittedPaths(member, path)))];
+        case "object":
+            return shape.fields.flatMap((field) => {
+                const at = path === "" ? field.name : `${path}.${field.name}`;
+                return isSensitiveFieldName(field.name) || field.shape.kind === "opaque"
+                    ? [at]
+                    : omittedPaths(field.shape, at);
+            });
+        default:
+            return [];
+    }
+}
+/** The paths a draft of `shape` admits any value at: `any` or `unknown` there, or a type too deep or
+ * recursive to read. The output guard drops nothing below them. */
+export function openPaths(shape, path = "") {
+    switch (shape.kind) {
+        case "json":
+            return shape.reason === undefined ? [] : [path === "" ? "(the whole value)" : path];
+        case "array":
+            return openPaths(shape.items, `${path}[]`);
+        case "tuple":
+            return openPaths(unionOf(shape.items), `${path}[]`);
+        case "record":
+            return openPaths(shape.values, `${path}{}`);
+        case "deferred":
+            return openPaths(shape.value, path);
+        case "union":
+            return [...new Set(shape.members.flatMap((member) => openPaths(member, path)))];
+        case "object":
+            return shape.fields.flatMap((field) => isSensitiveFieldName(field.name) || field.shape.kind === "opaque"
+                ? []
+                : openPaths(field.shape, path === "" ? field.name : `${path}.${field.name}`));
+        default:
+            return [];
+    }
+}
+/**
+ * The paths `returned` carries that `declared` does not, as `a.b`, `items[].c`: what the output guard
+ * drops before the page renders. A declared `t.json()` or record admits everything below it.
+ */
+export function undeclaredPaths(returned, declared, path = "") {
+    if (declared.kind === "json" || declared.kind === "record")
+        return [];
+    if (returned.kind === "union") {
+        const found = returned.members.flatMap((member) => undeclaredPaths(member, declared, path));
+        return [...new Set(found)];
+    }
+    if (declared.kind === "union") {
+        const candidates = declared.members.filter((m) => m.kind !== "null" && m.kind !== "undefined");
+        if (candidates.some((m) => m.kind === "json" || m.kind === "record"))
+            return [];
+        const results = candidates.map((candidate) => undeclaredPaths(returned, candidate, path));
+        const [first, ...rest] = results;
+        return first === undefined ? [] : first.filter((p) => rest.every((r) => r.includes(p)));
+    }
+    if (returned.kind === "deferred")
+        return undeclaredPaths(returned.value, declared.kind === "deferred" ? declared.value : declared, path);
+    if (declared.kind === "deferred")
+        return undeclaredPaths(returned, declared.value, path);
+    const items = (shape) => shape.kind === "array" ? shape.items : shape.kind === "tuple" ? unionOf(shape.items) : undefined;
+    const returnedItems = items(returned);
+    const declaredItems = items(declared);
+    if (returnedItems !== undefined && declaredItems !== undefined)
+        return undeclaredPaths(returnedItems, declaredItems, `${path}[]`);
+    if (returned.kind !== "object" || declared.kind !== "object")
+        return [];
+    const found = [];
+    for (const field of returned.fields) {
+        const at = path === "" ? field.name : `${path}.${field.name}`;
+        const match = declared.fields.find((candidate) => candidate.name === field.name);
+        if (match === undefined)
+            found.push(at);
+        else
+            found.push(...undeclaredPaths(field.shape, match.shape, at));
+    }
+    return found;
+}
+const hashOf = (body) => createHash("sha256").update(body).digest("hex").slice(0, 8);
+/**
+ * A schema expression as a formatter cannot change it: comments, whitespace, a comma before a closing
+ * bracket and a trailing semicolon dropped, every string written with double quotes, and a quoted key
+ * that needs no quotes written bare. Two texts
+ * that read the same here are the same schema; an edit to what it declares is not.
+ */
+function schemaTokens(text) {
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const c = text.charAt(i);
+        if (c === "/" && text[i + 1] === "/") {
+            const end = text.indexOf("\n", i);
+            i = end === -1 ? text.length : end;
+        }
+        else if (c === "/" && text[i + 1] === "*") {
+            const end = text.indexOf("*/", i + 2);
+            i = end === -1 ? text.length : end + 2;
+        }
+        else if (c === '"' || c === "'" || c === "`") {
+            let value = "";
+            let j = i + 1;
+            while (j < text.length && text[j] !== c) {
+                if (text[j] === "\\") {
+                    const next = text[j + 1] ?? "";
+                    value += next === c ? next : `\\${next}`;
+                    j += 2;
+                }
+                else {
+                    value += text[j];
+                    j++;
+                }
+            }
+            i = j + 1;
+            let after = i;
+            while (/\s/.test(text[after] ?? ""))
+                after++;
+            // `"name": …` and `name: …` declare the same key.
+            out +=
+                text[after] === ":" && IDENTIFIER.test(value) ? value : `"${value.replaceAll('"', '\\"')}"`;
+        }
+        else {
+            if (!/\s/.test(c))
+                out += c;
+            i++;
+        }
+    }
+    return out.replace(/,(?=[}\])])/g, "").replace(/;+$/, "");
+}
+function declarationText(schema, fn, body) {
+    return [
+        `// ${GENERATED_MARK} ${hashOf(body)} - drafted from the ${fn}'s return type; review that the browser may see every field it declares. \`nifra schemas --write\` keeps it current; delete this line to edit it by hand.`,
+        `export const ${schema} = ${body}`,
+    ].join("\n");
+}
+const posix = (path) => path.replaceAll("\\", "/");
+const PROBE_HELPERS = [
+    "type __NifraReturned<M, F extends string> = M extends { readonly [K in F]: (...args: any) => infer R } ? Awaited<R> : never",
+    'type __NifraDeclared<M, N extends string> = M extends { readonly [K in N]: infer S } ? S extends { readonly "~standard": { readonly types?: infer T } } ? NonNullable<T> extends { readonly output: infer O } ? O : never : never : never',
+];
+function probeSource(routes) {
+    const lines = [...PROBE_HELPERS];
+    const names = new Map();
+    routes.forEach((route, i) => {
+        const rel = posix(route.file);
+        lines.push(`import type * as __nifra_m${i} from ${JSON.stringify(rel.startsWith(".") ? rel : `./${rel}`)}`);
+        for (const fn of route.fns) {
+            const name = `__nifra_r${i}_${fn}`;
+            names.set(name, `${route.file}#${fn}`);
+            lines.push(`declare const ${name}: __NifraReturned<typeof __nifra_m${i}, "${fn}">`);
+        }
+        for (const schema of route.schemas) {
+            const name = `__nifra_d${i}_${schema}`;
+            names.set(name, `${route.file}#${schema}`);
+            lines.push(`declare const ${name}: __NifraDeclared<typeof __nifra_m${i}, "${schema}">`);
+        }
+    });
+    return { text: `${lines.join("\n")}\n`, names };
+}
+function legacyReader(ts, checker, location) {
+    const isReference = (type) => "target" in type;
+    return {
+        flag: flagsFrom((name) => Reflect.get(ts.TypeFlags, name)),
+        flags: (type) => type.flags,
+        members: async (type) => (type.isUnionOrIntersection() ? type.types : []),
+        symbolName: async (type) => type.getSymbol()?.name,
+        aliasName: async (type) => type.aliasSymbol?.name,
+        literal: async (type) => {
+            if (type.isStringLiteral() || type.isNumberLiteral())
+                return type.value;
+            if ((type.flags & ts.TypeFlags.BooleanLiteral) !== 0)
+                return checker.typeToString(type) === "true";
+            return undefined;
+        },
+        arrayElement: async (type) => checker.isArrayType(type) && isReference(type)
+            ? checker.getTypeArguments(type)[0]
+            : undefined,
+        tupleElements: async (type) => checker.isTupleType(type) && isReference(type) ? checker.getTypeArguments(type) : undefined,
+        typeArguments: async (type) => (isReference(type) ? checker.getTypeArguments(type) : []),
+        properties: async (type) => checker.getPropertiesOfType(type).map((property) => ({
+            name: property.name,
+            optional: (property.flags & ts.SymbolFlags.Optional) !== 0,
+            type: checker.getTypeOfSymbolAtLocation(property, location),
+        })),
+        stringIndex: async (type) => checker
+            .getIndexInfosOfType(type)
+            .find((info) => (info.keyType.flags & ts.TypeFlags.StringLike) !== 0)?.type,
+        callable: async (type) => checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0,
+        text: async (type) => checker.typeToString(type),
+    };
+}
+const CHECKER7_METHODS = [
+    "getTypeAtPosition",
+    "getTypeOfSymbol",
+    "getPropertiesOfType",
+    "getIndexInfosOfType",
+    "getSignaturesOfType",
+    "getTypeArguments",
+    "typeToString",
+    "isTupleType",
+    "isArrayType",
+];
+function isChecker7(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        CHECKER7_METHODS.every((method) => typeof Reflect.get(value, method) === "function"));
+}
+function reader7(semantic, checker) {
+    const flag = flagsFrom((name) => semantic.typeFlags[name]);
+    const optional = semantic.symbolFlags.Optional;
+    const call = semantic.signatureKind.Call;
+    return {
+        flag,
+        flags: (type) => type.flags,
+        members: async (type) => (await type.getTypes?.()) ?? [],
+        symbolName: async (type) => (await type.getSymbol())?.name,
+        aliasName: async (type) => (await type.getAliasSymbol?.())?.name,
+        literal: async (type) => {
+            if ((type.flags & flag.BooleanLiteral) !== 0)
+                return (await checker.typeToString(type)) === "true";
+            return typeof type.value === "string" || typeof type.value === "number"
+                ? type.value
+                : undefined;
+        },
+        arrayElement: async (type) => (await checker.isArrayType(type)) ? (await checker.getTypeArguments(type))[0] : undefined,
+        tupleElements: async (type) => (await checker.isTupleType(type)) ? checker.getTypeArguments(type) : undefined,
+        typeArguments: async (type) => {
+            try {
+                return await checker.getTypeArguments(type);
+            }
+            catch {
+                return [];
+            }
+        },
+        properties: async (type) => {
+            const out = [];
+            for (const property of await checker.getPropertiesOfType(type)) {
+                const propertyType = await checker.getTypeOfSymbol(property);
+                if (propertyType === undefined)
+                    continue;
+                out.push({
+                    name: property.name,
+                    optional: typeof optional === "number" && (property.flags & optional) !== 0,
+                    type: propertyType,
+                });
+            }
+            return out;
+        },
+        stringIndex: async (type) => (await checker.getIndexInfosOfType(type)).find((info) => (info.keyType.flags & flag.StringLike) !== 0)?.valueType,
+        callable: async (type) => typeof call === "number" && (await checker.getSignaturesOfType(type, call)).length > 0,
+        text: (type) => checker.typeToString(type),
+    };
+}
+/** Read every listed route function's return type and schema's output type through one program. */
+async function readShapes(root, routes, sources) {
+    const warnings = [];
+    const shapes = new Map();
+    if (routes.length === 0)
+        return { shapes, warnings };
+    // TypeScript 7 resolves node handles only inside a configured project's root, so the probe and a
+    // short-lived config extending the app's sit at the root, and are removed afterwards.
+    const temp = await mkdtemp(join(root, ".nifra-schemas-"));
+    const tempName = basename(temp);
+    const probePath = join(root, `.${tempName}.ts`);
+    const probeConfigPath = join(root, `.${tempName}.tsconfig.json`);
+    const { text: probe, names } = probeSource(routes);
+    const routeFiles = routes.map((route) => join(root, route.file));
+    let close;
+    try {
+        await writeFile(probePath, probe, "utf8");
+        const include = [...routes.map((route) => posix(route.file)), basename(probePath)];
+        await writeFile(probeConfigPath, JSON.stringify(existsSync(join(root, "tsconfig.json"))
+            ? {
+                extends: "./tsconfig.json",
+                compilerOptions: { allowImportingTsExtensions: true, noEmit: true },
+                include,
+            }
+            : {
+                compilerOptions: {
+                    module: "ESNext",
+                    moduleResolution: "Bundler",
+                    target: "ESNext",
+                    strict: true,
+                    allowImportingTsExtensions: true,
+                    noEmit: true,
+                    skipLibCheck: true,
+                },
+                include,
+            }), "utf8");
+        // The routes and every planned file the caller supplies are read from `sources`, not the disk:
+        // a migration plans against the layout it has not written yet.
+        const contents = new Map([[probePath, probe]]);
+        for (const [file, text] of sources)
+            contents.set(join(root, file), text);
+        for (const file of routeFiles)
+            if (!contents.has(file))
+                contents.set(file, readFileSync(file, "utf8"));
+        const loaded = await loadProjectTypeScript(root, undefined, {
+            files: [...contents.keys()],
+            read: (file) => contents.get(file),
+            projectConfig: probeConfigPath,
+        });
+        close = loaded.session?.close;
+        if (loaded.unsupported !== undefined) {
+            warnings.push(`TypeScript ${loaded.unsupported.version} is outside the supported API`);
+            return { shapes, warnings };
+        }
+        const ts = loaded.compiler;
+        if (ts === undefined) {
+            warnings.push("TypeScript is not installed, so return types could not be read");
+            return { shapes, warnings };
+        }
+        const semantic = loaded.session?.semantic;
+        if (semantic !== undefined) {
+            const checker = (await semantic.getCheckerForFile(probePath)) ?? semantic.checker;
+            if (!isChecker7(checker)) {
+                warnings.push("the TypeScript 7 checker lacks the calls this needs");
+                return { shapes, warnings };
+            }
+            const reader = reader7(semantic, checker);
+            for (const [name, key] of names) {
+                const at = probe.indexOf(`declare const ${name}:`) + "declare const ".length;
+                const type = await checker.getTypeAtPosition(probePath, at);
+                if (type !== undefined)
+                    shapes.set(key, await shapeOf(reader, type, new Set(), 0));
+            }
+            return { shapes, warnings };
+        }
+        const parsed = ts.getParsedCommandLineOfConfigFile(probeConfigPath, {}, {
+            ...ts.sys,
+            onUnRecoverableConfigFileDiagnostic: () => { },
+        });
+        const options = {
+            ...(parsed?.options ?? {}),
+            noEmit: true,
+            skipLibCheck: true,
+            allowImportingTsExtensions: true,
+        };
+        const program = ts.createProgram([probePath], options, overlaidHost(ts, options, contents));
+        const source = program.getSourceFile(probePath);
+        if (source === undefined) {
+            warnings.push("could not create the type probe");
+            return { shapes, warnings };
+        }
+        const checker = program.getTypeChecker();
+        const reader = legacyReader(ts, checker, source);
+        for (const statement of source.statements) {
+            if (!ts.isVariableStatement(statement))
+                continue;
+            for (const declaration of statement.declarationList.declarations) {
+                if (!ts.isIdentifier(declaration.name))
+                    continue;
+                const key = names.get(declaration.name.text);
+                if (key === undefined)
+                    continue;
+                const type = checker.getTypeAtLocation(declaration.name);
+                shapes.set(key, await shapeOf(reader, type, new Set(), 0));
+            }
+        }
+        return { shapes, warnings };
+    }
+    finally {
+        await close?.();
+        await rm(probePath, { force: true });
+        await rm(probeConfigPath, { force: true });
+        await rm(temp, { recursive: true, force: true });
+    }
+}
+/** A compiler host that reads `contents` (absolute path -> text) before the disk. */
+function overlaidHost(ts, options, contents) {
+    const host = ts.createCompilerHost(options, true);
+    const key = (file) => posix(ts.sys.resolvePath(file));
+    const overlay = new Map([...contents].map(([file, text]) => [key(file), text]));
+    const folders = new Set();
+    for (const file of overlay.keys())
+        for (let at = file.lastIndexOf("/"); at > 0; at = file.lastIndexOf("/", at - 1))
+            folders.add(file.slice(0, at));
+    const { fileExists, readFile, getSourceFile, directoryExists } = host;
+    return Object.assign(host, {
+        fileExists: (file) => overlay.has(key(file)) || fileExists.call(host, file),
+        readFile: (file) => overlay.get(key(file)) ?? readFile.call(host, file),
+        directoryExists: (folder) => folders.has(key(folder)) ||
+            (directoryExists === undefined
+                ? ts.sys.directoryExists(folder)
+                : directoryExists.call(host, folder)),
+        getSourceFile: (file, language, onError, fresh) => {
+            const text = overlay.get(key(file));
+            return text === undefined
+                ? getSourceFile.call(host, file, language, onError, fresh)
+                : ts.createSourceFile(file, text, language);
+        },
+    });
+}
+const lineAt = (text, index) => text.slice(0, index).split("\n").length;
+const lineStart = (text, index) => text.lastIndexOf("\n", index - 1) + 1;
+/** The start of the comment block directly above the line at `start`, or `start`. */
+function aboveComments(text, start) {
+    let at = start;
+    while (at > 0) {
+        const previous = lineStart(text, at - 1);
+        const line = text.slice(previous, at - 1).trim();
+        if (!(line.startsWith("//") || line.startsWith("/*") || line.startsWith("*")))
+            break;
+        at = previous;
+    }
+    return at;
+}
+function declarationOf(content, mask, schema) {
+    const found = new RegExp(`\\bexport\\s+(?:const|let|var)\\s+${schema}\\b[^=]*=`).exec(mask);
+    if (found === null)
+        return exported(mask, schema) === null ? undefined : null;
+    const valueStart = found.index + found[0].length;
+    let end = expressionEnd(mask, valueStart);
+    if (content[end] === ";")
+        end++;
+    const exportStart = lineStart(content, found.index);
+    const markerStart = exportStart === 0 ? -1 : lineStart(content, exportStart - 1);
+    const marker = markerStart === -1 ? null : MARKER.exec(content.slice(markerStart, exportStart - 1));
+    return {
+        start: marker === null ? found.index : markerStart,
+        end,
+        value: content.slice(valueStart, end),
+        line: lineAt(content, found.index),
+        hash: marker?.[1],
+    };
+}
+function targetsOf(content) {
+    const mask = codePositionMask(content);
+    const targets = [];
+    for (const [fn, schema] of PAIRS) {
+        const found = exported(mask, fn);
+        if (found === null)
+            continue;
+        const reexport = found[0].startsWith("export {") || found[0].startsWith("export{");
+        let after = found.index + found[0].length;
+        while (/\s/.test(mask[after] ?? ""))
+            after++;
+        targets.push({
+            fn,
+            schema,
+            insertAt: reexport ? content.length : aboveComments(content, lineStart(content, found.index)),
+            fnLine: lineAt(content, found.index),
+            annotated: !reexport &&
+                /^(?:const|let|var)\b/.test(found[0].replace(/^export\s+/, "")) &&
+                mask[after] === ":",
+            declaration: declarationOf(content, mask, schema),
+        });
+    }
+    return targets;
+}
+const SCHEMA_IMPORT = /\bimport\s*(type\s*)?\{([^}]*)\}\s*from\s*["']@nifrajs\/schema["']/g;
+const IMPORT = /^import\b[\s\S]*?from\s*["'][^"'\n]+["'];?|^import\s*["'][^"'\n]+["'];?/gm;
+const T_BINDING = /\b(?:const|let|var|function|class)\s+t\b|\bimport\s+t\b|[{,]\s*t\s*[,}]|\bas\s+t\b/;
+/**
+ * `content` with `t` imported from `@nifrajs/schema`, or `undefined` when `t` already names something
+ * else in the file. Strings are blank in the code mask, so imports are read from the text and kept
+ * only where the mask shows code.
+ */
+function withSchemaImport(content) {
+    const mask = codePositionMask(content);
+    const inCode = (match) => mask[match.index] === "i";
+    const imports = [...content.matchAll(SCHEMA_IMPORT)].filter(inCode);
+    if (imports.some((m) => m[1] === undefined && /(?:^|,)\s*t\s*(?:,|$)/.test(m[2] ?? "")))
+        return content;
+    if (T_BINDING.test(mask))
+        return undefined;
+    const named = imports.find((m) => m[1] === undefined);
+    if (named !== undefined) {
+        const brace = content.indexOf("{", named.index);
+        return `${content.slice(0, brace + 1)} t,${content.slice(brace + 1)}`;
+    }
+    let end = 0;
+    for (const match of content.matchAll(IMPORT))
+        if (inCode(match))
+            end = match.index + match[0].length;
+    const line = 'import { t } from "@nifrajs/schema"';
+    return end === 0
+        ? `${line}\n\n${content}`
+        : `${content.slice(0, end)}\n${line}${content.slice(end)}`;
+}
+/**
+ * What each listed route backend half needs, and the file contents that would apply it. `nifra
+ * schemas`, `nifra migrate layout` and the NF-C030 fix share it, so one return type drafts one schema.
+ */
+export async function planOutputSchemas(root, files, read, options = {}) {
+    const { draft } = options;
+    const perFile = new Map();
+    for (const file of files) {
+        const content = read(file);
+        if (content === undefined)
+            continue;
+        const targets = targetsOf(content);
+        if (targets.length > 0)
+            perFile.set(file, { content, targets });
+    }
+    const chosen = (file, target) => draft === undefined || (draft(file, target.schema) && target.declaration === undefined);
+    const probe = [...perFile].flatMap(([file, { targets }]) => {
+        const read = targets.filter((target) => chosen(file, target));
+        return read.length === 0
+            ? []
+            : [
+                {
+                    file,
+                    fns: read.map((target) => target.fn),
+                    schemas: read.filter((t) => t.declaration !== undefined).map((t) => t.schema),
+                },
+            ];
+    });
+    const sources = new Map(options.overlay);
+    for (const [file, { content }] of perFile)
+        sources.set(file, content);
+    const { shapes, warnings } = await readShapes(root, probe, sources);
+    const entries = [];
+    const edits = new Map();
+    if (warnings.length > 0)
+        return { entries, edits, warnings };
+    for (const [file, { content, targets }] of perFile) {
+        const mask = codePositionMask(content);
+        const replacements = [];
+        for (const target of targets) {
+            if (!chosen(file, target))
+                continue;
+            const raw = shapes.get(`${file}#${target.fn}`);
+            const declared = shapes.get(`${file}#${target.schema}`);
+            const { declaration } = target;
+            const line = declaration?.line ?? target.fnLine;
+            const entry = (status, dropped = [], reason, edited = false, omitted = [], open = []) => {
+                const schema = target.schema;
+                const generated = declaration?.hash !== undefined;
+                const base = { file, line, schema, status, generated, dropped };
+                const item = reason !== undefined ? { ...base, reason } : edited ? { ...base, edited } : base;
+                const withOmitted = omitted.length === 0 ? item : { ...item, omitted };
+                return entries.push(open.length === 0 ? withOmitted : { ...withOmitted, open }) - 1;
+            };
+            if (target.annotated) {
+                // A `Route.Loader` annotation returns the schema's own input type: comparing the two would
+                // always agree, so the schema is reported unchecked rather than passed.
+                entry("unreadable", [], `${target.fn} has a type annotation, so its return type is the annotation's, not what it returns. Remove the annotation to have the schema generated and checked, or delete the "nifra:generated" line to own the schema by hand`);
+                continue;
+            }
+            if (raw === undefined) {
+                entry("unreadable", [], "TypeScript could not read its type");
+                continue;
+            }
+            const returned = dataShape(raw);
+            if (returned.kind === "never") {
+                entry("no-data");
+                continue;
+            }
+            const dropped = declared === undefined || declared.kind === "never"
+                ? []
+                : undeclaredPaths(returned, declared);
+            if (declaration === null || (declaration !== undefined && declaration.hash === undefined)) {
+                entry("declared", dropped);
+                continue;
+            }
+            if (returned.kind === "json" && returned.reason !== undefined) {
+                entry("unreadable", dropped, `the ${target.fn}'s return type is ${returned.reason}: annotate it, or write the schema by hand`);
+                continue;
+            }
+            const body = schemaSource(returned);
+            const omitted = omittedPaths(returned);
+            const open = openPaths(returned);
+            if (declaration === undefined) {
+                // The name bound any other way (declared, imported) would clash with the one written here.
+                if (new RegExp(`(?<![\\w$.])${target.schema}(?![\\w$])`).test(mask)) {
+                    entry("missing", [], `\`${target.schema}\` already names something in this file, so no draft was written`);
+                    continue;
+                }
+                const at = entry("missing", [], undefined, false, omitted, open);
+                const written = declarationText(target.schema, target.fn, body);
+                const text = target.insertAt === content.length ? `\n${written}\n` : `${written}\n\n`;
+                replacements.push({ start: target.insertAt, end: target.insertAt, text, entry: at });
+            }
+            else if (declaration.hash === hashOf(body) &&
+                schemaTokens(declaration.value) === schemaTokens(body)) {
+                entry("current", [], undefined, false, [], open);
+            }
+            else {
+                // The marker still matches what would be written, so the text under it was edited.
+                const edited = declaration.hash === hashOf(body);
+                const at = entry("stale", dropped, undefined, edited, omitted, open);
+                const text = declarationText(target.schema, target.fn, body);
+                replacements.push({ start: declaration.start, end: declaration.end, text, entry: at });
+            }
+        }
+        if (replacements.length === 0)
+            continue;
+        let next = content;
+        for (const r of replacements.sort((a, b) => b.start - a.start))
+            next = `${next.slice(0, r.start)}${r.text}${next.slice(r.end)}`;
+        const imported = withSchemaImport(next);
+        if (imported === undefined) {
+            for (const r of replacements) {
+                const blocked = entries[r.entry];
+                if (blocked !== undefined)
+                    entries[r.entry] = {
+                        ...blocked,
+                        reason: "`t` already names something else in this file, so it was left as is",
+                    };
+            }
+            continue;
+        }
+        edits.set(file, imported);
+    }
+    entries.sort((a, b) => codeUnitOrder(a.file, b.file) || a.line - b.line);
+    return { entries, edits, warnings };
+}
+// ---- entry points ------------------------------------------------------------------------------
+const ROUTE_BACKEND_TS = /\.backend\.[cm]?ts$/;
+function routeBackends(dir) {
+    const routes = join(dir, "routes");
+    if (!existsSync(routes))
+        return [];
+    return readdirSync(routes, { recursive: true, encoding: "utf8" })
+        .map((file) => posix(join("routes", file)))
+        .filter((file) => ROUTE_BACKEND_TS.test(file) && !file.split("/").includes("node_modules"))
+        .sort(codeUnitOrder);
+}
+/**
+ * Every route backend half under `<dir>/routes`: report what each loader's and action's schema needs,
+ * and with `write`, write the missing schemas and refresh the stale generated ones. A hand-written
+ * schema is never touched; its entry lists the returned fields it drops.
+ */
+export async function outputSchemas(dir, options = {}) {
+    const write = options.write === true;
+    const { entries, edits, warnings } = await planOutputSchemas(dir, routeBackends(dir), (file) => {
+        try {
+            return readFileSync(join(dir, file), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    });
+    const written = [];
+    let final = entries;
+    if (write) {
+        for (const [file, content] of edits) {
+            writeFileSync(join(dir, file), content);
+            written.push(file);
+        }
+        final = entries.map((entry) => !written.includes(entry.file) || entry.reason !== undefined
+            ? entry
+            : entry.status === "missing"
+                ? { ...entry, status: "generated" }
+                : entry.status === "stale"
+                    ? { ...entry, status: "regenerated" }
+                    : entry);
+    }
+    // `check` also fails what a review still owes: a schema not written yet, and one that admits anything.
+    const owed = (entry) => entry.status === "missing" || (entry.open?.length ?? 0) > 0;
+    return {
+        ok: warnings.length === 0 &&
+            !final.some((entry) => entry.status === "stale" || (options.check === true && owed(entry))),
+        write,
+        entries: final,
+        written,
+        warnings,
+    };
+}
+/**
+ * The generated schemas among `files` whose route now returns a different shape (NF-C033), and those
+ * it could not compare. `warnings` says why nothing could be read at all.
+ */
+export async function staleGeneratedSchemas(root, files, read) {
+    const marked = files.filter((file) => read(file)?.includes(GENERATED_MARK) === true);
+    if (marked.length === 0)
+        return { stale: [], unchecked: [], warnings: [] };
+    const { entries, warnings } = await planOutputSchemas(root, marked, read);
+    return {
+        stale: entries.filter((entry) => entry.status === "stale"),
+        unchecked: entries.filter((entry) => entry.generated && entry.status === "unreadable"),
+        warnings,
+    };
+}
+//# sourceMappingURL=output-schemas.js.map