avouch 0.1.22

package/dist/cli/reconcile.js

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "yaml";
+import { isObj } from "../src/expr.js";
+import { reconcile } from "../src/reconcile.js";
+import { resolveProject } from "./check.js";
+import { jsonLines } from "./jsonl.js";
+export const RECONCILE_USAGE = "usage: avouch reconcile [-f <ontology.yaml>] [--config <avouch.config.json>] --cases <cases.jsonl>";
+const REASONS = ["missing", "unknown_param", "type", "not_found"];
+// Options in any position. Returns the positional arguments and the value of each option.
+export function parseOptions(args, values, flags) {
+    const pos = [];
+    const opts = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (opts.has(a))
+            throw new Error(`repeated option ${a}`);
+        if (flags.includes(a))
+            opts.set(a, true);
+        else if (values.includes(a)) {
+            if (i + 1 >= args.length || args[i + 1] === "")
+                throw new Error(`${a} needs a file`);
+            opts.set(a, args[++i]);
+        }
+        else if (a.startsWith("-"))
+            throw new Error(`unknown option ${a}`);
+        else
+            pos.push(a);
+    }
+    return { pos, opts };
+}
+// True when --help or -h is a whole argument that is not the value of an option in `values`.
+export function wantsHelp(args, values) {
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--help" || args[i] === "-h")
+            return true;
+        if (values.includes(args[i]))
+            i++;
+    }
+    return false;
+}
+// Exactly n positional arguments. A word of the old form (an ontology file as an argument) gets a pointer to -f.
+export function expectPositionals(pos, n) {
+    if (pos.length === n)
+        return;
+    const old = pos.find((a) => /\.ya?ml$/.test(a));
+    throw new Error(old !== undefined ? `unexpected argument ${old}: give the ontology with -f` : `expected ${n} argument(s), found ${pos.length}`);
+}
+export function readOntology(file) {
+    const ont = parse(readFileSync(resolve(file), "utf8"));
+    if (!isObj(ont))
+        throw new Error(`${file}: the root is not a mapping`);
+    return ont;
+}
+// The shape of a RuntimeCase (SPEC section 9). Extra keys are allowed; the snapshot content is not checked.
+function checkCase(x) {
+    if (!isObj(x))
+        return "case is not an object";
+    const c = x;
+    if (typeof c.id !== "string" || c.id === "")
+        return "id is not a non-empty string";
+    if (typeof c.action !== "string" || c.action === "")
+        return "action is not a non-empty string";
+    if (!Object.hasOwn(c, "snapshot"))
+        return "snapshot is missing";
+    if (c.snapshot !== null && !isObj(c.snapshot))
+        return "snapshot is not null or an object";
+    const i = c.inputs;
+    if (!isObj(i))
+        return "inputs is not an object";
+    if (!isObj(i.bindings))
+        return "inputs.bindings is not an object";
+    if (!isObj(i.actor))
+        return "inputs.actor is not an object";
+    if (typeof i.actor.id !== "string")
+        return "inputs.actor.id is not a string";
+    if (typeof i.actor.kind !== "string")
+        return "inputs.actor.kind is not a string";
+    if (!Array.isArray(i.actor.keys) || !i.actor.keys.every((k) => typeof k === "string"))
+        return "inputs.actor.keys is not a list of strings";
+    if (i.scope !== null && typeof i.scope !== "string")
+        return "inputs.scope is not a string or null";
+    if (typeof i.now !== "number" || !Number.isFinite(i.now))
+        return "inputs.now is not a finite number";
+    for (const k of ["reported", "expected"]) {
+        if (!Object.hasOwn(c, k))
+            return `${k} is missing`;
+        const r = c[k];
+        if (r === null)
+            continue;
+        if (!isObj(r))
+            return `${k} is not null or an object`;
+        if (typeof r.result !== "string" || r.result === "")
+            return `${k}.result is not a non-empty string`;
+        if (r.reason !== undefined && !REASONS.includes(r.reason))
+            return `${k}.reason is not one of ${REASONS.join(", ")}`;
+    }
+    return null;
+}
+async function main(args) {
+    const { pos, opts } = parseOptions(args, ["-f", "--config", "--cases"], []);
+    expectPositionals(pos, 0);
+    const cases = opts.get("--cases");
+    if (typeof cases !== "string")
+        throw new Error("--cases is required");
+    const ont = readOntology(resolveProject({ file: opts.get("-f"), config: opts.get("--config"), check: false }).file);
+    const lines = jsonLines(cases);
+    for (const { line, value } of lines) {
+        const problem = checkCase(value);
+        if (problem !== null)
+            throw new Error(`${cases}:${line}: ${problem}`);
+    }
+    const rows = reconcile(ont, lines.map((x) => x.value));
+    process.stdout.write(rows.map((r) => `${JSON.stringify(r)}\n`).join(""));
+    return 0;
+}
+// Exit 0: one row per case (the command does not judge the rows); 2: a usage, file, parse or shape error (one stderr line).
+export async function runReconcile(args) {
+    if (wantsHelp(args, ["-f", "--config", "--cases"])) {
+        console.log(RECONCILE_USAGE);
+        return 0;
+    }
+    try {
+        return await main(args);
+    }
+    catch (error) {
+        const msg = (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ");
+        console.error(`${msg}; ${RECONCILE_USAGE}`);
+        return 2;
+    }
+}

package/dist/src/checker.d.ts

@@ -0,0 +1,3 @@
+import { IDENT, type Report, type SourceFacts } from "./contract.js";
+export { IDENT };
+export declare function check(ontology: unknown, facts: SourceFacts): Report;