aontu 0.61.0 → 0.63.0

package/src/vet.ts

@@ -1,28 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// The validation verb: check a data document against a schema document
-// and return a MACHINE-READABLE report (G2 phase 2,
-// docs/capability-review/g2-validation-verb.md).
-//
-// This module is the engine only. The CLI verb, the JSON/SARIF
-// renderers and `--watch` are phase 3 and 5; the Go port is phase 4.
-// Keeping the engine transport-free is the split lsp.ts already uses,
-// and for the same reason: it is the part that has to be unit-testable
-// and embeddable.
-//
-// Two properties of the engine shape everything here, and both were
-// probed rather than assumed:
-//
-//   - A CONTRADICTION surfaces as a NilVal in the unified tree, so
-//     conflict findings come from a tree walk (the `walkNils` pattern
-//     lsp.ts already uses, generalised).
-//   - INCOMPLETENESS does not. `{name:"auth"}` against
-//     `{name:string, port:integer}` unifies cleanly and leaves
-//     `port:integer` standing — no nil, no error. It surfaces only when
-//     something tries to GENERATE, which is why vet runs a generate
-//     check in an isolated collect context and reads the
-//     `incomplete`-class errors out of it. The two verdicts the report
-//     distinguishes therefore come from two different mechanisms.
 
 import type { TrustOptions, Val } from './type'
 
@@ -40,12 +17,8 @@ import { collectDeprecations, walkBagVals, deprecationMessage,
   includeOpts,
 } from './utility'
 import { subsumeNode, effectiveDefault } from './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.
 import { noPathFinding } from './query'
+import { cmpCodePoint } from './keyorder'
 
 
 export type VetVerdict = 'valid' | 'invalid' | 'incomplete' | 'error'
@@ -56,34 +29,8 @@ export type VetSite = {
   file: string
   row: number
   col: number
-  // The extent in UTF-16 code units, or -1 when unknown — the same
-  // "unknown" row and col already use.
-  //
-  // THIS IS WHAT MAKES A FINDING REPAIRABLE. `value` is the CANON, not
-  // the source text: `port: 0x1F` reports canon `31` at column 7, so a
-  // consumer replacing `(col, value.length)` writes `port: 5x1F` and
-  // corrupts the document. With `len` the span is `(col, 4)` and the
-  // replacement is exact.
-  //
-  // NEVER GUESSED. Where the span is unknown this is -1 and a consumer
-  // must not edit — unlike the LSP, which falls back to canon because a
-  // wonky highlight is cosmetic while a wrong edit is a lost file.
-  // See ts/src/site.ts for what the extent covers.
   len: number
   role: VetRole
-  // The SOURCE TEXT the span covers, or '' when unknown.
-  //
-  // This is what makes the span SELF-VERIFYING, and it is not the same
-  // as `value`. For a scalar the two differ by normalisation — `0x1F`
-  // has src `0x1F` and value (canon) `31`. For a COMPOUND the span
-  // names the opening token only, exactly as row and col always have:
-  // a constraint `min(1)` reports src `min`, and a reference `$.b`
-  // reports src `$`.
-  //
-  // So a consumer must read the document at (row, col, len), compare it
-  // to `src`, and REFUSE when they differ — and, seeing `min` where it
-  // expected `min(1)`, refuse rather than replace the name and orphan
-  // the arguments. Without this field that mistake is undetectable.
   src?: string
   value?: string
 }
@@ -95,21 +42,6 @@ export type VetFinding = {
   path: string
   message: string
 
-  // THE REPAIR, not just the diagnosis. `message` is one line by
-  // design -- it is the headline, and the frames under it are for a
-  // human at a terminal -- but for several codes the part that says
-  // what to DO about the failure lived only in those frames, so a
-  // machine reader (an agent, a CI annotation, an editor) got the
-  // complaint and none of the cure. `0d` is the clearest case: the
-  // engine refuses a lossy integer literal and the hint names the
-  // exact-decimal escape that fixes it. Populated from the shared
-  // hints table (ts/src/hints.ts, mirrored by go/hints.go) whenever
-  // the code has one; absent when it does not (the report-layer
-  // compat_* codes, notably, carry no hint text).
-  //
-  // Excluded from spec goldens for the same reason `message` is: it is
-  // prose, it is long, and the two ports hold it to the byte through
-  // the message tests instead of through every vet row.
   hint?: string
 
   sites: VetSite[]
@@ -118,10 +50,27 @@ export type VetFinding = {
   note?: string
 }
 
+export type VetCoverage = {
+  checked: number
+  declared: number
+  // Data leaves in all, under `coverageAt` when it is given. `checked`
+  // over this is the ratio a reader wants.
+  leaves: number
+  unchecked: string[]
+  // The SHALLOWEST declarations no data path met.
+  unused: string[]
+  // NO data leaf was constrained, over a document that has leaves.
+  // The exact condition of the `"*"` failure, and what
+  // `--strict-coverage` exits 1 on.
+  vacuous: boolean
+}
+
 export type VetReport = {
   verdict: VetVerdict
   truncated: boolean
   findings: VetFinding[]
+  // Absent unless the run asked for it.
+  coverage?: VetCoverage
 }
 
 export type VetOptions = {
@@ -129,29 +78,18 @@ export type VetOptions = {
   closed?: boolean     // close() the anchor for this run
   partial?: boolean    // residue is not a failure
   maxErrors?: number   // cap the finding list (default 20)
-  schemaUrl?: string   // provenance label for schema sites
+
+  // Account for what the check examined (G11 phase 5). Off by default:
+  // the report gains a `coverage` object only when this is set, so no
+  // existing caller's report changes shape.
+  coverage?: boolean
+  coverageAt?: string
+  schemaUrl?: string
   dataUrl?: string     // provenance label for data sites
 
-  // Where each document CAME FROM, used to resolve its relative
-  // `@"file"` loads -- the file path, as `Aontu({path})` takes it, not
-  // the directory. Vet takes two documents from its caller rather than
-  // from the filesystem, so it cannot know this: without it a modular
-  // schema resolved its includes against the process working
-  // directory, which fails outside that directory and, worse, silently
-  // reads a same-named file that happens to sit there. The two
-  // documents get their OWN bases, because they need not live in the
-  // same place.
   schemaPath?: string
   dataPath?: string
 
-  // The trust profile this run evaluates under (G5, docs/trust.md).
-  // Vet's whole job is to evaluate a document its caller did not
-  // write, so the caller must be able to say what that document is
-  // allowed to reach: without this the include chain is the default
-  // one, and `@"../../etc/passwd.aon"` in hostile data reads whatever
-  // the validating process can. (`@"x.js"` no longer executes --
-  // ADR-012 refuses the extension -- but reading is enough.) A server
-  // passes `{include:'none'}`.
   trust?: TrustOptions
 
   // Extensions additionally read as text (the CLI's `--text-ext`).
@@ -170,37 +108,10 @@ 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: any, url: string, seen?: Set<string>): Set<string> {
   const urls = seen ?? new Set<string>()
   urls.add(url)
   walkVals(v, (n: any) => {
-    // 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
     }
@@ -211,10 +122,6 @@ function stampUrl(v: any, url: string, seen?: Set<string>): Set<string> {
 }
 
 
-// The provenance a report projects its sites through: which urls
-// belong to the DATA document, and how the caller reached each of the
-// two documents (which is what says how to NAME a third file either of
-// them included).
 type Prov = {
   // The urls the data walk reached. Roles are decided by membership,
   // on the RAW url -- never by a name comparison.
@@ -226,20 +133,6 @@ type Prov = {
 }
 
 
-// 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.
 export function displayFile(
   url: string, label: string, path?: string): string {
   if (url === label || null == path || '' === url || !isAbsolute(url)) {
@@ -251,12 +144,6 @@ export function displayFile(
 }
 
 
-// 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: string, role: VetRole, prov: Prov): string {
   return 'data' === role
     ? displayFile(file, prov.dataUrl ?? file, prov.dataPath)
@@ -264,50 +151,21 @@ function displayOf(file: string, role: VetRole, prov: Prov): string {
 }
 
 
-// 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: string, prov: Prov): VetRole {
   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?: string[]): string {
   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: any, prov: Prov): VetSite | undefined {
   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),
@@ -325,13 +183,6 @@ function siteOf(v: any, prov: Prov): VetSite | undefined {
 // The underlying NilVal fields are untouched: this is a report-layer
 // projection, so the existing error.tsv assertions do not move.
 function sitesOf(nil: any, prov: Prov): VetSite[] {
-  // `?? 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: VetSite[] = [siteOf(nil.primary ?? nil, prov) as VetSite]
 
   const secondary = siteOf(nil.secondary, prov)
@@ -339,9 +190,6 @@ function sitesOf(nil: any, prov: Prov): VetSite[] {
     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),
@@ -349,12 +197,6 @@ function sitesOf(nil: any, prov: Prov): VetSite[] {
 }
 
 
-// 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: any, ctx: any): void {
   if (null == nil.msg || '' === nil.msg) {
     descErr(nil, ctx)
@@ -379,32 +221,15 @@ function findingOf(nil: any, prov: Prov): VetFinding {
     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 = 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
   }
@@ -419,19 +244,6 @@ function findingOf(nil: any, prov: Prov): VetFinding {
 }
 
 
-// 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
 
 
@@ -440,12 +252,6 @@ function pad(n: number): string {
 }
 
 
-// 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: VetFinding, index: number): string {
   const site = f.sites[0]
   return [
@@ -459,44 +265,11 @@ function orderKey(f: VetFinding, index: number): string {
 }
 
 
-// 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.
 export function failureFinding(
   ctx: any, url?: string, failed?: any): VetFinding {
-  // 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: any = 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]) {
@@ -522,28 +295,8 @@ export function anchorAt(root: any, at: string): Val | undefined {
 
   let node: any = 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)) {
@@ -568,34 +321,183 @@ export function anchorAt(root: any, at: string): Val | 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.
 export function throughResidue(v: any): any {
   return 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: any): { key: string, val: any }[] {
+  const out: { key: string, val: any }[] = []
+  if (true === v.isMap && null != v.peg) {
+    for (const k of Object.keys(v.peg).sort(cmpCodePoint)) {
+      out.push({ key: k, val: v.peg[k] })
+    }
+  }
+  else if (true === v.isList && Array.isArray(v.peg)) {
+    v.peg.forEach((m: any, i: number) => out.push({ key: String(i), val: m }))
+  }
+  return out
+}
+
+
+function coverTemplate(v: any): any {
+  const cj = v?.spread?.cj
+  return null != cj && true === cj.isVal && true !== cj.isTop ? cj : undefined
+}
+
+
+function coverDeclare(
+  v: any, path: string[], out: Map<string, any>): void {
+  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: any, path: string[],
+  out: { path: string, leaf: boolean }[]): void {
+  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: any, segs: string[]): string | undefined {
+  let at: any = 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: string[]): string[] {
+  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(cmpCodePoint)
+}
+
+
+// The accounting itself: what the schema declared, what the data holds,
+// and which of each the other met.
+export function vetCoverage(
+  anchor: any, dataVal: any, coverageAt?: string): VetCoverage {
+  const declarations = new Map<string, any>()
+  coverDeclare(anchor, [], declarations)
+
+  const dataPaths: { path: string, leaf: boolean }[] = []
+  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: string): boolean => {
+    if (null == under || '' === under) {
+      return true
+    }
+    const want = '$.' + under
+    return p === want || p.startsWith(want + '.')
+  }
+
+  const used = new Set<string>()
+  const unchecked: string[] = []
+  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: string[] = []
+  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,
+  }
+}
+
+
 export function vet(
   schemaSrc: string, dataSrc: string, opts?: VetOptions): VetReport {
   const options = opts ?? {}
@@ -603,9 +505,6 @@ export function vet(
   const dataUrl = options.dataUrl ?? DEFAULT_DATA_URL
   const maxErrors = options.maxErrors ?? 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(includeOpts(options))
   const schemaOpts = null == options.schemaPath ?
     undefined : { path: options.schemaPath }
@@ -617,34 +516,8 @@ export function vet(
   const schemaCtx = aontu.ctx({ collect: true })
   const schemaVal: any = 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: any =
       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)
@@ -662,11 +535,6 @@ export function vet(
   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,
@@ -680,22 +548,6 @@ export function vet(
   const dataCtx = aontu.ctx({ collect: true })
   const dataVal: any = 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: [] }
@@ -708,17 +560,6 @@ export function vet(
       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
@@ -729,31 +570,18 @@ export function vet(
     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: VetCoverage | undefined
+  if (true === options.coverage) {
+    const coverCtx = aontu.ctx({ collect: true })
+    const settledData: any = 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: VetFinding[] = []
   walkBagVals(anchor, (v: any, path: string[]): void => {
     if (true === v.isDisjunct && Array.isArray(v.peg)) {
@@ -790,45 +618,10 @@ export function vet(
     }
   })
 
-  // `--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: any = anchor
   if (null == options.at) {
@@ -844,39 +637,13 @@ export function vet(
     }
   }
   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 as any)._fixroot = schemaVal
-    // And the meet DRIVES AT the anchor's own path, so every finding
-    // minted live during it sits in the schema's namespace
-    // ($.spec.Step.then.approver), exactly where the findings carried
-    // on the settled anchor's stored paths already sit -- the Go port
-    // gets this for free from its clone discipline, and the shared
-    // anchored-vet rows pin the agreement.
     ; (ctx as any).path = options.at.replace(/^\$\.?/, '')
       .split('.').filter((s: string) => '' !== s)
   }
   const pair = new ConjunctVal({ peg: [meetAnchor, dataVal] }, ctx)
   const unified: any = 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<any>()
   const nils: any[] = collectNils(unified, seen)
   for (const err of ctx.err) {
@@ -891,45 +658,17 @@ export function vet(
     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: any = 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 collectDeprecations(unified)) {
     const v: any = val
@@ -959,27 +698,6 @@ export function vet(
   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: VetFinding): string =>
     f.code + '\u0000' + f.sites.map((s) =>
       [s.file, s.row, s.col, s.role, s.value].join('\u0000')).join('\u0000')
@@ -1005,22 +723,6 @@ export function vet(
   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: VetVerdict = 'valid'
   const errors = ordered.filter((f) => 'error' === f.severity)
   const unmet = errors.filter((f) => 'incomplete' === f.class).length
@@ -1031,5 +733,8 @@ export function vet(
     verdict = 'incomplete'
   }
 
-  return { verdict, truncated, findings: kept }
+  return {
+    verdict, truncated, findings: kept,
+    ...(null == coverage ? {} : { coverage }),
+  }
 }