avouch 0.1.22

package/dist/cli/check.d.ts

@@ -0,0 +1,86 @@
+import { type ErrorObject } from "ajv/dist/2020.js";
+import type { Report } from "../src/contract.js";
+import type { QueryStamp } from "../src/query.js";
+import { type MarkdownConfig, type MarkdownDoc } from "../src/markdown.js";
+/** The project configuration file, at the git top level of the project. */
+export declare const CONFIG_FILE = "avouch.config.json";
+export declare const ADAPTER_HINT = "next step: https://github.com/githonllc/avouch/blob/main/docs/adapter-guide.md#for-ai-agents (Markdown documents need only {\"adapter\": {\"markdown\": {\"docs\": [...]}}} in avouch.config.json; other documents need an adapter module)";
+export declare const SETUP_HINT = "to set up a project, run `npx -y avouch init`, then /avouch:scan in Claude Code (it drafts avouch.config.json and a first ontology)";
+/**
+ * An adapter, ready to run. `label` is the value of `check.adapter` in a query or gate stamp. A Markdown configuration reads
+ * its documents relative to `dir`; `where` is the prefix of an error about it.
+ */
+export type Adapter = {
+    kind: "markdown";
+    config: MarkdownConfig;
+    dir: string;
+    where: string;
+    label: string;
+} | {
+    kind: "module";
+    path: string;
+    label: string;
+};
+/** The adapter named by `--adapter`: a `.json` file is the configuration of the built-in Markdown adapter, anything else a module. */
+export declare function adapterFromArgument(arg: string): Adapter;
+export declare function gitTop(cwd: string): string | null;
+export interface ProjectOptions {
+    /** -f */
+    file?: string;
+    /** --config */
+    config?: string;
+    /** --adapter */
+    adapter?: string;
+    /** true when the command must run the check */
+    check: boolean;
+}
+/**
+ * The ontology file of a command and, when it runs the check, the adapter.
+ * Ontology: -f, else `ontology` of the project configuration, else avouch/avouch.ontology.yaml at the git top level.
+ * Adapter: --adapter, else `adapter` of the project configuration.
+ * The project configuration is --config, else avouch.config.json at the git top level of the directory of -f (with -f)
+ * or of the working directory. It is read only when the command has no -f, or must run the check without --adapter.
+ * A named -f or --config that is not a file is an error, whether or not the configuration is read (a stat, nothing more).
+ */
+export declare function resolveProject(o: ProjectOptions): {
+    file: string;
+    adapter: Adapter | null;
+};
+/** The inputs of `avouch gate docs`: the ledger file, the ontology file and the documents (paths relative to the configuration directory, with `/`). */
+export interface LedgerProject {
+    config: string;
+    dir: string;
+    ledger: string;
+    ontology: string;
+    docs: string[];
+}
+/**
+ * The project of `avouch gate docs`: --config, else avouch.config.json at the git top level of the working directory.
+ * The ledger file is `ledger.file` (default avouch.ledger.jsonl), relative to the configuration file. The documents are
+ * `ledger.docs`, else the docs of the Markdown adapter; a module adapter has no docs, so it needs `ledger.docs`.
+ */
+export declare function resolveLedger(configOption: string | undefined): LedgerProject;
+export declare function readDocs(a: Extract<Adapter, {
+    kind: "markdown";
+}>): MarkdownDoc[];
+/**
+ * The Markdown configuration of `avouch facts`: --adapter, else the `adapter` of the project configuration (--config, else
+ * avouch.config.json at the git top level of the working directory). Reads no ontology. A module adapter is an error.
+ */
+export declare function resolveMarkdownAdapter(o: {
+    config?: string;
+    adapter?: string;
+}): Extract<Adapter, {
+    kind: "markdown";
+}>;
+export declare function runCheck(ontologyFile: string, adapter: Adapter): Promise<{
+    schemaErrors: ErrorObject[];
+    report: Report;
+}>;
+/** The `check` of a query or gate stamp: the check run with the adapter, or `not_run` when there is no adapter. */
+export declare function checkStamp(ontologyFile: string, adapter: Adapter | null): Promise<QueryStamp["check"]>;
+/** The project of a query or gate command: the check runs with --check, or with --adapter. */
+export declare function resolveQueryProject(opts: Map<string, string | true>): {
+    file: string;
+    adapter: Adapter | null;
+};

package/dist/cli/check.js

@@ -0,0 +1,333 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { parse } from "yaml";
+import { check } from "../src/checker.js";
+import { isObj } from "../src/expr.js";
+import { markdownFacts, parseMarkdownConfig, validateMarkdownConfig } from "../src/markdown.js";
+/** The project configuration file, at the git top level of the project. */
+export const CONFIG_FILE = "avouch.config.json";
+// The next step when a repository has no Avouch project yet (no configuration and no default ontology).
+// The next step when a command needs an adapter and none is set: the guide section for agents.
+export const ADAPTER_HINT = "next step: https://github.com/githonllc/avouch/blob/main/docs/adapter-guide.md#for-ai-agents (Markdown documents need only {\"adapter\": {\"markdown\": {\"docs\": [...]}}} in avouch.config.json; other documents need an adapter module)";
+export const SETUP_HINT = `to set up a project, run \`npx -y avouch init\`, then /avouch:scan in Claude Code (it drafts ${CONFIG_FILE} and a first ontology)`;
+/** The adapter named by `--adapter`: a `.json` file is the configuration of the built-in Markdown adapter, anything else a module. */
+export function adapterFromArgument(arg) {
+    if (!arg.endsWith(".json"))
+        return { kind: "module", path: resolve(arg), label: arg };
+    const path = resolve(arg);
+    return { kind: "markdown", config: parseMarkdownConfig(readFileSync(path, "utf8"), arg), dir: dirname(path), where: arg, label: arg };
+}
+// Reads and validates an avouch.config.json (strict: an unknown key is an error). Throws `<file>: <json path>: <problem>`.
+// `label` names the file in the stamp: the --config argument as given, or CONFIG_FILE when the file was found at the git top.
+function loadProjectConfig(file, label) {
+    const fail = (path, problem) => {
+        throw new Error(`${file}: ${path}: ${problem}`);
+    };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(resolve(file), "utf8"));
+    }
+    catch (error) {
+        return fail("(root)", `not valid JSON: ${error.message}`);
+    }
+    if (!isObj(raw))
+        return fail("(root)", "must be an object");
+    for (const k of Object.keys(raw))
+        if (k !== "ontology" && k !== "adapter" && k !== "ledger")
+            fail(k, "unknown key");
+    // `ontology` is optional here; a command that needs it fails in resolveProject or resolveLedger
+    if (Object.hasOwn(raw, "ontology") && (typeof raw.ontology !== "string" || raw.ontology === ""))
+        fail("ontology", "must be a non-empty string");
+    if (!Object.hasOwn(raw, "adapter"))
+        fail("adapter", "missing");
+    const a = raw.adapter;
+    const dir = dirname(resolve(file));
+    const ontology = typeof raw.ontology === "string" ? resolve(dir, raw.ontology) : null;
+    let ledger = null;
+    if (Object.hasOwn(raw, "ledger")) {
+        const l = raw.ledger;
+        if (!isObj(l))
+            fail("ledger", "must be an object");
+        for (const k of Object.keys(l))
+            if (k !== "file" && k !== "docs")
+                fail(`ledger.${k}`, "unknown key");
+        ledger = {};
+        if (Object.hasOwn(l, "file")) {
+            if (typeof l.file !== "string" || l.file === "")
+                fail("ledger.file", "must be a non-empty string");
+            ledger.file = l.file;
+        }
+        if (Object.hasOwn(l, "docs")) {
+            if (!Array.isArray(l.docs) || l.docs.length === 0)
+                fail("ledger.docs", "must be a non-empty array of strings");
+            const docs = l.docs;
+            docs.forEach((d, i) => {
+                if (typeof d !== "string" || d === "")
+                    fail(`ledger.docs[${i}]`, "must be a non-empty string");
+                const j = docs.indexOf(d);
+                if (j !== i)
+                    fail(`ledger.docs[${i}]`, `duplicate of ledger.docs[${j}]`);
+            });
+            ledger.docs = [...docs];
+        }
+    }
+    if (typeof a === "string") {
+        if (a === "")
+            fail("adapter", "must be a non-empty string");
+        return { file, ontology, adapter: { written: a, path: resolve(dir, a) }, ledger };
+    }
+    if (!isObj(a))
+        return fail("adapter", "must be a string or an object");
+    for (const k of Object.keys(a))
+        if (k !== "markdown")
+            fail(`adapter.${k}`, "unknown key");
+    if (!Object.hasOwn(a, "markdown"))
+        fail("adapter.markdown", "missing");
+    if (!isObj(a.markdown))
+        fail("adapter.markdown", "must be an object");
+    const where = `${file}: adapter.markdown`;
+    return { file, ontology, adapter: { kind: "markdown", config: validateMarkdownConfig(a.markdown, where), dir, where, label: `${label}#adapter` }, ledger };
+}
+// The git top level of a directory, or null when it is not in a git repository (or git is not available).
+export function gitTop(cwd) {
+    const r = spawnSync("git", ["--no-optional-locks", "rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
+    return r.error !== undefined || r.status !== 0 ? null : r.stdout.trim();
+}
+const isFile = (path) => {
+    try {
+        return statSync(resolve(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+const real = (path) => {
+    try {
+        return realpathSync(resolve(path));
+    }
+    catch {
+        return resolve(path);
+    }
+};
+// The project configuration: `configArg` (--config), else avouch.config.json at the git top level of `startDir` (a directory
+// that is not in a git repository has none). `top` is the git top level when it was looked up.
+function findProjectConfig(configArg, startDir) {
+    if (configArg !== undefined)
+        return { config: loadProjectConfig(configArg, configArg), top: null };
+    const top = gitTop(startDir);
+    const file = top !== null && existsSync(join(top, CONFIG_FILE)) ? join(top, CONFIG_FILE) : null;
+    return { config: file !== null ? loadProjectConfig(file, CONFIG_FILE) : null, top };
+}
+/**
+ * The ontology file of a command and, when it runs the check, the adapter.
+ * Ontology: -f, else `ontology` of the project configuration, else avouch/avouch.ontology.yaml at the git top level.
+ * Adapter: --adapter, else `adapter` of the project configuration.
+ * The project configuration is --config, else avouch.config.json at the git top level of the directory of -f (with -f)
+ * or of the working directory. It is read only when the command has no -f, or must run the check without --adapter.
+ * A named -f or --config that is not a file is an error, whether or not the configuration is read (a stat, nothing more).
+ */
+export function resolveProject(o) {
+    if (o.file !== undefined && !isFile(o.file))
+        throw new Error(`-f ${o.file}: file not found`);
+    if (o.config !== undefined && !isFile(o.config))
+        throw new Error(`--config ${o.config}: file not found`);
+    const needAdapterFromConfig = o.check && o.adapter === undefined;
+    const readConfig = o.file === undefined || needAdapterFromConfig;
+    let top = null;
+    let config = null;
+    if (readConfig)
+        ({ config, top } = findProjectConfig(o.config, o.file !== undefined ? dirname(resolve(o.file)) : process.cwd()));
+    let file;
+    if (o.file !== undefined)
+        file = o.file;
+    else if (config !== null) {
+        if (config.ontology === null)
+            throw new Error(`${config.file}: ontology: missing`);
+        if (!isFile(config.ontology))
+            throw new Error(`${config.file}: ontology: file not found`);
+        file = config.ontology;
+    }
+    else {
+        // no -f, no --config (a --config always gives a configuration): the git top level is the only place left to look
+        if (top === null)
+            throw new Error("no -f and no --config, and the working directory is not in a git repository (or git is not available)");
+        const dflt = join(top, "avouch", "avouch.ontology.yaml");
+        if (!existsSync(dflt))
+            throw new Error(`no -f, no ${CONFIG_FILE} at ${top}, and ${dflt} does not exist; ${SETUP_HINT}`);
+        file = dflt;
+    }
+    if (!o.check)
+        return { file, adapter: null };
+    if (o.adapter !== undefined)
+        return { file, adapter: adapterFromArgument(o.adapter) };
+    if (config === null) {
+        const dir = dirname(resolve(file));
+        const where = top !== null ? join(top, CONFIG_FILE) : CONFIG_FILE;
+        const rel = top !== null ? relative(top, join(dir, "avouch.json")) : join(dir, "avouch.json");
+        const old = existsSync(join(dir, "avouch.json")) ? `; ${join(dir, "avouch.json")} is no longer read: set "adapter": "${rel}" in ${CONFIG_FILE}, or pass --adapter ${join(dir, "avouch.json")}` : "";
+        throw new Error(`no adapter: pass --adapter, or set adapter in ${where}${old}; ${ADAPTER_HINT}`);
+    }
+    // a configuration without `ontology` has nothing to differ from -f
+    if (o.file !== undefined && config.ontology !== null && real(o.file) !== real(config.ontology))
+        throw new Error(`-f ${o.file} is not the ontology in ${config.file} (${config.ontology}): pass --adapter`);
+    if (!("written" in config.adapter))
+        return { file, adapter: config.adapter };
+    // the stamp holds the string as written, as --adapter stamps its argument as given
+    if (!isFile(config.adapter.path))
+        throw new Error(`${config.file}: adapter: file not found`);
+    return { file, adapter: { ...adapterFromArgument(config.adapter.path), label: config.adapter.written } };
+}
+/**
+ * The project of `avouch gate docs`: --config, else avouch.config.json at the git top level of the working directory.
+ * The ledger file is `ledger.file` (default avouch.ledger.jsonl), relative to the configuration file. The documents are
+ * `ledger.docs`, else the docs of the Markdown adapter; a module adapter has no docs, so it needs `ledger.docs`.
+ */
+export function resolveLedger(configOption) {
+    let configFile;
+    let label = CONFIG_FILE;
+    if (configOption !== undefined) {
+        if (!isFile(configOption))
+            throw new Error(`--config ${configOption}: file not found`);
+        configFile = label = configOption;
+    }
+    else {
+        const top = gitTop(process.cwd());
+        if (top === null)
+            throw new Error("no --config, and the working directory is not in a git repository (or git is not available)");
+        configFile = join(top, CONFIG_FILE);
+        if (!existsSync(configFile))
+            throw new Error(`no --config, and no ${CONFIG_FILE} at ${top}; ${SETUP_HINT}`);
+    }
+    const c = loadProjectConfig(configFile, label);
+    if (c.ontology === null)
+        throw new Error(`${configFile}: ontology: missing`);
+    const ontology = c.ontology;
+    const dir = dirname(resolve(configFile));
+    let base = dir;
+    let docs;
+    if (c.ledger?.docs !== undefined)
+        docs = c.ledger.docs;
+    else if (!("written" in c.adapter))
+        docs = c.adapter.kind === "markdown" ? c.adapter.config.docs : [];
+    else if (!c.adapter.written.endsWith(".json"))
+        throw new Error(`${configFile}: ledger.docs: missing (required with a module adapter)`);
+    else {
+        if (!isFile(c.adapter.path))
+            throw new Error(`${configFile}: adapter: file not found`);
+        docs = parseMarkdownConfig(readFileSync(c.adapter.path, "utf8"), c.adapter.written).docs;
+        base = dirname(c.adapter.path);
+    }
+    const rel = docs.map((d) => relative(dir, resolve(base, d)).split(sep).join("/"));
+    // file identity (device and inode), as in readDocs: a case variant on a case-insensitive file system or a link is the same document
+    const ids = rel.map((d) => {
+        try {
+            const st = statSync(resolve(dir, d));
+            return `${st.dev}:${st.ino}`;
+        }
+        catch (error) {
+            throw new Error(`${configFile}: ledger: ${d}: ${error.message}`);
+        }
+    });
+    ids.forEach((id, j) => {
+        if (ids.indexOf(id) !== j)
+            throw new Error(`${configFile}: ledger: document ${rel[j]} is named twice`);
+    });
+    if (!isFile(ontology))
+        throw new Error(`${configFile}: ontology: file not found`);
+    return { config: configFile, dir, ledger: resolve(dir, c.ledger?.file ?? "avouch.ledger.jsonl"), ontology, docs: rel };
+}
+// Reads the documents of a Markdown configuration (paths relative to the configuration file).
+export function readDocs(a) {
+    const cfg = a.config;
+    const docError = (i, error) => new Error(`${a.where}: docs[${i}]: ${error.message}`);
+    const paths = cfg.docs.map((doc) => resolve(a.dir, doc));
+    // file identity (device and inode), so a case variant on a case-insensitive file system or a link is a duplicate too
+    const ids = paths.map((path, i) => {
+        try {
+            const st = statSync(path);
+            return `${st.dev}:${st.ino}`;
+        }
+        catch (error) {
+            throw docError(i, error);
+        }
+    });
+    ids.forEach((id, j) => {
+        const i = ids.indexOf(id);
+        if (i !== j)
+            throw new Error(`${a.where}: docs[${j}]: duplicate of docs[${i}]`);
+    });
+    return paths.map((path, i) => {
+        try {
+            return { path: cfg.docs[i], text: readFileSync(path, "utf8") };
+        }
+        catch (error) {
+            throw docError(i, error);
+        }
+    });
+}
+// Built-in Markdown adapter: reads its documents.
+const markdownAdapter = (a) => markdownFacts(readDocs(a), a.config);
+/**
+ * The Markdown configuration of `avouch facts`: --adapter, else the `adapter` of the project configuration (--config, else
+ * avouch.config.json at the git top level of the working directory). Reads no ontology. A module adapter is an error.
+ */
+export function resolveMarkdownAdapter(o) {
+    if (o.config !== undefined && !isFile(o.config))
+        throw new Error(`--config ${o.config}: file not found`);
+    let adapter;
+    if (o.adapter !== undefined)
+        adapter = adapterFromArgument(o.adapter);
+    else {
+        const { config, top } = findProjectConfig(o.config, process.cwd());
+        if (config === null)
+            throw new Error(`facts: no adapter: pass --adapter, or set adapter in ${top !== null ? join(top, CONFIG_FILE) : CONFIG_FILE}; ${ADAPTER_HINT}`);
+        if ("written" in config.adapter) {
+            if (!isFile(config.adapter.path))
+                throw new Error(`${config.file}: adapter: file not found`);
+            adapter = { ...adapterFromArgument(config.adapter.path), label: config.adapter.written };
+        }
+        else
+            adapter = config.adapter;
+    }
+    if (adapter.kind !== "markdown")
+        throw new Error("facts: the adapter must be a Markdown configuration");
+    return adapter;
+}
+// Runs the JSON Schema validator and the checker on one ontology file with one adapter: a module that exports `facts`, or the
+// configuration of the built-in Markdown adapter. Shared by `avouch check` and the `--check` of `query` and `gate verify`,
+// so all report the same counts.
+export async function runCheck(ontologyFile, adapter) {
+    const ontologyPath = resolve(ontologyFile);
+    const schema = JSON.parse(readFileSync(new URL("../../ontology.schema.json", import.meta.url), "utf8"));
+    const ontology = parse(readFileSync(ontologyPath, "utf8"));
+    let facts;
+    if (adapter.kind === "markdown")
+        facts = markdownAdapter(adapter);
+    else {
+        const mod = await import(pathToFileURL(adapter.path).href);
+        if (typeof mod.facts !== "function")
+            throw new Error("adapter must export a named facts function");
+        facts = await mod.facts(ontologyPath);
+    }
+    const validate = new Ajv2020({ allErrors: true, allowUnionTypes: true }).compile(schema);
+    validate(ontology);
+    const schemaErrors = validate.errors ?? [];
+    const report = check(ontology, facts);
+    return { schemaErrors, report };
+}
+/** The `check` of a query or gate stamp: the check run with the adapter, or `not_run` when there is no adapter. */
+export async function checkStamp(ontologyFile, adapter) {
+    if (adapter === null)
+        return { status: "not_run" };
+    const { schemaErrors, report } = await runCheck(ontologyFile, adapter);
+    const pass = schemaErrors.length === 0 && report.violations.length === 0;
+    return { status: pass ? "pass" : "fail", adapter: adapter.label, schemaErrors: schemaErrors.length, violations: report.violations.length, waived: report.waived.length };
+}
+/** The project of a query or gate command: the check runs with --check, or with --adapter. */
+export function resolveQueryProject(opts) {
+    const adapter = opts.get("--adapter");
+    return resolveProject({ file: opts.get("-f"), config: opts.get("--config"), adapter, check: opts.get("--check") === true || adapter !== undefined });
+}

package/dist/cli/facts.d.ts

@@ -0,0 +1,3 @@
+export declare const FACTS_USAGE = "usage: avouch facts [--config <avouch.config.json>] [--adapter <config.json>] [--json] [--inventory <file.json>]";
+/** `avouch facts`: parses the documents with the built-in Markdown adapter, with no ontology, and reports what it read. */
+export declare function runFacts(args: string[]): Promise<number>;

package/dist/cli/facts.js

@@ -0,0 +1,157 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isObj } from "../src/expr.js";
+import { markdownFacts, markdownTextBlocks } from "../src/markdown.js";
+import { readDocs, resolveMarkdownAdapter } from "./check.js";
+import { expectPositionals, parseOptions, wantsHelp } from "./reconcile.js";
+export const FACTS_USAGE = "usage: avouch facts [--config <avouch.config.json>] [--adapter <config.json>] [--json] [--inventory <file.json>]";
+const NAMES = ["storeCatalog", "eventCatalog", "contextMembers", "permissions", "scenarios", "stateMachines", "transitionTriggers"];
+const sorted = (xs) => [...xs].sort();
+const byKey = (entries) => Object.fromEntries([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+/** A configured fact: the `FACT` lines and the JSON value (Sets as sorted arrays, Maps as objects with sorted keys), or null when it is not configured. */
+function describeFact(name, facts, config) {
+    const line = (anchor, text, object = "") => `FACT ${name}${object} ${anchor}: ${text}`;
+    const anchor = name === "stateMachines" ? "" : config.facts[name];
+    if (name === "stateMachines" ? facts.stateMachines === undefined : anchor === undefined)
+        return null;
+    switch (name) {
+        case "storeCatalog":
+        case "eventCatalog": {
+            const x = facts[name].value;
+            return { lines: [line(anchor, `${x.size} names`)], json: sorted(x) };
+        }
+        case "contextMembers": {
+            const x = facts.contextMembers;
+            return { lines: [line(anchor, `${x.size} contexts`)], json: byKey([...x].map(([c, m]) => [c, sorted(m.value)])) };
+        }
+        case "permissions": {
+            const x = facts.permissions;
+            return {
+                lines: [line(anchor, `${x.catalog.value.size} catalog names, ${x.rows.value.size} rows`)],
+                json: { catalog: sorted(x.catalog.value), rows: byKey([...x.rows.value].map(([n, r]) => [n, sorted(r.keys)])) },
+            };
+        }
+        case "scenarios": {
+            const x = facts.scenarios;
+            return { lines: [line(anchor, `${x.ids.size} scenarios`)], json: byKey([...x.cites].map(([id, c]) => [id, sorted(c)])) };
+        }
+        case "stateMachines": {
+            const x = facts.stateMachines;
+            return {
+                lines: [...x].map(([o, m]) => line(m.source.anchor, m.value === null ? "null" : `${m.value.nodes.length} states, ${m.value.edges.length} edges`, `.${o}`)),
+                json: byKey([...x].map(([o, m]) => [o, m.value === null ? null : { nodes: sorted(m.value.nodes), initial: sorted(m.value.initial), edges: sorted(m.value.edges) }])),
+            };
+        }
+        case "transitionTriggers": {
+            const x = facts.transitionTriggers;
+            const edges = [...x.values()].reduce((n, m) => n + m.size, 0);
+            return { lines: [line(anchor, `${edges} edges`)], json: byKey([...x].map(([o, m]) => [o, byKey([...m].map(([e, t]) => [e, sorted(t.value)]))])) };
+        }
+    }
+}
+const show = (x) => (x === undefined ? "(absent)" : JSON.stringify(x));
+/** Differences between the inventory and the parse result, one `DIFF <path>: inventory <x>, document <y>` line each. An array is compared as a set of strings. */
+function diff(path, inv, doc, out) {
+    if (Array.isArray(inv) && Array.isArray(doc) && inv.every((x) => typeof x === "string") && doc.every((x) => typeof x === "string")) {
+        if (JSON.stringify(sorted(inv)) !== JSON.stringify(sorted(doc)))
+            out.push(`DIFF ${path}: inventory ${show(sorted(inv))}, document ${show(sorted(doc))}`);
+    }
+    else if (isObj(inv) && isObj(doc)) {
+        for (const k of sorted(new Set([...Object.keys(inv), ...Object.keys(doc)])))
+            diff(`${path}.${k}`, inv[k], doc[k], out);
+    }
+    else if (JSON.stringify(inv) !== JSON.stringify(doc))
+        out.push(`DIFF ${path}: inventory ${show(inv)}, document ${show(doc)}`);
+}
+/** The inventory file: `{"conventionVersion": 1, "facts": {...}, "fields": {...}, "prose": [...]}`. Throws on any other shape. */
+function readInventory(file) {
+    const fail = (problem) => {
+        throw new Error(`${file}: ${problem}`);
+    };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(resolve(file), "utf8"));
+    }
+    catch (error) {
+        return fail(`not valid JSON: ${error.message}`);
+    }
+    if (!isObj(raw))
+        return fail("the root must be an object");
+    for (const k of Object.keys(raw))
+        if (!["conventionVersion", "facts", "fields", "prose"].includes(k))
+            fail(`${k}: unknown key`);
+    if (raw.conventionVersion !== 1)
+        fail("conventionVersion: must be 1");
+    if (!isObj(raw.facts))
+        fail("facts: must be an object");
+    if (!isObj(raw.fields))
+        fail("fields: must be an object");
+    if (!Array.isArray(raw.prose))
+        fail("prose: must be an array");
+    return { facts: raw.facts, fields: raw.fields };
+}
+/** `avouch facts`: parses the documents with the built-in Markdown adapter, with no ontology, and reports what it read. */
+export async function runFacts(args) {
+    if (wantsHelp(args, ["--config", "--adapter", "--inventory"])) {
+        console.log(FACTS_USAGE);
+        return 0;
+    }
+    let opts;
+    try {
+        const parsed = parseOptions(args, ["--config", "--adapter", "--inventory"], ["--json"]);
+        expectPositionals(parsed.pos, 0);
+        opts = parsed.opts;
+    }
+    catch (error) {
+        console.error((error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " "));
+        console.error(FACTS_USAGE);
+        return 2;
+    }
+    const adapter = resolveMarkdownAdapter({ config: opts.get("--config"), adapter: opts.get("--adapter") });
+    const inventory = opts.has("--inventory") ? readInventory(opts.get("--inventory")) : null;
+    const docs = readDocs(adapter);
+    const facts = markdownFacts(docs, adapter.config);
+    const lines = [];
+    const factsJson = {};
+    for (const name of NAMES) {
+        const d = describeFact(name, facts, adapter.config);
+        if (d === null)
+            lines.push(`FACT ${name}: not configured`);
+        else {
+            lines.push(...d.lines);
+            factsJson[name] = d.json;
+        }
+    }
+    const fieldsJson = {};
+    const warnings = [];
+    for (const b of markdownTextBlocks(docs)) {
+        const key = `${b.anchor}#${b.first}`;
+        lines.push(`FIELDS ${key}: ${b.fields.size} field(s)`);
+        for (const s of b.strays)
+            warnings.push(`${b.doc}:${s.line}: ${key}: line is not a field line: ${s.text}`);
+        if (Object.hasOwn(fieldsJson, key))
+            warnings.push(`${b.doc}:${b.line}: ${key}: another text block has the same section anchor and first line; this one is not in the fields`);
+        else
+            fieldsJson[key] = byKey(b.fields);
+    }
+    lines.push(...warnings.map((w) => `WARN ${w}`));
+    const diagnostics = facts.diagnostics.map(({ rule, kind, key, msg }) => ({ rule, kind, key, msg }));
+    lines.push(...diagnostics.map((d) => `DIAG ${d.rule} ${d.kind} ${d.key}: ${d.msg}`));
+    const differences = [];
+    if (inventory !== null) {
+        diff("facts", inventory.facts, factsJson, differences);
+        diff("fields", inventory.fields, fieldsJson, differences);
+    }
+    const ok = diagnostics.length === 0 && differences.length === 0;
+    if (opts.get("--json") === true) {
+        console.log(JSON.stringify({ facts: factsJson, fields: fieldsJson, warnings, diagnostics, ...(inventory !== null ? { differences } : {}) }, null, 2));
+    }
+    else {
+        for (const l of lines)
+            console.log(l);
+        for (const d of differences)
+            console.log(d);
+        console.log(diagnostics.length === 0 ? "OK: 0 diagnostic(s)" : `FAIL: ${diagnostics.length} diagnostic(s)`);
+    }
+    return ok ? 0 : 1;
+}

package/dist/cli/gate.d.ts

@@ -0,0 +1,3 @@
+export declare const GATE_USAGE = "usage: avouch gate verify [-f <ontology.yaml>] --rows <rows.jsonl> [--baseline <baseline.json>] [--json] [--check] [--config <avouch.config.json>] [--adapter <module|config.json>]";
+export declare const GATE_DOCS_USAGE = "usage: avouch gate docs [--config <avouch.config.json>] [--json]";
+export declare function runGate(args: string[]): Promise<number>;