aontu 0.61.0 → 0.63.0

package/dist/vet.js

@@ -6,6 +6,7 @@ exports.displayFile = displayFile;
 exports.failureFinding = failureFinding;
 exports.anchorAt = anchorAt;
 exports.throughResidue = throughResidue;
+exports.vetCoverage = vetCoverage;
 exports.vet = vet;
 const aontu_1 = require("./aontu");
 const node_path_1 = require("node:path");
@@ -15,49 +16,18 @@ const walk_1 = require("./walk");
 const BagVal_1 = require("./val/BagVal");
 const utility_1 = require("./utility");
 const subsume_1 = require("./subsume");
-// The `--at` refusal is the SAME refusal `get` and `why` give for a
-// path that names nothing, down to the "did you mean" -- so it is that
-// one, not a second spelling of it. A cycle in the module graph
-// (query imports anchorAt from here), and a benign one: both sides
-// use the other only from inside a function body, never at load time.
 const query_1 = require("./query");
+const keyorder_1 = require("./keyorder");
 // The default cap, exported because the CLI applies it to the WHOLE
 // report across several data files and must not carry a second copy of
 // the number (ts/src/cli.ts).
 exports.VET_MAX_ERRORS = 20;
 const DEFAULT_SCHEMA_URL = 'schema';
 const DEFAULT_DATA_URL = 'data';
-// Every site in a freshly parsed tree carries the same url, and for a
-// bare parse that url is the empty string: `site.url` is only populated
-// by the multisource loader (ts/src/lang.ts). Vet takes two documents
-// from its CALLER, not from the filesystem, so it stamps provenance
-// itself — which is what lets the report assign site ROLES by
-// provenance rather than by NilVal's source-order heuristic, exactly as
-// the design requires.
-// EVERY SITE NAMES THE FILE WHOSE TEXT IT EXCERPTS (the review's
-// finding F, use-cases/BUGS.md §25). The parser already names the file
-// each value was read from -- a value loaded through `@"lib/types.aon"`
-// carries that path, with that file's row and column -- and this walk
-// used to OVERWRITE every url with the entry document's name. The
-// coordinates stayed the included file's, so a finding cited
-// `entry.aon:3:7` for text that lives three files away, at a line the
-// entry may not even have. A repair agent that follows the site edits
-// the wrong file.
-//
-// Only the values that carry no name of their own are stamped: those
-// are the ones the engine minted rather than read, and the entry is
-// the honest name for them. The urls actually seen are collected, so
-// the report can still tell WHICH DOCUMENT a site belongs to without
-// pretending they all came from one file -- see roleOf.
 function stampUrl(v, url, seen) {
     const urls = seen ?? new Set();
     urls.add(url);
     (0, walk_1.walkVals)(v, (n) => {
-        // UNDEFINED counts as unstamped, not just empty: the parser leaves
-        // the url undefined on one of its two paths (ts/src/lang.ts), and
-        // treating that as a name would put `undefined` in the url set --
-        // where the OTHER document's unstamped values would then match it,
-        // and every site would read `data`.
         if (null == n.site.url || '' === n.site.url) {
             n.site.url = url;
         }
@@ -66,20 +36,6 @@ function stampUrl(v, url, seen) {
     }, new Set());
     return urls;
 }
-// A FILE THE READER CAN OPEN. The parser resolves an include to an
-// absolute path, which is the right identity (two files loading the
-// same library by different relative spellings must be one file) and
-// the wrong NAME: a report whose entry reads `contract.aon` and whose
-// included site reads `/home/someone/checkout/types.aon` is a report
-// that cannot be uploaded as SARIF, diffed between machines, or read
-// beside the command that produced it.
-//
-// So an included file is named as the ENTRY'S OWN NAME reaches it:
-// relative to the entry's directory, then re-anchored on however the
-// caller spelled the entry. `vet contract.aon` names `types.aon`;
-// `vet a/b/contract.aon` names `a/b/types.aon`; an absolute entry
-// keeps absolute includes. A caller who passed no path at all has no
-// base to relativise against and gets the url unchanged.
 function displayFile(url, label, path) {
     if (url === label || null == path || '' === url || !(0, node_path_1.isAbsolute)(url)) {
         return url;
@@ -88,57 +44,22 @@ function displayFile(url, label, path) {
     const dir = (0, node_path_1.dirname)(label);
     return '.' === dir ? rel : (0, node_path_1.join)(dir, rel);
 }
-// The name for one site, taken from the document the site BELONGS to
-// -- which is the role, already decided by url-set membership. Doing
-// it here rather than from a map built at stamping time is not a
-// shortcut: a nil's operands are off the tree by the time the report
-// is built, so a value first seen during the MEET (the commonest
-// schema site there is) would be missing from any such map.
 function displayOf(file, role, prov) {
     return 'data' === role
         ? displayFile(file, prov.dataUrl ?? file, prov.dataPath)
         : displayFile(file, prov.schemaUrl ?? file, prov.schemaPath);
 }
-// The ROLE of a site: which of the two documents it belongs to. Not a
-// name comparison -- a data document may itself include another file,
-// and that file's values are still data. Membership of the url set the
-// stamping walk collected is the question, and the answer is `schema`
-// for anything the data walk never reached (an engine-minted value
-// stamped with the schema entry, say).
 function roleOf(file, prov) {
     return prov.data.has(file) ? 'data' : 'schema';
 }
-// `$.a.b`, and `$` for the root. Deliberately NOT delimiter-escaped: a
-// map key may contain any character, including every separator a
-// compact summary might pick, so the path is carried as a JSON string
-// and never parsed back out of a larger token.
 function pathText(path) {
     return '$' + (null != path && 0 < path.length ? '.' + path.join('.') : '');
 }
-// `secondary` is the only operand that can be absent — a `closed` or an
-// incomplete finding has one side, a two-site conflict has both — so
-// this is the one nullable input, and every Val that does arrive
-// carries a site and a canon.
 function siteOf(v, prov) {
     if (null == v) {
         return undefined;
     }
-    // The report's `file` is whatever the site carries, and by the time a
-    // site reaches a report that is always a stamped name: vet walks both
-    // documents before they meet, and the walk reaches the off-peg values
-    // a finding can name (ts/src/walk.ts). A consumer therefore reads
-    // `file` without a presence check, and the Go port -- whose field is
-    // a plain string -- writes the same key.
-    //
-    // NOT coalesced. The parser leaves the url undefined on one of its
-    // two paths (ts/src/lang.ts), and a `?? ''` here would be dead code
-    // that hides it: if a value ever reaches a report unstamped, the two
-    // ports should disagree loudly rather than quietly agree on an empty
-    // name that neither of them meant.
     const file = v.site.url;
-    // NAMED for the reader, ROLED by the raw url: the two questions are
-    // different, and only the first is about how the file is spelled
-    // (see displayFile).
     const role = roleOf(file, prov);
     return {
         file: displayOf(file, role, prov),
@@ -154,32 +75,16 @@ function siteOf(v, prov) {
 // The underlying NilVal fields are untouched: this is a report-layer
 // projection, so the existing error.tsv assertions do not move.
 function sitesOf(nil, prov) {
-    // `?? nil`: a failure raised about a CONSTRUCT rather than about a
-    // failed meet -- a lossy integer literal, say -- carries no operands
-    // at all, and reporting it about ITSELF is what ctx.adderr already
-    // does for the same reason. Without the fallback the report built a
-    // site out of `undefined` and threw while partitioning it, which is
-    // the one thing vet promises not to do: a bad value in the data is
-    // DATA, and the caller gets a report.
     const sites = [siteOf(nil.primary ?? nil, prov)];
     const secondary = siteOf(nil.secondary, prov);
     if (null != secondary) {
         sites.push(secondary);
     }
-    // Partitioned rather than sorted: which of the two NilVal operands is
-    // `primary` follows source order within one document, which says
-    // nothing useful when one side is a schema and the other is data.
     return [
         ...sites.filter((s) => 'data' === s.role),
         ...sites.filter((s) => 'schema' === s.role),
     ];
 }
-// The message text is MATERIALISED on demand, exactly as handleErrors
-// materialises one before a caller sees it: makeNilErr defers it
-// because most NilVals are transient and never rendered, and only the
-// throwing path asks for it. Without this a finding could carry an
-// empty `message` -- which is what the incomplete half of every report
-// did, and what any nil built during the PARSE of a document did.
 function materialise(nil, ctx) {
     if (null == nil.msg || '' === nil.msg) {
         (0, err_1.descErr)(nil, ctx);
@@ -199,30 +104,13 @@ function findingOf(nil, prov) {
         class: nil.class,
         severity: 'error',
         path: pathText(nil.path),
-        // The HEADLINE only, WITHOUT ANSI: the frames below it are for a
-        // human reading a terminal, and the first line is the part the two
-        // ports hold to byte parity. Materialised before this runs, so it
-        // is always there (see materialise above). The escapes matter for
-        // one family only -- a parse failure's text comes from the parser,
-        // which colours its marker -- and a machine-readable report is no
-        // place for terminal control codes.
         message: stripAnsi(nil.msg.split('\n')[0]),
         sites: sitesOf(nil, prov),
     };
-    // The hint, whole, with its detail placeholders filled in exactly as
-    // the terminal frame fills them. Trailing whitespace is dropped
-    // because it is spacing for the frame that used to follow it, not
-    // part of the text; the deliberate blank lines INSIDE a hint are
-    // `\n \n` and survive.
     const hint = (0, err_1.getHint)(nil.why, nil.details);
     if (null != hint && '' !== hint) {
         finding.hint = stripAnsi(hint).replace(/\s+$/, '');
     }
-    // `expected`/`actual` are the admissible-alternatives contract, and
-    // the constraint algebra already produces them: G1's atoms attach the
-    // normalised residual and the offending value, and `must` attaches
-    // the author's message. Read them where they are rather than
-    // re-deriving them here.
     if ('string' === typeof details.expected) {
         finding.expected = details.expected;
     }
@@ -234,29 +122,10 @@ function findingOf(nil, prov) {
     }
     return finding;
 }
-// Findings are sorted BY VET, not by the walk. The underlying walk
-// iterates raw object keys and the two hosts disagree about their order
-// — `10:… 9:…` yields ["9","10"] in JavaScript, which hoists
-// integer-like keys, against Go's insertion order (ts/src/keyorder.ts
-// exists for exactly this) — so an unsorted report could never be in
-// cross-port parity.
-//
-// The order is by data site (file, row, column), then code, then path.
-// It is carried in ONE key string rather than a cascade of comparisons:
-// the row and column are zero-padded so lexicographic order is numeric
-// order, and NUL joins the fields because no field can contain one.
-// A cascade would need a test per tie-breaker to stay honest; a key
-// needs none, and cannot disagree with itself.
 const ORDER_PAD = 9;
 function pad(n) {
     return String(n).padStart(ORDER_PAD, '0');
 }
-// The walk index is the LAST field, which makes every key unique and
-// the sort below total: two findings can otherwise share everything the
-// key carries — same data site, same code, same path — and a comparator
-// that has to answer "equal" is one more thing to get right in two
-// languages. With the index appended, ties simply keep walk order, in
-// both ports, by construction rather than by the sort's promises.
 function orderKey(f, index) {
     const site = f.sites[0];
     return [
@@ -268,42 +137,9 @@ function orderKey(f, index) {
         pad(index),
     ].join('\u0000');
 }
-// A DOCUMENT THAT DOES NOT STAND UP, in the finding shape (the
-// review's finding F). `trim` and `relations` answered an unusable
-// document with `verdict: error` and an EMPTY list: the caller learned
-// that something was wrong and nothing about what, which is the one
-// thing a repair loop cannot work with. Both verbs take ONE document,
-// so there is no role to decide -- the document is the thing being
-// checked and the thing to edit, which is what `data` means here.
-//
-// The engine's own first error IS the finding: these verbs add nothing
-// to a diagnosis the evaluator already made, and the FIRST is enough
-// because everything after it is a consequence.
-//
-// The Go twin is failureFinding in go/vet.go.
 function failureFinding(ctx, url, failed) {
-    // ctx.err IS SOMETIMES EMPTY, and the comment that used to stand here
-    // said otherwise (use-cases/BUGS.md §43). `&: id(root)` fails with a
-    // NIL ROOT and NO COLLECTED ERROR -- the id-spread refusal is the
-    // root itself -- and every verb that reports "this document does not
-    // stand up" then read `ctx.err[0]` as undefined and died: a TypeError
-    // out of `relations`, `reaches` and `jsonschema` in TypeScript, a
-    // panic in Go. The one shape where finding F's own invariant, that a
-    // document which does not stand up SAYS SO in the finding shape, was
-    // answered with a stack trace.
-    //
-    // `failed` is the caller's own root -- every caller has it, and its
-    // condition is `0 < ctx.err.length || root.isNil`, so when the first
-    // half is false the second holds and the root IS the reason.
     const nil = ctx.err[0] ?? failed;
     materialise(nil, ctx);
-    // STAMPED, as vet stamps both documents before they meet: siteOf does
-    // not coalesce a missing name (deliberately -- see there), so a site
-    // that reached the report unstamped would carry `file: undefined`.
-    // The three Vals a finding can name are the nil and its two operands,
-    // and the url set collects whatever name each already had, so a value
-    // read from an included file keeps that file's name and still counts
-    // as part of the one document being checked.
     const at = url ?? '';
     const urls = new Set([at]);
     for (const v of [nil, nil.primary, nil.secondary]) {
@@ -325,27 +161,7 @@ function anchorAt(root, at) {
     const parts = trimmed.split('.').filter((p) => '' !== p);
     let node = root;
     for (const part of parts) {
-        // A SIZING RESIDUE IS ITS CONTAINER, plus a note about what the
-        // container must still satisfy (use-cases/BUGS.md §16). The path
-        // steps through it: `$.a.ports.0.port` names the same node whether
-        // or not `ports` still carries a `unique()`, and an anchor that
-        // stopped here would report `no_path` for a key the document
-        // plainly has.
         node = throughResidue(node);
-        // TYPE-DIRECTED, not a property lookup on whatever `peg` happens to
-        // be. An anchor is a STRUCTURAL path into the schema — the same
-        // thing a reference means by `$.a.b` — so it walks map keys and
-        // list indices, and stops at anything else.
-        //
-        // Indexing the peg generically walked much further than that: into
-        // a junction's branches (`a:1|2` with `--at $.a.0` validated
-        // against ONE branch), into a constraint's atom arguments (so
-        // `min(2)` with `--at $.a.0` reported the bound's own argument as
-        // the truth), into a pref's wrapped value through the literal key
-        // `peg`, and into an array's `length` — that last one handing back
-        // a JavaScript NUMBER as the anchor, after which every document
-        // whatsoever came back valid. The Go port has always been
-        // type-directed here; this is the canonical side moving to it.
         if (true === node?.isMap) {
             const peg = node.peg;
             if (null == peg || !Object.prototype.hasOwnProperty.call(peg, part)) {
@@ -369,38 +185,158 @@ function anchorAt(root, at) {
             return undefined;
         }
     }
-    // THE ANCHOR KEEPS ITS ATOM. Stepping THROUGH a residue is right --
-    // `$.x.a` names a key of the container whatever the container still
-    // has to satisfy -- but ARRIVING at one and handing back the bare
-    // container drops a constraint the author wrote, so `--at $.x` vetted
-    // clean against a `length` the evaluator enforces. The residue is the
-    // honest schema for the node: the meet drives it, and generation
-    // settles it, exactly as it does without an anchor.
     return node;
 }
-// The container inside a settled sizing residue, or the value itself.
-// EXPORTED for the `doc` figure, which walks the same shape the anchor
-// does: a list still carrying a `unique()` is a list, and a drawing
-// that stopped at the residue would omit keys the document plainly
-// has.
 function throughResidue(v) {
     return (0, BagVal_1.sizingResidue)(v)?.bag ?? v;
 }
-// Validate `dataSrc` against `schemaSrc`.
-//
-// Never throws for findings: a contradiction in the data is DATA, and
-// the caller gets a report. It throws only when the caller's own inputs
-// are unusable — which is why an unusable schema is a verdict (`error`)
-// rather than an exception too: "the schema is broken" is a fact the
-// agent loop needs to branch on, not an exceptional condition.
+const COVER_TEMPLATE = '&';
+// Is this value a bag with children to walk?
+function coverKids(v) {
+    const out = [];
+    if (true === v.isMap && null != v.peg) {
+        for (const k of Object.keys(v.peg).sort(keyorder_1.cmpCodePoint)) {
+            out.push({ key: k, val: v.peg[k] });
+        }
+    }
+    else if (true === v.isList && Array.isArray(v.peg)) {
+        v.peg.forEach((m, i) => out.push({ key: String(i), val: m }));
+    }
+    return out;
+}
+function coverTemplate(v) {
+    const cj = v?.spread?.cj;
+    return null != cj && true === cj.isVal && true !== cj.isTop ? cj : undefined;
+}
+function coverDeclare(v, path, out) {
+    const tpl = coverTemplate(v);
+    if (null != tpl) {
+        const at = [...path, COVER_TEMPLATE];
+        out.set(pathText(at), tpl);
+        coverDeclare(tpl, at, out);
+    }
+    for (const { key, val } of coverKids(v)) {
+        const at = [...path, key];
+        out.set(pathText(at), val);
+        coverDeclare(val, at, out);
+    }
+}
+// Every path in the data, and whether it is a LEAF -- a node with no
+// children, which is where a value lives.
+function coverDataPaths(v, path, out) {
+    const kids = coverKids(v);
+    if (0 < path.length) {
+        out.push({ path: pathText(path), leaf: 0 === kids.length });
+    }
+    for (const { key, val } of kids) {
+        coverDataPaths(val, [...path, key], out);
+    }
+}
+// Walk one data path down the schema, naming the declaration that
+// constrains it -- the exact key where the schema has one, else the
+// covering template. Undefined when the schema declares nothing there.
+function coverMatch(anchor, segs) {
+    let at = anchor;
+    let decl = '';
+    for (const seg of segs) {
+        const named = true === at.isMap && null != at.peg ? at.peg[seg]
+            : true === at.isList && Array.isArray(at.peg) ? at.peg[Number(seg)]
+                : undefined;
+        if (null != named && true === named.isVal) {
+            decl = '' === decl ? seg : decl + '.' + seg;
+            at = named;
+            continue;
+        }
+        const tpl = coverTemplate(at);
+        if (null == tpl) {
+            return undefined;
+        }
+        decl = '' === decl ? COVER_TEMPLATE : decl + '.' + COVER_TEMPLATE;
+        at = tpl;
+    }
+    return '$.' + decl;
+}
+// The SHALLOWEST members of a set of paths: one whose parent is also in
+// the set is covered by naming the parent, and naming both is noise.
+// `render --coverage`'s `dead` is built on the same rule.
+function coverShallowest(paths) {
+    const held = new Set(paths);
+    return paths.filter((p) => {
+        for (let at = p; -1 !== at.lastIndexOf('.');) {
+            at = at.slice(0, at.lastIndexOf('.'));
+            if (held.has(at)) {
+                return false;
+            }
+        }
+        return true;
+    }).sort(keyorder_1.cmpCodePoint);
+}
+// The accounting itself: what the schema declared, what the data holds,
+// and which of each the other met.
+function vetCoverage(anchor, dataVal, coverageAt) {
+    const declarations = new Map();
+    coverDeclare(anchor, [], declarations);
+    const dataPaths = [];
+    coverDataPaths(dataVal, [], dataPaths);
+    // `--coverage-at` narrows the DATA side, which is the side a caller
+    // gating one subtree is asking about. The schema side follows from
+    // it: a declaration is unused only among the data actually measured.
+    const under = null == coverageAt ? undefined
+        : coverageAt.replace(/^\$\.?/, '');
+    const inScope = (p) => {
+        if (null == under || '' === under) {
+            return true;
+        }
+        const want = '$.' + under;
+        return p === want || p.startsWith(want + '.');
+    };
+    const used = new Set();
+    const unchecked = [];
+    let checked = 0;
+    let leaves = 0;
+    for (const { path, leaf } of dataPaths) {
+        if (!inScope(path)) {
+            continue;
+        }
+        const segs = path.replace(/^\$\.?/, '').split('.').filter((x) => '' !== x);
+        const decl = coverMatch(anchor, segs);
+        if (leaf) {
+            leaves++;
+        }
+        if (null == decl) {
+            unchecked.push(path);
+            continue;
+        }
+        used.add(decl);
+        if (leaf) {
+            checked++;
+        }
+    }
+    // A declaration is met when it constrained a data path, or when a
+    // declaration BENEATH it was: `$.a` is used by `$.a.b` meeting
+    // `$.a.b`, and reporting the parent as unused would be false.
+    const unused = [];
+    for (const decl of declarations.keys()) {
+        const covered = used.has(decl) ||
+            [...used].some((u) => u.startsWith(decl + '.'));
+        if (!covered) {
+            unused.push(decl);
+        }
+    }
+    return {
+        checked,
+        declared: declarations.size,
+        leaves,
+        unchecked: coverShallowest(unchecked),
+        unused: coverShallowest(unused),
+        vacuous: 0 === checked && 0 < leaves,
+    };
+}
 function vet(schemaSrc, dataSrc, opts) {
     const options = opts ?? {};
     const schemaUrl = options.schemaUrl ?? DEFAULT_SCHEMA_URL;
     const dataUrl = options.dataUrl ?? DEFAULT_DATA_URL;
     const maxErrors = options.maxErrors ?? exports.VET_MAX_ERRORS;
-    // ONE instance, two bases: the path rides on each CALL rather than on
-    // the constructor, because the schema and the data may live in
-    // different directories (Lang.parse takes `opts.path` per parse).
     const aontu = new aontu_1.Aontu((0, utility_1.includeOpts)(options));
     const schemaOpts = null == options.schemaPath ?
         undefined : { path: options.schemaPath };
@@ -411,33 +347,7 @@ function vet(schemaSrc, dataSrc, opts) {
     const schemaCtx = aontu.ctx({ collect: true });
     const schemaVal = aontu.unify(schemaSrc, schemaOpts, schemaCtx);
     if (0 < schemaCtx.err.length || true === schemaVal?.isNil) {
-        // A broken schema REPORTS, exactly as broken data does. It used to
-        // answer `findings: []` with exit 4 and nothing else, in both
-        // ports: the engine had collected the fault and vet threw it away,
-        // so an agent -- or a person -- was told the schema was broken and
-        // not what or where. The verdict stays `error` (the fault is in
-        // the truth, not in the data, and that distinction is the whole
-        // point of the class), but the finding travels with it.
-        //
-        // The FIRST error only, and the data path's reasoning applies
-        // unchanged: later errors in a document that does not stand up are
-        // consequences of the first rather than separate things to fix.
-        //
-        // ONE OF THE TWO IS ALWAYS THERE, and both are nils: the branch
-        // condition admits a collected error or a nil root, and every
-        // value on `schemaCtx.err` is a NilVal. There is no third case, so
-        // there is no guard here -- a guard that cannot fire is dead code,
-        // and dead code is what ADR-002 exists to keep out. (One stood
-        // here and the TypeScript line report called it covered; the Go
-        // gate, which measures blocks, refused the twin.)
         const failure = 0 < schemaCtx.err.length ? schemaCtx.err[0] : schemaVal;
-        // The normal path stamps both documents before they meet
-        // (stampUrl(anchor...) below), and this early return never reaches
-        // it, so it stamps what it is about to report: the unified root,
-        // and the failure itself -- a COLLECTED error is minted during
-        // unification and hangs off no tree, so nothing else would name
-        // it. The walk reaches a failure's operands (ts/src/walk.ts),
-        // which is what makes the sites say which file.
         stampUrl(schemaVal, schemaUrl);
         stampUrl(failure, schemaUrl);
         materialise(failure, schemaCtx);
@@ -454,11 +364,6 @@ function vet(schemaSrc, dataSrc, opts) {
     if (null != options.at) {
         anchor = anchorAt(schemaVal, options.at);
         if (null == anchor) {
-            // AND IT SAYS WHICH SEGMENT. `--at` naming nothing is an error
-            // verdict for the same reason a broken schema is -- the run
-            // could not be set up from the truth's side -- and it reports
-            // for the same reason too: a caller handed exit 4 and an empty
-            // list has nothing to act on.
             return {
                 verdict: 'error',
                 truncated: false,
@@ -471,22 +376,6 @@ function vet(schemaSrc, dataSrc, opts) {
     const dataCtx = aontu.ctx({ collect: true });
     const dataVal = aontu.parse(dataSrc, dataOpts, dataCtx);
     if (0 < dataCtx.err.length || null == dataVal) {
-        // A DATA DOCUMENT THAT WILL NOT PARSE IS THE DATA'S FAULT, and the
-        // report says so: verdict `invalid`, with a finding carrying the
-        // parser's own code and a site in the data. `error` is left to mean
-        // what the exit table says it means -- the run could not be set up
-        // from the SCHEMA side.
-        //
-        // The engine already answered it this way one character earlier: a
-        // refused CONSTRUCT (`a: 9007199254740993`) reaches the tree as an
-        // ordinary nil and is reported as an invalid data finding. A stray
-        // `]` took the throwing path instead and came back as a broken
-        // SCHEMA -- the same fault, classified two opposite ways by which
-        // branch the parser happened to take.
-        //
-        // The FIRST error only: the parser stops at the first syntax error,
-        // so a second entry would be a consequence of the first rather than
-        // a separate thing to fix.
         const failure = dataCtx.err[0];
         if (null == failure) {
             return { verdict: 'error', truncated: false, findings: [] };
@@ -499,17 +388,6 @@ function vet(schemaSrc, dataSrc, opts) {
             findings: [findingOf(failure, { data: new Set([dataUrl]) })],
         };
     }
-    // STAMP THE WHOLE SETTLED SCHEMA, not just the lifted anchor.
-    // Without `--at` these are the same tree. With it, the anchor is a
-    // subtree and the rest of the schema is still REACHABLE from inside
-    // it -- a `%alias` declaration (`[&: %U]`, target `$.%U`) or a
-    // recursive residual's `$.spec.Step`, both of which the meet
-    // resolves through _fixroot (RefVal.find, RecurseVal.body). A node
-    // reached that way but never stamped carries no url, so its site
-    // named no file while excerpting the schema's text -- against the
-    // invariant that every site names the file whose text it shows
-    // (finding F, §25). stampUrl only fills a url that is EMPTY, so
-    // stamping the superset never renames a value read from an include.
     stampUrl(schemaVal, schemaUrl);
     const dataUrls = stampUrl(dataVal, dataUrl);
     // The projection every site in this report goes through: roles by
@@ -519,31 +397,17 @@ function vet(schemaSrc, dataSrc, opts) {
         schemaUrl, schemaPath: options.schemaPath,
         dataUrl, dataPath: options.dataPath,
     };
-    // Default-validity lint (G3 phase 5, re-examined under ADR-004): for
-    // every disjunction in the SCHEMA carrying a preference, warn when
-    // the effective default is not an instance of any REMAINING
-    // alternative (code `pref_not_instance`, class compat, severity
-    // warning).
-    //
-    // What the finding MEANS changed with the admission gate (ADR-004).
-    // Before the gate it flagged a soundness hole: the preference held
-    // the disjunction open, so `a:*5|string` both generated a value the
-    // alternatives refuse AND admitted any same-kind override. The gate
-    // closed that hole — a preferred branch now contributes exactly its
-    // own value to the admitted set, so a default can no longer be
-    // "invalid against its own disjunct" and the enum-with-default idiom
-    // (`*'auto'|'literal'|'data'`) is sound as written. The lint is KEPT,
-    // as an advisory: a default admitted only because it is the default
-    // is also the exact shape of a typo'd default
-    // (`level:*wran|info|warn|debug` — the intended `*warn` would be
-    // silent), and nothing at meet time can catch that. The
-    // repeated-branch spelling (`*warn|warn|...`) states "the default is
-    // a first-class member", silences the lint, and — unlike before the
-    // gate — enforces exactly the same admitted set. The message names
-    // the REMAINING alternatives because that is what was scanned: the
-    // preferred branch itself always admits its own default, so the old
-    // wording ("any alternative of *5|string") read as false on its face
-    // (use-cases/BUGS.md §4).
+    let coverage;
+    if (true === options.coverage) {
+        const coverCtx = aontu.ctx({ collect: true });
+        const settledData = aontu.unify(dataSrc, dataOpts, coverCtx);
+        // A data document that does not stand alone is already reported by
+        // the meet below; here it falls back to what was parsed, which is
+        // the same paths minus whatever an include would have added.
+        const measured = 0 === coverCtx.err.length && true !== settledData?.isNil
+            ? settledData : dataVal;
+        coverage = vetCoverage(anchor, measured, options.coverageAt);
+    }
     const lintFindings = [];
     (0, utility_1.walkBagVals)(anchor, (v, path) => {
         if (true === v.isDisjunct && Array.isArray(v.peg)) {
@@ -578,44 +442,9 @@ function vet(schemaSrc, dataSrc, opts) {
             }
         }
     });
-    // `--closed` sets the flag `close()` itself sets, rather than wrapping
-    // the anchor in a CloseFuncVal: the anchor is an already-evaluated
-    // tree, and a func value would have to resolve again to have any
-    // effect. A scalar anchor has no keys to close, so the flag is only
-    // meaningful on a bag.
     if (true === options.closed && (true === anchor.isMap || true === anchor.isList)) {
         anchor.closed = true;
     }
-    // THE MEET IS FROM A FRESH PARSE, NOT THE SETTLED SCHEMA (the
-    // review's finding C, use-cases/BUGS.md §15).
-    //
-    // Step 1 evaluated the schema ALONE, to decide whether it stands up
-    // before any data is blamed for it. That answer is a diagnosis, and
-    // it was also being used as the left side of the meet -- so every
-    // reference in the schema had already RESOLVED against the schema's
-    // own values and been replaced by them. `a:integer b:$.a` settled to
-    // `a:integer b:integer`, and data `{a:3,b:4}` then vetted VALID,
-    // while the same four lines as one document refuse with
-    // scalar_value. A reference is a statement about the FINAL model, and
-    // vet is asking about a model the data is part of.
-    //
-    // Parsing again is what makes `vet(S,D)` and `eval(S ∪ D)` the same
-    // question: the meet runs the fixpoint once, over both documents, so
-    // references, spreads and generators all see the data. Parsed trees
-    // are single-use, hence a second parse rather than a reuse of step
-    // 1's. The lint above still reads the SETTLED tree, where
-    // disjunctions are ranked and normalised.
-    //
-    // ONLY WHEN THERE IS NO `--at`. An anchor is a SUBTREE lifted out of
-    // the schema, and an absolute reference inside it (`$.OrderPlaced`,
-    // the discriminated-union idiom) names a sibling of the document
-    // root -- which the lifted subtree no longer has. The settled tree is
-    // where those references have already been resolved and substituted,
-    // so an anchored run keeps meeting that, exactly as it always has.
-    // Making the rule explicit rather than leaving it to whether
-    // anchorAt happens to find the path in an unresolved tree: the two
-    // ports answered that differently, which is an ADR-001 divergence
-    // waiting to happen.
     const ctx = aontu.ctx({ collect: true });
     let meetAnchor = anchor;
     if (null == options.at) {
@@ -631,15 +460,6 @@ function vet(schemaSrc, dataSrc, opts) {
         }
     }
     else {
-        // A RECURSIVE residual inside the lifted anchor still names its
-        // definition by absolute path (`then?: $.spec.Step` -- the
-        // fixpoint, RECURSION.0.md), and the meet's root is the anchored
-        // subtree, which does not contain `$.spec`. Without a tree to
-        // walk, the residual held its peer forever and everything under a
-        // recursive field vetted VALID unchecked. The settled schema root
-        // is kept on the meet context for exactly that walk
-        // (AontuContext._fixroot; RecurseVal.body and RefVal.find fall
-        // back to it).
         ;
         ctx._fixroot = schemaVal;
         ctx.path = options.at.replace(/^\$\.?/, '')
@@ -647,17 +467,6 @@ function vet(schemaSrc, dataSrc, opts) {
     }
     const pair = new ConjunctVal_1.ConjunctVal({ peg: [meetAnchor, dataVal] }, ctx);
     const unified = aontu.unify(pair, undefined, ctx);
-    // 4. Contradictions: every NilVal standing in the result, PLUS the
-    //    ones that never made it into the tree.
-    //
-    // The second half is not belt-and-braces. When a parent collapses to
-    // a nil the whole subtree goes with it, so `service: close({...})`
-    // meeting a typo AND a kind conflict leaves ONE nil in the tree and
-    // reports the other only on the context — the vet verb's own
-    // motivating example, reporting half of what it found. The language
-    // server already walks both for this reason; vet dedups by identity
-    // the same way, and skips the transient disjunct-trial sentinel,
-    // which is bookkeeping rather than a finding.
     const seen = new Set();
     const nils = (0, walk_1.collectNils)(unified, seen);
     for (const err of ctx.err) {
@@ -670,44 +479,16 @@ function vet(schemaSrc, dataSrc, opts) {
         materialise(n, ctx);
         return findingOf(n, prov);
     });
-    // 5. Incompleteness: what is left standing that cannot generate. The
-    //    generate check runs in its own collect context so nothing it
-    //    raises reaches the caller's error list, and so a schema that is
-    //    merely unsatisfied does not look like one that is contradicted.
-    // No try/catch: in collect mode `gen` records its reasons on the
-    // context instead of throwing, which is the whole point of the mode.
     const genCtx = aontu.ctx({ collect: true });
     genCtx.root = unified;
-    // Under `--at` the probe descends through the OUTPUT marks: the
-    // caller named this node as the truth to validate against, so a
-    // `type()` or `hide()` on it (or propagated into it) is not a reason
-    // to check nothing. See AontuContext.probe.
     genCtx.probe = null != options.at;
     unified.gen(genCtx);
     for (const err of genCtx.err) {
-        // A CONFLICT RAISED AT GENERATION COUNTS TOO (the review's finding
-        // C, use-cases/BUGS.md §16). The filter used to keep the
-        // `incomplete` class alone, on the reading that step 4 had already
-        // found every contradiction -- true while every conflict was
-        // decided during the meet, and untrue since a sizing atom or a
-        // container `must` may hold a PROVISIONAL reading until generation,
-        // which is where no more members can arrive. Dropping those left
-        // `vet` answering `valid` for data the evaluator refuses, which is
-        // the one disagreement the vet-equals-eval harness exists to catch
-        // -- and did.
-        //
-        // Deduped against step 4 by the same cause key the loop below uses,
-        // so a contradiction seen twice is still reported once.
         if ('incomplete' === err.class || 'conflict' === err.class) {
             materialise(err, genCtx);
             findings.push(findingOf(err, prov));
         }
     }
-    // 5b. Deprecation warnings (G3 phase 4): a value that carries the
-    //     deprecate() record after the meet was USED — the data met a
-    //     deprecated schema value, or the schema's own default will
-    //     generate one. Severity `warning` (the slot G2 reserved for
-    //     exactly this mark), and warnings never touch the verdict below.
     findings.push(...lintFindings);
     for (const { val, path } of (0, utility_1.collectDeprecations)(unified)) {
         const v = val;
@@ -735,27 +516,6 @@ function vet(schemaSrc, dataSrc, opts) {
     const keyed = findings.map((f, i) => ({ key: orderKey(f, i), finding: f }));
     keyed.sort((a, b) => a.key < b.key ? -1 : 1);
     let ordered = keyed.map((k) => k.finding);
-    // ONE CAUSE, ONE FINDING. A reference resolves by CLONING its target,
-    // so a target that later fails can fail once per referrer — same
-    // code, same two source sites, a different path each time. Multi-pass
-    // collection (G2 phase 6) made this reachable: the pass loop now
-    // continues past the erroring pass, so the clones' own folds run too.
-    // The dedup key is the CODE plus the SITES (file, row, col, value,
-    // role): two findings that name the same meet of the same two source
-    // positions are one contradiction observed from two paths. The key is
-    // NOT (code, path) — the design's sketch — because the paths are
-    // exactly what differ. Sorted order makes the kept finding the first
-    // by data site then path, deterministically in both ports.
-    //
-    // THE KEPT PATH IS THE DEEPEST one (use-cases/BUGS.md §41). A meet
-    // that fails inside a REFERENCED map is recorded twice: once at the
-    // key that actually conflicts, and once at the enclosing map, which
-    // collapsed as a consequence and carries the child's two sites. Both
-    // are the same cause; only the deeper one names the field an author
-    // or an agent has to edit, and `$.q` for a conflict in `$.q.a` sent a
-    // repair loop to rewrite the whole record -- twice over, identically,
-    // when two of its fields conflicted. Depth first, then the sort order
-    // above, so the choice stays deterministic in both ports.
     const causeKey = (f) => f.code + '\u0000' + f.sites.map((s) => [s.file, s.row, s.col, s.role, s.value].join('\u0000')).join('\u0000');
     const depth = (f) => f.path.split('.').length;
     const deepest = new Map();
@@ -777,22 +537,6 @@ function vet(schemaSrc, dataSrc, opts) {
     });
     const truncated = maxErrors < ordered.length;
     const kept = truncated ? ordered.slice(0, maxErrors) : ordered;
-    // 6. The verdict derives from finding CLASSES, never from codes, so a
-    //    new code can never change exit behaviour.
-    //
-    // BY CLASS, NOT BY STAGE. The split used to be positional -- whatever
-    // step 4 found counted as contradiction and whatever step 5 added
-    // counted as incompleteness -- which stopped being true when a sizing
-    // atom or a container `must` began holding a provisional reading
-    // until generation (the review's finding C, use-cases/BUGS.md §16). A
-    // CONTRADICTION found at generation is still a contradiction: reading
-    // it as mere incompleteness answered `incomplete` where the evaluator
-    // refuses, and `vet` and `eval` have to agree.
-    //
-    // So: an error-severity finding that is not INCOMPLETENESS makes the
-    // document invalid, wherever it was found -- a contradiction, a parse
-    // refusal, an unresolvable reference alike. Warnings (the `compat`
-    // class: lint and deprecation) never touch the verdict.
     let verdict = 'valid';
     const errors = ordered.filter((f) => 'error' === f.severity);
     const unmet = errors.filter((f) => 'incomplete' === f.class).length;
@@ -802,6 +546,9 @@ function vet(schemaSrc, dataSrc, opts) {
     else if (0 < unmet && true !== options.partial) {
         verdict = 'incomplete';
     }
-    return { verdict, truncated, findings: kept };
+    return {
+        verdict, truncated, findings: kept,
+        ...(null == coverage ? {} : { coverage }),
+    };
 }
 //# sourceMappingURL=vet.js.map