aontu 0.54.0 → 0.55.0

package/src/cli.ts

@@ -40,10 +40,10 @@ import type { TrimReport, TrimVerdict } from './trim'
 import type { RelationReport, RelationVerdict } from './relation'
 import { reachCheck } from './reach'
 import type { ReachReport, ReachVerdict } from './reach'
-import { view, viewSet } from './view'
+import { view, viewSet, viewDefaultProfile } from './view'
 import type {
   ViewEdges, ViewFigure, ViewKind, ViewLoss, ViewOptions, ViewProfile,
-  ViewReport, ViewSetReport, ViewVerdict,
+  ViewReport, ViewSetReport, ViewStyle, ViewVerdict,
 } from './view'
 import type { QueryView } from './query'
 import type { WhyRecord } from './provenance'
@@ -190,13 +190,14 @@ kind and out file, nothing is written unless every figure rendered,
 and --check gates the committed set.
 
 View options:
-  --as <profile>    text | mermaid | dot | er | svg, per kind: tree,
-                    matrix, sets and layers draw text (default) or
-                    svg; graph draws mermaid (default), dot or er;
+  --as <profile>    text | mermaid | dot | er | svg, per kind: doc,
+                    tree, matrix, sets and layers draw text (default)
+                    or svg; graph draws mermaid (default), dot or er;
                     layer draws text (default), mermaid or svg; ladder
                     and poset draw mermaid (default) or dot
   --at <path>       Restrict the figure to nodes under this path; the
-                    path the ladder draws; where the poset compares
+                    subtree doc draws; the path the ladder draws;
+                    where the poset compares
   --views <path>    Draw every figure the document declares at this
                     path, one evaluation, all or nothing; each
                     declaration names its own kind and out file
@@ -205,7 +206,20 @@ View options:
                     nothing is written
   --strict          Exit 1 when the loss report holds anything beyond
                     edges_deduped, inverse_suppressed and crossings
+  --depth <n>       doc: how many levels of key to draw (default 3)
   --max-rows <n>    Refuse a figure above this many rows (default 60)
+  --style <s>       auto (default), none, ansi or css. A figure's
+                    marks carry their meaning -- a direct cell, a
+                    closure cell, an upward edge -- and each profile
+                    has one way to show it: SGR escapes for text, CSS
+                    classes for svg. auto picks that mechanism where
+                    the destination can carry it: escapes only on a
+                    terminal (NO_COLOR is honoured), and an svg keeps
+                    the stylesheet that makes it standalone. none
+                    drops both; on svg the classes stay and only the
+                    stylesheet goes, for a host page that has already
+                    bound --av-ink and its kin. Escapes are never
+                    written to a file
   --format <f>      text (default) or json, the whole report
   --relation <n>    tree, matrix, layer: draw over this relation only;
                     graph: keep this predicate (repeatable)
@@ -1774,12 +1788,47 @@ const VIEW_HELP =
   'aontu view <kind> [options] <file>... (try --help)'
 
 const VIEW_KINDS: ViewKind[] =
-  ['tree', 'matrix', 'graph', 'layer', 'sets', 'layers', 'ladder', 'poset']
+  ['doc', 'tree', 'matrix', 'graph', 'layer', 'sets', 'layers', 'ladder',
+    'poset']
 
 const VIEW_PROFILES: ViewProfile[] = ['text', 'mermaid', 'dot', 'er', 'svg']
 
 const VIEW_EDGES: ViewEdges[] = ['upward', 'all', 'none']
 
+// The styles the CLI accepts (VIEWS.0.md, "7. Styling"). `auto` is
+// here and NOT in ViewStyle: resolving it means knowing whether stdout
+// is a terminal, which is the CLI's to know and the library's never --
+// the same division err.ts already draws for the error frames.
+const VIEW_STYLES = ['auto', 'none', 'ansi', 'css']
+
+// `--style auto` resolved, which only the CLI can do. The mechanism is
+// the PROFILE's and the library knows it -- an SVG carries its
+// stylesheet unless told not to, which is what makes a figure stand
+// alone. What the library cannot know is whether the DESTINATION is a
+// terminal, so that is the only thing decided here: escapes on the
+// text profile when stdout is a terminal and NO_COLOR is unset, the
+// same two conditions the error frames use. `undefined` leaves the
+// profile's own default in place.
+function viewStyleOf(
+  asked: string | undefined, as: ViewProfile | undefined
+): ViewStyle | undefined {
+  if (undefined !== asked && 'auto' !== asked) {
+    return asked as ViewStyle
+  }
+  // STDOUT'S OWN TERMINAL-NESS, and NO_COLOR read here rather than
+  // through colorActive(). The figure goes to STDOUT and the error
+  // frames go to STDERR, and they are not the same destination: main()
+  // has already called setColor for stderr, so asking colorActive()
+  // would answer the wrong question twice --- no escapes for
+  // `aontu view tree m.aon 2>/dev/null` at a terminal, and escapes
+  // into the pipe for `aontu view tree m.aon | less`. The NO_COLOR
+  // rule is the one no-color.org states and err.ts implements:
+  // set, to anything but empty, means no colour.
+  const no = process.env.NO_COLOR
+  return 'text' === as && true === process.stdout.isTTY
+    && (null == no || '' === no) ? 'ansi' : undefined
+}
+
 // The figure was drawn (0, `lossy` included: the loss report says
 // what it could not draw, and --strict is the gate on that), or the
 // document could not be drawn (4). An EMPTY figure is a drawing, not
@@ -1795,7 +1844,7 @@ const VIEW_EXIT: Record<ViewVerdict, number> = {
 const VIEW_USAGE_CODES = [
   'view_kind_unknown', 'view_profile_unknown', 'view_rows_exceeded',
   'view_at_required', 'view_sets_required', 'view_group_required',
-  'view_document_shape',
+  'view_document_shape', 'view_style_profile', 'view_style_unknown',
 ]
 
 const MOD_HELP = 'aontu mod tidy|verify|vendor|manifest [dir] (try --help)'
@@ -1860,7 +1909,8 @@ function runMod(argv: string[]): number {
   if ('get' === sub || 'publish' === sub) {
     process.stderr.write(
       'aontu: mod ' + sub + ' needs a registry client, which this build ' +
-      'does not ship (docs/capability-review/g6-distribution.md)\n')
+      'does not ship; vendor the module by hand and run ' +
+      "'aontu mod tidy'\n")
     return 2
   }
 
@@ -2180,6 +2230,9 @@ function runView(argv: string[]): number {
   const relations: string[] = []
   const roots: string[] = []
   const opts: ViewOptions = {}
+  // The style ASKED FOR, which may be `auto` -- a word ViewStyle does
+  // not have, because resolving it is the CLI's job.
+  let style: string | undefined = undefined
 
   // A flag that takes a value, read into `opts` by name.
   const valued: Record<string, keyof ViewOptions> = {
@@ -2191,6 +2244,7 @@ function runView(argv: string[]): number {
   const counted: Record<string, keyof ViewOptions> = {
     '--max-rows': 'maxRows', '--max-cols': 'maxCols',
     '--min-degree': 'minDegree', '--min-size': 'minSize',
+    '--depth': 'depth',
   }
 
   for (let i = 0; i < argv.length; i++) {
@@ -2230,6 +2284,14 @@ function runView(argv: string[]): number {
         return 2
       }
     }
+    else if ('--style' === arg) {
+      style = argv[++i]
+      if (null == style || !VIEW_STYLES.includes(style)) {
+        process.stderr.write(
+          `aontu: --style needs one of ${VIEW_STYLES.join(', ')}\n`)
+        return 2
+      }
+    }
     else if ('--check' === arg) {
       check = true
     }
@@ -2273,9 +2335,26 @@ function runView(argv: string[]): number {
     }
   }
 
+  // ESCAPES NEVER GO INTO A FILE. A pinned golden holding terminal
+  // control codes is not a golden anybody can read, and a byte
+  // comparison against one would fail on the reader's terminal
+  // settings. `auto` resolves to `none` there on its own; asking for
+  // `ansi` explicitly is a usage error rather than a silent downgrade,
+  // so a script that wanted colour is told where it went.
+  if ('ansi' === style && (undefined !== out || undefined !== opts.views)) {
+    process.stderr.write(
+      'aontu: --style ansi writes to a terminal, not to a file\n')
+    return 2
+  }
+
   // THE VIEW DOCUMENT draws every figure a document declares, so it
   // names no kind: the declarations do, one each.
   if (undefined !== opts.views) {
+    // A declaration names its own profile, so the style is left to
+    // each figure's own default; `--style none` still reaches every
+    // one of them, which is how a host page that binds the CSS
+    // variables asks for eight figures without eight stylesheets.
+    opts.style = viewStyleOf(style, undefined)
     return runViewSet(rest, opts, trust, { format, check, strict, out })
   }
 
@@ -2341,6 +2420,7 @@ function runView(argv: string[]): number {
 
   const report = view(srcs[0], {
     ...opts,
+    style: viewStyleOf(style, opts.as ?? viewDefaultProfile(kind)),
     kind,
     path: files[0],
     roots,

package/src/hints.ts

@@ -192,6 +192,8 @@ const hints: Record<string, string> = {
   view_kind_unknown: 'The figure kind is not one the verb draws. The kinds are tree, matrix,\ngraph, layer, sets, layers, ladder and poset; the note lists them.',
 
   view_profile_unknown: 'The figure kind does not render into the profile asked for: there is no\ntext form of a node-link drawing and no Mermaid form of a matrix. The\nnote lists the profiles the kind declares; the first is its default.',
+  view_style_profile: 'Each profile has ONE way to carry the meaning of a figure\'s marks:\nSGR escapes for text, CSS classes for svg. Asking for the other one is\na usage error rather than a silent no-op. `none` works everywhere.',
+  view_style_unknown: 'The styles are none, ansi and css, plus `auto` at the command line,\nwhich the command resolves before the library runs: whether the\ndestination is a terminal is not something a library can see.',
 
   view_rows_exceeded: 'The figure has more rows than --max-rows allows. This is a REFUSAL,\nnot a truncation: a view that quietly omits things is the failure the\nverb exists to avoid. Narrow the figure with --at or --relation, or\nraise the limit.',
 
@@ -509,6 +511,8 @@ const codeClasses: Record<string, string> = {
   view_relation_unknown: 'reference',
   view_kind_unknown: 'reference',
   view_profile_unknown: 'reference',
+  view_style_profile: 'reference',
+  view_style_unknown: 'reference',
   view_rows_exceeded: 'budget',
   view_line_break: 'parse',
   view_relation_ambiguous: 'reference',

package/src/mcp.ts

@@ -543,15 +543,30 @@ const TOOLS: ToolDef[] = [
         type: 'string',
         description: 'sets: the full element domain (optional)',
       },
+      depth: {
+        type: 'integer',
+        description: 'doc: how many levels of key to draw (default 3)',
+      },
       maxRows: {
         type: 'integer',
         description: 'Refuse a figure above this many rows (default 60)',
       },
+      style: {
+        type: 'string',
+        description:
+          'How the figure carries the meaning of its marks: none, ansi ' +
+          '(SGR escapes, text only) or css (classes and the embedded ' +
+          'stylesheet, svg only). Absent means the profile\'s own ' +
+          'default -- svg keeps its stylesheet, everything else has no ' +
+          'mechanism. There is no auto here: resolving it needs a ' +
+          'terminal, which a server does not have (optional)',
+      },
     },
     required: ['source'],
     docs: ['source'],
     check: (a) => {
-      const kinds = ['tree', 'matrix', 'graph', 'layer', 'sets', 'layers', 'ladder']
+      const kinds = ['doc', 'tree', 'matrix', 'graph', 'layer', 'sets',
+        'layers', 'ladder']
       if (null != a.kind && !kinds.includes(a.kind)) {
         return `kind must be one of ${kinds.join(', ')}, not ${JSON.stringify(a.kind)}`
       }
@@ -563,6 +578,10 @@ const TOOLS: ToolDef[] = [
       if (null != a.edges && !edges.includes(a.edges)) {
         return `edges must be one of ${edges.join(', ')}, not ${JSON.stringify(a.edges)}`
       }
+      const styles = ['none', 'ansi', 'css']
+      if (null != a.style && !styles.includes(a.style)) {
+        return `style must be one of ${styles.join(', ')}, not ${JSON.stringify(a.style)}`
+      }
       return undefined
     },
     refuse: (a, finding) =>
@@ -586,7 +605,9 @@ const TOOLS: ToolDef[] = [
         sets: null == a.sets ? undefined : str(a.sets),
         member: null == a.member ? undefined : str(a.member),
         universe: null == a.universe ? undefined : str(a.universe),
+        depth: 'number' === typeof a.depth ? a.depth : undefined,
         maxRows: 'number' === typeof a.maxRows ? a.maxRows : undefined,
+        style: null == a.style ? undefined : a.style,
       }),
   },
   {

package/src/std.ts

@@ -87,7 +87,7 @@ view: {
   # it belongs; everything else narrows the drawing, and each option
   # belongs to the kinds that read it.
   Figure: type({
-    kind: tree | matrix | graph | layer | sets | layers | ladder
+    kind: doc | tree | matrix | graph | layer | sets | layers | ladder
     out: string
 
     # Every kind.
@@ -95,6 +95,9 @@ view: {
     at?: string
     maxRows?: integer & min(0)
 
+    # doc: how many levels of key to draw.
+    depth?: integer & min(0)
+
     # tree, matrix, layer: the relation drawn. graph: the predicates
     # kept. tree: the subtrees drawn.
     relation?: string

package/src/vet.ts

@@ -573,7 +573,11 @@ export function anchorAt(root: any, at: string): Val | undefined {
 
 
 // The container inside a settled sizing residue, or the value itself.
-function throughResidue(v: any): any {
+// 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
 }