aontu 0.53.0 → 0.55.0

package/dist/cli.js

@@ -11,6 +11,7 @@ exports.runBreaking = runBreaking;
 exports.runTrim = runTrim;
 exports.runRelations = runRelations;
 exports.runReaches = runReaches;
+exports.runView = runView;
 exports.runJsonSchema = runJsonSchema;
 exports.runMod = runMod;
 exports.runHash = runHash;
@@ -43,6 +44,7 @@ const mod_tool_1 = require("./mod-tool");
 const mod_1 = require("./mod");
 const vet_1 = require("./vet");
 const reach_1 = require("./reach");
+const view_1 = require("./view");
 const agentsmd_1 = require("./agentsmd");
 const HELP = `Usage: aontu [options] [file]
        aontu vet [options] <schema> <data> [more-data...]
@@ -51,6 +53,8 @@ const HELP = `Usage: aontu [options] [file]
        aontu trim --check [options] <file>
        aontu relations [options] <file>
        aontu reaches <from> <to> [--relation <name>] [options] <file>
+       aontu view <kind> [options] <file>...
+       aontu view --views <path> [--check] [options] <file>
        aontu jsonschema [--at <path>] [--strict] [options] <file>
        aontu hash [options] <file>
        aontu mod tidy|verify|vendor|manifest [options] [dir]
@@ -171,6 +175,72 @@ 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
+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,
+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
+  --at <path>       Restrict the figure to nodes under this path; the
+                    subtree doc draws; 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
+  -o, --out <file>  Write the figure here instead of stdout
+  --check           Exit 1 if --out differs from what would be drawn;
+                    nothing is written
+  --strict          Exit 1 when the loss report holds anything beyond
+                    edges_deduped, inverse_suppressed and crossings
+  --depth <n>       doc: how many levels of key to draw (default 3)
+  --max-rows <n>    Refuse a figure above this many rows (default 60)
+  --style <s>       auto (default), none, ansi or css. A figure's
+                    marks carry their meaning -- a direct cell, a
+                    closure cell, an upward edge -- and each profile
+                    has one way to show it: SGR escapes for text, CSS
+                    classes for svg. auto picks that mechanism where
+                    the destination can carry it: escapes only on a
+                    terminal (NO_COLOR is honoured), and an svg keeps
+                    the stylesheet that makes it standalone. none
+                    drops both; on svg the classes stay and only the
+                    stylesheet goes, for a host page that has already
+                    bound --av-ink and its kin. Escapes are never
+                    written to a file
+  --format <f>      text (default) or json, the whole report
+  --relation <n>    tree, matrix, layer: draw over this relation only;
+                    graph: keep this predicate (repeatable)
+  --root <path>     tree: draw only the subtree under this node;
+                    repeatable
+  --order <o>       matrix: canon (default) or partition
+  --closure         matrix: mark transitively reachable cells +
+  --group-by <k>    graph: one subgraph per distinct value of field k;
+                    layer: one band per value (required)
+  --layers <a,b>    layer: the bands in this order, top first; without
+                    it the order is derived from the relation
+  --edges <e>       layer: which of the relation's edges to draw over
+                    the bands -- upward (the violations, the default
+                    for text and svg), all (mermaid's default) or none
+  --label <k>       graph: label each node with field k
+  --sets <path>     sets: the map whose keys are the sets
+  --member <k>      sets: the field holding each set's members
+  --universe <p>    sets: the full element domain, so the empty
+                    column exists
+  --min-degree <n>  sets: drop intersections below this degree
+  --min-size <n>    layers: drop intersections below this many paths
+  --max-cols <n>    sets, layers: elide columns beyond this many
+  --profile <p>     poset: values | defaults (default) | gen
+
+View exit codes: 0 rendered, 1 --check mismatch or lossy under
+--strict, 2 usage or --max-rows exceeded, 4 the document does not stand
+up on its own, or a relation, root or path that names nothing.
+
 Set options:
   --entry <file>    The document the change is checked against
   --overlay <file>  The file the change is appended to (created if
@@ -1419,6 +1489,57 @@ const REACHES_EXIT = {
     unreachable: 1,
     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_PROFILES = ['text', 'mermaid', 'dot', 'er', 'svg'];
+const VIEW_EDGES = ['upward', 'all', 'none'];
+// The styles the CLI accepts (VIEWS.0.md, "7. Styling"). `auto` is
+// here and NOT in ViewStyle: resolving it means knowing whether stdout
+// is a terminal, which is the CLI's to know and the library's never --
+// the same division err.ts already draws for the error frames.
+const VIEW_STYLES = ['auto', 'none', 'ansi', 'css'];
+// `--style auto` resolved, which only the CLI can do. The mechanism is
+// the PROFILE's and the library knows it -- an SVG carries its
+// stylesheet unless told not to, which is what makes a figure stand
+// alone. What the library cannot know is whether the DESTINATION is a
+// terminal, so that is the only thing decided here: escapes on the
+// text profile when stdout is a terminal and NO_COLOR is unset, the
+// same two conditions the error frames use. `undefined` leaves the
+// profile's own default in place.
+function viewStyleOf(asked, as) {
+    if (undefined !== asked && 'auto' !== asked) {
+        return asked;
+    }
+    // STDOUT'S OWN TERMINAL-NESS, and NO_COLOR read here rather than
+    // through colorActive(). The figure goes to STDOUT and the error
+    // frames go to STDERR, and they are not the same destination: main()
+    // has already called setColor for stderr, so asking colorActive()
+    // would answer the wrong question twice --- no escapes for
+    // `aontu view tree m.aon 2>/dev/null` at a terminal, and escapes
+    // into the pipe for `aontu view tree m.aon | less`. The NO_COLOR
+    // rule is the one no-color.org states and err.ts implements:
+    // set, to anything but empty, means no colour.
+    const no = process.env.NO_COLOR;
+    return 'text' === as && true === process.stdout.isTTY
+        && (null == no || '' === no) ? 'ansi' : undefined;
+}
+// The figure was drawn (0, `lossy` included: the loss report says
+// what it could not draw, and --strict is the gate on that), or the
+// document could not be drawn (4). An EMPTY figure is a drawing, not
+// a failure: a model with no links has nothing to draw, honestly.
+const VIEW_EXIT = {
+    rendered: 0,
+    lossy: 0,
+    error: 4,
+};
+// The refusals that are USAGE, not the document's fault: exit 2, as
+// every other verb's usage errors do.
+const VIEW_USAGE_CODES = [
+    'view_kind_unknown', 'view_profile_unknown', 'view_rows_exceeded',
+    'view_at_required', 'view_sets_required', 'view_group_required',
+    'view_document_shape', 'view_style_profile', 'view_style_unknown',
+];
 const MOD_HELP = 'aontu mod tidy|verify|vendor|manifest [dir] (try --help)';
 // The module tooling (G6 phase 3, ts/src/mod-tool.ts). All LOCAL:
 // `tidy` resolves the closure from what is in the stores and rewrites
@@ -1476,7 +1597,8 @@ function runMod(argv) {
     const dir = rest[1] ?? '.';
     if ('get' === sub || 'publish' === sub) {
         process.stderr.write('aontu: mod ' + sub + ' needs a registry client, which this build ' +
-            'does not ship (docs/capability-review/g6-distribution.md)\n');
+            'does not ship; vendor the module by hand and run ' +
+            "'aontu mod tidy'\n");
         return 2;
     }
     if (!MOD_SUBS.includes(sub) || 2 < rest.length) {
@@ -1690,7 +1812,7 @@ function runReaches(argv) {
         }
     }
     if (3 !== rest.length) {
-        process.stderr.write(`aontu: reaches needs two entities and one file\n${REACHES_HELP}\n`);
+        process.stderr.write(`aontu: reaches needs two node paths and one file\n${REACHES_HELP}\n`);
         return 2;
     }
     let src;
@@ -1732,6 +1854,376 @@ function renderReachesJson(report) {
         ...(null == report.errors ? {} : { errors: report.errors }),
     }, 2);
 }
+// ---------------------------------------------------------------------
+// The tree view (docs/design/VIEWS.0.md, ts/src/view.ts): the drawn
+// edge set, as text a golden diff can check.
+function runView(argv) {
+    const trusted = takeTrust(argv);
+    if (null == trusted) {
+        return 2;
+    }
+    argv = trusted.argv;
+    const trust = trusted.trust;
+    const rest = [];
+    let format = 'text';
+    let out = undefined;
+    let check = false;
+    let strict = false;
+    const relations = [];
+    const roots = [];
+    const opts = {};
+    // The style ASKED FOR, which may be `auto` -- a word ViewStyle does
+    // not have, because resolving it is the CLI's job.
+    let style = undefined;
+    // A flag that takes a value, read into `opts` by name.
+    const valued = {
+        '--as': 'as', '--at': 'at', '--order': 'order', '--group-by': 'groupBy',
+        '--label': 'label', '--sets': 'sets', '--member': 'member',
+        '--universe': 'universe', '--profile': 'profile', '--views': 'views',
+        '--edges': 'edges',
+    };
+    const counted = {
+        '--max-rows': 'maxRows', '--max-cols': 'maxCols',
+        '--min-degree': 'minDegree', '--min-size': 'minSize',
+        '--depth': 'depth',
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if ('-h' === arg || '--help' === arg) {
+            process.stdout.write(HELP);
+            return 0;
+        }
+        if ('--format' === arg) {
+            const f = argv[++i];
+            if ('text' !== f && 'json' !== f) {
+                process.stderr.write('aontu: --format needs text or json\n');
+                return 2;
+            }
+            format = f;
+        }
+        else if ('--relation' === arg) {
+            const relation = argv[++i];
+            if (null == relation || '' === relation) {
+                process.stderr.write('aontu: --relation needs a name\n');
+                return 2;
+            }
+            relations.push(relation);
+        }
+        else if ('--root' === arg) {
+            const root = argv[++i];
+            if (null == root) {
+                process.stderr.write('aontu: --root needs a node path\n');
+                return 2;
+            }
+            roots.push(root);
+        }
+        else if ('-o' === arg || '--out' === arg) {
+            out = argv[++i];
+            if (null == out) {
+                process.stderr.write('aontu: --out needs a file\n');
+                return 2;
+            }
+        }
+        else if ('--style' === arg) {
+            style = argv[++i];
+            if (null == style || !VIEW_STYLES.includes(style)) {
+                process.stderr.write(`aontu: --style needs one of ${VIEW_STYLES.join(', ')}\n`);
+                return 2;
+            }
+        }
+        else if ('--check' === arg) {
+            check = true;
+        }
+        else if ('--strict' === arg) {
+            strict = true;
+        }
+        else if ('--closure' === arg) {
+            opts.closure = true;
+        }
+        else if ('--layers' === arg) {
+            const v = argv[++i];
+            if (null == v || '' === v) {
+                process.stderr.write('aontu: --layers needs a comma-separated list\n');
+                return 2;
+            }
+            opts.layers = v.split(',');
+        }
+        else if (undefined !== valued[arg]) {
+            const v = argv[++i];
+            if (null == v || '' === v) {
+                process.stderr.write(`aontu: ${arg} needs a value\n`);
+                return 2;
+            }
+            opts[valued[arg]] = v;
+        }
+        else if (undefined !== counted[arg]) {
+            const v = argv[++i];
+            if (null == v || !/^[0-9]+$/.test(v)) {
+                process.stderr.write(`aontu: ${arg} needs a count\n`);
+                return 2;
+            }
+            opts[counted[arg]] = parseInt(v, 10);
+        }
+        else if (arg.startsWith('-')) {
+            process.stderr.write(`aontu: unknown view option ${arg} (try --help)\n`);
+            return 2;
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    // ESCAPES NEVER GO INTO A FILE. A pinned golden holding terminal
+    // control codes is not a golden anybody can read, and a byte
+    // comparison against one would fail on the reader's terminal
+    // settings. `auto` resolves to `none` there on its own; asking for
+    // `ansi` explicitly is a usage error rather than a silent downgrade,
+    // so a script that wanted colour is told where it went.
+    if ('ansi' === style && (undefined !== out || undefined !== opts.views)) {
+        process.stderr.write('aontu: --style ansi writes to a terminal, not to a file\n');
+        return 2;
+    }
+    // THE VIEW DOCUMENT draws every figure a document declares, so it
+    // names no kind: the declarations do, one each.
+    if (undefined !== opts.views) {
+        // A declaration names its own profile, so the style is left to
+        // each figure's own default; `--style none` still reaches every
+        // one of them, which is how a host page that binds the CSS
+        // variables asks for eight figures without eight stylesheets.
+        opts.style = viewStyleOf(style, undefined);
+        return runViewSet(rest, opts, trust, { format, check, strict, out });
+    }
+    if (2 > rest.length) {
+        process.stderr.write(`aontu: view needs a kind and a file\n${VIEW_HELP}\n`);
+        return 2;
+    }
+    const kind = rest[0];
+    if (!VIEW_KINDS.includes(kind)) {
+        process.stderr.write(`aontu: unknown view kind ${kind} (the kinds are: ${VIEW_KINDS.join(', ')})\n`);
+        return 2;
+    }
+    if (undefined !== opts.as && !VIEW_PROFILES.includes(opts.as)) {
+        process.stderr.write(`aontu: --as needs one of ${VIEW_PROFILES.join(', ')}\n`);
+        return 2;
+    }
+    if (undefined !== opts.order && 'canon' !== opts.order && 'partition' !== opts.order) {
+        process.stderr.write('aontu: --order needs canon or partition\n');
+        return 2;
+    }
+    if (undefined !== opts.edges && !VIEW_EDGES.includes(opts.edges)) {
+        process.stderr.write(`aontu: --edges needs one of ${VIEW_EDGES.join(', ')}\n`);
+        return 2;
+    }
+    if (undefined !== opts.profile && !['values', 'defaults', 'gen'].includes(opts.profile)) {
+        process.stderr.write('aontu: --profile needs values, defaults or gen\n');
+        return 2;
+    }
+    if ('poset' !== kind && 2 !== rest.length) {
+        process.stderr.write(`aontu: view ${kind} takes one file\n`);
+        return 2;
+    }
+    if ('graph' === kind) {
+        opts.relations = relations;
+    }
+    else if (1 < relations.length) {
+        process.stderr.write(`aontu: view ${kind} takes one --relation\n`);
+        return 2;
+    }
+    else {
+        opts.relation = relations[0];
+    }
+    if (check && undefined === out) {
+        process.stderr.write('aontu: --check needs --out\n');
+        return 2;
+    }
+    const files = rest.slice(1);
+    const srcs = [];
+    for (const file of files) {
+        try {
+            srcs.push((0, node_fs_1.readFileSync)(file, 'utf8'));
+        }
+        catch (err) {
+            process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`);
+            return 2;
+        }
+    }
+    const report = (0, view_1.view)(srcs[0], {
+        ...opts,
+        style: viewStyleOf(style, opts.as ?? (0, view_1.viewDefaultProfile)(kind)),
+        kind,
+        path: files[0],
+        roots,
+        trust: verbTrust(trust, entryRootOf(files[0])),
+        docs: files.slice(1).map((path, i) => ({ src: srcs[i + 1], path })),
+    });
+    if ('json' === format) {
+        process.stdout.write(renderViewJson(report) + '\n');
+    }
+    else if ('error' === report.verdict) {
+        process.stderr.write(report.errors.map(renderFinding).join('\n') + '\n');
+    }
+    else {
+        // THE FIGURE AND NOTHING ELSE on stdout (or in the file): stdout is
+        // what a golden diff reads, and a verdict line would be part of
+        // every drawing. The loss report goes to stderr, so a figure
+        // written to a file still tells the reader what it could not draw.
+        const text = report.text + '\n';
+        if (undefined === out) {
+            process.stdout.write(text);
+        }
+        else if (check) {
+            let have = undefined;
+            try {
+                have = (0, node_fs_1.readFileSync)(out, 'utf8');
+            }
+            catch (_err) {
+                // Absent is a mismatch.
+            }
+            if (have !== text) {
+                process.stderr.write(`aontu: ${out} differs from the ${kind} figure\n`);
+                return 1;
+            }
+        }
+        else {
+            (0, node_fs_1.writeFileSync)(out, text, 'utf8');
+        }
+        if (0 < report.loss.length) {
+            process.stderr.write(renderViewLoss(report.loss) + '\n');
+        }
+    }
+    if ('error' === report.verdict) {
+        const code = report.errors[0]?.code;
+        return VIEW_USAGE_CODES.includes(code) ? 2 : VIEW_EXIT.error;
+    }
+    return strict && 'lossy' === report.verdict ? 1 : VIEW_EXIT[report.verdict];
+}
+// `aontu view --views <path> <file>`: every figure the document
+// declares, from one evaluation, all or nothing.
+//
+// A declared `out` is resolved against the DOCUMENT's own directory,
+// not the caller's: a view document is committed beside the figures it
+// gates, and a gate that only passes from one working directory is not
+// a gate.
+function runViewSet(rest, opts, trust, how) {
+    if (1 !== rest.length) {
+        process.stderr.write('aontu: view --views takes one file\n');
+        return 2;
+    }
+    if (undefined !== how.out) {
+        process.stderr.write('aontu: --out is per figure in a view document; each declares its own\n');
+        return 2;
+    }
+    const file = rest[0];
+    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;
+    }
+    const report = (0, view_1.viewSet)(src, {
+        ...opts, path: file, trust: verbTrust(trust, entryRootOf(file)),
+    });
+    if ('json' === how.format) {
+        process.stdout.write(renderViewSetJson(report) + '\n');
+    }
+    else if (undefined !== report.errors) {
+        process.stderr.write(report.errors.map(renderFinding).join('\n') + '\n');
+    }
+    else {
+        for (const fig of report.views) {
+            if (undefined !== fig.errors) {
+                process.stderr.write(`${fig.name} (${fig.kind}):\n` +
+                    fig.errors.map(renderFinding).join('\n') + '\n');
+            }
+            else if (0 < fig.loss.length) {
+                process.stderr.write(renderViewLoss(fig.loss)
+                    .split('\n').map((l) => `${fig.name}  ${l}`).join('\n') + '\n');
+            }
+        }
+    }
+    if ('error' === report.verdict) {
+        return setExit(report);
+    }
+    // EVERY FIGURE RENDERED, so the whole set is written -- or, under
+    // --check, the whole set is compared and every difference named.
+    const dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(file));
+    let differ = 0;
+    for (const fig of report.views) {
+        const path = (0, node_path_1.resolve)(dir, fig.out);
+        const text = fig.text + '\n';
+        if (how.check) {
+            let have = undefined;
+            try {
+                have = (0, node_fs_1.readFileSync)(path, 'utf8');
+            }
+            catch (_err) {
+                // Absent is a mismatch.
+            }
+            if (have !== text) {
+                differ++;
+                process.stderr.write(`aontu: ${fig.out} differs from the ${fig.name} figure\n`);
+            }
+        }
+        else {
+            try {
+                (0, node_fs_1.writeFileSync)(path, text, 'utf8');
+            }
+            catch (err) {
+                process.stderr.write(`aontu: cannot write ${err.path}: ${err.message}\n`);
+                return 2;
+            }
+            if ('json' !== how.format) {
+                process.stderr.write(`wrote ${fig.out}  ${fig.name} (${fig.kind})\n`);
+            }
+        }
+    }
+    if (0 < differ) {
+        return 1;
+    }
+    return how.strict && 'lossy' === report.verdict ? 1 : VIEW_EXIT[report.verdict];
+}
+// A set's exit code is the worst of its figures': a usage refusal
+// anywhere is usage, and any other refusal is the document's fault.
+function setExit(report) {
+    const codes = [
+        ...(report.errors ?? []),
+        ...report.views.flatMap((v) => v.errors ?? []),
+    ].map((e) => e.code);
+    return codes.some((c) => VIEW_USAGE_CODES.includes(c))
+        ? 2 : VIEW_EXIT.error;
+}
+function renderViewSetJson(report) {
+    return (0, aontu_1.exactJSON)({
+        aontu: { version: version(), verb: 'view' },
+        verdict: report.verdict,
+        views: report.views.map((v) => ({
+            name: v.name,
+            kind: v.kind,
+            out: v.out,
+            verdict: v.verdict,
+            ...(null == v.text ? {} : { text: v.text }),
+            loss: v.loss,
+            ...(null == v.errors ? {} : { errors: v.errors }),
+        })),
+        ...(null == report.errors ? {} : { errors: report.errors }),
+    }, 2);
+}
+// One line per code: the code, the count, and the detail if any.
+function renderViewLoss(loss) {
+    return loss.map((l) => `${l.code}  ${l.count}` +
+        (undefined === l.detail ? '' : '  ' + l.detail.join(' '))).join('\n');
+}
+function renderViewJson(report) {
+    return (0, aontu_1.exactJSON)({
+        aontu: { version: version(), verb: 'view' },
+        kind: report.kind,
+        verdict: report.verdict,
+        ...(null == report.text ? {} : { text: report.text }),
+        loss: report.loss,
+        ...(null == report.errors ? {} : { errors: report.errors }),
+    }, 2);
+}
 function renderRelationsText(report) {
     const head = `verdict: ${report.verdict}`;
     // WHY, when the document could not be evaluated at all: rendered as
@@ -1745,11 +2237,8 @@ function renderRelationsText(report) {
     }
     const lines = report.findings.map((f) => 'relation_cycle' === f.code
         ? `${f.at}  ${f.relation}: cycle ${f.detail.join(' -> ')}`
-        : 'relation_target_unmet' === f.code
-            ? `${f.at}  ${f.relation}: ${f.detail[1]} is not what ` +
-                `${f.relation} targets (${f.detail[2]})`
-            : `${f.at}  ${f.relation}: ${f.detail[1]} does not list ` +
-                `${f.detail[0]} under ${f.detail[2]}`);
+        : `${f.at}  ${f.relation}: ${f.detail[1]} does not list ` +
+            `${f.detail[0]} under ${f.detail[2]}`);
     return [head, ''].concat(lines).join('\n');
 }
 function renderRelationsJson(report) {
@@ -2468,6 +2957,9 @@ function main(argv) {
     if ('reaches' === argv[2]) {
         return finish(runReaches(argv.slice(3)));
     }
+    if ('view' === argv[2]) {
+        return finish(runView(argv.slice(3)));
+    }
     if ('trim' === argv[2]) {
         return finish(runTrim(argv.slice(3)));
     }
@@ -2546,5 +3038,5 @@ function main(argv) {
     else {
         runStdin(mode, trust).then((code) => finish(code));
     }
-} /* node:coverage ignore next 15 */
+} /* node:coverage ignore next 16 */
 //# sourceMappingURL=cli.js.map