aontu 0.63.0 → 0.64.0

package/dist/cli.js

@@ -13,8 +13,8 @@ exports.runRelations = runRelations;
 exports.runReaches = runReaches;
 exports.runView = runView;
 exports.runJsonSchema = runJsonSchema;
-exports.runRender = runRender;
 exports.runTemplate = runTemplate;
+exports.runTrace = runTrace;
 exports.runMod = runMod;
 exports.runHash = runHash;
 exports.runGet = runGet;
@@ -40,8 +40,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 trace_1 = require("./trace");
 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");
@@ -67,11 +67,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>]
                       [--profile <file>] <file>
+       aontu trace [--at <path>] [--format json] [--marker <token>]
+                   [--profile <file>] <file>
        aontu hash [options] <file>
        aontu mod tidy|verify|vendor|manifest [options] [dir]
        aontu get <path> [options] <file>
@@ -317,37 +316,11 @@ 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, aontu: render: Lang: {lang,
-                    ...}, vetted against aontu:render; 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 a language the table does not know names its marker with
---marker, or declares it once in a profile file that --profile reads.
+A template entry file whose extension is not .aon is a GENERATOR: a
+document 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 a language the table does not know names its marker with --marker,
+or declares it once in a profile file that --profile reads.
 
 Template options:
   --resugar       The file is the canonical aontu; print the template
@@ -457,11 +430,11 @@ Fmt options:
 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.
 
-A file whose extension is not .aon is a GENERATOR, as it is for render:
-the aontu its marker lines carry is formatted, the marker stands at the
-left margin with the aontu indented after it, and every line of output
-is held on a line of its own. A file with no marker line in it is
-another language's, and is refused.
+A file whose extension is not .aon is a GENERATOR, as it is for
+template: the aontu its marker lines carry is formatted, the marker
+stands at the left margin with the aontu indented after it, and every
+line of output is held on a line of its own. A file with no marker line
+in it is another language's, and is refused.
 
 Fmt exit codes: 0 formatted or clean, 1 a --check file would change or
 a --strict finding, 2 usage, 4 a document does not parse.
@@ -1764,6 +1737,12 @@ const VIEW_USAGE_CODES = [
 ];
 const MOD_HELP = 'aontu mod tidy|verify|vendor|manifest [dir] (try --help)';
 function runMod(argv) {
+    const trusted = takeTrust(argv);
+    if (null == trusted) {
+        return 2;
+    }
+    argv = trusted.argv;
+    const trust = trusted.trust;
     const rest = [];
     let format = 'text';
     let against;
@@ -1819,10 +1798,11 @@ function runMod(argv) {
         process.stderr.write('aontu: --against is a manifest option\n');
         return 2;
     }
-    const report = 'tidy' === sub ? (0, mod_tool_1.modTidy)(dir, modToolOptions()) :
-        'verify' === sub ? (0, mod_tool_1.modVerify)(dir, modToolOptions()) :
-            'vendor' === sub ? (0, mod_tool_1.modVendor)(dir, modToolOptions()) :
-                (0, mod_tool_1.modManifest)(dir, modToolOptions(), against);
+    const modopts = modToolOptions(trust, (0, node_path_1.resolve)(dir));
+    const report = 'tidy' === sub ? (0, mod_tool_1.modTidy)(dir, modopts) :
+        'verify' === sub ? (0, mod_tool_1.modVerify)(dir, modopts) :
+            'vendor' === sub ? (0, mod_tool_1.modVendor)(dir, modopts) :
+                (0, mod_tool_1.modManifest)(dir, modopts, against);
     process.stdout.write(('json' === format ?
         (0, aontu_1.exactJSON)({ aontu: { version: version(), verb: 'mod ' + sub }, ...report }, 2) :
         modText(sub, report)) + '\n');
@@ -1843,11 +1823,16 @@ const MOD_EXIT = {
 // The tooling's evaluator: the same standalone evaluation the module
 // resolver verifies with (ts/src/mod.ts), and for the same reason —
 // only the engine can say what a module MEANS.
-function modToolOptions() {
+function modToolOptions(trust, entryRoot) {
+    const opts = verbOpts(trust, entryRoot);
+    // The user cache lives outside any confinement root, so a confined
+    // run reads the vendor tree only -- as the evaluator's own module
+    // leg already does when a root is set.
+    const rooted = null != opts.trust?.include?.root;
     return {
-        cache: (0, mod_1.modCacheDir)(),
+        ...(rooted ? {} : { cache: (0, mod_1.modCacheDir)() }),
         eval: (src, path) => {
-            const a0 = new aontu_1.Aontu();
+            const a0 = new aontu_1.Aontu(opts);
             const ctx = a0.ctx({ collect: true });
             const val = a0.unify(src, { path }, ctx);
             return {
@@ -1981,6 +1966,108 @@ function runRelations(argv) {
     }
     return RELATIONS_EXIT[report.verdict];
 }
+const TRACE_HELP = 'aontu trace [--at <path>] [--format json] [--marker <token>] ' +
+    '[--profile <file>] <file>';
+// WHAT WROTE THIS LINE. Every piece a rule stamped, under the
+// component tree, with the file it reached, the rule set that wrote it
+// and the model node the dispatch matched.
+function runTrace(argv) {
+    const trusted = takeTrust(argv);
+    if (null == trusted) {
+        return 2;
+    }
+    argv = trusted.argv;
+    const trust = trusted.trust;
+    const rest = [];
+    const profileFiles = [];
+    let format = 'text';
+    let at = 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 ('--marker' === arg) {
+            marker = argv[++i];
+            if (null == marker) {
+                process.stderr.write('aontu: --marker needs a token\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 (arg.startsWith('-')) {
+            process.stderr.write(`aontu: unknown trace option ${arg} (try --help)\n`);
+            return 2;
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    if (1 !== rest.length) {
+        process.stderr.write(`aontu: trace needs one file\n${TRACE_HELP}\n`);
+        return 2;
+    }
+    let src;
+    try {
+        src = (0, node_fs_1.readFileSync)(rest[0], 'utf8');
+    }
+    catch (err) {
+        process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`);
+        return 2;
+    }
+    const declared = loadProfiles(profileFiles, trust);
+    if ('number' === typeof declared) {
+        return declared;
+    }
+    // A GENERATOR IS AN ENTRY, not a preprocessing step: the file whose
+    // provenance is asked for is the one the author edits.
+    if (!rest[0].endsWith('.aon')) {
+        src = (0, template_1.desugarTemplate)(src, marker ??
+            (0, template_1.markerFromProfiles)(declared, rest[0]) ?? (0, template_1.markerFor)(rest[0]));
+    }
+    const report = (0, trace_1.traceRun)(src, {
+        path: rest[0], at,
+        ...verbOpts(trust, entryRootOf(rest[0])),
+    });
+    if ('error' === report.verdict) {
+        // An error report always carries its findings.
+        const errors = report.errors;
+        process.stderr.write(errors.map(renderFinding).join('\n') + '\n');
+        return 4;
+    }
+    if ('json' === format) {
+        process.stdout.write(JSON.stringify({ trace: report.trace }) + '\n');
+        return 0;
+    }
+    for (const e of report.trace) {
+        process.stdout.write([e.file, e.at, e.node, e.rule].join('\t') + '\n');
+    }
+    return 0;
+}
 function runReaches(argv) {
     const trusted = takeTrust(argv);
     if (null == trusted) {
@@ -2530,281 +2617,6 @@ function runJsonSchema(argv) {
     return 'error' === report.verdict ? 4 :
         strict && 'lossy' === report.verdict ? 1 : 0;
 }
-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;
-    }
-    const loadedProfiles = loadProfiles(profileFiles, trust);
-    if ('number' === typeof loadedProfiles) {
-        return loadedProfiles;
-    }
-    const profiles = loadedProfiles;
-    if (!files[0].endsWith('.aon')) {
-        src = (0, template_1.desugarTemplate)(src, marker ??
-            (0, template_1.markerFromProfiles)(profiles, files[0]) ?? (0, template_1.markerFor)(files[0]));
-    }
-    // A RENDER WITH NO PROFILE PRODUCES NO UNITS, and said so with zero
-    // bytes and exit 0. The profile is what maps a model onto a
-    // language, so without one there is nothing for the renderer to
-    // write -- which is a usable answer only if the caller is told.
-    const noProfiles = 0 === profiles.length;
-    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])),
-    });
-    // Said once, whatever the format: stdout stays the report.
-    if ('error' !== report.verdict && 0 === report.units.length) {
-        vacuous('nothing was rendered', noProfiles
-            ? 'no profile was given, and the document declares none' +
-                ' (see aontu help tasks)'
-            : 'the document produced no units under this profile');
-    }
-    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;
-}
 const TEMPLATE_HELP = 'aontu template [--resugar] [--check] [--marker <token>] <file> (try --help)';
 function runTemplate(argv) {
     const trusted = takeTrust(argv);
@@ -2896,9 +2708,9 @@ function runTemplate(argv) {
     return 0;
 }
 // The profiles named by --profile, vetted, or the exit code that says
-// why not. A profile is a language declared as data: `render` matches
-// one to a unit by `lang`, and `template` and `fmt` match one to a file
-// by the extensions its `template.ext` names.
+// why not. A profile is a language declared as data: `template` and
+// `fmt` match one to a file by the extensions its `template.ext`
+// names.
 function loadProfiles(profileFiles, trust) {
     const profiles = [];
     const langs = new Map();
@@ -2911,7 +2723,7 @@ function loadProfiles(profileFiles, trust) {
             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)) });
+        const loaded = (0, aontu_1.loadProfile)(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;
@@ -3583,8 +3395,8 @@ function runFmt(argv) {
         }
         else if ('--marker' === arg) {
             // THE MARKER SAYS THE FILE IS A GENERATOR, whatever its
-            // extension: `render` and `template` take the same option for
-            // the same reason, a language the table has never seen.
+            // extension: `fmt` and `template` take the same option for the
+            // same reason, a language the table has never seen.
             marker = argv[++i];
             if (null == marker) {
                 process.stderr.write('aontu: --marker needs a token\n');
@@ -3991,8 +3803,8 @@ function runInit(argv) {
 const KNOWN_VERBS = [
     'agentsmd', 'allow', 'breaking', 'explain', 'fmt', 'get', 'hash',
     'help', 'init', 'jsonschema', 'lsp', 'mcp', 'mod', 'reaches',
-    'relations', 'render', 'set', 'subsume', 'template', 'trim', 'vet',
-    'view', 'why',
+    'relations', 'set', 'subsume', 'template', 'trace', 'trim',
+    'vet', 'view', 'why',
 ];
 exports.KNOWN_VERBS = KNOWN_VERBS;
 // looksLikeVerb reports whether an unreadable argument was meant as a
@@ -4112,12 +3924,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 ('trace' === argv[2]) {
+        return finish(runTrace(argv.slice(3)));
+    }
     if ('reaches' === argv[2]) {
         return finish(runReaches(argv.slice(3)));
     }
@@ -4212,5 +4024,5 @@ function main(argv, servers = SERVERS) {
     else {
         runStdin(mode, format, trust).then((code) => finish(code));
     }
-} /* node:coverage ignore next 20 */
+} /* node:coverage ignore next 21 */
 //# sourceMappingURL=cli.js.map