kibi-cli 2.31.1 → 2.35.1

package/dist/public/proof-sources.js

@@ -0,0 +1,1292 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+/**
+ * Project sources Kibi reads by itself for the `source` proof kind, and for
+ * source-backed rule domains, rule predicates and count value sources: a
+ * JSON or YAML file, the files a glob matches, an OpenAPI document, the
+ * references the code makes (environment variables, imports, calls, string
+ * arguments, thrown error codes, property values), a data schema (drizzle,
+ * Prisma or SQL migrations), a web app's route table (Hono, Express) and a
+ * validator object (zod and anything with safeParse).
+ *
+ * Every reader is exact or refuses: a member Kibi cannot read statically (a
+ * computed environment variable name, a dynamic import, an ALTER TABLE form
+ * it does not know, a router mounted on a pattern) fails the read with its
+ * location, so a set claim is never decided over a set Kibi only partly saw.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import fg from "fast-glob";
+import { parse as parseYaml } from "yaml";
+// implements REQ-kibi-source-proof-kinds
+export const SOURCE_READERS = [
+    "json",
+    "yaml",
+    "glob",
+    "openapi",
+    "references",
+    "schema",
+    "routes",
+    "validator",
+];
+const SELECTS = {
+    json: ["keys", "values", "items"],
+    yaml: ["keys", "values", "items"],
+    openapi: [
+        "operations",
+        "unsecured_operations",
+        "security_schemes",
+        "responses",
+    ],
+    schema: [
+        "tables",
+        "columns",
+        "required_columns",
+        "nullable_columns",
+        "foreign_keys",
+    ],
+    routes: ["routes", "middleware"],
+    validator: ["fields", "required_fields", "optional_fields"],
+};
+export const REFERENCE_EXTRACTS = [
+    "env",
+    "imports",
+    "calls",
+    "string_args",
+    "thrown",
+    "property",
+];
+const KEYS = {
+    json: ["reader", "file", "path", "select"],
+    yaml: ["reader", "file", "path", "select"],
+    glob: ["reader", "pattern", "capture", "ignore"],
+    openapi: ["reader", "file", "select"],
+    references: ["reader", "files", "extract", "callee", "key", "ignore"],
+    schema: ["reader", "format", "file", "files", "exports", "table", "select"],
+    routes: [
+        "reader",
+        "file",
+        "export",
+        "framework",
+        "path_prefix",
+        "names_from",
+        "select",
+    ],
+    validator: ["reader", "file", "export", "select"],
+};
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function stringList(value) {
+    return Array.isArray(value) && value.length > 0 && value.every(nonEmpty);
+}
+function relativeSafe(value) {
+    return !path.isAbsolute(value) && !value.split(/[\\/]/).includes("..");
+}
+/**
+ * Why a source spec is not one Kibi can read, or [] when it is. `label`
+ * names the field in the messages (proof_contract.source, ...).
+ */
+// implements REQ-kibi-source-proof-kinds
+export function sourceSpecErrors(value, label) {
+    const row = record(value);
+    if (!row || !SOURCE_READERS.includes(row.reader))
+        return [
+            `${label} must be an object whose reader is one of: ${SOURCE_READERS.join(", ")}`,
+        ];
+    const reader = row.reader;
+    const errors = [];
+    const unknown = Object.keys(row).filter((key) => !KEYS[reader].includes(key));
+    if (unknown.length > 0)
+        errors.push(`${label} (reader ${reader}) does not take ${unknown.join(", ")}; it takes ${KEYS[reader].join(", ")}`);
+    const file = (key, required) => {
+        const raw = row[key];
+        if (raw === undefined) {
+            if (required)
+                errors.push(`${label}.${key} is required for reader ${reader}`);
+            return;
+        }
+        if (!nonEmpty(raw) || !relativeSafe(raw))
+            errors.push(`${label}.${key} must be a repository-relative path inside the workspace`);
+    };
+    const globs = (key, required) => {
+        const raw = row[key];
+        if (raw === undefined) {
+            if (required)
+                errors.push(`${label}.${key} is required for reader ${reader}`);
+            return;
+        }
+        const list = typeof raw === "string" ? [raw] : raw;
+        if (!stringList(list) || !list.every(relativeSafe))
+            errors.push(`${label}.${key} must be a repository-relative glob or a list of them`);
+    };
+    const select = SELECTS[reader];
+    if (row.select !== undefined &&
+        (select === undefined || !select.includes(String(row.select))))
+        errors.push(select === undefined
+            ? `${label}.select does not apply to reader ${reader}`
+            : `${label}.select must be one of: ${select.join(", ")}`);
+    switch (reader) {
+        case "json":
+        case "yaml":
+            file("file", true);
+            if (row.path !== undefined && typeof row.path !== "string")
+                errors.push(`${label}.path must be a dotted path or a JSON pointer`);
+            break;
+        case "glob":
+            globs("pattern", true);
+            globs("ignore", false);
+            if (row.capture !== undefined && typeof row.capture !== "boolean")
+                errors.push(`${label}.capture must be true or false`);
+            break;
+        case "openapi":
+            file("file", true);
+            break;
+        case "references":
+            globs("files", true);
+            globs("ignore", false);
+            if (!REFERENCE_EXTRACTS.includes(row.extract))
+                errors.push(`${label}.extract must be one of: ${REFERENCE_EXTRACTS.join(", ")}`);
+            if (row.extract === "string_args" && !nonEmpty(row.callee))
+                errors.push(`${label}.callee is required for extract string_args: name the function whose first argument is read`);
+            if (row.callee !== undefined && !nonEmpty(row.callee))
+                errors.push(`${label}.callee must be a function name`);
+            if (row.extract === "property" && !nonEmpty(row.key))
+                errors.push(`${label}.key is required for extract property: name the property whose string values are read`);
+            if (row.key !== undefined && row.extract !== "property")
+                errors.push(`${label}.key applies only to extract property`);
+            break;
+        case "schema":
+            if (!["drizzle", "prisma", "sql"].includes(String(row.format)))
+                errors.push(`${label}.format must be drizzle, prisma or sql`);
+            if (row.format === "sql") {
+                globs("files", true);
+                if (row.file !== undefined)
+                    errors.push(`${label}.file does not apply to format sql; use files`);
+            }
+            else {
+                file("file", true);
+                if (row.files !== undefined)
+                    errors.push(`${label}.files applies only to format sql`);
+            }
+            if (row.exports !== undefined &&
+                (!stringList(row.exports) || row.format !== "drizzle"))
+                errors.push(`${label}.exports must be a list of export names, for format drizzle only`);
+            if (row.table !== undefined && !nonEmpty(row.table))
+                errors.push(`${label}.table must be a table name or a glob of table names`);
+            break;
+        case "routes":
+            file("file", true);
+            if (!nonEmpty(row.export))
+                errors.push(`${label}.export is required for reader routes: name the app (or a function returning it)`);
+            if (row.framework !== undefined &&
+                !["hono", "express"].includes(String(row.framework)))
+                errors.push(`${label}.framework must be hono or express`);
+            if (row.path_prefix !== undefined &&
+                (!nonEmpty(row.path_prefix) || !String(row.path_prefix).startsWith("/")))
+                errors.push(`${label}.path_prefix must be a path starting with /`);
+            if (row.names_from !== undefined &&
+                (!stringList(row.names_from) || !row.names_from.every(relativeSafe)))
+                errors.push(`${label}.names_from must list repository-relative module files whose exports name middleware`);
+            break;
+        case "validator":
+            file("file", true);
+            if (!nonEmpty(row.export))
+                errors.push(`${label}.export is required for reader validator: name the object schema`);
+            break;
+    }
+    return errors;
+}
+/** The spec with only the keys its reader takes, for contract hashing. */
+// implements REQ-kibi-source-proof-kinds
+export function normalizeSourceSpec(value) {
+    const row = record(value);
+    if (!row || !SOURCE_READERS.includes(row.reader))
+        return undefined;
+    const reader = row.reader;
+    const out = {};
+    for (const key of KEYS[reader])
+        if (row[key] !== undefined)
+            out[key] = row[key];
+    return out;
+}
+function globList(value) {
+    if (typeof value === "string")
+        return [value];
+    return Array.isArray(value) ? value.filter(nonEmpty) : [];
+}
+const DEFAULT_IGNORE = ["**/node_modules/**", "**/.git/**", "**/.kb/**"];
+/** Workspace-relative files a glob list matches, sorted. */
+// implements REQ-kibi-source-proof-kinds
+export function matchWorkspaceFiles(workspaceRoot, patterns, ignore = []) {
+    return fg
+        .sync([...patterns], {
+        cwd: workspaceRoot,
+        ignore: [...DEFAULT_IGNORE, ...ignore],
+        dot: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+    })
+        .map((file) => file.split(path.sep).join("/"))
+        .sort();
+}
+function readText(workspaceRoot, relative) {
+    const absolute = path.resolve(workspaceRoot, relative);
+    const root = path.resolve(workspaceRoot);
+    if (absolute !== root && !absolute.startsWith(root + path.sep))
+        return null;
+    if (!existsSync(absolute) || !statSync(absolute).isFile())
+        return null;
+    return readFileSync(absolute, "utf8");
+}
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+const MISSING_FILE_HASH = "missing";
+/**
+ * What a read of `spec` depends on, so a receipt goes stale when any of it
+ * changes: each file the reader parses (its contents), the set of files a
+ * glob matches (their paths), and for the readers that evaluate a module
+ * (drizzle schemas, route tables, validators) every workspace module that
+ * module imports through relative or tsconfig path imports.
+ */
+// implements REQ-kibi-source-proof-kinds
+export function sourceDependencies(workspaceRoot, spec) {
+    const files = new Set();
+    const out = [];
+    const addFile = (relative) => files.add(relative.split(path.sep).join("/"));
+    switch (spec.reader) {
+        case "json":
+        case "yaml":
+        case "openapi":
+        case "validator":
+            addFile(String(spec.file));
+            break;
+        case "glob": {
+            const matched = matchWorkspaceFiles(workspaceRoot, globList(spec.pattern), globList(spec.ignore));
+            out.push({
+                id: `source-glob:${globList(spec.pattern).join(",")}`,
+                hash: sha256(matched.join("\n")),
+            });
+            break;
+        }
+        case "references":
+            for (const file of matchWorkspaceFiles(workspaceRoot, globList(spec.files), globList(spec.ignore)))
+                addFile(file);
+            out.push({
+                id: `source-glob:${globList(spec.files).join(",")}`,
+                hash: sha256(matchWorkspaceFiles(workspaceRoot, globList(spec.files), globList(spec.ignore)).join("\n")),
+            });
+            break;
+        case "schema":
+            if (spec.format === "sql") {
+                const matched = matchWorkspaceFiles(workspaceRoot, globList(spec.files));
+                for (const file of matched)
+                    addFile(file);
+                out.push({
+                    id: `source-glob:${globList(spec.files).join(",")}`,
+                    hash: sha256(matched.join("\n")),
+                });
+            }
+            else
+                addFile(String(spec.file));
+            break;
+        case "routes":
+            addFile(String(spec.file));
+            for (const file of globList(spec.names_from))
+                addFile(file);
+            break;
+    }
+    if (spec.reader === "routes" ||
+        spec.reader === "validator" ||
+        (spec.reader === "schema" && spec.format === "drizzle"))
+        for (const file of [...files])
+            for (const imported of importClosure(workspaceRoot, file))
+                addFile(imported);
+    for (const file of [...files].sort()) {
+        const text = readText(workspaceRoot, file);
+        out.push({
+            id: `source-file:${file}`,
+            hash: text === null ? MISSING_FILE_HASH : sha256(text),
+        });
+    }
+    return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+const IMPORT_SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\brequire\s*\(\s*|\bexport\s+\*\s+from\s*)["']([^"']+)["']/g;
+const MODULE_SUFFIXES = [
+    "",
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    "/index.ts",
+    "/index.tsx",
+    "/index.js",
+    "/index.mjs",
+];
+function readJsonc(file) {
+    try {
+        const text = readFileSync(file, "utf8")
+            .replace(/\/\*[\s\S]*?\*\//g, "")
+            .replace(/(^|[^:"])\/\/.*$/gm, "$1")
+            .replace(/,(\s*[}\]])/g, "$1");
+        return record(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+// The paths a tsconfig declares, following `extends` (a relative file, or a
+// list of them) the way tsc does: the nearest declaration of paths wins, and
+// its targets resolve against baseUrl, else against the file declaring them.
+function tsconfigPaths(file, depth = 0) {
+    const config = readJsonc(file);
+    if (config === null || depth > 10)
+        return null;
+    const dir = path.dirname(file);
+    const options = record(config.compilerOptions);
+    const paths = record(options?.paths);
+    if (paths)
+        return {
+            base: path.resolve(dir, typeof options?.baseUrl === "string" ? options.baseUrl : "."),
+            paths: Object.entries(paths).map(([key, targets]) => [
+                key,
+                Array.isArray(targets) ? targets.map(String) : [],
+            ]),
+        };
+    const parents = (Array.isArray(config.extends) ? config.extends : [config.extends]).filter((parent) => typeof parent === "string");
+    for (const parent of parents.reverse()) {
+        if (!parent.startsWith("."))
+            continue;
+        const target = path.resolve(dir, parent);
+        const candidate = existsSync(target) ? target : `${target}.json`;
+        if (!existsSync(candidate))
+            continue;
+        const inherited = tsconfigPaths(candidate, depth + 1);
+        if (inherited === null)
+            continue;
+        // A baseUrl in the child re-roots inherited paths.
+        return typeof options?.baseUrl === "string"
+            ? { ...inherited, base: path.resolve(dir, options.baseUrl) }
+            : inherited;
+    }
+    return null;
+}
+function tsconfigAliases(workspaceRoot, fromFile) {
+    const root = path.resolve(workspaceRoot);
+    let dir = path.dirname(path.resolve(root, fromFile));
+    for (;;) {
+        const config = path.join(dir, "tsconfig.json");
+        if (existsSync(config))
+            return tsconfigPaths(config);
+        if (dir === root || path.dirname(dir) === dir)
+            return null;
+        dir = path.dirname(dir);
+    }
+}
+// A bare specifier that names a workspace package: node_modules/<name> is a
+// link into the repository (pnpm, yarn and npm workspaces), so its source is
+// part of the closure. A package installed from a registry is not.
+function workspacePackageBases(root, fromFile, specifier) {
+    const parts = specifier.split("/");
+    const nameLength = specifier.startsWith("@") ? 2 : 1;
+    if (parts.length < nameLength || parts.some((part) => part === ""))
+        return [];
+    const name = parts.slice(0, nameLength).join("/");
+    const subpath = parts.slice(nameLength).join("/");
+    let dir = path.dirname(path.resolve(root, fromFile));
+    for (;;) {
+        const link = path.join(dir, "node_modules", name);
+        if (existsSync(link)) {
+            let real;
+            try {
+                real = realpathSync(link);
+            }
+            catch {
+                return [];
+            }
+            const relative = path.relative(root, real);
+            if (relative.startsWith("..") ||
+                path.isAbsolute(relative) ||
+                relative.split(path.sep).includes("node_modules"))
+                return [];
+            if (subpath !== "")
+                return [path.join(real, subpath), path.join(real, "src", subpath)];
+            const manifest = readJsonc(path.join(real, "package.json"));
+            const entries = [];
+            const collect = (value) => {
+                if (typeof value === "string")
+                    entries.push(value);
+                else if (record(value))
+                    for (const key of [
+                        "source",
+                        "import",
+                        "module",
+                        "default",
+                        "require",
+                        "node",
+                    ])
+                        collect(value[key]);
+            };
+            const exported = record(manifest?.exports)?.["."] ?? manifest?.exports;
+            collect(exported);
+            for (const key of ["source", "module", "main"])
+                collect(manifest?.[key]);
+            return [
+                ...entries
+                    .filter((entry) => !entry.endsWith(".d.ts"))
+                    .map((entry) => path.resolve(real, entry)),
+                path.join(real, "src", "index"),
+                path.join(real, "index"),
+            ];
+        }
+        if (path.resolve(dir) === root || path.dirname(dir) === dir)
+            return [];
+        dir = path.dirname(dir);
+    }
+}
+function resolveModule(workspaceRoot, fromFile, specifier, aliases) {
+    const root = path.resolve(workspaceRoot);
+    const bases = [];
+    if (specifier.startsWith("."))
+        bases.push(path.resolve(root, path.dirname(fromFile), specifier));
+    else if (aliases !== null)
+        for (const [key, targets] of aliases.paths) {
+            const star = key.indexOf("*");
+            const prefix = star === -1 ? key : key.slice(0, star);
+            const suffix = star === -1 ? "" : key.slice(star + 1);
+            if (star === -1
+                ? specifier !== key
+                : !specifier.startsWith(prefix) || !specifier.endsWith(suffix))
+                continue;
+            const middle = star === -1
+                ? ""
+                : specifier.slice(prefix.length, specifier.length - suffix.length);
+            for (const target of targets)
+                bases.push(path.resolve(aliases.base, target.replace("*", middle)));
+        }
+    if (bases.length === 0 &&
+        !specifier.startsWith(".") &&
+        !path.isAbsolute(specifier))
+        bases.push(...workspacePackageBases(root, fromFile, specifier));
+    for (const base of bases) {
+        const stripped = base.replace(/\.[cm]?js$/, "");
+        for (const candidate of [
+            base,
+            ...MODULE_SUFFIXES.map((suffix) => stripped + suffix),
+        ]) {
+            if (!existsSync(candidate) || !statSync(candidate).isFile())
+                continue;
+            let real = candidate;
+            try {
+                real = realpathSync(candidate);
+            }
+            catch {
+                // A dangling link resolves to nothing.
+            }
+            const relative = path.relative(root, real);
+            if (relative.startsWith("..") || path.isAbsolute(relative))
+                return null;
+            if (relative.split(path.sep).includes("node_modules"))
+                return null;
+            return relative.split(path.sep).join("/");
+        }
+    }
+    return null;
+}
+/**
+ * The workspace modules `file` imports, directly or not, through relative
+ * imports, the nearest tsconfig's `paths` aliases (following `extends`) and
+ * workspace packages linked into node_modules (packages installed from a
+ * registry are left out: a lockfile change stales nothing here).
+ */
+// implements REQ-kibi-source-proof-kinds
+export function importClosure(workspaceRoot, file) {
+    const seen = new Set();
+    const queue = [file.split(path.sep).join("/")];
+    while (queue.length > 0 && seen.size < 5000) {
+        const current = queue.pop();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const text = readText(workspaceRoot, current);
+        if (text === null)
+            continue;
+        const aliases = tsconfigAliases(workspaceRoot, current);
+        for (const match of text.matchAll(IMPORT_SPECIFIER)) {
+            const resolved = resolveModule(workspaceRoot, current, match[1] ?? "", aliases);
+            if (resolved !== null && !seen.has(resolved))
+                queue.push(resolved);
+        }
+    }
+    seen.delete(file.split(path.sep).join("/"));
+    return [...seen].sort();
+}
+function sortedUnique(values) {
+    return [...new Set(values)].sort();
+}
+function scalarText(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint")
+        return String(value);
+    return null;
+}
+function navigate(document, rawPath) {
+    const trimmed = rawPath.trim();
+    if (trimmed === "" || trimmed === "/")
+        return { ok: true, value: document };
+    const parts = trimmed.startsWith("/")
+        ? trimmed
+            .slice(1)
+            .split("/")
+            .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"))
+        : trimmed.split(".");
+    let value = document;
+    for (const part of parts) {
+        if (Array.isArray(value) && /^\d+$/.test(part))
+            value = value[Number(part)];
+        else if (record(value) !== null &&
+            part in value)
+            value = value[part];
+        else
+            return {
+                ok: false,
+                reason: `the document has nothing at ${rawPath} (no ${part})`,
+            };
+    }
+    return { ok: true, value };
+}
+function parseDocument(workspaceRoot, file, yaml) {
+    const text = readText(workspaceRoot, file);
+    if (text === null)
+        return { ok: false, reason: `${file} does not exist in the workspace` };
+    try {
+        return {
+            ok: true,
+            value: yaml || /\.ya?ml$/i.test(file) ? parseYaml(text) : JSON.parse(text),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `Kibi could not parse ${file}: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`,
+        };
+    }
+}
+function readDocumentMembers(workspaceRoot, spec) {
+    const parsed = parseDocument(workspaceRoot, String(spec.file), spec.reader === "yaml");
+    if (!parsed.ok)
+        return parsed;
+    const at = navigate(parsed.value, typeof spec.path === "string" ? spec.path : "");
+    if (!at.ok)
+        return at;
+    const value = at.value;
+    const select = typeof spec.select === "string" ? spec.select : undefined;
+    let raw;
+    if (Array.isArray(value)) {
+        if (select === "keys")
+            return {
+                ok: false,
+                reason: `${spec.path ?? "the document"} is a list, which has no keys (use select items)`,
+            };
+        raw = value;
+    }
+    else if (record(value) !== null) {
+        const object = value;
+        if (select === "items")
+            return {
+                ok: false,
+                reason: `${spec.path ?? "the document"} is an object, not a list (use select keys or values)`,
+            };
+        raw = select === "values" ? Object.values(object) : Object.keys(object);
+    }
+    else if (scalarText(value) !== null)
+        raw = [value];
+    else
+        return { ok: false, reason: `${spec.path ?? "the document"} is empty` };
+    const members = [];
+    for (const item of raw) {
+        const text = scalarText(item);
+        if (text === null)
+            return {
+                ok: false,
+                reason: `${spec.path ?? "the document"} holds a value that is not a string, number or boolean, so it cannot be a member (select keys, or point path at the list)`,
+            };
+        members.push(text);
+    }
+    return { ok: true, model: { members: sortedUnique(members) } };
+}
+function globCaptureRegex(pattern) {
+    let out = "";
+    for (let index = 0; index < pattern.length; index++) {
+        const char = pattern[index];
+        if (char === "*" && pattern[index + 1] === "*") {
+            index++;
+            // "**/" is any number of directories, captured without the slash.
+            if (pattern[index + 1] === "/") {
+                out += "(?:(.*)/)?";
+                index++;
+            }
+            else
+                out += "(.*)";
+        }
+        else if (char === "*")
+            out += "([^/]*)";
+        else if (char === "?")
+            out += "([^/])";
+        else
+            out += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}
+function readGlob(workspaceRoot, spec) {
+    const patterns = globList(spec.pattern);
+    const matched = matchWorkspaceFiles(workspaceRoot, patterns, globList(spec.ignore));
+    // No match proves nothing: a mistyped pattern would pass every subset_of
+    // and excludes fact.
+    if (matched.length === 0)
+        return { ok: false, reason: `${patterns.join(", ")} matches no file` };
+    if (spec.capture !== true)
+        return { ok: true, model: { members: matched } };
+    const members = [];
+    for (const file of matched) {
+        const match = patterns
+            .map((pattern) => file.match(globCaptureRegex(pattern)))
+            .find((result) => result !== null);
+        if (!match)
+            return {
+                ok: false,
+                reason: `capture reads only *, ** and ? in the pattern; ${file} matched a pattern Kibi cannot capture from (braces or classes)`,
+            };
+        members.push(match
+            .slice(1)
+            .filter((part) => part !== undefined && part !== "")
+            .join("/"));
+    }
+    return { ok: true, model: { members: sortedUnique(members) } };
+}
+const HTTP_METHODS = [
+    "get",
+    "put",
+    "post",
+    "delete",
+    "options",
+    "head",
+    "patch",
+    "trace",
+];
+function readOpenApi(workspaceRoot, spec) {
+    const parsed = parseDocument(workspaceRoot, String(spec.file), false);
+    if (!parsed.ok)
+        return parsed;
+    const document = record(parsed.value);
+    if (!document ||
+        (document.openapi === undefined && document.swagger === undefined))
+        return {
+            ok: false,
+            reason: `${spec.file} is not an OpenAPI or Swagger document`,
+        };
+    const select = typeof spec.select === "string" ? spec.select : "operations";
+    if (select === "security_schemes") {
+        const schemes = record(record(document.components)?.securitySchemes) ??
+            record(document.securityDefinitions) ??
+            {};
+        return { ok: true, model: { members: sortedUnique(Object.keys(schemes)) } };
+    }
+    const rootSecurity = document.security;
+    const members = [];
+    for (const [route, rawItem] of Object.entries(record(document.paths) ?? {})) {
+        const item = record(rawItem) ?? {};
+        for (const method of HTTP_METHODS) {
+            const operation = record(item[method]);
+            if (!operation)
+                continue;
+            const name = `${method.toUpperCase()} ${route}`;
+            if (select === "operations")
+                members.push(name);
+            else if (select === "responses")
+                for (const code of Object.keys(record(operation.responses) ?? {}))
+                    members.push(`${name} ${code}`);
+            else {
+                const security = operation.security ?? rootSecurity;
+                const unsecured = !Array.isArray(security) ||
+                    security.length === 0 ||
+                    security.some((row) => record(row) !== null && Object.keys(row).length === 0);
+                if (unsecured)
+                    members.push(name);
+            }
+        }
+    }
+    return { ok: true, model: { members: sortedUnique(members) } };
+}
+function identifierName(raw) {
+    const cleaned = raw.trim();
+    const parts = cleaned.match(/("[^"]+"|`[^`]+`|\[[^\]]+\]|[A-Za-z_][\w$]*)/g) ?? [cleaned];
+    return (parts[parts.length - 1] ?? cleaned).replace(/^["`[]|["`\]]$/g, "");
+}
+function splitTopLevel(body) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    let quote = null;
+    for (const char of body) {
+        if (quote !== null) {
+            current += char;
+            if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === "`")
+            quote = char;
+        if (char === "(")
+            depth++;
+        if (char === ")")
+            depth--;
+        if (char === "," && depth === 0) {
+            parts.push(current.trim());
+            current = "";
+        }
+        else
+            current += char;
+    }
+    if (current.trim() !== "")
+        parts.push(current.trim());
+    return parts;
+}
+function stripSqlComments(text) {
+    return text.replace(/--[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+}
+// Statements split at top-level semicolons. Quoted text and dollar-quoted
+// bodies ($$ ... $$, $fn$ ... $fn$) stay whole, so a function body's
+// semicolons do not split it.
+function sqlStatements(text) {
+    const statements = [];
+    let current = "";
+    let quote = null;
+    const source = stripSqlComments(text);
+    for (let index = 0; index < source.length; index++) {
+        const char = source[index];
+        if (quote !== null) {
+            if (quote.length > 1) {
+                if (source.startsWith(quote, index)) {
+                    current += quote;
+                    index += quote.length - 1;
+                    quote = null;
+                }
+                else
+                    current += char;
+                continue;
+            }
+            current += char;
+            if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === "$") {
+            const tag = source.slice(index).match(/^\$[A-Za-z_]*\$/)?.[0];
+            if (tag !== undefined) {
+                quote = tag;
+                current += tag;
+                index += tag.length - 1;
+                continue;
+            }
+        }
+        if (char === "'" || char === '"' || char === "`")
+            quote = char;
+        if (char === ";") {
+            if (current.trim() !== "")
+                statements.push(current.trim());
+            current = "";
+        }
+        else
+            current += char;
+    }
+    if (current.trim() !== "")
+        statements.push(current.trim());
+    return statements;
+}
+// One name part, and a possibly schema-qualified name: users, public.users,
+// "public"."users", [dbo].[users].
+const SQL_NAME_PART = '(?:"[^"]+"|`[^`]+`|\\[[^\\]]+\\]|[\\w$]+)';
+const SQL_NAME = String.raw `(${SQL_NAME_PART}(?:\s*\.\s*${SQL_NAME_PART})*)`;
+const COLUMN_CONSTRAINT_START = /^(?:constraint|primary\s+key|foreign\s+key|unique|check|key|index|exclude)\b/i;
+function foreignKeyText(table, columns, target, targetColumns, rest) {
+    const onDelete = rest.match(/\bon\s+delete\s+(cascade|restrict|set\s+null|set\s+default|no\s+action)/i);
+    const from = splitTopLevel(columns).map(identifierName).join(",");
+    const to = splitTopLevel(targetColumns).map(identifierName).join(",");
+    return `${table}.${from}->${identifierName(target)}.${to}${onDelete?.[1]
+        ? ` on delete ${onDelete[1].toLowerCase().replace(/\s+/g, " ")}`
+        : ""}`;
+}
+// A foreign key with the name a later DROP CONSTRAINT uses: the declared
+// name, or PostgreSQL's default <table>_<columns>_fkey.
+function addForeignKey(table, constraint, columns, target, targetColumns, rest) {
+    const text = foreignKeyText(table.name, columns, target, targetColumns, rest);
+    table.foreignKeys.push(text);
+    const name = constraint !== undefined
+        ? identifierName(constraint)
+        : `${table.name}_${splitTopLevel(columns).map(identifierName).join("_")}_fkey`;
+    table.constraints.set(name.toLowerCase(), text);
+}
+function sqlColumn(table, definition) {
+    const head = definition.match(new RegExp(`^${SQL_NAME_PART}`))?.[0] ?? "";
+    const name = identifierName(head);
+    const rest = definition.slice(head.length);
+    const notNull = /\bnot\s+null\b/i.test(rest) || /\bprimary\s+key\b/i.test(rest);
+    table.columns.set(name, { name, nullable: !notNull, optional: false });
+    const reference = rest.match(new RegExp(String.raw `\breferences\s+${SQL_NAME}\s*\(([^)]*)\)(.*)$`, "is"));
+    if (reference) {
+        const constraint = rest.match(new RegExp(String.raw `\bconstraint\s+(${SQL_NAME_PART})\s+references\b`, "i"))?.[1];
+        addForeignKey(table, constraint, name, reference[1] ?? "", reference[2] ?? "", reference[3] ?? "");
+    }
+}
+function setPrimaryKey(table, columns) {
+    for (const column of splitTopLevel(columns).map(identifierName)) {
+        const existing = table.columns.get(column);
+        if (existing)
+            existing.nullable = false;
+    }
+}
+// ALTER TABLE actions that change neither the columns, their nullability nor
+// the foreign keys: row level security, triggers, ownership, storage,
+// defaults, column types, statistics and comments.
+const SCHEMA_NEUTRAL_ALTER = /^(?:(?:enable|disable|force|no\s+force)\s+row\s+level\s+security|(?:enable|disable)\s+(?:always\s+|replica\s+)?(?:trigger|rule)\b|replica\s+identity\b|owner\s+to\b|set\s+(?:schema|tablespace|logged|unlogged|without\s+(?:oids|cluster)|access\s+method)\b|set\s*\(|reset\s*\(|cluster\s+on\b|inherit\b|no\s+inherit\b|validate\s+constraint\b|rename\s+constraint\b|alter\s+constraint\b|alter\s+(?:column\s+)?\S+\s+(?:set\s+default|drop\s+default|(?:set\s+data\s+)?type|set\s+statistics|set\s+storage|set\s+compression|add\s+generated|set\s+generated|drop\s+identity|drop\s+expression|reset\s*\(|set\s*\(|options\s*\())/i;
+function applyAlterAction(table, action) {
+    const add = action.match(/^add\s+(?:column\s+)?(?:if\s+not\s+exists\s+)?(.*)$/is);
+    if (add && !COLUMN_CONSTRAINT_START.test(add[1] ?? "")) {
+        sqlColumn(table, add[1] ?? "");
+        return null;
+    }
+    const dropColumn = action.match(new RegExp(String.raw `^drop\s+(?:column\s+)?(?:if\s+exists\s+)?(${SQL_NAME_PART})(?:\s+(?:cascade|restrict))?$`, "i"));
+    if (dropColumn && !/^drop\s+constraint\b/i.test(action)) {
+        const column = identifierName(dropColumn[1] ?? "");
+        table.columns.delete(column);
+        table.foreignKeys = table.foreignKeys.filter((fk) => !fk.startsWith(`${table.name}.${column}->`));
+        for (const [name, fk] of table.constraints)
+            if (fk.startsWith(`${table.name}.${column}->`))
+                table.constraints.delete(name);
+        return null;
+    }
+    const renameColumn = action.match(new RegExp(String.raw `^rename\s+(?:column\s+)?(${SQL_NAME_PART})\s+to\s+(${SQL_NAME_PART})$`, "i"));
+    if (renameColumn && !/^rename\s+constraint\b/i.test(action)) {
+        const from = identifierName(renameColumn[1] ?? "");
+        const to = identifierName(renameColumn[2] ?? "");
+        const column = table.columns.get(from);
+        if (column) {
+            table.columns.delete(from);
+            column.name = to;
+            table.columns.set(to, column);
+        }
+        const renamed = (fk) => fk.replace(`${table.name}.${from}->`, `${table.name}.${to}->`);
+        table.foreignKeys = table.foreignKeys.map(renamed);
+        for (const [name, fk] of table.constraints)
+            table.constraints.set(name, renamed(fk));
+        return null;
+    }
+    const nullability = action.match(new RegExp(String.raw `^alter\s+(?:column\s+)?(${SQL_NAME_PART})\s+(set|drop)\s+not\s+null$`, "i"));
+    if (nullability) {
+        const column = table.columns.get(identifierName(nullability[1] ?? ""));
+        if (column)
+            column.nullable = (nullability[2] ?? "").toLowerCase() === "drop";
+        return null;
+    }
+    const addFk = action.match(new RegExp(String.raw `^add\s+(?:constraint\s+(${SQL_NAME_PART})\s+)?foreign\s+key\s*\(([^)]*)\)\s*references\s+${SQL_NAME}\s*\(([^)]*)\)(.*)$`, "is"));
+    if (addFk) {
+        addForeignKey(table, addFk[1], addFk[2] ?? "", addFk[3] ?? "", addFk[4] ?? "", addFk[5] ?? "");
+        return null;
+    }
+    const addPrimary = action.match(new RegExp(String.raw `^add\s+(?:constraint\s+${SQL_NAME_PART}\s+)?primary\s+key\s*\(([^)]*)\)`, "i"));
+    if (addPrimary) {
+        setPrimaryKey(table, addPrimary[1] ?? "");
+        return null;
+    }
+    if (new RegExp(String.raw `^add\s+(?:constraint\s+${SQL_NAME_PART}\s+)?(?:unique|check|exclude)\b`, "i").test(action))
+        return null;
+    const dropConstraint = action.match(new RegExp(String.raw `^drop\s+constraint\s+(if\s+exists\s+)?(${SQL_NAME_PART})(?:\s+(?:cascade|restrict))?$`, "i"));
+    if (dropConstraint) {
+        const name = identifierName(dropConstraint[2] ?? "").toLowerCase();
+        const fk = table.constraints.get(name);
+        if (fk !== undefined) {
+            table.constraints.delete(name);
+            const index = table.foreignKeys.indexOf(fk);
+            if (index >= 0)
+                table.foreignKeys.splice(index, 1);
+            return null;
+        }
+        // With IF EXISTS a constraint the replay never declared is not there.
+        // Without it the database had it, so a foreign key Kibi did not read
+        // would leave the schema unknown.
+        if (dropConstraint[1] === undefined && /(?:_fkey|_fk)$/i.test(name))
+            return `drops constraint ${name}, a foreign key Kibi did not read`;
+        return null;
+    }
+    if (SCHEMA_NEUTRAL_ALTER.test(action))
+        return null;
+    return "cannot read this ALTER TABLE form";
+}
+function applySqlStatement(tables, statement, where) {
+    const normalized = statement.replace(/\s+/g, " ").trim();
+    const create = normalized.match(new RegExp(String.raw `^create\s+(?:(?:global|local)\s+)?(?:(?:temp(?:orary)?|unlogged)\s+)?table\s+(?:if\s+not\s+exists\s+)?${SQL_NAME}\s*\((.*)\)[^)]*$`, "is"));
+    if (create) {
+        const name = identifierName(create[1] ?? "");
+        const table = {
+            name,
+            columns: new Map(),
+            foreignKeys: [],
+            constraints: new Map(),
+        };
+        for (const part of splitTopLevel(create[2] ?? "")) {
+            if (COLUMN_CONSTRAINT_START.test(part)) {
+                const fk = part.match(new RegExp(String.raw `^(?:constraint\s+(${SQL_NAME_PART})\s+)?foreign\s+key\s*\(([^)]*)\)\s*references\s+${SQL_NAME}\s*\(([^)]*)\)(.*)$`, "is"));
+                if (fk)
+                    addForeignKey(table, fk[1], fk[2] ?? "", fk[3] ?? "", fk[4] ?? "", fk[5] ?? "");
+                const primary = part.match(/primary\s+key\s*\(([^)]*)\)/i);
+                if (primary)
+                    setPrimaryKey(table, primary[1] ?? "");
+                continue;
+            }
+            sqlColumn(table, part);
+        }
+        tables.set(name, table);
+        return null;
+    }
+    if (/^create\s+(?:(?:global|local)\s+)?(?:(?:temp(?:orary)?|unlogged)\s+)?table\b/i.test(normalized))
+        return `${where}: Kibi cannot read this CREATE TABLE form (${normalized.slice(0, 80)})`;
+    const drop = normalized.match(/^drop\s+table\s+(?:if\s+exists\s+)?(.*?)(?:\s+(?:cascade|restrict))?$/i);
+    if (drop) {
+        for (const name of splitTopLevel(drop[1] ?? ""))
+            tables.delete(identifierName(name));
+        return null;
+    }
+    const alter = normalized.match(new RegExp(String.raw `^alter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?${SQL_NAME}\s+(.*)$`, "i"));
+    if (!alter)
+        return null;
+    const tableName = identifierName(alter[1] ?? "");
+    const action = alter[2] ?? "";
+    const rename = action.match(new RegExp(String.raw `^rename\s+to\s+${SQL_NAME}$`, "i"));
+    const table = tables.get(tableName);
+    // A statement-wide neutral form needs no table: RLS on a table another
+    // tool created changes nothing Kibi reads.
+    const actions = splitTopLevel(action);
+    if (!table) {
+        if (actions.every((part) => SCHEMA_NEUTRAL_ALTER.test(part)))
+            return null;
+        return `${where}: ALTER TABLE ${tableName} before Kibi read its CREATE TABLE`;
+    }
+    if (rename) {
+        tables.delete(tableName);
+        const renamedTo = identifierName(rename[1] ?? "");
+        const prefix = (fk) => fk.replace(new RegExp(`^${tableName}\\.`), `${renamedTo}.`);
+        table.name = renamedTo;
+        table.foreignKeys = table.foreignKeys.map(prefix);
+        for (const [name, fk] of table.constraints)
+            table.constraints.set(name, prefix(fk));
+        tables.set(table.name, table);
+        return null;
+    }
+    for (const part of actions) {
+        const problem = applyAlterAction(table, part);
+        if (problem !== null)
+            return `${where}: ALTER TABLE ${tableName} ${problem} (${normalized.slice(0, 80)}), so the schema after it is unknown`;
+    }
+    return null;
+}
+function readSqlSchema(workspaceRoot, spec) {
+    const files = matchWorkspaceFiles(workspaceRoot, globList(spec.files));
+    if (files.length === 0)
+        return `${globList(spec.files).join(", ")} matches no file`;
+    const tables = new Map();
+    let created = 0;
+    for (const file of files) {
+        const text = readText(workspaceRoot, file) ?? "";
+        const statements = sqlStatements(text.replace(/-->\s*statement-breakpoint/g, ";"));
+        for (const statement of statements) {
+            if (/^\s*create\s+(?:\S+\s+){0,2}table\b/i.test(statement))
+                created++;
+            const problem = applySqlStatement(tables, statement, file);
+            if (problem !== null)
+                return problem;
+        }
+    }
+    // A replay that read no table proves nothing about the schema: a
+    // mistyped pattern or a folder of TypeScript migrations would otherwise
+    // pass every subset_of and excludes fact.
+    if (created === 0)
+        return `${globList(spec.files).join(", ")} holds no CREATE TABLE statement Kibi can read (${files.length} file${files.length === 1 ? "" : "s"})`;
+    return [...tables.values()];
+}
+const PRISMA_SCALARS = new Set([
+    "String",
+    "Boolean",
+    "Int",
+    "BigInt",
+    "Float",
+    "Decimal",
+    "DateTime",
+    "Json",
+    "Bytes",
+]);
+function readPrismaSchema(workspaceRoot, spec) {
+    const text = readText(workspaceRoot, String(spec.file));
+    if (text === null)
+        return `${spec.file} does not exist in the workspace`;
+    const source = text.replace(/\/\/[^\n]*/g, "");
+    const enums = new Set([...source.matchAll(/\benum\s+(\w+)\s*\{/g)].map((m) => m[1]));
+    const types = new Set([...source.matchAll(/\b(?:type)\s+(\w+)\s*\{/g)].map((m) => m[1]));
+    const tables = [];
+    for (const model of source.matchAll(/\bmodel\s+(\w+)\s*\{([^}]*)\}/g)) {
+        const body = model[2] ?? "";
+        const mapped = body.match(/@@map\(\s*"([^"]+)"\s*\)/)?.[1];
+        const name = mapped ?? model[1];
+        const table = {
+            name,
+            columns: new Map(),
+            foreignKeys: [],
+            constraints: new Map(),
+        };
+        const fieldNames = new Map();
+        for (const line of body.split("\n")) {
+            const field = line.trim().match(/^(\w+)\s+(\w+)(\[\])?(\?)?(.*)$/);
+            if (!field)
+                continue;
+            const [, fieldName = "", type = "", list, optional, attributes = ""] = field;
+            const columnName = attributes.match(/@map\(\s*"([^"]+)"\s*\)/)?.[1] ?? fieldName;
+            fieldNames.set(fieldName, columnName);
+            if (PRISMA_SCALARS.has(type) ||
+                enums.has(type) ||
+                types.has(type) ||
+                list === "[]") {
+                if (list === "[]" && !PRISMA_SCALARS.has(type) && !enums.has(type))
+                    continue;
+                table.columns.set(columnName, {
+                    name: columnName,
+                    nullable: optional === "?",
+                    optional: false,
+                });
+            }
+        }
+        for (const line of body.split("\n")) {
+            const relation = line.match(/^\s*\w+\s+(\w+)\??\s+.*@relation\(([^)]*)\)/);
+            if (!relation)
+                continue;
+            const fields = relation[2]?.match(/fields:\s*\[([^\]]*)\]/)?.[1];
+            const references = relation[2]?.match(/references:\s*\[([^\]]*)\]/)?.[1];
+            if (!fields || !references)
+                continue;
+            const target = relation[1];
+            const targetModel = source.match(new RegExp(`\\bmodel\\s+${target}\\s*\\{([^}]*)\\}`));
+            const targetName = targetModel?.[1]?.match(/@@map\(\s*"([^"]+)"\s*\)/)?.[1] ?? target;
+            const onDelete = relation[2]?.match(/onDelete:\s*(\w+)/)?.[1];
+            const columns = fields
+                .split(",")
+                .map((f) => fieldNames.get(f.trim()) ?? f.trim())
+                .join(",");
+            const targetColumns = references
+                .split(",")
+                .map((f) => f.trim())
+                .join(",");
+            table.foreignKeys.push(`${name}.${columns}->${targetName}.${targetColumns}${onDelete
+                ? ` on delete ${onDelete.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase()}`
+                : ""}`);
+        }
+        tables.push(table);
+    }
+    if (tables.length === 0)
+        return `${spec.file} declares no model`;
+    return tables;
+}
+function globMatcher(pattern) {
+    if (pattern === undefined || pattern === "*")
+        return () => true;
+    const regex = new RegExp(`^${pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".")}$`);
+    return (name) => regex.test(name);
+}
+/** The entities (tables or validator objects) a spec's table filter selects. */
+export function selectedEntities(spec, model) {
+    const matches = globMatcher(typeof spec.table === "string" ? spec.table : undefined);
+    return (model.entities ?? []).filter((entity) => matches(entity.name));
+}
+function entityMembers(spec, entities) {
+    const select = typeof spec.select === "string"
+        ? spec.select
+        : spec.reader === "validator"
+            ? "fields"
+            : "tables";
+    const prefix = (entity, column) => spec.reader === "validator" ? column.name : `${entity.name}.${column.name}`;
+    const members = [];
+    for (const entity of entities) {
+        if (select === "tables")
+            members.push(entity.name);
+        else if (select === "foreign_keys")
+            members.push(...entity.foreign_keys);
+        else
+            for (const column of entity.columns) {
+                const required = !column.nullable && !column.optional;
+                if (select === "columns" ||
+                    select === "fields" ||
+                    ((select === "required_columns" || select === "required_fields") &&
+                        required) ||
+                    (select === "nullable_columns" && column.nullable) ||
+                    (select === "optional_fields" && !required))
+                    members.push(prefix(entity, column));
+            }
+    }
+    return sortedUnique(members);
+}
+function finishEntities(spec, tables) {
+    const entities = tables
+        .map((table) => "columns" in table && table.columns instanceof Map
+        ? {
+            name: table.name,
+            columns: [...table.columns.values()]
+                .map((column) => ({ ...column }))
+                .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+            foreign_keys: sortedUnique(table.foreignKeys),
+        }
+        : table)
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const model = { members: [], entities };
+    const selected = selectedEntities(spec, model);
+    if (typeof spec.table === "string" && selected.length === 0)
+        return {
+            ok: false,
+            reason: `no ${spec.reader === "validator" ? "object" : "table"} matches ${spec.table} (${entities
+                .map((e) => e.name)
+                .slice(0, 10)
+                .join(", ") || "none read"})`,
+        };
+    return {
+        ok: true,
+        model: { members: entityMembers(spec, selected), entities: selected },
+    };
+}
+/** The routes a spec's path_prefix selects. */
+export function selectedRoutes(spec, routes) {
+    const prefix = typeof spec.path_prefix === "string"
+        ? spec.path_prefix.replace(/\/+$/, "")
+        : "";
+    return routes.filter((route) => prefix === "" ||
+        route.path === prefix ||
+        route.path.startsWith(`${prefix}/`));
+}
+/**
+ * Read `spec` from the workspace. Readers that evaluate code (drizzle
+ * schemas, route tables, validators) and the references reader go through
+ * `evaluate`, which the CLI supplies; a read without it refuses those.
+ */
+// implements REQ-kibi-source-proof-kinds
+export async function readSource(workspaceRoot, spec, evaluate) {
+    const errors = sourceSpecErrors(spec, "source");
+    if (errors.length > 0)
+        return { ok: false, reason: errors.join("; ") };
+    switch (spec.reader) {
+        case "json":
+        case "yaml":
+            return readDocumentMembers(workspaceRoot, spec);
+        case "glob":
+            return readGlob(workspaceRoot, spec);
+        case "openapi":
+            return readOpenApi(workspaceRoot, spec);
+        case "schema": {
+            if (spec.format === "sql") {
+                const tables = readSqlSchema(workspaceRoot, spec);
+                return typeof tables === "string"
+                    ? { ok: false, reason: tables }
+                    : finishEntities(spec, tables);
+            }
+            if (spec.format === "prisma") {
+                const tables = readPrismaSchema(workspaceRoot, spec);
+                return typeof tables === "string"
+                    ? { ok: false, reason: tables }
+                    : finishEntities(spec, tables);
+            }
+            break;
+        }
+        default:
+            break;
+    }
+    if (evaluate === undefined)
+        return {
+            ok: false,
+            reason: `reader ${spec.reader} needs Kibi's code evaluator`,
+        };
+    const evaluated = await evaluate(workspaceRoot, spec);
+    if (!evaluated.ok)
+        return evaluated;
+    if (spec.reader === "references")
+        return {
+            ok: true,
+            model: { members: sortedUnique(evaluated.members ?? []) },
+        };
+    if (spec.reader === "routes") {
+        const routes = selectedRoutes(spec, evaluated.routes ?? []).sort((a, b) => `${a.path} ${a.method}` < `${b.path} ${b.method}` ? -1 : 1);
+        if (typeof spec.path_prefix === "string" && routes.length === 0)
+            return {
+                ok: false,
+                reason: `no route of ${spec.export} is under ${spec.path_prefix}`,
+            };
+        const members = spec.select === "middleware"
+            ? routes.flatMap((route) => route.middleware.map((name) => `${route.method} ${route.path} ${name}`))
+            : routes.map((route) => `${route.method} ${route.path}`);
+        return { ok: true, model: { members: sortedUnique(members), routes } };
+    }
+    return finishEntities(spec, evaluated.entities ?? []);
+}
+/** A short description of a spec, for messages. */
+export function describeSource(spec) {
+    switch (spec.reader) {
+        case "json":
+        case "yaml":
+        case "openapi":
+            return `${spec.reader} ${spec.file}${spec.path ? ` at ${spec.path}` : ""}`;
+        case "glob":
+            return `files matching ${globList(spec.pattern).join(", ")}`;
+        case "references":
+            return `${spec.extract} references in ${globList(spec.files).join(", ")}`;
+        case "schema":
+            return `${spec.format} schema ${spec.file ?? globList(spec.files).join(", ")}${spec.table ? ` (tables ${spec.table})` : ""}`;
+        case "routes":
+            return `routes of ${spec.export} in ${spec.file}${spec.path_prefix ? ` under ${spec.path_prefix}` : ""}`;
+        case "validator":
+            return `validator ${spec.export} in ${spec.file}`;
+    }
+}
+/** Unresolved references, as one rejection reason naming the first few. */
+export function unresolvedReason(what, unresolved) {
+    const shown = unresolved
+        .slice(0, 5)
+        .map((row) => `${row.file}:${row.line} ${row.text}`)
+        .join("; ");
+    return `Kibi cannot read ${unresolved.length} ${what} statically, so the set is not known exactly: ${shown}${unresolved.length > 5 ? "; ..." : ""}`;
+}