aontu 0.57.0 → 0.59.0

package/dist/cli.js

@@ -13,6 +13,8 @@ exports.runRelations = runRelations;
 exports.runReaches = runReaches;
 exports.runView = runView;
 exports.runJsonSchema = runJsonSchema;
+exports.runRender = runRender;
+exports.runTemplate = runTemplate;
 exports.runMod = runMod;
 exports.runHash = runHash;
 exports.runGet = runGet;
@@ -39,6 +41,8 @@ const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const node_readline_1 = require("node:readline");
 const aontu_1 = require("./aontu");
+const template_1 = require("./template");
+const mcp_1 = require("./mcp");
 const report_sarif_1 = require("./report-sarif");
 const lsp_server_1 = require("./lsp-server");
 const mcp_server_1 = require("./mcp-server");
@@ -61,6 +65,10 @@ const HELP = `Usage: aontu [options] [file]
        aontu view <kind> [options] <file>...
        aontu view --views <path> [--check] [options] <file>
        aontu jsonschema [--at <path>] [--strict] [options] <file>
+       aontu render [--at <path>] [--profile <file>]... [--unit <path>]
+                    [--stdout | --out <dir> | --check <dir> | --coverage]
+                    [--coverage-at <path>] [--strict] <file>
+       aontu template [--resugar] [--check] [--marker <token>] <file>
        aontu hash [options] <file>
        aontu mod tidy|verify|vendor|manifest [options] [dir]
        aontu get <path> [options] <file>
@@ -71,7 +79,7 @@ const HELP = `Usage: aontu [options] [file]
        aontu lsp
        aontu mcp [--root <dir>]
 
-Evaluate an Aontu source file and print the result as JSON.
+Evaluate an aontu source file and print the result as JSON.
 With no file on an interactive terminal, start a REPL.
 With no file and piped input, read the source from stdin.
 
@@ -253,6 +261,51 @@ 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.
 
+Render options:
+  --at <path>       Render the value at this path ($.a.b); the root by
+                    default
+  --profile <file>  A profile document, profile: {lang, ...}, vetted
+                    against aontu:profile; repeatable, one per language
+  --unit <path>     Render only the unit with this path
+  --stdout          One unit's bytes and nothing else (with --unit when
+                    the instance has several)
+  --out <dir>       Write every unit below dir, or nothing; never deletes
+  --check <dir>     Compare every unit with dir/<path>; drift is listed
+  --coverage        Report what the render read and what it did not:
+                    model paths no output consumed, and rendered
+                    declarations no rule produced. Writes nothing
+  --coverage-at <p> Measure coverage under this path only, instead of
+                    the document root
+  --strict          Refuse the opaque escapes (a text declaration, a raw
+                    block)
+  --format <f>      text (default) or json, the whole report; json
+                    carries the dispatch trace, one entry per emitted
+                    piece
+
+Render exit codes: 0 rendered, 1 lossy under --strict or drift under
+--check, 2 usage or I/O (a refused unit path included), 4 the document
+does not stand up or the instance is not aontu:code.
+
+A render entry file whose extension is not .aon is a TEMPLATE: a
+generator in the target's own syntax, whose marker lines carry aontu
+and whose other lines are output. It is desugared before it is
+evaluated, and --marker names the marker for a language the table does
+not know.
+
+Template options:
+  --resugar       The file is the canonical aontu; print the template
+                  form instead of reading one
+  --check         Desugar and resugar, and exit 1 if the file is not
+                  what the round trip answers
+  --marker <t>    The marker, when the extension does not name it
+                  (default //-, and #- --- /*- by extension)
+
+The template verb prints the canonical aontu form of a generator
+written in the target's own syntax: a marked line is aontu source, and
+every other line is a line of output.
+
+Template exit codes: 0 written, 1 --check drift, 2 usage or I/O.
+
 Set options:
   --entry <file>    The document the change is checked against
   --overlay <file>  The file the change is appended to (created if
@@ -491,7 +544,17 @@ function runFile(file, mode, trust) {
         return 1;
     }
     const path = (0, node_path_1.resolve)(file);
-    const aontu = new aontu_1.Aontu({ path, ...trustOpts(trust, (0, node_path_1.dirname)(path)) });
+    // `fs` IS WHAT MAKES A FRAME EXCERPT THE FILE IT NAMES. Without it,
+    // err.ts's resolveSrc falls back to the ENTRY text, so a frame whose
+    // arrow says `lib/types.aon:2:6` printed the entry's line 2 under it
+    // -- a real file name over another file's line, which
+    // docs/reference-api.md forbids in the same words it uses to require
+    // the name.
+    const aontu = new aontu_1.Aontu({
+        path,
+        errfs: { existsSync: node_fs_1.existsSync, readFileSync: node_fs_1.readFileSync },
+        ...trustOpts(trust, (0, node_path_1.dirname)(path)),
+    });
     const res = evalSource(aontu, src, mode);
     (res.ok ? process.stdout : process.stderr).write(res.text + '\n');
     return res.ok ? 0 : 1;
@@ -609,7 +672,7 @@ function runRepl(initialMode, jsonl, trust) {
         prompt: jsonl ? '' : 'aontu> ',
     });
     if (!jsonl) {
-        process.stdout.write(`Aontu v${version()} REPL — :help for commands, :quit to exit\n`);
+        process.stdout.write(`aontu v${version()} REPL — :help for commands, :quit to exit\n`);
     }
     rl.prompt();
     rl.on('line', (line) => {
@@ -2432,6 +2495,403 @@ function runJsonSchema(argv) {
         strict && 'lossy' === report.verdict ? 1 : 0;
 }
 // ---------------------------------------------------------------------
+// THE RENDER VERB (docs/design/RENDER.0.md D8): evaluate a document,
+// vet the value at --at against aontu:code, fold code.units into bytes,
+// and put them where the flag says -- one unit on stdout, every unit
+// below --out (all or nothing), or compared against --check. Exit codes
+// mirror jsonschema's: 0 ok; 1 lossy under --strict or drift under
+// --check; 2 usage or I/O, a refused unit path included; 4 the
+// document does not stand up or the instance is not aontu:code.
+const RENDER_HELP = 'aontu render [--at <path>] [--profile <file>]... [--unit <path>] ' +
+    '[--stdout | --out <dir> | --check <dir> | --coverage] ' +
+    '[--coverage-at <path>] [--strict] [--marker <token>] <file> (try --help)';
+function runRender(argv) {
+    const trusted = takeTrust(argv);
+    if (null == trusted) {
+        return 2;
+    }
+    argv = trusted.argv;
+    const trust = trusted.trust;
+    const files = [];
+    const profileFiles = [];
+    let format = 'text';
+    let at = undefined;
+    let unit = undefined;
+    let out = undefined;
+    let check = undefined;
+    let toStdout = false;
+    let strict = false;
+    let coverage = false;
+    let coverageAt = undefined;
+    let marker = undefined;
+    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 ('--at' === arg) {
+            at = argv[++i];
+            if (null == at) {
+                process.stderr.write('aontu: --at needs a path\n');
+                return 2;
+            }
+        }
+        else if ('--unit' === arg) {
+            unit = argv[++i];
+            if (null == unit) {
+                process.stderr.write('aontu: --unit needs a unit path\n');
+                return 2;
+            }
+        }
+        else if ('--profile' === arg) {
+            const pf = argv[++i];
+            if (null == pf) {
+                process.stderr.write('aontu: --profile needs a file\n');
+                return 2;
+            }
+            profileFiles.push(pf);
+        }
+        else if ('--out' === arg) {
+            out = argv[++i];
+            if (null == out) {
+                process.stderr.write('aontu: --out needs a directory\n');
+                return 2;
+            }
+        }
+        else if ('--check' === arg) {
+            check = argv[++i];
+            if (null == check) {
+                process.stderr.write('aontu: --check needs a directory\n');
+                return 2;
+            }
+        }
+        else if ('--stdout' === arg) {
+            toStdout = true;
+        }
+        else if ('--coverage' === arg) {
+            coverage = true;
+        }
+        else if ('--marker' === arg) {
+            marker = argv[++i];
+            if (null == marker) {
+                process.stderr.write('aontu: --marker needs a token\n');
+                return 2;
+            }
+        }
+        else if ('--coverage-at' === arg) {
+            coverageAt = argv[++i];
+            if (null == coverageAt) {
+                process.stderr.write('aontu: --coverage-at needs a path\n');
+                return 2;
+            }
+        }
+        else if ('--strict' === arg) {
+            strict = true;
+        }
+        else if (arg.startsWith('-')) {
+            process.stderr.write(`aontu: unknown render option ${arg} (try --help)\n`);
+            return 2;
+        }
+        else {
+            files.push(arg);
+        }
+    }
+    if (1 !== files.length) {
+        process.stderr.write(`aontu: render needs one file\n${RENDER_HELP}\n`);
+        return 2;
+    }
+    const modes = [toStdout, undefined !== out, undefined !== check, coverage]
+        .filter((on) => on).length;
+    if (1 < modes) {
+        process.stderr.write('aontu: render takes one of --stdout, --out, --check or --coverage\n');
+        return 2;
+    }
+    // A NARROWER MEASURE NEEDS SOMETHING TO NARROW. `--coverage-at`
+    // without `--coverage` asks for a report the run does not compute,
+    // and answering silently would be the wrong half of the request.
+    if (undefined !== coverageAt && !coverage) {
+        process.stderr.write('aontu: --coverage-at needs --coverage\n');
+        return 2;
+    }
+    let src;
+    try {
+        src = (0, node_fs_1.readFileSync)(files[0], 'utf8');
+    }
+    catch (err) {
+        process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`);
+        return 2;
+    }
+    // THE ENTRY MAY BE A TEMPLATE (TEMPLATE.0.md; P8), and its EXTENSION
+    // decides, as an include's extension decides what the include is
+    // (ADR-012): a generator is a file in the target's own syntax, so it
+    // carries the target's extension and never `.aon`. Desugared here
+    // rather than anywhere deeper, because a template is an entry
+    // spelling and not a value: an include is still aontu.
+    if (!files[0].endsWith('.aon')) {
+        src = (0, template_1.desugarTemplate)(src, marker ?? (0, template_1.markerFor)(files[0]));
+    }
+    // THE PROFILES (D5): each --profile file is a document whose root is
+    // `profile: {lang, ...}`, evaluated under the verb's trust and vetted
+    // against aontu:profile as a settled value before the fold reads it
+    // (renderProfile, which also fills the defaults). Two files claiming
+    // one lang is a usage error: the fold could not choose.
+    const profiles = [];
+    const langs = new Map();
+    for (const pf of profileFiles) {
+        let text;
+        try {
+            text = (0, node_fs_1.readFileSync)(pf, 'utf8');
+        }
+        catch (err) {
+            process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`);
+            return 2;
+        }
+        const loaded = (0, aontu_1.renderProfile)(text, { path: (0, node_path_1.resolve)(pf), ...verbOpts(trust, entryRootOf(pf)) });
+        if (undefined !== loaded.errors) {
+            process.stderr.write(loaded.errors.map(renderFinding).join('\n') + '\n');
+            return 4;
+        }
+        const profile = loaded.profile;
+        const prev = langs.get(profile.lang);
+        if (undefined !== prev) {
+            process.stderr.write(`aontu: two profiles claim ${profile.lang}: ${prev} and ${pf}\n`);
+            return 2;
+        }
+        langs.set(profile.lang, pf);
+        profiles.push(profile);
+    }
+    const report = (0, aontu_1.render)(src, {
+        at, unit, strict, profiles, path: files[0],
+        coverage, coverageAt,
+        // THE JSON REPORT CARRIES THE TRACE (D9), which is what the shape
+        // there has always said; a text run computes it only when the
+        // coverage report needs it.
+        trace: 'json' === format,
+        ...verbOpts(trust, entryRootOf(files[0])),
+    });
+    if ('json' === format) {
+        process.stdout.write((0, aontu_1.exactJSON)({
+            aontu: { version: version(), verb: 'render' },
+            verdict: report.verdict,
+            units: report.units,
+            lossy: report.lossy,
+            ...(null == report.errors ? {} : { errors: report.errors }),
+            ...(null == report.trace ? {} : { trace: report.trace }),
+            ...(null == report.coverage ? {} : { coverage: report.coverage }),
+        }, 2) + '\n');
+        return renderExit(report, 0);
+    }
+    if ('error' === report.verdict) {
+        process.stderr.write(report.errors.map(renderFinding).join('\n') + '\n');
+        return renderExit(report, 0);
+    }
+    let drift = 0;
+    if (toStdout) {
+        // ONE UNIT'S BYTES AND NOTHING ELSE, so the output can be piped
+        // into a formatter or a file.
+        if (1 !== report.units.length) {
+            process.stderr.write('aontu: --stdout needs exactly one unit, and the instance has ' +
+                `${report.units.length}; --unit names one\n`);
+            return 2;
+        }
+        process.stdout.write(report.units[0].text);
+    }
+    else if (undefined !== out) {
+        // EVERY UNIT BELOW <dir>, OR NOTHING: every unit rendered first
+        // (the report above), and no file touched unless all did. The
+        // directory is realpath-confined; a unit path is already a relative
+        // descent (render_path refuses the rest), and the check here is
+        // against the symlink inside it. render never deletes.
+        for (const u of report.units) {
+            if ((0, mcp_1.outsideRoot)(out, (0, node_path_1.resolve)(out, u.path))) {
+                process.stderr.write(`aontu: ${u.path} escapes ${out}\n`);
+                return 2;
+            }
+        }
+        for (const u of report.units) {
+            const full = (0, node_path_1.resolve)(out, u.path);
+            try {
+                (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(full), { recursive: true });
+                (0, node_fs_1.writeFileSync)(full, u.text, 'utf8');
+            }
+            catch (err) {
+                process.stderr.write(`aontu: cannot write ${u.path}: ${err.message}\n`);
+                return 2;
+            }
+            process.stderr.write(`wrote ${u.path}\n`);
+        }
+    }
+    else if (undefined !== check) {
+        // RENDER AND COMPARE: a unit whose bytes differ from the file at
+        // <dir>/<path>, or whose file is absent, is drift, listed by path.
+        // The CI form.
+        for (const u of report.units) {
+            let have = undefined;
+            try {
+                have = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(check, u.path), 'utf8');
+            }
+            catch {
+                // Absent is drift, reported below.
+            }
+            if (undefined === have) {
+                drift++;
+                process.stderr.write(`aontu: ${u.path} is missing from ${check}\n`);
+            }
+            else if (have !== u.text) {
+                drift++;
+                process.stderr.write(`aontu: ${u.path} differs from the rendered unit\n`);
+            }
+        }
+    }
+    else if (coverage) {
+        // THE COVERAGE REPORT (P7), one line per finding and a count at
+        // the end: dead model first, then the declarations no rule
+        // produced. A clean report is the count line alone.
+        const cov = report.coverage;
+        for (const d of cov.dead) {
+            process.stdout.write(`dead: ${d}\n`);
+        }
+        for (const u of cov.unruled) {
+            process.stdout.write(`unruled: ${u.unit} ${u.path}\n`);
+        }
+        process.stdout.write(`coverage: ${cov.read.length} path(s) read, ${cov.dead.length} ` +
+            `no output consumed, ${cov.unruled.length} declaration(s) ` +
+            'no rule produced\n');
+    }
+    else {
+        // THE SUMMARY: one line per unit -- its path, its language and its
+        // size -- since several units have no one text to print.
+        for (const u of report.units) {
+            process.stdout.write(`${u.path}\t${u.lang}\t${u.text.length} bytes\n`);
+        }
+    }
+    for (const l of report.lossy) {
+        process.stderr.write(`lossy: ${l.unit} ${l.path} tier ${l.tier} ${l.construct}: ${l.reason}\n`);
+    }
+    return renderExit(report, drift);
+}
+// D8's exit table over a report: a refused unit path is usage (2), a
+// strict refusal is lossy (1), any other error is the document's (4);
+// drift under --check is 1.
+function renderExit(report, drift) {
+    if ('error' === report.verdict) {
+        const errors = report.errors;
+        if (errors.every((f) => 'render_path' === f.code)) {
+            return 2;
+        }
+        if (errors.every((f) => 'render_strict' === f.code)) {
+            return 1;
+        }
+        return 4;
+    }
+    return 0 < drift ? 1 : 0;
+}
+// ---------------------------------------------------------------------
+// THE TEMPLATE SURFACE (docs/design/TEMPLATE.0.md; RENDER.0.md P8): the
+// two transforms and the round trip between them. `render` reads a
+// template directly, by its extension; this verb is for seeing the
+// canonical form, for writing one by hand and sugaring it, and for the
+// check that keeps a committed template and its meaning in agreement.
+const TEMPLATE_HELP = 'aontu template [--resugar] [--check] [--marker <token>] <file> (try --help)';
+function runTemplate(argv) {
+    const files = [];
+    let resugar = false;
+    let check = false;
+    let marker = undefined;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if ('-h' === arg || '--help' === arg) {
+            process.stdout.write(HELP);
+            return 0;
+        }
+        else if ('--resugar' === arg) {
+            resugar = true;
+        }
+        else if ('--check' === arg) {
+            check = true;
+        }
+        else if ('--marker' === arg) {
+            marker = argv[++i];
+            if (null == marker) {
+                process.stderr.write('aontu: --marker needs a token\n');
+                return 2;
+            }
+        }
+        else if (arg.startsWith('-')) {
+            process.stderr.write(`aontu: unknown template option ${arg} (try --help)\n`);
+            return 2;
+        }
+        else {
+            files.push(arg);
+        }
+    }
+    if (1 !== files.length) {
+        process.stderr.write(`aontu: template needs one file\n${TEMPLATE_HELP}\n`);
+        return 2;
+    }
+    // THE TWO ARE DIRECTIONS, NOT MODES THAT COMPOSE: `--check` reads a
+    // template and asks whether the round trip answers it back, and
+    // `--resugar` reads the canonical form instead. A run cannot be both
+    // at once, because the file is one thing or the other.
+    if (resugar && check) {
+        process.stderr.write('aontu: template takes one of --resugar or --check\n');
+        return 2;
+    }
+    let src;
+    try {
+        src = (0, node_fs_1.readFileSync)(files[0], 'utf8');
+    }
+    catch (err) {
+        process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`);
+        return 2;
+    }
+    const mark = marker ?? (0, template_1.markerFor)(files[0]);
+    if (check) {
+        // THE ROUND TRIP IS THE CHECK (D6): the file held to the spelling
+        // the two transforms answer. What that names is a marker line the
+        // transform would not have written -- one without its space, or one
+        // whose aontu is indented after the marker rather than before it,
+        // since the marker keeps its own indentation. It does NOT name a
+        // changed body line: a template's whitespace is output, so a
+        // trimmed trailing space is still a valid template and it is
+        // `render --check` against the committed files that catches it.
+        // The first line that differs is the report, since a whole diff of
+        // a generator is the file again.
+        const back = (0, template_1.resugarTemplate)((0, template_1.desugarTemplate)(src, mark), mark);
+        if (back === src) {
+            return 0;
+        }
+        const want = back.split('\n');
+        const have = src.split('\n');
+        let n = 0;
+        while (n < want.length && n < have.length && want[n] === have[n]) {
+            n++;
+        }
+        // THE TWO ARE THE SAME LENGTH, always: each transform maps one
+        // line to one line and applies the same trailing-newline rule, so
+        // `back` has as many lines as `src`. The loop above therefore stops
+        // at a real difference rather than by running out of either -- an
+        // equal prefix all the way to the end IS `back === src`, which
+        // returned above. So both indexes are in range here.
+        process.stderr.write(`aontu: ${files[0]}:${n + 1} is not what the round trip answers\n` +
+            `  have: ${JSON.stringify(have[n])}\n` +
+            `  want: ${JSON.stringify(want[n])}\n`);
+        return 1;
+    }
+    process.stdout.write(resugar ?
+        (0, template_1.resugarTemplate)(src, mark) : (0, template_1.desugarTemplate)(src, mark));
+    return 0;
+}
+// ---------------------------------------------------------------------
 // The canon-hash (G6 phase 1): the pin an agent, a lockfile or a
 // registry stores for "this module, this meaning". The hash covers the
 // module evaluated STANDALONE -- its own include closure resolved and
@@ -3022,6 +3482,22 @@ function runFmt(argv) {
     }
     let worst = 0;
     for (const file of files) {
+        // FMT FORMATS AONTU SOURCE, AND THE EXTENSION SAYS WHAT A FILE IS
+        // (ADR-012's rule, and the one `render` reads a template by).
+        // A TEMPLATE FILE IS NOT AONTU (docs/design/TEMPLATE.0.md; P8):
+        // its marker lines are fragments of a document and its other lines
+        // are the target's, so there is nothing here to format that would
+        // not also rewrite the output. Refused rather than attempted, and
+        // refused BY NAME rather than by a parse failure, because a `#-`
+        // template parses: `#` opens a comment, so every marker line
+        // vanishes and what is left is read as a document that was never
+        // written. The verb answered `0` over one, having understood none
+        // of it.
+        if (!/[.](aon|aontu)$/.test(file)) {
+            process.stderr.write(`aontu: ${file} is not aontu source (.aon, .aontu); a generator ` +
+                'written in the target\'s own syntax is aontu template\'s\n');
+            return 2;
+        }
         let src;
         try {
             src = (0, node_fs_1.readFileSync)(file, 'utf8');
@@ -3199,6 +3675,12 @@ function main(argv, servers = SERVERS) {
     if ('jsonschema' === argv[2]) {
         return finish(runJsonSchema(argv.slice(3)));
     }
+    if ('render' === argv[2]) {
+        return finish(runRender(argv.slice(3)));
+    }
+    if ('template' === argv[2]) {
+        return finish(runTemplate(argv.slice(3)));
+    }
     if ('reaches' === argv[2]) {
         return finish(runReaches(argv.slice(3)));
     }
@@ -3296,5 +3778,5 @@ function main(argv, servers = SERVERS) {
     else {
         runStdin(mode, trust).then((code) => finish(code));
     }
-} /* node:coverage ignore next 16 */
+} /* node:coverage ignore next 18 */
 //# sourceMappingURL=cli.js.map