aontu 0.62.0 → 0.64.0

package/src/view.ts

@@ -1,45 +1,5 @@
 /* Copyright (c) 2026 Richard Rodger, MIT License */
 
-// THE VIEWS (docs/design/VIEWS.0.md and VIEWS-ORDER.0.md): figures of
-// an evaluated document, drawn as deterministic text a golden diff can
-// check. Nine kinds:
-//
-//   doc      the shape of the document itself
-//   lattice  the language's value lattice, with the document's own
-//            values placed on it
-//   tree     the dependency tree of one relation
-//   matrix   the dependency matrix over one relation, in canon or
-//            partition order, with closure and the unmirrored mark
-//   graph    the node-link drawing, as Mermaid, DOT or an ER diagram
-//   layer    the architecture layers: stacked bands, one per value of
-//            a field, with the relation's upward edges called out
-//   sets     the set-intersection panel over a named set family
-//   layers   which document contributed which path (provenance)
-//   ladder   the meet ladder at one path (the `why` record, drawn)
-//   poset    the subsumption order over a set of documents
-//
-// A view consumes a REPORT, never the Val tree: the edge set `graphOf`
-// derives (ts/src/graph.ts), the relation declarations, the generated
-// value, the provenance record, the subsumption verdict. That is what
-// keeps the two ports at parity -- Go's exported Val interface is five
-// methods, and a Val-walking view would be TypeScript-only on the day
-// it landed.
-//
-// Everything here is deterministic: nodes and edges are sorted by code
-// point before emission, nothing iterates a map in insertion order, no
-// coordinate is computed and no number is formatted beyond its decimal
-// digits. The Go twin is go/view.go; what the two ports must agree on
-// -- the rendered text, the loss report and the refusals -- is
-// test/spec/view.tsv.
-//
-// EVERY RUN CARRIES A LOSS REPORT: what the figure could not draw, or
-// drew differently from the model, aggregated by code with a count.
-// Three codes are informational -- `edges_deduped` (several written
-// positions, one fact), `inverse_suppressed` (a declared mirror,
-// implied by the edge drawn) and `crossings` (a property of the
-// emitted order, not of the model) -- and leave the verdict `rendered`. Every
-// other code makes it `lossy`, which `--strict` refuses: a figure that
-// quietly omits things is the failure this capability exists to avoid.
 
 import { basename, dirname, isAbsolute, relative, resolve } from 'node:path'
 
@@ -71,52 +31,14 @@ export type ViewProfile = 'text' | 'mermaid' | 'dot' | 'er' | 'svg'
 
 export type ViewOrder = 'canon' | 'partition'
 
-// Which of the relation's edges the layer figure DRAWS. The bands
-// already say which way every edge goes, so the default shows the ones
-// that break the rule: `upward`. `all` draws the relation over the
-// bands -- what a reader tracing one module's dependencies wants --
-// and `none` leaves the bands alone. The default is `all` for a
-// profile that lays edges out itself (mermaid) and `upward` for the
-// fixed grids (text, svg), which is what each drew before the option
-// existed.
 export type ViewEdges = 'upward' | 'all' | 'none'
 
-// STYLING (VIEWS.0.md, "7. Styling"), which amends that note's colour
-// boundary. Every mark a figure makes already has a reason the
-// extractor established -- a cell is `direct` because the edge is
-// declared, an arrow is `upward` because it runs against the bands --
-// and the SVG profile has published those reasons as classes since it
-// landed, because an SVG cannot be drawn without saying what each
-// shape is. This declares the same vocabulary for the text profile and
-// adds the one thing missing: a way to turn it on at the call.
-//
-// NEITHER MECHANISM STATES A COLOUR, which is what keeps the boundary
-// intact. SGR 31 does not mean red; it means the colour the reader's
-// terminal calls red, which the reader chose. A CSS class states
-// nothing at all, and the stylesheet reads `var(--av-closure, ...)` so
-// a host page's palette wins. A hex triple is the thing that cannot
-// follow a theme, and it stays refused -- no truecolour escape, no
-// 256-colour escape, no `classDef`.
 export type ViewRole =
   'label' | 'muted' | 'rule' | 'direct' | 'closure' | 'unmirrored'
   | 'upward' | 'repeat' | 'bar' | 'hole'
 
-// `none` is plain characters, and an SVG carrying its classes but not
-// the embedded stylesheet -- what a host page wants once it has bound
-// the variables and is embedding eight figures. `ansi` is the text
-// profile's mechanism and `css` the SVG's; asking for either on the
-// wrong profile is a usage error.
-//
-// `auto` IS NOT HERE ON PURPOSE. Resolving it means knowing whether
-// the destination is a terminal, which err.ts already settles for the
-// error frames: a library cannot see its destination and a caller who
-// can is the only one who may decide. The CLI maps `auto`; `viewOf`
-// takes a resolved value, so every shared-spec row is deterministic.
 export type ViewStyle = 'none' | 'ansi' | 'css'
 
-// The text profile's mechanism: the eight named colours, `bold` and
-// `dim`, and nothing else. `label` is unstyled -- an entity's own name
-// is the figure's content, not a mark about it.
 const SGR: Record<ViewRole, string> = {
   label: '', muted: '2', rule: '2', direct: '1', closure: '36',
   unmirrored: '33', upward: '31', repeat: '2', bar: '36', hole: '2',
@@ -135,10 +57,6 @@ const ANSI: Paint = (role, text) =>
 
 const painter = (style: ViewStyle): Paint => 'ansi' === style ? ANSI : PLAIN
 
-// The style a figure gets when the caller named none. An SVG carries
-// its stylesheet, which is what makes it standalone and what every
-// pinned golden holds; everything else carries no mechanism, since a
-// library cannot see whether its output is a terminal.
 const styleOf = (
   style: ViewStyle | undefined, as: ViewProfile
 ): ViewStyle => style ?? ('svg' === as ? 'css' : 'none')
@@ -205,7 +123,6 @@ export type ViewSetReport = {
 
 
 export type ViewOptions = {
-  // The figure to draw. Absent means `tree`.
   kind?: ViewKind
   // The target grammar. Absent means the kind's first profile.
   as?: ViewProfile
@@ -215,20 +132,11 @@ export type ViewOptions = {
   // The include capability this document evaluates under
   // (docs/trust.md).
   trust?: TrustOptions
-  // The extensions an include additionally reads as text (the CLI's
-  // --text-ext). It rides WITH the capability everywhere, never beside
-  // it: both answer "what may an include read", and a verb that
-  // threads one and not the other refuses under a flag the bare
-  // command honours -- which is exactly what this verb did.
   textExt?: string[]
   // Restrict the figure to nodes (or paths) under this path. For the
   // ladder it is the path drawn, and required; for the poset it is
   // where the documents are compared.
   at?: string
-  // Refuse a figure with more than this many rows (matrix rows, graph
-  // and tree nodes, set rows, poset nodes, ladder rungs). Absent means
-  // sixty. A REFUSAL, not a truncation: a view that quietly omits
-  // things is the failure this capability exists to avoid.
   maxRows?: number
 
   // tree, matrix: draw OVER THIS RELATION. The tree draws every
@@ -268,7 +176,6 @@ export type ViewOptions = {
   // means three, which is the depth at which a model's shape is
   // legible and its data is not yet enumerated.
   depth?: number
-  // sets: drop intersections below this degree.
   minDegree?: number
   // sets, layers: elide columns beyond this many, counted in the loss
   // report.
@@ -286,12 +193,6 @@ export type ViewOptions = {
   // document, only once every figure of the set rendered.
   out?: string
 
-  // How the figure is styled (VIEWS.0.md, "7. Styling"). Absent means
-  // `none`: plain characters, and an SVG carrying its classes without
-  // the embedded stylesheet. THE CALLER RESOLVES `auto` -- see
-  // ViewStyle. A figure written to a file is written plain whatever
-  // this says, which the CLI enforces: a pinned golden with terminal
-  // escapes in it is not a golden anybody can read.
   style?: ViewStyle
 
   // The VIEW DOCUMENT (VIEWS.0.md, "6. The view document"): the path of
@@ -352,11 +253,6 @@ function finding(
 }
 
 
-// A relation that draws nothing is a typo, and is refused for the same
-// reason a misspelled root is: an empty figure and a misspelled name
-// are the same file on disk, so the one that means nothing must not be
-// renderable. NOT `refer_unresolved`: a relation name is not an
-// address.
 function relationFinding(relation: string, have: string[]): VetFinding {
   return finding('view_relation_unknown', 'reference', '$',
     `${relation} names no relation with edges in this document.`,
@@ -364,10 +260,6 @@ function relationFinding(relation: string, have: string[]): VetFinding {
 }
 
 
-// A root is a node of the DRAWN graph, the rule the node set follows:
-// a path that exists in the document but takes no part in the relation
-// is not in the drawing, and a root naming it is refused rather than
-// drawn as an empty tree.
 function rootFinding(
   root: string, relation: string | undefined, nodes: string[]): VetFinding {
   return finding('refer_unresolved', 'reference', '$',
@@ -412,20 +304,6 @@ function under(path: string, at: string | undefined): boolean {
 }
 
 
-// The deduplicated edge set, with the hidden contributions and the
-// out-of-scope edges removed and the loss report told.
-//
-// `graphOf` emits one edge per WRITTEN POSITION by design, because each
-// `at` is an editable site, and an identity-merged model declares each
-// entity at two positions. Deduplication is part of the extraction
-// contract, not a renderer's private cleverness, and the count is
-// reported so nobody has to guess which number they are looking at.
-//
-// A HIDDEN edge -- one written inside a `hide()`-marked subtree -- is
-// not drawn. A figure is committed to a repository, so anything drawn
-// is disclosed, and the subtree's whole purpose is to say "not
-// output". It is reported with its path instead, and `--strict`
-// refuses the figure.
 function triplesOf(
   graph: Graph, at: string | undefined, loss: ViewLoss[]): Triple[] {
   const edges = graph.edges
@@ -450,10 +328,6 @@ function triplesOf(
       detail: hidden.sort(cmpCodePoint),
     })
   }
-  // A link under an UNRESOLVED DISJUNCTION is not an edge (ADR-007),
-  // and the figure says so rather than dropping it in silence: the
-  // document has not decided, and a drawing that quietly picked an arm
-  // would be inventing the decision.
   const undecided = (graph.disjunct ?? []).filter((p) => under(p, at))
   if (0 < undecided.length) {
     loss.push({
@@ -491,21 +365,6 @@ function nodesOf(triples: { from: string, to: string }[]): string[] {
 }
 
 
-// THE SHORTEST SUFFIX THAT IS STILL UNIQUE, as a node's visible label.
-//
-// A node's name IS its path (ADR-014), and the paths in a real model
-// are long: eight nodes labelled `$.catalog.domains.identity.services.auth`
-// and its siblings is a correct diagram nobody can read. The label is
-// therefore the fewest trailing segments that still tell this node from
-// every other in the same drawing -- `auth` where that is unambiguous,
-// `identity.auth` where it is not.
-//
-// The rule is a function of the node SET, so a drawing is deterministic
-// while two drawings of different slices may label the same node
-// differently -- which is correct, because uniqueness is a property of
-// the set being drawn. The search is unbounded on purpose: at the full
-// segment count the candidate is the whole path, which no other node
-// shares, so it always ends.
 function labelsOf(nodes: string[]): Map<string, string> {
   const segs = new Map<string, string[]>(
     nodes.map((n) => [n, n.replace(/^\$\.?/, '').split('.')]))
@@ -568,13 +427,6 @@ const widest = (ss: string[]): number =>
 // ---------------------------------------------------------------------
 // Identifiers and escapes (VIEWS.0.md, "The renderers and the profiles")
 
-// Injective by construction, with two disjoint prefixes and one
-// predicate: `n_` + the name when its first code point is an ASCII
-// letter and every code point is an ASCII letter, digit or `_`;
-// otherwise `nq_` + the name with every other code point replaced by
-// `_` and its lower-case hex. A code-point class test, not a regular
-// expression: pattern matching is the one subsystem with a stated
-// RE2-versus-RegExp divergence, and an encoder runs on every name.
 function ident(name: string): string {
   const letter = (c: number): boolean =>
     (65 <= c && c <= 90) || (97 <= c && c <= 122)
@@ -594,11 +446,6 @@ function ident(name: string): string {
 }
 
 
-// One pass, per code point, from a table keyed by DECIMAL CODE POINT.
-// Mermaid: numeric entities only, never HTML names, so there is no
-// name table to diverge; 124 is in it because `|` is the edge-label
-// delimiter. DOT: the two escapes that also make it impossible for user
-// text to forge DOT's own `\n` / `\l` / `\r` justification escapes.
 const MERMAID_ESC: Record<number, string> = {
   34: '#34;', 35: '#35;', 38: '#38;', 60: '#60;', 62: '#62;',
   123: '#123;', 124: '#124;', 125: '#125;',
@@ -614,24 +461,11 @@ function escape(text: string, table: Record<number, string>): string {
   return out
 }
 
-// U+000A, U+000D, U+2028 and U+2029: the four code points that end a
-// line somewhere.
 function hasLineBreak(text: string): boolean {
   return /[\n\r\u2028\u2029]/.test(text)
 }
 
 
-// ---------------------------------------------------------------------
-// SVG (VIEWS.0.md, "No SVG in v1" -- the phase after the text kinds)
-//
-// The cell-based kinds draw into SVG under the INTEGER RULE: every
-// coordinate is a whole number of a fixed cell -- 8 units per
-// character, 20 per line -- from the same counts that lay the text
-// figure out, so no font is measured and both ports emit the same
-// bytes. The reader's browser shapes the text; the geometry is ours.
-// A figure is standalone (its own style block, with default colours)
-// and themeable (every colour a CSS variable a host page can set).
-
 const CH = 8
 const LH = 20
 const PAD = 8
@@ -663,11 +497,6 @@ const svgEsc = (s: string): string => escape(s, SVG_ESC)
 function svgDoc(
   w: number, h: number, about: string, parts: string[], style: ViewStyle
 ): string {
-  // The CLASSES are structure and are always written -- a rect that
-  // does not say whether it is a direct cell or a closure cell is not
-  // a figure. What `--style none` drops is the STYLESHEET, for a host
-  // page that has already bound the variables and would otherwise
-  // carry one copy of these rules per embedded figure.
   return [
     `<svg xmlns="http://www.w3.org/2000/svg" class="av" viewBox="0 0 ${w} ${h}" ` +
     `width="${w}" height="${h}" role="img" aria-label="${svgEsc(about)}">`,
@@ -700,25 +529,11 @@ function svgPath(d: string, cls: string): string {
 }
 
 
-// ---------------------------------------------------------------------
-// The tree
-
 // One edge as the tree draws it: a declared inverse pair collapsed to
 // one edge, and the label the branch carries.
 type Drawn = { from: string, to: string, label: string }
 
 
-// THE EDGE SET WITH DECLARED INVERSE PAIRS COLLAPSED to one logical
-// edge, the tree's way: a relation with a declared inverse arrives
-// twice -- once per direction -- and drawing it raw doubles every such
-// relation.
-//
-// WHAT IS NOT COLLAPSED IS A MUTUAL RELATION: `a dependsOn b` and `b
-// dependsOn a` are two facts under ONE key, and folding them into a
-// single undirected edge erases the shortest cycle a model can have.
-// The collapse is therefore per KEY PAIR rather than per node pair --
-// two keys facing each other are an inverse, one key facing itself is
-// a loop -- which is what makes `acyclic()`'s refusal drawable.
 function collapse(triples: Triple[], relation: string | undefined): Drawn[] {
   const pairs = new Map<string, Triple[]>()
   for (const e of triples) {
@@ -734,15 +549,6 @@ function collapse(triples: Triple[], relation: string | undefined): Drawn[] {
 
   const out: Drawn[] = []
   for (const group of pairs.values()) {
-    // ONE KEY WINS THE PAIR, and every edge written under it stands.
-    // The named relation wins; otherwise the code-point-least key,
-    // which is arbitrary but stable. Keeping every edge under the
-    // winner is what preserves a MUTUAL relation, while the losing keys
-    // are the declared inverses, implied by the winner and not drawn
-    // again. With a relation named, its inverse is implied and naming
-    // both would double the label; without one, every key is shown,
-    // because picking silently would hide that two predicates are in
-    // play.
     const keys = keysOf(group)
     const named = undefined !== relation && keys.includes(relation)
     const winner = named ? (relation as string) : keys[0]
@@ -765,27 +571,6 @@ type Kid = { to: string, label: string }
 type Figure = { text?: string, errors?: VetFinding[] }
 
 
-// THE DEPENDENCY TREE: the drawn edges, walked from each root, indented.
-//
-// A dependency graph is a DAG and not a tree -- two modules may share a
-// dependency, and drawing that shared node once under each parent is
-// what makes `cargo tree` and `npm ls` readable rather than
-// exponential. So this is a SPANNING WALK with two honest marks: `(*)`
-// where a subtree is elided because the node was expanded earlier, and
-// `(cycle)` where an edge closes a loop. The first is routine in a
-// correct model -- a diamond is good engineering, not a fault. The
-// second cannot arise from a model whose relation declares
-// `acyclic()`, and is drawn rather than thrown because a renderer that
-// hangs on a hostile input is a renderer that cannot be pointed at one.
-//
-// Which nodes are roots is DERIVED, not asked for: a root is a node
-// nothing depends on. `roots` overrides that to draw named subtrees.
-// The order of everything -- roots, children, the choice of which
-// occurrence of a shared node is the expanded one -- follows the label
-// sort, so the drawing is a function of the model alone.
-// One drawn row of the tree, for the SVG: its depth, its text, the
-// mark after it, and the row of its parent (-1 for a root). A blank
-// separator between roots is `null`.
 type TreeRow = { depth: number, text: string, mark: string, parent: number }
 
 
@@ -794,11 +579,6 @@ function drawTree(
   as: ViewProfile, style: ViewStyle
 ): Figure {
   const paint = painter(style)
-  // With a relation named, the tree is OVER THAT RELATION. A node-link
-  // diagram can label each edge and so draw every relation at once; a
-  // tree cannot without becoming unreadable, and walking two relations
-  // as though they were one would draw a containment the model does
-  // not state.
   const kept = undefined === relation
     ? all : all.filter((e) => e.label === relation)
 
@@ -827,10 +607,6 @@ function drawTree(
     list.sort((x, y) => cmpCodePoint(label(x.to), label(y.to)))
   }
 
-  // The relation is named on the branch only where more than one is
-  // drawn. Naming the single relation on every line of a tree that has
-  // exactly one is noise; leaving it off where there are two would
-  // hide which edge was walked.
   const many = 1 < new Set(kept.map((e) => e.label)).size
   const byLabel = (a: string, b: string): number =>
     cmpCodePoint(label(a), label(b))
@@ -844,10 +620,6 @@ function drawTree(
     named = [...new Set(roots)].sort(byLabel)
   }
   else {
-    // A root is a node nothing depends on. A SELF-EDGE does not make a
-    // node depended upon for this purpose: a module that names itself
-    // would otherwise stop being a root and take its whole subtree out
-    // of the drawing.
     const depended = new Set(
       kept.filter((e) => e.to !== e.from).map((e) => e.to))
     named = nodes.filter((n) => !depended.has(n)).sort(byLabel)
@@ -866,11 +638,6 @@ function drawTree(
     rows.push({ depth: 0, text: label(root), mark: '', parent: rows.length })
     expanded.add(root)
 
-    // ITERATIVE, with the ancestor chain carried as a set that is added
-    // to on the way down and removed from on the way up. A recursive
-    // walk is O(depth) stack frames and a deep dependency chain is a
-    // real shape, so the drawing of a model must not depend on how deep
-    // the interpreter lets it go.
     const chain = new Set<string>([root])
     const stack: { node: string, prefix: string, at: number, row: number }[] =
       [{ node: root, prefix: '', at: 0, row: rows.length - 1 }]
@@ -910,13 +677,6 @@ function drawTree(
     draw(root)
   }
 
-  // EVERY NODE IS DRAWN. A component whose nodes all depend on each
-  // other has no node nothing depends on, so the derived roots miss it
-  // entirely -- and a graph with roots elsewhere would drop it in
-  // silence, which is the one thing a drawing must not do. The
-  // least-labelled node left is taken as a root of its own, until
-  // nothing is left. An explicitly named root is a request for one
-  // subtree and is left alone.
   if (0 === roots.length) {
     for (const n of nodes) {
       if (!expanded.has(n)) {
@@ -933,10 +693,6 @@ function drawTree(
 }
 
 
-// The tree as SVG: one line per row, each node indented one unit per
-// depth, joined to its parent by a path that drops from the parent's
-// row and turns in to the child. The marks are muted text after the
-// label.
 function treeSvg(
   rows: (TreeRow | null)[], about: string, style: ViewStyle
 ): string {
@@ -966,42 +722,7 @@ function treeSvg(
 // ---------------------------------------------------------------------
 // The document tree
 
-// THE SHAPE OF THE MODEL ITSELF, which no other kind draws. Every
-// other figure here reads a REPORT -- the edge set, the provenance
-// record, the subsumption order -- and so can only draw a document
-// that has links, contributions or peers. A reader meeting a model for
-// the first time wants the plainer thing first: what is in it, and how
-// it is arranged.
-//
-// This is `get --keys --types` as a picture, and it reads the same
-// walk: map keys in code-point order, list indices in order, and a
-// leaf's KIND rather than its value -- the canon of a scalar's type,
-// not the scalar. Values are what the document is for; the shape is
-// what a reader needs before any of them mean anything.
-//
-// DEPTH IS A BOUND, NOT AN ELISION MARK. Below it the subtree is not
-// drawn and the row says how many keys were not drawn, because a tree
-// that stops without saying so is the one thing a structural drawing
-// must not be.
 
-// ---------------------------------------------------------------------
-// THE VALUE LATTICE, and where this document's values sit on it.
-//
-// THE SCAFFOLD IS THE LANGUAGE'S, NOT THE DOCUMENT'S: `top` at the
-// join, the four kind families under it, `path()` under `string`, the
-// four numeric leaves under `number`, and `nil` at the meet. Every
-// Aontu document is drawn against the SAME shape, which is what makes
-// two of these figures comparable -- and what makes this a view of the
-// language that a document annotates, rather than a picture assembled
-// out of whatever the document happened to contain.
-//
-// See docs/unification.md for what the ordering means.
-
-// The scaffold: each kind and the one above it. The ENGINE decides
-// which kind sits under which -- kindParent in ts/src/val/ScalarKindVal.ts,
-// and its twin in go/scalar.go -- and a test in each port holds this
-// table to it, so adding a kind to the engine makes the figure grow a
-// node rather than quietly leave one out.
 const LATTICE_PARENT: [string, string][] = [
   ['string', 'top'],
   ['path()', 'string'],
@@ -1014,12 +735,6 @@ const LATTICE_PARENT: [string, string][] = [
   ['null', 'top'],
 ]
 
-// The columns, left to right: the MINIMAL kinds, the ones with nothing
-// under them. Everything else is drawn centred over the columns it
-// covers, so this list alone fixes the figure's horizontal order -- and
-// it puts the kinds that reach the bottom from higher up (`boolean`,
-// `null`) on the outside, where their lines pass the numeric fan
-// rather than crossing it.
 const LATTICE_COLS =
   ['path()', 'integer', 'float', 'biginteger', 'bigdecimal', 'boolean',
     'null']
@@ -1050,10 +765,6 @@ function latticeAncestors(name: string): string[] {
   return out
 }
 
-// The columns one node covers: its own if it is minimal, otherwise
-// every column beneath it. `nil` is beneath everything and above
-// nothing, so the walk finds no column under it and the whole width is
-// its span -- which is where it belongs.
 function latticeSpan(name: string): number[] {
   const own = LATTICE_COLS.indexOf(name)
   if (-1 !== own) {
@@ -1065,10 +776,6 @@ function latticeSpan(name: string): number[] {
   return 0 === under.length ? LATTICE_COLS.map((_, i) => i) : under
 }
 
-// True when `parent` is immediately above `child`. NIL IS COVERED BY
-// EVERY MINIMAL KIND: it is the meet of all of them, and the only node
-// the parent table does not name, because nothing in the engine ever
-// answers `nil` as a superior.
 function latticeCovers(parent: string, child: string): boolean {
   return 'nil' === child
     ? -1 !== LATTICE_COLS.indexOf(parent)
@@ -1076,18 +783,6 @@ function latticeCovers(parent: string, child: string): boolean {
 }
 
 
-// WHERE ONE VALUE SITS, or undefined for a value that is not at a
-// single point. The answers are the kinds of thing a document holds:
-//
-//   a CONCRETE scalar sits at its kind -- `8080` is an `integer`, and
-//   `superior()` is the lattice's own answer to which;
-//   a KIND MARKER sits AT that kind -- `integer` written as a schema
-//   is the node itself, not a value under it;
-//   everything else -- a constraint, an unresolved disjunction, a
-//   reference -- is not one point. `integer & min(1)` is a REGION of
-//   the lattice and `*8080 | integer` is two places at once, so
-//   drawing either at a node would be a claim the figure cannot
-//   support. Both are counted into the loss report instead.
 function latticePoint(v: any): string | undefined {
   const node: any = throughDoc(v)
   if (true === node?.isNil) {
@@ -1096,10 +791,6 @@ function latticePoint(v: any): string | undefined {
   if (true === node?.isTop) {
     return 'top'
   }
-  // A kind marker names its own node; a concrete scalar names the node
-  // above it. Either way the name has to BE one of the figure's: a
-  // kind the scaffold does not draw has nowhere to go, and saying so
-  // through the loss report is the only honest answer.
   const name: string = true === node?.isScalarKind ? String(node.canon)
     : true === node?.isScalar ? String(node.superior?.().canon) : ''
   return LATTICE_NODES.includes(name) ? name : undefined
@@ -1151,22 +842,11 @@ function latticeCensus(root: any, at: string):
 }
 
 
-// What one node is written as: its name, and the count of the
-// document's values that landed on it. A node with nothing at it is
-// still drawn -- the shape is the language's, and a figure that left
-// the empty nodes out would be a different lattice for every document.
 function latticeCell(counts: Map<string, string[]>, name: string): string {
   const n = (counts.get(name) ?? []).length
   return 0 === n ? name : `${name} (${n})`
 }
 
-// The horizontal layout, in characters: one column per minimal kind,
-// each as wide as the widest cell drawn over it plus a gutter, and the
-// centre of each. The spanning nodes are narrower than the span they
-// cover, so none of them needs a width of its own. The gutter is THREE
-// because the SVG draws a box a character wider than its text: two of
-// those characters are the box's own padding and the third is the gap
-// between one box and the next.
 const LATTICE_GUTTER = 3
 
 function latticeCols(counts: Map<string, string[]>):
@@ -1194,13 +874,6 @@ function latticeAt(name: string, cx: number[]): number {
 }
 
 
-// The box-drawing glyph for one column of a rule, from the four facts
-// that meet there: whether the rule continues left and right, and
-// whether a stem leaves upward and downward. Deciding it this way is
-// what lets `number` -- which is BOTH one of the many under `top` and
-// the one above the numeric leaves -- come out as the join it is,
-// without a case written for it. The table is total, so no column has
-// to be asked whether it has a glyph.
 const LATTICE_GLYPH: Record<string, string> = {
   '....': '─', '...d': '│', '..u.': '│', '..ud': '│',
   '.r..': '─', '.r.d': '┌', '.ru.': '└', '.rud': '├',
@@ -1208,10 +881,6 @@ const LATTICE_GLYPH: Record<string, string> = {
   'lr..': '─', 'lr.d': '┬', 'lru.': '┴', 'lrud': '┼',
 }
 
-// The figure is PAINTED rather than assembled from padded strings: the
-// nodes have to line up with the rules that join them, and a count
-// changes a cell's width -- so the geometry is settled first, in
-// columns, and every glyph is then written at a place already known.
 function latticeText(counts: Map<string, string[]>, style: ViewStyle): string {
   const paint = painter(style)
   const { cx, width } = latticeCols(counts)
@@ -1227,9 +896,6 @@ function latticeText(counts: Map<string, string[]>, style: ViewStyle): string {
       roles[y][x + i] = role
     }
   }
-  // A cell is its name and, where the document reached it, the count:
-  // two roles, so a terminal can mute the second without touching the
-  // first.
   const cell = (y: number, name: string) => {
     const text = latticeCell(counts, name)
     const left = latticeAt(name, cx) - Math.floor(text.length / 2)
@@ -1256,9 +922,6 @@ function latticeText(counts: Map<string, string[]>, style: ViewStyle): string {
     stems(y, by)
   }
 
-  // Four node rows and three joins. `open` is every node whose line
-  // downward has not been drawn yet, which is what carries `boolean`
-  // and `null` past the numeric row to the bottom rule.
   let open: string[] = []
   let y = 0
   for (let r = 0; r < LATTICE_ROWS.length; r++) {
@@ -1296,14 +959,6 @@ function latticeText(counts: Map<string, string[]>, style: ViewStyle): string {
 }
 
 
-// The same figure as SVG, off the same column layout, so the two
-// profiles are one drawing in two grammars rather than two drawings.
-// A node the document REACHES is drawn with the ordinary rule stroke
-// (`av-box`) and one it does not with the faint one (`av-cell`),
-// because every node is drawn whether this document reaches it or not
-// and a reader has to see which is which without counting. NO NEW
-// CLASS: those two already mean a box and a faint box, so a host page
-// that themed the other figures gets this one for nothing.
 function latticeSvg(
   counts: Map<string, string[]>, at: string, style: ViewStyle
 ): string {
@@ -1317,11 +972,6 @@ function latticeSvg(
   const y = (name: string): number =>
     PAD + BOXH / 2 + (rowOf.get(name) as number) * ROWH
 
-  // Edges first, so a box always sits over the lines that reach it.
-  // The horizontal jog is placed just above the CHILD rather than
-  // halfway down, which is what keeps `boolean` and `null` -- three
-  // rows from `top` to `nil` with nothing between -- clear of the
-  // numeric row they pass.
   const edges: [string, string][] = [...LATTICE_PARENT,
     ...LATTICE_COLS.map((col): [string, string] => ['nil', col])]
   for (const [child, parent] of edges) {
@@ -1335,9 +985,6 @@ function latticeSvg(
     const w = (text.length + 2) * CH
     parts.push(svgRect(x(name) - w / 2, y(name) - BOXH / 2, w, BOXH,
       name === text ? 'av-cell' : 'av-box'))
-    // The name and the count in ONE text element, as the tree does it:
-    // two runs on one baseline, so the count is muted without the
-    // figure having to place it.
     parts.push(`<text x="${x(name)}" y="${y(name) + 5}" text-anchor="middle">` +
       `<tspan class="av-t">${svgEsc(name)}</tspan>` +
       `<tspan class="av-m">${svgEsc(text.slice(name.length))}</tspan></text>`)
@@ -1350,11 +997,6 @@ function latticeSvg(
 }
 
 
-// The figure. The row count is fixed -- the lattice is the language's,
-// and no option makes it smaller -- so `--max-rows` below it is still a
-// refusal, because a figure that quietly overran a stated bound is the
-// thing every other kind here refuses to be; the message says raise
-// rather than narrow.
 const LATTICE_LINES = 3 * LATTICE_ROWS.length - 2
 
 function drawLattice(
@@ -1406,13 +1048,6 @@ const DEFAULT_DOC_DEPTH = 3
 function docKids(v: any): string[] {
   const node: any = throughDoc(v)
   if (true === node?.isMap) {
-    // AN ALIAS DECLARATION IS NOT PART OF THE DOCUMENT
-    // (docs/reference-language.md, "Aliases"): it does not generate
-    // and it does not appear in canon. It IS a key of the root map in
-    // the value tree, which `get --keys` reports and this does not --
-    // a figure of the document's shape that showed `%Cents` beside
-    // `customers` would be drawing the declaration as data
-    // (use-cases/BUGS.md 74).
     return Object.keys(node.peg)
       .filter((k) => !k.startsWith('%')).sort(cmpCodePoint)
   }
@@ -1437,13 +1072,6 @@ function throughDoc(v: any): any {
 // is the constraint and for a scalar its value. Long canons are cut,
 // since the figure is the shape and not the data.
 function docLeaf(v: any): string {
-  // A CONTAINER WITH NOTHING IN IT IS NOT A LEAF, and calling it one
-  // by writing nothing after the key would make it read as a value the
-  // figure declined to describe. Its canon says what it is -- `{}`,
-  // `[]`, or a template a spread wrote and no member filled.
-  //
-  // `canon` is a string on every Val, so there is no other-type arm to
-  // take; the cut is the only decision here.
   const canon: string = throughDoc(v).canon
   return 32 < canon.length ? canon.slice(0, 29) + '...' : canon
 }
@@ -1492,11 +1120,6 @@ function drawDoc(
     const child = throughDoc(throughDoc(frame.node).peg[key])
     const kids = docKids(child)
     const under = stack.length < depth
-    // A container the depth bound stops at says how many keys are not
-    // drawn; a leaf says what it is.
-    // A leaf says what it is and a stopped container says how many
-    // keys it holds; both are written after the key with one space,
-    // and neither is ever empty (a canon has at least one character).
     const mark = 0 === kids.length ? ' ' + docLeaf(child)
       : under ? '' : ` (${kids.length})`
     if (0 < kids.length && !under) {
@@ -1533,15 +1156,6 @@ function drawDoc(
 // ---------------------------------------------------------------------
 // The matrix (Ghoniem et al. 2004; Sangal et al. 2005)
 
-// THE PARTITION ORDER: leaves first. Repeatedly take every unplaced
-// node whose every successor is placed, in label order, as the next
-// layer. That is a topological sort with a canonical tiebreak, and on
-// an acyclic relation it yields a perfect lower triangle -- which IS
-// the acyclicity proof, in the picture's own shape. Where nothing can
-// be placed the relation has a cycle: the least unplaced node is
-// placed alone, the strongly connected component it sits in is
-// reported as `cycle_block`, and the walk continues -- the cycle's
-// above-diagonal cell is then the acyclicity violation, drawn.
 function partition(
   nodes: string[], succ: Map<string, string[]>,
   reach: Map<string, Set<string>>, label: (n: string) => string,
@@ -1576,9 +1190,6 @@ function partition(
 }
 
 
-// The relation a matrix draws: the one named, else the only one with
-// edges, else a refusal -- a matrix over two predicates at once would
-// draw a containment the model does not state.
 function pickRelation(
   relation: string | undefined, keys: string[]
 ): { relation?: string, error?: VetFinding } {
@@ -1696,11 +1307,6 @@ const CELL_CLASS: Record<string, string> = {
   '.': 'av-cell', '\\': 'av-cell',
 }
 
-// The same five states as ROLES, for the text profile. One table per
-// mechanism rather than one shared one, because the two vocabularies
-// are not in step: SVG needs a class for the empty cell (it draws a
-// rect there) and the text profile has nothing to say about a `.`
-// beyond that it is not a mark.
 const CELL_ROLE: Record<string, ViewRole> = {
   X: 'direct', '!': 'unmirrored', '+': 'closure',
   '.': 'muted', '\\': 'rule',
@@ -1863,9 +1469,6 @@ function drawGraph(
     || cmpCodePoint(node(a.to).label, node(b.to).label)
     || cmpCodePoint(a.key, b.key))
 
-  // Crossings in the emitted order: two edges cross when their spans
-  // interleave. A count, not a layout -- the consumer lays the picture
-  // out, and this says how tangled the order it is handed is.
   let crossings = 0
   const span = (e: GEdge): [number, number] => {
     const a = at.get(e.from) as number
@@ -1923,14 +1526,6 @@ function drawGraph(
     out.push('}')
   }
   else {
-    // Entity relationships, as Mermaid's own erDiagram. Cardinality is
-    // not something the model states, so every relationship is drawn
-    // many-to-many and the label carries the predicate: drawing a
-    // cardinality the model does not assert would be an invention. An
-    // erDiagram has no separate label -- the identifier IS what the
-    // reader sees -- so it is the encoded label, unique by the label
-    // rule. Every node is in some relationship, since the node set is
-    // what the edges connect.
     const esc = (s: string): string => escape(s, MERMAID_ESC)
     out.push('erDiagram')
     for (const e of drawn) {
@@ -1947,19 +1542,6 @@ function drawGraph(
 type Band = { name: string, nodes: GNode[] }
 
 
-// THE LAYER DIAGRAM every architecture document has a hand-drawn
-// version of: one band per layer, the layers stacked with the one
-// nothing depends on at the top, each module in its band, and the
-// rule -- dependencies point DOWN -- read off the bands. The band a
-// node belongs to is the value of `--group-by`; the order of the
-// bands is DERIVED from the relation, as the partition order over the
-// layer-level graph (a layer depends on the layers its modules depend
-// on), so it is a function of the model and not of a list somebody has
-// to keep in step with it -- unless the model has an upward edge, when
-// the layer graph is cyclic and no order is derivable, which is what
-// `--layers` (top first) is for. A sideways edge (within one band) is
-// ordinary engineering and counted; an UPWARD edge is the violation
-// the drawing exists to show, and is named under the figure.
 function drawLayer(
   triples: Triple[], root: any,
   o: {
@@ -2082,9 +1664,6 @@ function drawLayer(
   }
   const out: string[] = []
   if ('svg' === o.as) {
-    // The description says WHAT WAS DRAWN, because two layer figures of
-    // one model on one page differ by exactly that, and a reader who
-    // cannot see them has only this to tell them apart.
     const drew = 'all' === edges
       ? `${shown.length} edges drawn, ${upward} of them upward`
       : 'none' === edges
@@ -2146,14 +1725,6 @@ function drawLayer(
 type Drawing = { edge: GEdge, way: 'downward' | 'sideways' | 'upward' }
 
 
-// The layers as SVG: one band per row, its modules as boxes laid left
-// to right, and every SHOWN edge drawn between them -- an upward one
-// dashed and alert-coloured, because it is the violation the bands
-// cannot show on their own; a downward one straight down from the
-// bottom of its box to the top of the one it names; a sideways one
-// dipped below the boxes, since two modules of one band sit on the
-// same line and a straight edge between them would cross whatever
-// stands between.
 function layerSvg(
   bands: Band[], shown: Drawing[], footer: string[], about: string,
   style: ViewStyle
@@ -2514,20 +2085,10 @@ function drawLayers(
   },
   max: number, loss: ViewLoss[]
 ): Figure {
-  // Every path something met at AND THE DOCUMENT HAS A VALUE AT,
-  // mapped to the documents that met there. A meet can happen at a
-  // position the finished document does not have -- a template's own
-  // child, folded into each key it is spread over -- and the panel is
-  // about the document, so only its paths are rows. A path is shown
-  // as `a.b.c`; the root as `$`.
   const members = new Map<string, Set<string>>()
   const paths: string[] = []
   const atParts = undefined === o.at ? [] : pathParts(o.at)
   for (const [key, rec] of prov.paths) {
-    // A record at a position the document does not have is the Go
-    // recorder's template ghost (use-cases/BUGS.md 70); this port's
-    // recorder does not write one, and the two ports must skip the
-    // same rows.
     if (0 === rec.conjuncts.length || null == anchorAt(root, '$.' + key)) {
       continue
     }
@@ -2578,13 +2139,6 @@ function drawLayers(
 // ---------------------------------------------------------------------
 // The meet ladder (VIEWS-ORDER.0.md)
 
-// The descent from `top` through each contribution to the resolved
-// value, one rung per conjunct. Where the contributions are ranked
-// preferences the ladder IS the arbitration: fewer stars win, so the
-// rungs read weakest-first and the winner is the last before the
-// value. `why`'s record is in source order, which is not rank order,
-// so the rungs are SORTED -- an emitter that trusted the record would
-// draw an arbitration that did not happen.
 function drawLadder(
   src: string, options: ViewOptions, as: ViewProfile, max: number
 ): Figure {
@@ -2653,17 +2207,6 @@ type Doc = ViewPosetDoc
 type Cls = { members: number[], label: string }
 
 
-// The order over a document set, in the design's five steps: the
-// verdict matrix; the quotient by MUTUAL subsumption (two documents
-// that subsume each other are one node -- mandatory, since without it
-// the relation is not antisymmetric and the cover relation is
-// undefined); the closure, then the cover relation over the closure;
-// and a canonical order, so the result does not depend on the order the
-// files were given.
-// One pairwise comparison: does the general document admit everything
-// the specific one does? `subsume`, with the poset's anchor and
-// profile; a parameter so a test can hand the drawing a verdict matrix
-// the checker cannot be made to produce.
 export type ViewCompare = (
   general: Doc, specific: Doc, options: ViewOptions
 ) => { verdict: string, code: string }
@@ -2749,11 +2292,6 @@ function drawPoset(
       if (!closure[lo][hi]) {
         continue
       }
-      // A pair the closure implies but the checker measured as
-      // `does_not_subsume` is reported rather than absorbed: the
-      // measured relation is a conservative under-approximation, and
-      // an under-approximation of a transitive relation need not be
-      // transitive.
       if ('does_not_subsume' === verdict[rep(hi)][rep(lo)]) {
         intransitive.push(`${classes[lo].label} < ${classes[hi].label}`)
       }
@@ -2931,12 +2469,6 @@ export function view(
         `profiles: ${profiles.join(', ')}`)],
     })
   }
-  // ONE MECHANISM PER PROFILE (VIEWS.0.md, "7. Styling"). `ansi` is
-  // the text profile's and `css` the SVG's; asking for one on a
-  // profile that has no way to carry it is a usage error rather than a
-  // silent no-op, so a script that asks for colour and gets none is
-  // told why. `none` is always available -- it is the absence of a
-  // mechanism.
   const style: ViewStyle = styleOf(options.style, as)
   const carrier: Record<string, ViewProfile> = { ansi: 'text', css: 'svg' }
   if (undefined !== carrier[style] && carrier[style] !== as) {
@@ -2980,13 +2512,6 @@ export function view(
 }
 
 
-// THE KINDS THAT DRAW FROM A LOADED MODEL, so a view document can load
-// once and draw N figures from the one evaluation. `gen` is the
-// generated value where the caller already holds it -- a view document
-// reads its own declarations out of one -- and undefined where the set
-// panel must generate its own. It is a BOX rather than the value, so
-// that a document generating `undefined` is still a value the panel
-// has rather than one it must recompute.
 function drawLoaded(
   root: any, ctx: any, gen: { value: any } | undefined,
   prov: Provenance | undefined,
@@ -3066,20 +2591,6 @@ export function viewTree(src: string, opts?: ViewOptions): ViewReport {
 }
 
 
-// ---------------------------------------------------------------------
-// The view document (VIEWS.0.md, "6. The view document")
-//
-// A projection that runs in CI belongs in a file. A view document is an
-// ORDINARY document that includes the model and declares its figures as
-// data; `views` is the AUTHOR's key and nothing here knows the name
-// (ADR-010), which is why `--views` names the path.
-//
-// The declaration keys ARE the library's option names, which are the
-// CLI's flag names without the dashes: one vocabulary, three doors. A
-// declaration must name its `kind` and its `out` -- a figure in a file
-// that a review reads should say what it draws and where it goes,
-// rather than inheriting a default from whoever ran the verb.
-
 const DECL_TEXT = [
   'kind', 'as', 'out', 'at', 'relation', 'order', 'groupBy', 'label',
   'sets', 'member', 'universe', 'edges',
@@ -3105,9 +2616,6 @@ function documentFinding(path: string, message: string, note?: string): VetFindi
 }
 
 
-// One validated declaration: everything the drawing needs, decided
-// before any figure is drawn, so a document with three bad
-// declarations reports three faults rather than the first.
 type Plan = {
   name: string
   kind: ViewKind
@@ -3183,9 +2691,6 @@ function planOf(name: string, decl: any, at: string): {
       'kinds: ' + Object.keys(PROFILES).join(', ')))
   }
   else if ('poset' === kind) {
-    // The poset is an order over SEVERAL documents, and a view document
-    // declares figures of the one it includes. `aontu view poset` draws
-    // it, naming the documents on the command line.
     errors.push(documentFinding(`${where}.kind`,
       'A view document draws figures of one document; ' +
       'the poset compares several.'))
@@ -3219,13 +2724,6 @@ function planOf(name: string, decl: any, at: string): {
 }
 
 
-// N FIGURES OF ONE DOCUMENT. The document is evaluated ONCE, with the
-// provenance recorder on, and every figure but the ladder draws from
-// that one root; the ladder re-runs `why` by construction.
-//
-// The caller writes the files, and only when the whole set rendered:
-// N figures of one model are only meaningful together, so a set whose
-// third figure refuses must not leave the first two on disk.
 export function viewSet(
   src: string, opts?: ViewOptions, hooks?: ViewHooks
 ): ViewSetReport {
@@ -3238,11 +2736,6 @@ export function viewSet(
         'the map that declares the figures; name it with --views.')],
     }
   }
-  // ONE EVALUATION, and it is INSTRUMENTED: the layers panel reads the
-  // provenance record, which is written during unification, so a set
-  // that declares one would otherwise need a second run. Recording it
-  // always costs a little and makes the one-evaluation claim true for
-  // every kind but the ladder, which re-runs `why` by construction.
   const prov = (hooks?.provenance ?? (() => new Provenance()))()
   const loaded = load(src, options.path, options, prov)
   if (undefined !== loaded.errors) {