@rse/specbook 1.2.4 → 1.2.6

package/dst/specbook-format.md

@@ -74,6 +74,7 @@ type SchemaObject = {
     refs?:             string
     optional?:         boolean
     referenced?:       string[]
+    coverage?:         string[]
     automaton?:        SchemaAutomaton
     diagram?:          SchemaDiagram
     format?:           SchemaFormat
@@ -100,6 +101,7 @@ type SchemaDiagramCenterEdges = {
     outbound?:         string
     both?:             string
     labeled?:          string
+    via?:              string
 }
 type SchemaDiagram = {
     type?:             "graph" | "hub" | "grid"
@@ -123,6 +125,7 @@ type SchemaDiagram = {
 type SchemaFormat = {
     type?:             "auto" | "complex" | "concise"
     maxTableColumns?:  number
+    maxCellHeight?:    number
     withUnusedProps?:  boolean
 }
 type SchemaProperty = {
@@ -234,6 +237,13 @@ type SchemaGradiaConfig = Partial<{
     at least once, where a lapse is reported as a warning only,
     BECAUSE a term nobody uses or a requirement no use case exercises is dead weight
 
+-   `SchemaObject.coverage?: string[]`:
+    wildcard references (e.g. `[[SCENARIO:*]]` for the use case scenarios)
+    matching the objects whose reference coverage every object of this kind
+    reports: the share of them referenced -- themselves or through their
+    descendants -- from the object or its descendants (see below),
+    BECAUSE a test artifact has to state how much of the specification it verifies
+
 -   `SchemaObject.automaton?: SchemaAutomaton`:
     finite state machine the child objects of every object of this kind form,
     BECAUSE a lifecycle is only trustworthy when its dead-ends and
@@ -318,9 +328,11 @@ type SchemaGradiaConfig = Partial<{
     objects whose `inbound` value maps onto a node-to-center edge, whose
     `outbound` value onto a center-to-node edge, and whose `both` value
     onto both edges (the second placement rendered as a "ghost" node),
-    each optionally named by the value of the `labeled` property,
-    BECAUSE the nodes carry no `[[xxx]]` reference to a synthetic center,
-    so their relation to it lives in a direction property instead
+    each optionally named by the value of the `labeled` property and/or
+    by the mediating object referenced by the `via` property (as `via
+    <name>`), BECAUSE the nodes carry no `[[xxx]]` reference to a
+    synthetic center, so their relation to it lives in a direction
+    property instead
 
 -   `SchemaDiagram.links?: "props" | "all"`:
     edge source: property values (`props`) or also texts (`all`),
@@ -350,7 +362,7 @@ type SchemaGradiaConfig = Partial<{
 
 -   `SchemaDiagram.deep?: boolean`:
     whether the references of the descendants of a node count as its own,
-    lifted to their nearest node and counted as the arity (default: `false`),
+    counted as the arity (default: `false`),
     BECAUSE the relations between coarse objects live in their fine parts
 
 -   `SchemaDiagram.onlyConnected?: boolean`:
@@ -365,6 +377,40 @@ type SchemaGradiaConfig = Partial<{
     whether every node is labeled with its kind (default: `false`),
     BECAUSE names alone are ambiguous across multiple object kinds
 
+-   `SchemaDiagram.ordered?: boolean`:
+    whether the nodes are placed in document order instead of by the
+    layered layout, the top-level ones stacked top-down and the members
+    of a container lined up left-to-right (default: `false`),
+    BECAUSE in a coarse-to-fine specification the references then all
+    point backward, i.e. upward
+
+-   `SchemaDiagram.nest?: SchemaDiagramNest`:
+    nesting of the nodes into container nodes,
+    BECAUSE a containment drawn as a box beats one drawn as an edge
+
+-   `SchemaDiagramNest.properties?: string[]`:
+    properties whose single referenced object is the container of a node,
+    BECAUSE a `PART-OF` or `TIER` reference is a containment, not a relation
+
+-   `SchemaDiagramNest.parent?: boolean`:
+    whether the parent object is the container of a node (default: `false`),
+    BECAUSE the nesting of the objects is a containment, too
+
+-   `SchemaDiagramNest.kind?: boolean`:
+    whether a synthetic container per object kind holds the nodes
+    (default: `false`),
+    BECAUSE a kind is a grouping no object models
+
+-   `SchemaDiagramNest.layout?: "graph" | "hub" | "grid"`:
+    shape the members of every container are laid out with
+    (default: the diagram type),
+    BECAUSE the inside of a container may tell a different story than the whole
+
+-   `SchemaDiagramNest.crossing?: "nodes" | "target" | "both"`:
+    ends of a boundary-crossing edge lifted onto the containers
+    (default: `nodes`, i.e. none),
+    BECAUSE a bundle of references into a container reads as one edge onto it
+
 -   `SchemaDiagram.properties?: string[]`:
     property names attached to the nodes as key/value annotations,
     BECAUSE the node name alone rarely makes the nodes comparable
@@ -385,6 +431,10 @@ type SchemaGradiaConfig = Partial<{
     maximum column count of the table of the kind (default: `4`),
     BECAUSE the fixed print/PDF page width bounds the table width
 
+-   `SchemaFormat.maxCellHeight?: number`:
+    percent a table cell may tower over its row before it folds (default: `40`),
+    BECAUSE a cell of rich prose otherwise dwarfs the whole table
+
 -   `SchemaFormat.withUnusedProps?: boolean`:
     whether unused properties still render (default: `false`),
     BECAUSE empty entries are noise, unless the gap is the message
@@ -474,9 +524,10 @@ type SchemaGradiaConfig = Partial<{
 
 The edges are derived from the `[[xxx]]` references of the node objects
 -- from their property values only, or, with `links: all`, from their
-descriptions as well. With `deep: true` the references of all
-descendants of a node object count as its own, every referenced object
-is lifted to its nearest ancestor-or-self within the node set, and the
+descriptions as well. Every referenced object is lifted to its nearest
+ancestor-or-self within the node set, so a reference onto the scenario
+of a use case yields an edge onto the use case. With `deep: true` the
+references of all descendants of a node object count as its own and the
 number of references behind an edge becomes its arity, so a diagram of
 coarse objects (like the artifacts of a whole specification) shows the
 relations living in their fine-grained parts. With `labeled: true` an
@@ -527,6 +578,52 @@ nodes as key/value annotations (with every `[[xxx]]` reference stripped
 to its target object name), and `config` passes arbitrary Gradia
 rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
 
+`ordered` replaces the layered layout of a `graph` by the document
+order of the objects: the top-level nodes stack top-down in that order
+(a synthetic container at the position of its first member), while the
+members of a container line up left-to-right in it, wrapped by the
+Gradia option `graph-columns-max`, so the references of a coarse-to-fine
+specification all point backward, i.e. upward or leftward.
+
+`nest` nests the nodes into *container* nodes, drawn as boxes around
+their members with the edges crossing the box borders: the first of its
+`properties` carrying exactly one resolvable reference names the
+container of a node (a container outside the node set is added to it,
+labeled and linked like a node, and nested on its own in turn, so a
+`NODE` sits in its `TIER` and the tier in the tier it is `PART-OF`),
+else with `parent: true` the parent object is the container when part
+of the node set, else with `kind: true` a synthetic container per object
+kind is. An edge between a container and one of its own members is
+dropped, as the nesting already shows it, `layout` selects the shape
+the members of every container are laid out with (default: the diagram
+type), a `hub` carries no containers, as every container would need a
+primary node of its own, and a node nested into itself or into a cycle
+is reported. With `crossing: target` an edge crossing a container
+boundary ends at the outermost container of its target not enclosing
+its source, too, and with `crossing: both` it also starts at the
+corresponding container of its source, where the edges coinciding
+afterwards merge into one with their arities summed, so the edges
+inside a container stay node-to-node while the bundles of references
+into a container become single edges onto it.
+
+### Coverage
+
+An object kind can carry a `coverage` field, a list of `[[xxx]]`
+reference patterns, which makes every object of that kind report how
+much of the objects matching each pattern it references: the *coverage*
+is the share of the matching objects (those below the reporting object
+itself excluded) which are referenced from the reporting object or one
+of its descendants, where a matching object also counts as referenced
+through one of its descendants, so a use case is covered as soon as one
+of its scenarios is. While the `referenced` field demands the coverage
+of an object kind and warns about every lapse, the `coverage` field
+merely measures it: the HTML/PDF export renders a coverage table below
+the description of the reporting object (one row per pattern, labeled
+by the kinds of the matching objects, with the covered and total counts
+and the ratio as a bar), the AST exports attach the counts as the
+`coverage` field of the object, and the verbose output of `lint` and
+`export` names the unreferenced objects.
+
 ### Format
 
 An object kind can furthermore carry a `format` field, which controls
@@ -542,7 +639,10 @@ Inside a `concise` table, unconfigured child kinds implicitly stay
 an explicitly configured `type` is always honored, even a `complex`
 rendering pressed into a cell. `maxTableColumns` (default: `4`) bounds
 the columns of the compact table of the kind (a wider group chunks
-its properties into embedded per-object tables), and `withUnusedProps`
+its properties into embedded per-object tables), `maxCellHeight`
+(default: `40`) is the percentage a table cell of the kind may exceed
+the height of every other non-empty cell of its row before the HTML
+export folds its remaining text away, and `withUnusedProps`
 (default: `false`) unconditionally renders the defined but unused
 properties of that kind, as property table lines or table columns. In
 the HTML/PDF export, a property absent from an object shows an "empty
@@ -837,7 +937,7 @@ In all formats, the `<name/>` may carry trailing decorations, in any
 order:
 
 -   `{{<id/>}}`: the explicit Wiki-style anchor, setting the object id
-    (e.g. `## ENTITY: Attendee Browser {{attendee}}`).
+    (e.g. `## ENTITY: Attendee {{attendee}}`).
 
 -   `(<token/>)`: a parenthesized token with three possible roles: on
     level 1 it becomes the artifact id (e.g. `# DATA: Data Model (DM)`);
@@ -896,7 +996,7 @@ exports. A reference is a `.`-separated path of segments, where each
 segment matches a single object as:
 
 -   `<id/>`: the object id or explicit anchor (e.g. `[[attendee]]`)
--   `<name/>`: the object name (e.g. `[[Attendee Browser]]`)
+-   `<name/>`: the object name (e.g. `[[Attendee]]`)
 -   `<kind/>:<name-or-id/>`: kind-qualified (e.g. `[[ENTITY:Event]]`)
 -   `<kind/>:*` or `*`: wildcards (for match sets, see below)