aontu 0.55.0 → 0.56.0

package/dist/cli.js

@@ -20,6 +20,7 @@ exports.runWhy = runWhy;
 exports.renderWhyText = renderWhyText;
 exports.runSet = runSet;
 exports.runAgentsMd = runAgentsMd;
+exports.runFmt = runFmt;
 exports.watchChange = watchChange;
 exports.watchSignature = watchSignature;
 exports.deprecatedAt = deprecatedAt;
@@ -46,6 +47,8 @@ const vet_1 = require("./vet");
 const reach_1 = require("./reach");
 const view_1 = require("./view");
 const agentsmd_1 = require("./agentsmd");
+const format_1 = require("./format");
+const utility_1 = require("./utility");
 const HELP = `Usage: aontu [options] [file]
        aontu vet [options] <schema> <data> [more-data...]
        aontu subsume [options] <general> <specific>
@@ -62,6 +65,7 @@ const HELP = `Usage: aontu [options] [file]
        aontu why <path> [options] <file>
        aontu set <path>=<value>... --entry <file> --overlay <file>
        aontu agentsmd [--write <AGENTS.md>] <file>
+       aontu fmt [-w|-l|--check|-d] <file>...
 
 Evaluate an Aontu source file and print the result as JSON.
 With no file on an interactive terminal, start a REPL.
@@ -84,6 +88,10 @@ Options:
                   Every verb takes it too, and a bare root means the
                   document's own directory
   --include-root <dir>  Shorthand for --trust root:<dir>
+  --text-ext <e>  Read these extensions as text too, comma-separated
+                  and without dots (md,sql). .txt needs no flag; a
+                  named format keeps its meaning, and .js stays
+                  refused. Every verb takes it
 
 Mod options:
   --format <f>    text (default) or json
@@ -175,8 +183,8 @@ Why options:
 Why exit codes mirror get's: 0 explained, 1 the path names nothing,
 2 usage, 4 the document does not stand up on its own.
 
-View kinds: tree, matrix, graph, layer, sets, layers, ladder, poset
-(the poset takes several files). The figure goes to stdout, the loss
+View kinds: doc, lattice, tree, matrix, graph, layer, sets, layers,
+ladder, poset (the poset takes several files). The figure goes to stdout, the loss
 report to stderr. With --views it draws every figure a document
 declares as data, from one evaluation: each declaration names its own
 kind and out file, nothing is written unless every figure rendered,
@@ -184,13 +192,13 @@ and --check gates the committed set.
 
 View options:
   --as <profile>    text | mermaid | dot | er | svg, per kind: doc,
-                    tree, matrix, sets and layers draw text (default)
-                    or svg; graph draws mermaid (default), dot or er;
-                    layer draws text (default), mermaid or svg; ladder
-                    and poset draw mermaid (default) or dot
+                    lattice, tree, matrix, sets and layers draw text
+                    (default) or svg; graph draws mermaid (default),
+                    dot or er; layer draws text (default), mermaid or
+                    svg; ladder and poset draw mermaid (default) or dot
   --at <path>       Restrict the figure to nodes under this path; the
-                    subtree doc draws; the path the ladder draws;
-                    where the poset compares
+                    subtree doc draws; the subtree the lattice counts;
+                    the path the ladder draws; where the poset compares
   --views <path>    Draw every figure the document declares at this
                     path, one evaluation, all or nothing; each
                     declaration names its own kind and out file
@@ -269,6 +277,19 @@ Agentsmd options:
 Agentsmd exit codes: 0 generated, 2 usage, 4 the document does not
 stand up on its own.
 
+Fmt options:
+  -w, --write     Rewrite each file in place, when its form would change
+  -l, --list      Print the name of each file whose form would change
+  --check         Like --list, and exit 1 when any would: the CI gate
+  -d, --diff      Print a unified diff for each file whose form would
+                  change
+
+The fmt verb prints one document in the agreed form; with no file it
+reads standard input. Several files need one of the options above.
+
+Fmt exit codes: 0 formatted or clean, 1 a --check file would change,
+2 usage, 4 a document does not parse.
+
 REPL commands:
   :help           Show REPL help
   :load <file>    Evaluate a document and hold it for the commands below
@@ -333,15 +354,16 @@ function makeTrustWarn() {
 // entryRoot (the entry file's directory, or the working directory for
 // stdin/REPL).
 function trustOpts(trust, entryRoot) {
+    const text = 0 === trust.textExt.length ? {} : { textExt: trust.textExt };
     switch (trust.kind) {
         case 'none':
-            return { trust: { include: 'none' } };
+            return { ...text, trust: { include: 'none' } };
         case 'root':
-            return { trust: { include: { root: trust.dir ?? entryRoot } } };
+            return { ...text, trust: { include: { root: trust.dir ?? entryRoot } } };
         case 'system':
-            return {};
+            return { ...text };
         default: // system-warn: today's default plus the warning window
-            return { trustWarn: makeTrustWarn(), trustWarnRoot: entryRoot };
+            return { ...text, trustWarn: makeTrustWarn(), trustWarnRoot: entryRoot };
     }
 }
 // EVERY VERB honours the include capability, not just the bare
@@ -356,7 +378,8 @@ function trustOpts(trust, entryRoot) {
 // already printed: the caller answers the usage class.
 function takeTrust(argv) {
     const rest = [];
-    let trust = { kind: 'system-warn' };
+    let trust = { kind: 'system-warn', textExt: [] };
+    let textExt = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if ('--trust' === arg) {
@@ -373,18 +396,42 @@ function takeTrust(argv) {
                 process.stderr.write('aontu: --include-root needs a directory\n');
                 return undefined;
             }
-            trust = { kind: 'root', dir };
+            trust = { kind: 'root', dir, textExt };
+        }
+        else if ('--text-ext' === arg) {
+            const list = null == argv[i + 1] ? undefined : parseTextExt(argv[++i]);
+            if (null == list) {
+                process.stderr.write('aontu: --text-ext needs extensions, without dots' +
+                    ' (--text-ext md,sql)\n');
+                return undefined;
+            }
+            textExt = [...textExt, ...list];
         }
         else {
             rest.push(arg);
         }
     }
-    return { argv: rest, trust };
+    return { argv: rest, trust: { ...trust, textExt } };
+}
+// `md,sql` or `.md,.sql` -- the dot is accepted and dropped, because a
+// reader who has just written `@"notes.txt"` reaches for one. An empty
+// element, or anything that is not an extension, is a usage error
+// rather than a silently ignored word: a flag that quietly does
+// nothing is how a document ends up refused with no reason visible.
+function parseTextExt(arg) {
+    const out = [];
+    for (const raw of arg.split(',')) {
+        const ext = raw.trim().replace(/^\./, '').toLowerCase();
+        if ('' === ext || !/^[a-z0-9]+$/.test(ext)) {
+            return undefined;
+        }
+        out.push(ext);
+    }
+    return out;
 }
 // The evaluator options a REPL session's capability means.
 function replTrust(state, entryRoot) {
-    const capability = verbTrust(state.trust ?? { kind: 'system-warn' }, entryRoot);
-    return null == capability ? {} : { trust: capability };
+    return verbOpts(state.trust ?? { kind: 'system-warn', textExt: [] }, entryRoot);
 }
 // The capability a verb's engine runs under. `system` and the staged
 // warning default both mean today's behaviour (no option); the warning
@@ -400,6 +447,18 @@ function verbTrust(trust, entryRoot) {
             return undefined;
     }
 }
+// THE INCLUDE OPTIONS A VERB RUNS UNDER, spread into its engine call:
+// the capability above, and the extensions `--text-ext` widened. Both
+// are absent when unset rather than present-and-undefined, so a verb's
+// options bag is byte-identical to what it was before either flag
+// existed and no engine sees a key it has to ignore.
+function verbOpts(trust, entryRoot) {
+    const include = verbTrust(trust, entryRoot);
+    return {
+        ...(undefined === include ? {} : { trust: include }),
+        ...(0 === trust.textExt.length ? {} : { textExt: trust.textExt }),
+    };
+}
 // The directory a bare `--trust root` confines to for a verb: the
 // primary document's own, matching the bare command's entry root.
 function entryRootOf(file) {
@@ -505,7 +564,7 @@ function replCommand(state, line, read) {
             if (':why' === cmd) {
                 const report = (0, aontu_1.why)(src, path, {
                     path: state.name,
-                    trust: verbTrust(state.trust ?? { kind: 'system-warn' }, entryRootOf(state.name)),
+                    ...verbOpts(state.trust ?? { kind: 'system-warn', textExt: [] }, entryRootOf(state.name)),
                 });
                 return report.ok
                     ? answer(renderWhyText(report.record))
@@ -515,7 +574,7 @@ function replCommand(state, line, read) {
                 ? 'keys' : 'canon' === state.mode ? 'canon' : 'json';
             const report = (0, aontu_1.get)(src, path, {
                 view, path: state.name,
-                trust: verbTrust(state.trust ?? { kind: 'system-warn' }, entryRootOf(state.name)),
+                ...verbOpts(state.trust ?? { kind: 'system-warn', textExt: [] }, entryRootOf(state.name)),
             });
             return report.ok
                 ? answer(report.out)
@@ -746,7 +805,7 @@ function vetOnce(args, trust) {
     const findings = [];
     for (const source of sources) {
         const report = (0, aontu_1.vet)(schemaSrc, source.src, {
-            trust: verbTrust(trust, entryRootOf(args.schema)),
+            ...verbOpts(trust, entryRootOf(args.schema)),
             at: args.at,
             closed: args.closed,
             partial: args.partial,
@@ -985,7 +1044,7 @@ function runSubsume(argv) {
         return 2;
     }
     const report = (0, aontu_1.subsume)(generalSrc, specificSrc, {
-        trust: verbTrust(trust, entryRootOf(args.general)),
+        ...verbOpts(trust, entryRootOf(args.general)),
         profile: args.profile,
         at: args.at,
         generalUrl: args.general,
@@ -1165,15 +1224,17 @@ function oldVersion(spec, file) {
 // The document's own compatibility declaration: `$.aontu_policy.compat`,
 // a disjunction whose default is the declared mode. Undefined when the
 // key is absent or does not spell a mode.
-function policyCompat(newSrc, path, trust) {
+function policyCompat(newSrc, path, include) {
     const aontu = new aontu_1.Aontu();
     const ctx = aontu.ctx({ collect: true });
     // The declaration is read by EVALUATING the document, so this leg
-    // runs the include resolver too and has to run it under the verb's
-    // capability -- a `breaking --trust none` that read its own mode
-    // through an unconfined resolver would confine the comparison and
-    // not the question (use-cases/REVIEW.md finding G).
-    const v = aontu.unify(newSrc, { path, ...(null == trust ? {} : { trust }) }, ctx);
+    // runs the include resolver too and has to run it under BOTH of the
+    // verb's include options -- a `breaking --trust none` that read its
+    // own mode through an unconfined resolver would confine the
+    // comparison and not the question (use-cases/REVIEW.md finding G),
+    // and one that took the capability alone read no mode at all when
+    // the declaration arrived through a `--text-ext` include.
+    const v = aontu.unify(newSrc, { path, ...(0, utility_1.includeOpts)(include) }, ctx);
     if (0 < ctx.err.length || true === v?.isNil) {
         return undefined;
     }
@@ -1266,7 +1327,7 @@ function runBreaking(argv) {
     // neither means backward, the index's framing (v1-valid documents
     // stay valid).
     const mode = args.mode ??
-        policyCompat(newSrc, args.file, verbTrust(trust, entryRootOf(args.file))) ??
+        policyCompat(newSrc, args.file, verbOpts(trust, entryRootOf(args.file))) ??
         'backward';
     if ('none' === mode) {
         // The document declares no compatibility promise: nothing to check.
@@ -1309,7 +1370,7 @@ function runBreaking(argv) {
             const oldPath = old.path;
             for (const check of checks) {
                 const report = (0, aontu_1.subsume)(check.general[0], check.specific[0], {
-                    trust: verbTrust(trust, entryRootOf(args.file)),
+                    ...verbOpts(trust, entryRootOf(args.file)),
                     at: args.at,
                     generalUrl: check.general[1],
                     specificUrl: check.specific[1],
@@ -1439,7 +1500,7 @@ function runTrim(argv) {
         return 2;
     }
     const report = (0, aontu_1.trimCheck)(src, {
-        path: files[0], trust: verbTrust(trust, entryRootOf(files[0])),
+        path: files[0], ...verbOpts(trust, entryRootOf(files[0])),
     });
     const text = 'json' === format
         ? renderTrimJson(report)
@@ -1490,8 +1551,8 @@ const REACHES_EXIT = {
     error: 4,
 };
 const VIEW_HELP = 'aontu view <kind> [options] <file>... (try --help)';
-const VIEW_KINDS = ['doc', 'tree', 'matrix', 'graph', 'layer', 'sets', 'layers', 'ladder',
-    'poset'];
+const VIEW_KINDS = ['doc', 'lattice', 'tree', 'matrix', 'graph', 'layer', 'sets', 'layers',
+    'ladder', 'poset'];
 const VIEW_PROFILES = ['text', 'mermaid', 'dot', 'er', 'svg'];
 const VIEW_EDGES = ['upward', 'all', 'none'];
 // The styles the CLI accepts (VIEWS.0.md, "7. Styling"). `auto` is
@@ -1764,7 +1825,7 @@ function runRelations(argv) {
         return 2;
     }
     const report = (0, aontu_1.relationCheck)(src, {
-        path: files[0], trust: verbTrust(trust, entryRootOf(files[0])),
+        path: files[0], ...verbOpts(trust, entryRootOf(files[0])),
     });
     const text = 'json' === format
         ? renderRelationsJson(report)
@@ -1825,7 +1886,7 @@ function runReaches(argv) {
     }
     const report = (0, reach_1.reachCheck)(src, rest[0], rest[1], {
         path: rest[2], relation,
-        trust: verbTrust(trust, entryRootOf(rest[2])),
+        ...verbOpts(trust, entryRootOf(rest[2])),
     });
     const text = 'json' === format
         ? renderReachesJson(report)
@@ -2052,7 +2113,7 @@ function runView(argv) {
         kind,
         path: files[0],
         roots,
-        trust: verbTrust(trust, entryRootOf(files[0])),
+        ...verbOpts(trust, entryRootOf(files[0])),
         docs: files.slice(1).map((path, i) => ({ src: srcs[i + 1], path })),
     });
     if ('json' === format) {
@@ -2122,7 +2183,7 @@ function runViewSet(rest, opts, trust, how) {
         return 2;
     }
     const report = (0, view_1.viewSet)(src, {
-        ...opts, path: file, trust: verbTrust(trust, entryRootOf(file)),
+        ...opts, path: file, ...verbOpts(trust, entryRootOf(file)),
     });
     if ('json' === how.format) {
         process.stdout.write(renderViewSetJson(report) + '\n');
@@ -2319,7 +2380,7 @@ function runJsonSchema(argv) {
         return 2;
     }
     const report = (0, jsonschema_1.jsonSchema)(src, {
-        at, path: files[0], trust: verbTrust(trust, entryRootOf(files[0])),
+        at, path: files[0], ...verbOpts(trust, entryRootOf(files[0])),
     });
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
@@ -2402,8 +2463,7 @@ function runHash(argv) {
     }
     // The file's own directory is the include base, as every verb
     // resolves a named file (vet's aontuForPath rule).
-    const capability = verbTrust(trust, entryRootOf(files[0]));
-    const aontu = new aontu_1.Aontu(null == capability ? undefined : { trust: capability });
+    const aontu = new aontu_1.Aontu(verbOpts(trust, entryRootOf(files[0])));
     const ctx = aontu.ctx({ collect: true });
     const v = aontu.unify(src, { path: files[0] }, ctx);
     if (0 < ctx.err.length || true === v?.isNil) {
@@ -2507,7 +2567,7 @@ function runGet(argv) {
         return 2;
     }
     const report = (0, aontu_1.get)(src, path, {
-        view, depth, path: file, trust: verbTrust(trust, entryRootOf(file)),
+        view, depth, path: file, ...verbOpts(trust, entryRootOf(file)),
     });
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
@@ -2582,7 +2642,7 @@ function runWhy(argv) {
         return 2;
     }
     const report = (0, aontu_1.why)(src, path, {
-        path: file, trust: verbTrust(trust, entryRootOf(file)),
+        path: file, ...verbOpts(trust, entryRootOf(file)),
     });
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
@@ -2703,7 +2763,7 @@ function runSet(argv) {
         }
     }
     const report = (0, aontu_1.patch)(entrySrc, overlaySrc, assignments, {
-        trust: verbTrust(trust, entryRootOf(entry)),
+        ...verbOpts(trust, entryRootOf(entry)),
         entryPath: entry,
         overlayPath: overlayFile,
         inPlace,
@@ -2823,7 +2883,7 @@ function runAgentsMd(argv) {
     }
     const report = (0, aontu_1.agentsMd)(src, {
         name: files[0], path: files[0],
-        trust: verbTrust(trust, entryRootOf(files[0])),
+        ...verbOpts(trust, entryRootOf(files[0])),
     });
     if (!report.ok) {
         process.stderr.write(report.findings.map(renderFinding).join('\n') + '\n');
@@ -2869,6 +2929,116 @@ function runAgentsMd(argv) {
 // on the parity-probe discipline in AGENTS.md, which derives expected
 // spec values by piping BOTH CLIs and comparing. A truncated pipe there
 // reads as a port divergence.
+// ---------------------------------------------------------------------
+// The source formatter (docs/design/FMT.0.md): one agreed form, in the
+// tradition of gofmt. The verb prints, lists, checks, diffs or rewrites;
+// the form itself is the library's (ts/src/format.ts), and the two
+// ports agree on it row by row in test/spec/fmt.tsv.
+const FMT_HELP = 'aontu fmt [-w|-l|--check|-d] <file>... (try --help)';
+function runFmt(argv) {
+    const files = [];
+    const flags = { write: false, list: false, check: false, diff: false };
+    for (const arg of argv) {
+        if ('-h' === arg || '--help' === arg) {
+            process.stdout.write(HELP);
+            return 0;
+        }
+        if ('-w' === arg || '--write' === arg) {
+            flags.write = true;
+        }
+        else if ('-l' === arg || '--list' === arg) {
+            flags.list = true;
+        }
+        else if ('--check' === arg) {
+            flags.check = true;
+        }
+        else if ('-d' === arg || '--diff' === arg) {
+            flags.diff = true;
+        }
+        else if (arg.startsWith('-')) {
+            process.stderr.write(`aontu: unknown fmt option ${arg} (try --help)\n`);
+            return 2;
+        }
+        else {
+            files.push(arg);
+        }
+    }
+    if (0 === files.length) {
+        // Standard input: formatted onto standard output, or listed,
+        // checked and diffed under the name <stdin>. It cannot be written
+        // back.
+        if (flags.write) {
+            process.stderr.write(`aontu: --write needs a file\n${FMT_HELP}\n`);
+            return 2;
+        }
+        return new Promise((resolve) => {
+            let src = '';
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (d) => (src += d));
+            process.stdin.on('end', () => resolve(fmtOne('<stdin>', src, flags)));
+        });
+    }
+    // Several files onto standard output would be one stream nobody can
+    // split again (the note's X-6): the verb refuses unless an option
+    // says what to do with each.
+    if (1 < files.length && !fmtQuiet(flags)) {
+        process.stderr.write(`aontu: fmt prints one file; with ${files.length}, say --write, ` +
+            `--list, --check or --diff\n${FMT_HELP}\n`);
+        return 2;
+    }
+    let worst = 0;
+    for (const file of files) {
+        let src;
+        try {
+            src = (0, node_fs_1.readFileSync)(file, 'utf8');
+        }
+        catch (err) {
+            process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`);
+            return 2;
+        }
+        worst = Math.max(worst, fmtOne(file, src, flags));
+    }
+    return worst;
+}
+// An option that says what to do with a file that would change, in
+// place of printing it.
+function fmtQuiet(flags) {
+    return flags.write || flags.list || flags.check || flags.diff;
+}
+// One document: 0 printed, clean or done; 1 a --check that would
+// change; 2 a file that cannot be written; 4 a document that does not
+// format, with the finding that says why.
+function fmtOne(name, src, flags) {
+    const report = (0, format_1.format)(src, { path: name });
+    if ('error' === report.verdict) {
+        process.stderr.write(`aontu: ${name} was not formatted\n` +
+            report.errors.map(renderFinding).join('\n') + '\n');
+        return 4;
+    }
+    if (!fmtQuiet(flags)) {
+        process.stdout.write(report.text);
+        return 0;
+    }
+    if (!report.changed) {
+        return 0;
+    }
+    if (flags.list || flags.check) {
+        process.stdout.write(name + '\n');
+    }
+    if (flags.diff) {
+        process.stdout.write((0, format_1.unifiedDiff)(name, src, report.text));
+    }
+    if (flags.write) {
+        try {
+            (0, node_fs_1.writeFileSync)(name, report.text);
+        }
+        catch (err) {
+            process.stderr.write(`aontu: cannot write ${name}: ${err.message}\n`);
+            return 2;
+        }
+    }
+    return flags.check ? 1 : 0;
+}
 function finish(code) {
     process.exitCode = code;
 }
@@ -2876,16 +3046,16 @@ function finish(code) {
 // spelling, so the caller owns the usage error.
 function parseTrustArg(value) {
     if ('system' === value) {
-        return { kind: 'system' };
+        return { kind: 'system', textExt: [] };
     }
     if ('none' === value) {
-        return { kind: 'none' };
+        return { kind: 'none', textExt: [] };
     }
     if ('root' === value) {
-        return { kind: 'root' };
+        return { kind: 'root', textExt: [] };
     }
     if (value.startsWith('root:') && 'root:'.length < value.length) {
-        return { kind: 'root', dir: value.slice('root:'.length) };
+        return { kind: 'root', dir: value.slice('root:'.length), textExt: [] };
     }
     return undefined;
 }
@@ -2906,7 +3076,8 @@ function main(argv) {
     // overwritten twice. In a tool loop that reads as a passing
     // validation. Counting them is what lets the refusal below happen.
     const files = [];
-    let trust = { kind: 'system-warn' };
+    let trust = { kind: 'system-warn', textExt: [] };
+    let textExt = [];
     // The REPL's SESSION protocol (G7 phase 7): one JSON line per
     // answer, so a harness can drive the session. Named --jsonl rather
     // than the design's --json, which would read as the `:json` output
@@ -2933,6 +3104,9 @@ function main(argv) {
     if ('agentsmd' === argv[2]) {
         return finish(runAgentsMd(argv.slice(3)));
     }
+    if ('fmt' === argv[2]) {
+        return void Promise.resolve(runFmt(argv.slice(3))).then(finish);
+    }
     if ('set' === argv[2]) {
         return finish(runSet(argv.slice(3)));
     }
@@ -3000,7 +3174,16 @@ function main(argv) {
                 process.stderr.write('aontu: --include-root needs a directory\n');
                 return finish(2);
             }
-            trust = { kind: 'root', dir };
+            trust = { kind: 'root', dir, textExt };
+        }
+        else if ('--text-ext' === arg) {
+            const list = null == args[i + 1] ? undefined : parseTextExt(args[++i]);
+            if (null == list) {
+                process.stderr.write('aontu: --text-ext needs extensions, without dots' +
+                    ' (--text-ext md,sql)\n');
+                return finish(2);
+            }
+            textExt = [...textExt, ...list];
         }
         else if (arg.startsWith('-')) {
             process.stderr.write(`aontu: unknown option ${arg} (try --help)\n`);
@@ -3024,6 +3207,10 @@ function main(argv) {
             ' (try --help)\n');
         return finish(2);
     }
+    // The extensions ride with the capability from here on, so the three
+    // entry shapes below (file, REPL, stdin) each get them by threading
+    // the one value they already thread.
+    trust = { ...trust, textExt };
     const file = files[0];
     if (null != file) {
         finish(runFile(file, mode, trust));