avouch 0.1.22

package/dist/cli/gate.js

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { verifyCoverage } from "../src/coverage.js";
+import { parseLedger, unitKeyText, verifyLedger } from "../src/ledger.js";
+import { checkStamp, resolveLedger, resolveQueryProject } from "./check.js";
+import { jsonLines, readJsonLines } from "./jsonl.js";
+import { expectPositionals, parseOptions, readOntology, wantsHelp } from "./reconcile.js";
+export 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 const GATE_DOCS_USAGE = "usage: avouch gate docs [--config <avouch.config.json>] [--json]";
+const unitText = (row) => (row === "otherwise" ? "otherwise" : `rows.${row}`);
+function text(check, r, pass) {
+    const lines = [];
+    if (check.status === "fail")
+        lines.push(`FAIL check: ${check.schemaErrors} schema error(s), ${check.violations} violation(s)`);
+    for (const u of r.uncovered)
+        lines.push(`FAIL uncovered ${u.action}:${unitText(u.row)}`);
+    for (const g of r.unexempted)
+        lines.push(`FAIL unexempted ${g.action}:${g.condition}`);
+    for (const g of r.unreasoned)
+        lines.push(`FAIL unreasoned ${g.action}:${g.condition}`);
+    for (const s of r.stale)
+        lines.push(s.list === "uncovered" ? `FAIL stale uncovered ${s.action}:${unitText(s.row)} ${s.why}` : `FAIL stale exempt ${s.action}:${s.condition} ${s.why}`);
+    for (const f of r.failed)
+        lines.push(`FAIL case ${f.id} ${f.action} ${f.why}`);
+    lines.push(`INFO check ${check.status}`);
+    for (const b of r.blocked)
+        lines.push(`INFO blocked ${b.action}:${unitText(b.row)} by ${b.condition}`);
+    for (const a of r.noTable)
+        lines.push(`INFO no_table ${a}`);
+    for (const c of r.unasserted)
+        lines.push(`INFO unasserted ${c.id} ${c.action}`);
+    lines.push(`${pass ? "PASS" : "FAIL"}: ${r.units} unit(s), ${r.verified.length} verified, ${r.baselined.length} baselined, ${r.blocked.length} blocked, ` +
+        `${r.uncovered.length} uncovered; ${r.unexempted.length} unexempted, ${r.unreasoned.length} unreasoned, ${r.stale.length} stale, ` +
+        `${r.failed.length} failed case(s), ${r.unasserted.length} unasserted`);
+    return lines.join("\n") + "\n";
+}
+async function verify(args) {
+    const { pos, opts } = parseOptions(args, ["-f", "--rows", "--baseline", "--config", "--adapter"], ["--json", "--check"]);
+    expectPositionals(pos, 0);
+    const rowsFile = opts.get("--rows");
+    if (typeof rowsFile !== "string")
+        throw new Error("--rows is required");
+    const baselineFile = opts.get("--baseline");
+    const { file, adapter } = resolveQueryProject(opts);
+    const ont = readOntology(file);
+    const rows = readJsonLines(rowsFile);
+    let baseline = null;
+    if (baselineFile !== undefined) {
+        const raw = readFileSync(resolve(baselineFile), "utf8");
+        try {
+            baseline = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`${baselineFile}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    let result;
+    try {
+        result = verifyCoverage(ont, rows, baseline);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`${msg.startsWith("baseline:") ? baselineFile : msg.startsWith("ontology:") ? file : rowsFile}: ${msg}`);
+    }
+    const check = await checkStamp(file, adapter);
+    const pass = result.ok && check.status !== "fail";
+    process.stdout.write(opts.get("--json") === true ? `${JSON.stringify({ avouchGate: 1, gate: "verify", check, result }, null, 2)}\n` : text(check, result, pass));
+    return pass ? 0 : 1;
+}
+const sha256 = (text) => createHash("sha256").update(text, "utf8").digest("hex");
+function docsText(r) {
+    const lines = [];
+    for (const u of r.changed)
+        lines.push(`FAIL changed ${unitKeyText(u)}`);
+    for (const u of r.unreviewed)
+        lines.push(`FAIL unreviewed ${unitKeyText(u)}`);
+    for (const s of r.stale)
+        lines.push(`FAIL stale ${"outline" in s ? `${s.doc} outline` : unitKeyText(s)}`);
+    for (const o of r.outline)
+        lines.push(`FAIL outline ${o.doc}`);
+    for (const d of r.dangling)
+        lines.push(`FAIL dangling ${unitKeyText(d)} ${d.pointer}`);
+    lines.push(`${r.ok ? "PASS" : "FAIL"}: ${r.docs} document(s), ${r.units} unit(s), ${r.emptyUnits} empty unit(s); ${r.changed.length} changed, ` +
+        `${r.unreviewed.length} unreviewed, ${r.stale.length} stale, ${r.outline.length} outline, ${r.dangling.length} dangling`);
+    return lines.join("\n") + "\n";
+}
+async function docs(args) {
+    const { pos, opts } = parseOptions(args, ["--config"], ["--json"]);
+    expectPositionals(pos, 0);
+    const p = resolveLedger(opts.get("--config"));
+    if (!existsSync(p.ledger))
+        throw new Error(`${p.ledger}: file not found`);
+    let entries;
+    try {
+        entries = parseLedger(jsonLines(p.ledger, readFileSync(p.ledger, "utf8").replace(/^\ufeff/, "")));
+    }
+    catch (error) {
+        const msg = error.message;
+        throw new Error(msg.startsWith(`${p.ledger}:`) ? msg : `${p.ledger}:${msg}`);
+    }
+    const ont = readOntology(p.ontology);
+    const texts = p.docs.map((doc) => {
+        try {
+            return { doc, text: readFileSync(resolve(p.dir, doc), "utf8") };
+        }
+        catch (error) {
+            throw new Error(`${p.config}: ledger: ${doc}: ${error.message}`);
+        }
+    });
+    const result = verifyLedger(texts, entries, ont, sha256);
+    process.stdout.write(opts.get("--json") === true ? `${JSON.stringify({ avouchGate: 1, gate: "docs", result }, null, 2)}\n` : docsText(result));
+    return result.ok ? 0 : 1;
+}
+// Exit 0: the gate passes; 1: it fails; 2: a usage, file, parse or shape error, or an adapter error (one stderr line).
+export async function runGate(args) {
+    let usage = `${GATE_USAGE}; ${GATE_DOCS_USAGE}`;
+    try {
+        if (args[0] === "--help" || args[0] === "-h") {
+            console.log(GATE_USAGE);
+            console.log(GATE_DOCS_USAGE);
+            return 0;
+        }
+        if (args.length === 0)
+            throw new Error("missing gate");
+        if (args[0] === "verify") {
+            usage = GATE_USAGE;
+            if (wantsHelp(args.slice(1), ["-f", "--rows", "--baseline", "--config", "--adapter"])) {
+                console.log(usage);
+                return 0;
+            }
+            return await verify(args.slice(1));
+        }
+        if (args[0] === "docs") {
+            usage = GATE_DOCS_USAGE;
+            if (wantsHelp(args.slice(1), ["--config"])) {
+                console.log(usage);
+                return 0;
+            }
+            return await docs(args.slice(1));
+        }
+        throw new Error(`unknown gate ${args[0]}`);
+    }
+    catch (error) {
+        const msg = (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ");
+        console.error(`${msg}; ${usage}`);
+        return 2;
+    }
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,21 @@
+import { type SpawnSyncOptions } from "node:child_process";
+export declare const INIT_USAGE = "usage: avouch init [--append | --print] [--plugin | --no-plugin] [--dry-run]";
+/**
+ * Yes/no questions on one readline interface, made at the first question. Lines that arrive before a question is asked
+ * (typed ahead) are queued and answer the next questions in order; at the end of input a question gets no (an empty answer).
+ */
+export declare function createAsker(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): {
+    ask: (question: string) => Promise<boolean>;
+    close: () => void;
+};
+/**
+ * How to run `claude` with fixed arguments. On Windows `claude` is usually `claude.cmd`, which only a shell can run; the
+ * arguments are constants, so the command line is safe for the shell. Elsewhere no shell.
+ */
+export declare function pluginSpawn(args: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+    options: SpawnSyncOptions;
+};
+/** `avouch init`. Exit 0: done (also the print fallback and a dry run); 1: a plugin command failed or a file could not be written; 2: a usage error or not in a git repository. */
+export declare function runInit(args: string[]): Promise<number>;

package/dist/cli/init.js

@@ -0,0 +1,282 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { createInterface } from "node:readline";
+import { fences } from "../src/markdown.js";
+import { gitTop } from "./check.js";
+import { expectPositionals, parseOptions, wantsHelp } from "./reconcile.js";
+export const INIT_USAGE = "usage: avouch init [--append | --print] [--plugin | --no-plugin] [--dry-run]";
+const FLAGS = ["--append", "--print", "--plugin", "--no-plugin", "--dry-run"];
+const PLUGIN_COMMANDS = [
+    ["plugin", "marketplace", "add", "githonllc/avouch"],
+    ["plugin", "install", "avouch@avouch"],
+];
+const BEGIN = "<!-- BEGIN avouch -->";
+const END = "<!-- END avouch -->";
+const TARGETS = ["AGENTS.md", "CLAUDE.md"];
+const isTty = () => process.stdin.isTTY === true && process.stdout.isTTY === true;
+const commandLine = (args) => `claude ${args.join(" ")}`;
+/**
+ * Yes/no questions on one readline interface, made at the first question. Lines that arrive before a question is asked
+ * (typed ahead) are queued and answer the next questions in order; at the end of input a question gets no (an empty answer).
+ */
+export function createAsker(input, output) {
+    let rl;
+    let ended = false;
+    const lines = [];
+    const waiting = [];
+    const next = () => {
+        if (lines.length > 0)
+            return Promise.resolve(lines.shift());
+        if (ended)
+            return Promise.resolve("");
+        return new Promise((resolve) => waiting.push(resolve));
+    };
+    return {
+        ask: async (question) => {
+            if (rl === undefined) {
+                rl = createInterface({ input, output });
+                rl.on("line", (line) => (waiting.length > 0 ? waiting.shift()(line) : lines.push(line)));
+                rl.on("close", () => {
+                    ended = true;
+                    for (const resolve of waiting.splice(0))
+                        resolve("");
+                });
+            }
+            if (ended)
+                output.write(`${question} [y/N] \n`);
+            else {
+                rl.setPrompt(`${question} [y/N] `);
+                rl.prompt();
+            }
+            return /^y(es)?$/i.test((await next()).trim());
+        },
+        close: () => rl?.close(),
+    };
+}
+let asker = createAsker(process.stdin, process.stdout);
+const ask = (question) => asker.ask(question);
+/**
+ * How to run `claude` with fixed arguments. On Windows `claude` is usually `claude.cmd`, which only a shell can run; the
+ * arguments are constants, so the command line is safe for the shell. Elsewhere no shell.
+ */
+export function pluginSpawn(args, platform = process.platform) {
+    return platform === "win32"
+        ? { command: commandLine(args), args: [], options: { stdio: "inherit", shell: true } }
+        : { command: "claude", args, options: { stdio: "inherit" } };
+}
+// True when an executable file named `claude` is in a PATH directory.
+function claudeOnPath() {
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (dir === "")
+            continue;
+        for (const name of process.platform === "win32" ? ["claude.exe", "claude.cmd", "claude"] : ["claude"]) {
+            const path = join(dir, name);
+            try {
+                if (!statSync(path).isFile())
+                    continue;
+                accessSync(path, constants.X_OK);
+                return true;
+            }
+            catch {
+                // not there or not executable
+            }
+        }
+    }
+    return false;
+}
+/** The agent instructions, wrapped in the markers, with `eol` line endings. */
+function wrappedBlock(eol) {
+    const block = readFileSync(new URL("../../templates/agents-block.md", import.meta.url), "utf8").replace(/\r\n/g, "\n").replace(/\n+$/, "");
+    return `${BEGIN}\n${block}\n${END}\n`.replace(/\n/g, eol);
+}
+const BOM = "\xef\xbb\xbf"; // the UTF-8 byte order mark, as latin1 text
+/**
+ * The new bytes of one file, or an error when its markers are not exactly one BEGIN and one END in that order. The file is
+ * processed as latin1 (one byte, one character), so every byte outside the block is kept as it is, also a byte order mark
+ * and bytes that are not valid UTF-8; the block is written as UTF-8. A marker line starts at column 0 and is outside a
+ * fence (the fence rules of the Markdown convention); any such line that starts with "<!-- BEGIN avouch" or
+ * "<!-- END avouch" is a marker candidate and must be exactly a marker, trailing white space allowed.
+ */
+function planFile(file, content) {
+    const all = content.toString("latin1");
+    const bom = all.startsWith(BOM) ? BOM : "";
+    const body = all.slice(bom.length);
+    const eol = body.includes("\r\n") ? "\r\n" : "\n";
+    const block = Buffer.from(wrappedBlock(eol), "utf8");
+    const lines = body.match(/[^\n]*(\n|$)/g).filter((l, i, every) => l !== "" || i < every.length - 1);
+    const { inFence } = fences(lines.map((l) => l.replace(/\r?\n$/, "")));
+    const candidates = lines.flatMap((l, i) => (!inFence[i] && (l.startsWith("<!-- BEGIN avouch") || l.startsWith("<!-- END avouch")) ? [i] : []));
+    const bad = candidates.find((i) => ![BEGIN, END].includes(lines[i].replace(/[ \t\r\n]+$/, "")));
+    if (bad !== undefined) {
+        return { file, error: `${file}: line ${bad + 1} is not exactly "${BEGIN}" or "${END}": ${lines[bad].replace(/[ \t\r\n]+$/, "")}; the file is not changed` };
+    }
+    const begins = candidates.filter((i) => lines[i].startsWith(BEGIN));
+    const ends = candidates.filter((i) => lines[i].startsWith(END));
+    const latin1 = (text) => Buffer.from(text, "latin1");
+    if (candidates.length === 0) {
+        const sep = body === "" ? "" : `${/\n$/.test(body) ? "" : eol}${eol}`;
+        return { file, action: "append", bytes: Buffer.concat([content, latin1(sep), block]) };
+    }
+    if (begins.length !== 1 || ends.length !== 1 || begins[0] > ends[0]) {
+        return { file, error: `${file}: expected one "${BEGIN}" line and then one "${END}" line, found ${begins.length} and ${ends.length}${begins.length === 1 && ends.length === 1 ? " in the wrong order" : ""}; the file is not changed` };
+    }
+    const bytes = Buffer.concat([latin1(bom + lines.slice(0, begins[0]).join("")), block, latin1(lines.slice(ends[0] + 1).join(""))]);
+    return { file, action: bytes.equals(content) ? "unchanged" : "replace", bytes };
+}
+function printBlock() {
+    console.log("Add the text between the two cut lines to AGENTS.md (and, in CLAUDE.md, the line `@AGENTS.md`) yourself:");
+    console.log("-----8<----- Avouch agent instructions -----8<-----");
+    process.stdout.write(wrappedBlock("\n"));
+    console.log("-----8<----- end of the Avouch agent instructions -----8<-----");
+}
+/** Step 1: the Claude Code plugin. Returns false when a plugin command failed. */
+async function plugin(opts, dryRun) {
+    console.log("Step 1: the Avouch plugin for Claude Code (a hook that blocks text reads of an ontology, and the skills /avouch:scan and /avouch:cli).");
+    if (opts.has("--no-plugin")) {
+        console.log("Skipped (--no-plugin).");
+        return true;
+    }
+    const printCommands = (why) => {
+        console.log(`${why} To install the plugin, run:`);
+        for (const c of PLUGIN_COMMANDS)
+            console.log(`  ${commandLine(c)}`);
+    };
+    if (!claudeOnPath()) {
+        printCommands("No `claude` executable is on PATH.");
+        return true;
+    }
+    if (dryRun) {
+        if (opts.has("--plugin")) {
+            console.log("Dry run. These commands would run:");
+            for (const c of PLUGIN_COMMANDS)
+                console.log(`  ${commandLine(c)}`);
+        }
+        else
+            printCommands(`Dry run. Without --plugin, init would ${isTty() ? "ask before it runs these commands" : "only print these commands"}.`);
+        return true;
+    }
+    let run = opts.has("--plugin");
+    if (!run) {
+        if (!isTty()) {
+            printCommands("No terminal, so init does not run the commands.");
+            return true;
+        }
+        run = await ask("Install the Avouch plugin for Claude Code (user scope)?");
+        if (!run) {
+            printCommands("Not installed.");
+            return true;
+        }
+    }
+    let ok = true;
+    // Both commands run even when the first fails: adding a marketplace that is already added can fail while the install still works.
+    for (const c of PLUGIN_COMMANDS) {
+        console.log(`Running: ${commandLine(c)}`);
+        const s = pluginSpawn(c);
+        const r = spawnSync(s.command, s.args, s.options);
+        if (r.error !== undefined || r.status !== 0) {
+            ok = false;
+            console.error(`FAIL: ${commandLine(c)}: ${r.error !== undefined ? r.error.message : r.status !== null ? `exit ${r.status}` : `signal ${r.signal}`}`);
+        }
+    }
+    return ok;
+}
+/** Step 2: the agent instructions. Returns false when a file could not be written. */
+async function instructions(top, opts, dryRun) {
+    console.log("Step 2: the Avouch instructions for coding agents (AGENTS.md, CLAUDE.md).");
+    const exists = (name) => existsSync(join(top, name)) && statSync(join(top, name)).isFile();
+    const files = [];
+    for (const name of TARGETS) {
+        if (!exists(name))
+            continue;
+        if (name === "CLAUDE.md" && exists("AGENTS.md") && readFileSync(join(top, name), "utf8").split(/\r?\n/).some((l) => l.trim() === "@AGENTS.md")) {
+            console.log("CLAUDE.md is skipped: it has the line `@AGENTS.md`, so it imports the instructions from AGENTS.md.");
+            continue;
+        }
+        files.push(name);
+    }
+    let append = opts.has("--append");
+    if (!append && !opts.has("--print") && files.length > 0) {
+        if (dryRun) {
+            console.log("Dry run without --append or --print: this is the plan for --append (init asks in a terminal and prints otherwise).");
+            append = true;
+        }
+        else if (isTty())
+            append = await ask(`Append the Avouch instructions to ${files.join(", ")}?`);
+    }
+    if (!append) {
+        printBlock();
+        return true;
+    }
+    if (files.length === 0) {
+        console.log(`No file to append to: AGENTS.md and CLAUDE.md do not exist at ${top}, and init never creates a file.`);
+        printBlock();
+        return true;
+    }
+    let ok = true;
+    for (const name of files) {
+        const path = join(top, name);
+        const plan = planFile(name, readFileSync(path));
+        if ("error" in plan) {
+            ok = false;
+            console.error(`FAIL: ${plan.error}`);
+            continue;
+        }
+        if (dryRun) {
+            console.log(`Dry run: ${name}: ${plan.action === "unchanged" ? "unchanged" : `would ${plan.action === "append" ? "append the block" : "replace the block"}`}`);
+            continue;
+        }
+        if (plan.action === "unchanged") {
+            console.log(`${name}: unchanged (the block is up to date)`);
+            continue;
+        }
+        try {
+            writeFileSync(path, plan.bytes);
+            console.log(`${name}: ${plan.action === "append" ? "appended the block" : "replaced the block"}`);
+        }
+        catch (error) {
+            ok = false;
+            console.error(`FAIL: ${name}: ${error.message}`);
+        }
+    }
+    return ok;
+}
+/** `avouch init`. Exit 0: done (also the print fallback and a dry run); 1: a plugin command failed or a file could not be written; 2: a usage error or not in a git repository. */
+export async function runInit(args) {
+    if (wantsHelp(args, [])) {
+        console.log(INIT_USAGE);
+        return 0;
+    }
+    let opts;
+    try {
+        const parsed = parseOptions(args, [], FLAGS);
+        expectPositionals(parsed.pos, 0);
+        opts = parsed.opts;
+        if (opts.has("--append") && opts.has("--print"))
+            throw new Error("--append and --print cannot be used together");
+        if (opts.has("--plugin") && opts.has("--no-plugin"))
+            throw new Error("--plugin and --no-plugin cannot be used together");
+    }
+    catch (error) {
+        console.error((error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " "));
+        console.error(INIT_USAGE);
+        return 2;
+    }
+    const top = gitTop(process.cwd());
+    if (top === null) {
+        console.error("avouch init must run inside a git repository (or git is not available)");
+        return 2;
+    }
+    const dryRun = opts.has("--dry-run");
+    let pluginOk, filesOk;
+    try {
+        pluginOk = await plugin(opts, dryRun);
+        filesOk = await instructions(top, opts, dryRun);
+    }
+    finally {
+        asker.close();
+        asker = createAsker(process.stdin, process.stdout);
+    }
+    console.log("Step 3: next, run `/avouch:scan` in Claude Code at the top level of the repository. It drafts avouch.config.json, a first ontology and the document review ledger. The scan skill is for Claude Code only.");
+    return pluginOk && filesOk ? 0 : 1;
+}

package/dist/cli/jsonl.d.ts

@@ -0,0 +1,5 @@
+export declare function jsonLines(file: string, text?: string): {
+    line: number;
+    value: unknown;
+}[];
+export declare function readJsonLines(file: string): unknown[];

package/dist/cli/jsonl.js

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+// One JSON value per line, with its line number (from 1). Lines that are empty or only white space are skipped; the
+// line numbers count them. `text`: the text of the file, when the caller has read it.
+export function jsonLines(file, text = readFileSync(file, "utf8")) {
+    return text
+        .split("\n")
+        .flatMap((text, i) => {
+        if (text.trim() === "")
+            return [];
+        try {
+            return [{ line: i + 1, value: JSON.parse(text) }];
+        }
+        catch (error) {
+            throw new Error(`${file}:${i + 1}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export function readJsonLines(file) {
+    return jsonLines(file).map((x) => x.value);
+}

package/dist/cli/query.d.ts

@@ -0,0 +1,2 @@
+export declare const QUERY_USAGE = "usage: avouch query <list|action|object|result|writes|reads|cites|link> <arg> [-f <ontology.yaml>] [--json] [--check] [--config <avouch.config.json>] [--adapter <module|config.json>]";
+export declare function runQuery(args: string[]): Promise<number>;

package/dist/cli/query.js

@@ -0,0 +1,138 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { parse } from "yaml";
+import { isObj } from "../src/expr.js";
+import { QUERY_LIST_KINDS, queryAction, queryCites, queryDisposition, queryLink, queryList, queryObject, queryReads, queryWrites, } from "../src/query.js";
+import { checkStamp, resolveQueryProject } from "./check.js";
+import { expectPositionals, parseOptions, wantsHelp } from "./reconcile.js";
+export const QUERY_USAGE = "usage: avouch query <list|action|object|result|writes|reads|cites|link> <arg> [-f <ontology.yaml>] [--json] [--check] [--config <avouch.config.json>] [--adapter <module|config.json>]";
+const VERBS = ["list", "action", "object", "result", "writes", "reads", "cites", "link"];
+// Read-only git commands, run from the directory of the ontology file. null when any of them fails.
+function gitStamp(file) {
+    const git = (...args) => {
+        const r = spawnSync("git", ["--no-optional-locks", ...args], { cwd: dirname(file), encoding: "utf8" });
+        return r.error !== undefined || r.status !== 0 ? null : r.stdout;
+    };
+    const commit = git("rev-parse", "HEAD");
+    const top = git("rev-parse", "--show-toplevel");
+    const status = git("status", "--porcelain", "--", file);
+    if (commit === null || top === null || status === null)
+        return null;
+    // status prints nothing for an ignored file; a file that is not tracked is in no commit, so it is dirty.
+    const tracked = git("ls-files", "--error-unmatch", "--", file);
+    return { commit: commit.trim(), dirty: status.trim() !== "" || tracked === null, path: relative(top.trim(), file).split(sep).join("/") };
+}
+function run(verb, arg, ont) {
+    switch (verb) {
+        case "list": {
+            const r = queryList(ont, arg);
+            return { result: r, empty: r === null || r.items.length === 0 };
+        }
+        case "cites": {
+            const r = queryCites(ont, arg);
+            return { result: r, empty: r.claims.length === 0 };
+        }
+        default: {
+            const f = { action: queryAction, object: queryObject, result: queryDisposition, writes: queryWrites, reads: queryReads, link: queryLink }[verb];
+            const r = f(ont, arg);
+            return { result: r, empty: r === null };
+        }
+    }
+}
+// ---------------------------------------------------------------------------------------------------------- text
+const isScalar = (x) => x === null || typeof x !== "object";
+const isCite = (x) => isObj(x) && Object.keys(x).length === 2 && typeof x.doc === "string" && (typeof x.quote === "string" || x.quote === null);
+// A scalar on one line: a line break becomes the two characters \n (or \r).
+const esc = (x) => String(x).replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+// The one-line form of a value, or undefined when it needs a block.
+function inline(v) {
+    if (v === null || v === undefined)
+        return "-";
+    if (typeof v !== "object")
+        return esc(v);
+    if (isCite(v))
+        return v.quote === null ? `[${esc(v.doc)}]` : `[${esc(v.doc)}] ${esc(v.quote)}`;
+    if (Array.isArray(v)) {
+        if (v.length === 0)
+            return "-";
+        return v.every(isScalar) ? v.map((x) => (x === null ? "-" : esc(x))).join(", ") : undefined;
+    }
+    return Object.keys(v).length === 0 ? "-" : undefined;
+}
+function block(v, pad) {
+    if (Array.isArray(v))
+        return v.flatMap((el) => {
+            const s = inline(el);
+            if (s !== undefined)
+                return [`${pad}- ${s}`];
+            const sub = block(el, `${pad}  `);
+            if (sub.length === 0)
+                return [`${pad}- -`];
+            return [`${pad}- ${sub[0].slice(pad.length + 2)}`, ...sub.slice(1)];
+        });
+    const o = v;
+    return Object.keys(o)
+        .filter((k) => !(k === "expr" && "exprText" in o))
+        .flatMap((k) => {
+        const s = inline(o[k]);
+        return s !== undefined ? [`${pad}${k}: ${s}`] : [`${pad}${k}:`, ...block(o[k], `${pad}  `)];
+    });
+}
+function text(env) {
+    const { stamp } = env;
+    const c = stamp.check;
+    const lines = [
+        `ontology: ${stamp.ontology}`,
+        stamp.git === null ? "commit: none (not in git)" : `commit: ${stamp.git.commit}${stamp.git.dirty ? " (dirty)" : ""}`,
+        c.status === "not_run" ? "check: not_run" : `check: ${c.status} (${c.schemaErrors} schema error(s), ${c.violations} violation(s), ${c.waived} waived)`,
+        "",
+    ];
+    const s = inline(env.result);
+    return [...lines, ...(s !== undefined ? [s] : block(env.result, ""))].join("\n") + "\n";
+}
+// ---------------------------------------------------------------------------------------------------------- main
+function parseArgs(args) {
+    const { pos, opts } = parseOptions(args, ["-f", "--config", "--adapter"], ["--json", "--check"]);
+    expectPositionals(pos, 2);
+    const json = opts.get("--json") === true;
+    const [verb, arg] = pos;
+    if (!VERBS.includes(verb))
+        throw new Error(`unknown verb ${verb}`);
+    if (verb === "list" && !QUERY_LIST_KINDS.includes(arg))
+        throw new Error(`unknown list kind ${arg}`);
+    if ((verb === "writes" || verb === "reads") && arg.split(".").length !== 2)
+        throw new Error(`${verb} takes <Object>.<property>`);
+    const { file, adapter } = resolveQueryProject(opts);
+    return { verb: verb, arg, file, json, adapter };
+}
+async function query(args) {
+    const { verb, arg, file, json, adapter } = parseArgs(args);
+    const real = realpathSync(resolve(file));
+    const ont = parse(readFileSync(real, "utf8"));
+    if (!isObj(ont))
+        throw new Error(`${file}: the root is not a mapping`);
+    const check = await checkStamp(file, adapter);
+    const { result, empty } = run(verb, arg, ont);
+    const git = gitStamp(real);
+    // the stamp holds no absolute path: the path in the repository, or else the path from the working directory
+    const stampPath = git?.path ?? relative(realpathSync(process.cwd()), real).split(sep).join("/");
+    const env = { avouchQuery: 1, stamp: { ontology: stampPath, git, check }, verb, arg, result };
+    process.stdout.write(json ? `${JSON.stringify(env, null, 2)}\n` : text(env));
+    return empty ? 1 : 0;
+}
+// Exit 0: a result; 1: no result (null or an empty list); 2: a usage, file, parse or adapter error (one stderr line).
+export async function runQuery(args) {
+    if (wantsHelp(args, ["-f", "--config", "--adapter"])) {
+        console.log(QUERY_USAGE);
+        return 0;
+    }
+    try {
+        return await query(args);
+    }
+    catch (error) {
+        const msg = (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ");
+        console.error(`${msg}; ${QUERY_USAGE}`);
+        return 2;
+    }
+}

package/dist/cli/reconcile.d.ts

@@ -0,0 +1,9 @@
+export declare const RECONCILE_USAGE = "usage: avouch reconcile [-f <ontology.yaml>] [--config <avouch.config.json>] --cases <cases.jsonl>";
+export declare function parseOptions(args: string[], values: readonly string[], flags: readonly string[]): {
+    pos: string[];
+    opts: Map<string, string | true>;
+};
+export declare function wantsHelp(args: readonly string[], values: readonly string[]): boolean;
+export declare function expectPositionals(pos: string[], n: number): void;
+export declare function readOntology(file: string): Record<string, unknown>;
+export declare function runReconcile(args: string[]): Promise<number>;