@rse/specbook 1.2.5 → 1.2.6

package/README.md

@@ -72,14 +72,17 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 -   **AST Exports for AI/LLMs**:
     The parsed specification Abstract Syntax Tree (AST) can be exported in
     JSON, JSON5, YAML, or TOON format for machine consumption, with the
-    derived diagram of an object attached to it as a textual Gradia spec.
+    derived diagram of an object attached to it as a textual Gradia spec
+    and the reference coverage it reports attached as its counts.
     Together with the `describe` command, which explains the models and
     formats, this enables LLMs to both read and write specifications.
 
 -   **HTML Export for Developers**:
     The HTML export is a self-contained single document with a title page,
     a table-of-contents (also as a slide-in side panel for quick navigation),
-    a diagram-of-contents, a fuzzy full-text search, embedded images, a
+    a diagram-of-contents, a fuzzy full-text search, embedded images,
+    reference coverage tables (e.g. the share of the use cases, scenarios,
+    requirements, and rules the test cases verify), a
     scroll progress meter (which also scrolls back to the top on click),
     description popups (which show the schema and corpus description of
     an object kind, property, or object instance on hover), and a
@@ -182,7 +185,10 @@ Options:
     all diagnostics and fail on any error among them (a warning, like a
     lapse of the reference coverage a `referenced` object kind demands,
     is reported only), so a partial or invalid specification is never
-    exported.
+    exported. The verbose output additionally states the reference
+    coverage ratios: the ones the `referenced` object kinds receive and
+    the ones the `coverage` object kinds report, the latter naming the
+    unreferenced objects.
     The option accepts glob patterns and can be given multiple times: the
     matching files (in the order of the patterns and alphabetically within
     a pattern, where the literal `std` names the bundled standard schema

package/dst/specbook-cmd-lint.js

@@ -7,7 +7,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadConfig, configStatistics } from "./specbook-config.js";
 import { literal } from "./specbook-verbose.js";
-import { parseSpecification, specStatistics, resolveArtifact } from "./specbook-parse.js";
+import { parseSpecification, specStatistics, resolveArtifact, collectSchemas } from "./specbook-parse.js";
+import { buildLinkIndex, chainOf, plainText } from "./specbook-link.js";
+import { referencedCoverage, specCoverage, coverageRatio } from "./specbook-coverage.js";
 /*  collect the distinct artifact files the schema configuration
     references, in their declaration order, each mapped onto whether
     all of its artifacts are optional and hence the file may be absent  */
@@ -72,6 +74,28 @@ export const lint = (options) => {
     const stats = specStatistics(result.specification);
     options.verbose(`parsed specification defining ${literal(stats.objects)} object(s) ` +
         `and ${literal(stats.links)} link relationship(s)`);
+    /*  report the reference coverage the "referenced"-flagged object
+        kinds receive and the "coverage"-configured objects report, the
+        unreferenced objects of the latter by name (the ones of the
+        former are already reported as warnings)  */
+    if (config !== undefined && result.specification.artifacts.length > 0) {
+        const index = buildLinkIndex(result.specification);
+        const schemas = collectSchemas(result.specification, config);
+        const label = (object) => `${object.kind} "${literal(plainText(object.name))}"`;
+        const ratio = (covered, uncovered) => `${literal(covered.length)} of ${literal(covered.length + uncovered.length)} ` +
+            `(${literal(coverageRatio(covered.length, covered.length + uncovered.length))}%)`;
+        for (const { schema, covered, uncovered } of referencedCoverage(index, schemas)) {
+            const chain = chainOf(index, covered[0] ?? uncovered[0]);
+            options.verbose((schema.referenced ?? []).map((entry) => `"${literal(entry)}"`).join(" or ") +
+                ` references ${ratio(covered, uncovered)} ${schema.kind} object(s)` +
+                (chain.length > 1 ? ` below ${label(chain[0])}` : ""));
+        }
+        for (const [object, entries] of specCoverage(index, schemas))
+            for (const { pattern, covered, uncovered } of entries)
+                options.verbose(`${label(object)} references ${ratio(covered, uncovered)} ` +
+                    `"${literal(pattern)}" object(s)` + (uncovered.length > 0 ?
+                    `, unreferenced: ${uncovered.map(label).join(", ")}` : ""));
+    }
     /*  report the non-optional artifacts absent from the specification,
         against their loaded artifact file (an absent or unreadable file
         is already reported above) or else against the configuration  */

package/dst/specbook-config.js

@@ -190,10 +190,10 @@ const checkAutomaton = (object, at, diagnose) => {
     are beyond its schema: sibling objects have to stay distinctly
     resolvable, "file" fields are allowed on the first (artifact) level
     only, property value and marker expressions have to be syntactically
-    valid, "referenced" entries have to be reference expressions, an
-    "automaton" has to name existing child kinds and properties, and the
-    names of non-artifact objects have to be valid patterns (as they are
-    compiled into regular expressions)  */
+    valid, "referenced" and "coverage" entries have to be reference
+    expressions, an "automaton" has to name existing child kinds and
+    properties, and the names of non-artifact objects have to be valid
+    patterns (as they are compiled into regular expressions)  */
 const checkConstraints = (config, posOfPath) => {
     const diagnostics = new Array();
     const diagnose = (path, message) => {
@@ -216,20 +216,21 @@ const checkConstraints = (config, posOfPath) => {
                 diagnose([...at, "file"], `"file" field is only allowed on the first (artifact) level (found on level ${depth})`);
             checkProperties(object.props ?? [], at, diagnose);
             checkAutomaton(object, at, diagnose);
-            for (const [j, entry] of (object.referenced ?? []).entries()) {
-                /*  a reference coverage entry has to be a single
-                    (usually wildcard) reference expression  */
-                let expr;
-                try {
-                    expr = compileValueExpr(entry);
+            for (const field of ["referenced", "coverage"])
+                for (const [j, entry] of (object[field] ?? []).entries()) {
+                    /*  a reference coverage entry has to be a single
+                        (usually wildcard) reference expression  */
+                    let expr;
+                    try {
+                        expr = compileValueExpr(entry);
+                    }
+                    catch (err) {
+                        diagnose([...at, field, j], `invalid "${field}" entry "${entry}": ` +
+                            (err instanceof Error ? err.message : String(err)));
+                    }
+                    if (expr !== undefined && expr.kind !== "reference")
+                        diagnose([...at, field, j], `"${field}" entry "${entry}" is not a single "[[xxx]]" reference`);
                 }
-                catch (err) {
-                    diagnose([...at, "referenced", j], `invalid "referenced" entry "${entry}": ` +
-                        (err instanceof Error ? err.message : String(err)));
-                }
-                if (expr !== undefined && expr.kind !== "reference")
-                    diagnose([...at, "referenced", j], `"referenced" entry "${entry}" is not a single "[[xxx]]" reference`);
-            }
             if (depth > 1 && object.name !== undefined) {
                 try {
                     anchored(object.name);

package/dst/specbook-coverage.d.ts

@@ -0,0 +1,17 @@
+import { type SpecObject } from "./specbook-format-spec.js";
+import { type SchemaObject } from "./specbook-format-schema.js";
+import { type LinkIndex } from "./specbook-link.js";
+export interface ReferencedCoverage {
+    schema: SchemaObject;
+    covered: SpecObject[];
+    uncovered: SpecObject[];
+}
+export declare const referencedCoverage: (index: LinkIndex, schemas: Map<SpecObject, SchemaObject>) => ReferencedCoverage[];
+export interface Coverage {
+    pattern: string;
+    kinds: string[];
+    covered: SpecObject[];
+    uncovered: SpecObject[];
+}
+export declare const specCoverage: (index: LinkIndex, schemas: Map<SpecObject, SchemaObject>) => Map<SpecObject, Coverage[]>;
+export declare const coverageRatio: (covered: number, total: number) => number;

package/dst/specbook-coverage.js

@@ -0,0 +1,106 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { referenceRegex, resolveUnique, resolveSet, chainOf, plainText } from "./specbook-link.js";
+import { compileValueExpr } from "./specbook-parse-value.js";
+/*  the referencing objects of every referenced object, resolved from
+    the names, property values, descriptions, and rationales of all
+    objects, where the references from within the subtree of the
+    referenced object itself do not count (an object cannot cover
+    itself), leniently skipping the unresolvable references, as those
+    are already reported by the reference pass  */
+const referrerIndex = (index) => {
+    const referrers = new Map();
+    for (const { object } of index) {
+        const chain = chainOf(index, object);
+        const texts = [object.name, ...object.properties.map((p) => p.value)];
+        if (object.description !== undefined)
+            texts.push(object.description.description, object.description.rationale ?? "");
+        for (const text of texts)
+            for (const m of plainText(text).matchAll(referenceRegex)) {
+                const target = resolveUnique(index, m[1].trim(), object).target;
+                if (target !== undefined && !chain.includes(target))
+                    referrers.set(target, (referrers.get(target) ?? new Set()).add(object));
+            }
+    }
+    return referrers;
+};
+/*  whether an object is covered by a set of source objects: it is
+    referenced from an object lying below one of the sources (itself
+    or through an ancestor) or, when lifting, so is one of its
+    descendants  */
+const isCovered = (index, referrers, sources, object, lifting) => {
+    for (const referrer of referrers.get(object) ?? [])
+        if (chainOf(index, referrer).some((o) => sources.has(o)))
+            return true;
+    return lifting && object.children.some((child) => isCovered(index, referrers, sources, child, true));
+};
+/*  the objects matching the reference patterns of a schema field  */
+const matchingObjects = (index, patterns) => {
+    const objects = new Array();
+    for (const pattern of patterns) {
+        const expr = compileValueExpr(pattern);
+        if (expr.kind === "reference")
+            for (const object of resolveSet(index, expr.pattern))
+                if (!objects.includes(object))
+                    objects.push(object);
+    }
+    return objects;
+};
+/*  determine the coverage the objects of every "referenced"-flagged
+    kind receive, one entry per flagged schema node (in the order of
+    the first objects of the nodes), as the semantic validation
+    reports every uncovered object and the verbose output the ratio  */
+export const referencedCoverage = (index, schemas) => {
+    const referrers = referrerIndex(index);
+    const results = new Map();
+    for (const [object, schema] of schemas) {
+        if (schema.referenced === undefined)
+            continue;
+        let result = results.get(schema);
+        if (result === undefined) {
+            result = { schema, sources: new Set(matchingObjects(index, schema.referenced)),
+                covered: [], uncovered: [] };
+            results.set(schema, result);
+        }
+        const bucket = isCovered(index, referrers, result.sources, object, false) ?
+            result.covered : result.uncovered;
+        bucket.push(object);
+    }
+    return Array.from(results.values()).map(({ schema, covered, uncovered }) => ({ schema, covered, uncovered }));
+};
+/*  determine the coverage the objects of every "coverage"-configured
+    kind report, one entry per configured pattern: the objects matching
+    the pattern (those below the reporting object itself excluded) count
+    as covered once referenced -- themselves or through one of their
+    descendants, so a use case is covered through its scenarios -- from
+    the reporting object or one of its descendants  */
+export const specCoverage = (index, schemas) => {
+    const referrers = referrerIndex(index);
+    const results = new Map();
+    for (const [object, schema] of schemas) {
+        if (schema.coverage === undefined)
+            continue;
+        const sources = new Set([object]);
+        const entries = new Array();
+        for (const pattern of schema.coverage) {
+            const targets = matchingObjects(index, [pattern])
+                .filter((target) => !chainOf(index, target).includes(object));
+            const entry = { pattern, kinds: [], covered: [], uncovered: [] };
+            for (const target of targets) {
+                if (!entry.kinds.includes(target.kind))
+                    entry.kinds.push(target.kind);
+                const bucket = isCovered(index, referrers, sources, target, true) ?
+                    entry.covered : entry.uncovered;
+                bucket.push(target);
+            }
+            entries.push(entry);
+        }
+        results.set(object, entries);
+    }
+    return results;
+};
+/*  the percentage of a coverage, rounded to the integer  */
+export const coverageRatio = (covered, total) => total > 0 ? Math.round(covered * 100 / total) : 0;

package/dst/specbook-diagram.js

@@ -340,7 +340,9 @@ const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, parenProp
     direction property of the node objects: the "inbound" value
     maps onto a node-to-center edge, the "outbound" value onto a
     center-to-node edge, and the "both" value onto both (which
-    Gradia renders as an input node plus an output "ghost" node)  */
+    Gradia renders as an input node plus an output "ghost" node),
+    named by the "labeled" property and/or by the mediating object
+    the "via" property references (as "via <name>")  */
 const deriveCenterEdges = (cfg, nodes, center, index, parenProps, errors) => {
     const edges = new Array();
     for (const node of nodes) {
@@ -356,9 +358,17 @@ const deriveCenterEdges = (cfg, nodes, center, index, parenProps, errors) => {
                     `carries the unmapped diagram "centerEdges" value "${value}"` });
             continue;
         }
+        const expand = (text) => plainText(expandReferences(text, (reference) => resolveUnique(index, reference, node).target?.name ?? reference));
         const label = cfg.labeled !== undefined ?
             propValue(parenProps, node, cfg.labeled) : undefined;
-        const name = label !== undefined ? plainText(expandReferences(label, (reference) => resolveUnique(index, reference, node).target?.name ?? reference)) : undefined;
+        const via = cfg.via !== undefined ?
+            propValue(parenProps, node, cfg.via) : undefined;
+        const names = new Array();
+        if (label !== undefined)
+            names.push(expand(label));
+        if (via !== undefined)
+            names.push(`via ${expand(via)}`);
+        const name = names.length > 0 ? names.join(" ") : undefined;
         if (inbound || both)
             edges.push({ source: node, target: center, name });
         if (outbound || both)

package/dst/specbook-export-ast.js

@@ -7,6 +7,9 @@ import JSON5 from "json5";
 import { stringify as stringifyYaml } from "yaml";
 import { encode as encodeToon } from "@toon-format/toon";
 import { specDiagrams } from "./specbook-diagram.js";
+import { specCoverage } from "./specbook-coverage.js";
+import { buildLinkIndex } from "./specbook-link.js";
+import { collectSchemas } from "./specbook-parse-semantic.js";
 import { isTitleObject } from "./specbook-export-common.js";
 /*  render the specification AST into a serialization format  */
 export const renderAst = (specification, format, config) => {
@@ -16,13 +19,20 @@ export const renderAst = (specification, format, config) => {
         "diagram" fields onto the corresponding plain object nodes
         (an invalid diagram situation omits the diagram, as it is
         already reported as a lint diagnostic, and the diagram of
-        the title object is reserved for the HTML/PDF export)  */
+        the title object is reserved for the HTML/PDF export), and
+        the reference coverage of the coverage-configured objects as
+        "coverage" fields (the counts only, as the export is intended
+        for machine consumption)  */
     if (config !== undefined) {
         const diagrams = specDiagrams(specification, config);
+        const coverages = specCoverage(buildLinkIndex(specification), collectSchemas(specification, config));
         const walk = (object, node) => {
             const result = diagrams.get(object);
             if (result?.spec !== undefined && !isTitleObject(object))
                 node.diagram = result.spec;
+            const coverage = coverages.get(object);
+            if (coverage !== undefined)
+                node.coverage = coverage.map(({ pattern, covered, uncovered }) => ({ pattern, covered: covered.length, total: covered.length + uncovered.length }));
             object.children.forEach((child, i) => walk(child, node.children[i]));
         };
         specification.artifacts.forEach((artifact, i) => artifact.objects.forEach((object, j) => walk(object, plain.artifacts[i].objects[j])));

package/dst/specbook-export-html.css

@@ -486,7 +486,7 @@ div.fold-switch div.fold-controls svg {
 /*  the folding of the diagrams and the over-long table cells
     (screen-only): a diagram sits in a fold container carrying a chevron
     mark in the muted symbol color of the anchors at its top left corner
-    -- in the page margin beside the content, and in the flow left of
+    -- in the page margin beside the content, and in a flex row left of
     the diagram inside a table cell, where no margin is left -- while an
     over-long cell carries its own chevron in a rounded grey box behind
     the last still shown word; a folded diagram leaves the icon of its
@@ -543,19 +543,25 @@ span.fold-label svg {
   height: 1.1rem;
 }
 @media screen {
+  td div.fold {
+    display: flex;
+    align-items: flex-start;
+  }
   td div.fold > span.fold-mark {
     position: static;
-    display: inline-block;
-    vertical-align: middle;
-    margin-right: 0.3rem;
+    flex: 0 0 auto;
+    margin: 0.3rem 0.3rem 0 0;
+  }
+  td div.fold > div.diagram {
+    flex: 1 1 auto;
+    min-width: 0;
   }
   body:not(.searching) div.fold.folded > span.fold-label {
     display: block;
   }
   body:not(.searching) td div.fold.folded > span.fold-label {
-    display: inline-block;
-    vertical-align: middle;
-    margin-bottom: 0;
+    display: block;
+    margin: 0.15rem 0 0 0;
   }
   body:not(.searching) div.fold.folded > div.diagram,
   body:not(.searching) td.folded .fold-rest {
@@ -1103,6 +1109,58 @@ table.objects td section {
 table.objects td section h6 {
   margin: 0.5rem 0 0.25rem 0;
 }
+/*  the reference coverage tables of the coverage-configured objects:
+    the headers like the "Properties" and "Diagram" headers of the
+    compact tables (as they name neither object kinds nor properties),
+    the counts in narrow columns, the ratio as a bar in the accent
+    color over the remaining width, followed by its percentage  */
+table.coverage {
+  border-collapse: collapse;
+  margin: 1rem 0;
+  width: 100%;
+}
+table.coverage th,
+table.coverage td {
+  border: 0;
+  border-left: 1px solid var(--theme-color-specbook-border);
+  padding: 0.3rem 0.6rem;
+  text-align: left;
+  vertical-align: top;
+  white-space: nowrap;
+}
+table.coverage th:first-child,
+table.coverage td:first-child {
+  border-left: 0;
+}
+table.coverage td:first-child {
+  font-weight: 600;
+}
+table.coverage th {
+  background-color: var(--theme-color-specbook-tint);
+  font-weight: normal;
+  color: var(--theme-color-specbook-accent);
+}
+table.coverage tbody tr.even td {
+  background-color: var(--theme-color-specbook-stripe);
+}
+table.coverage th.ratio,
+table.coverage td.ratio {
+  width: 100%;
+}
+table.coverage span.bar {
+  display: inline-block;
+  vertical-align: middle;
+  width: 12rem;
+  height: 0.6rem;
+  border-radius: 0.3rem;
+  background-color: var(--theme-color-specbook-tint-deep);
+  overflow: hidden;
+}
+table.coverage span.bar > span {
+  display: block;
+  height: 100%;
+  background-color: var(--theme-color-specbook-accent);
+}
 /*  the object descriptions and their embedded images  */
 p.description,
 div.description {

package/dst/specbook-export-html.js

@@ -15,6 +15,7 @@ import { embeddingRegex, embeddingMimeType, embeddingThemes, embeddingVariants }
 import { escapeHtml, stylesheet, searchScript, fallbackLogo, isTitleObject, titleObject, documentTitle, documentLang, documentThemeStyle } from "./specbook-export-common.js";
 import { collectSchemas } from "./specbook-parse-semantic.js";
 import { renderDiagrams } from "./specbook-diagram.js";
+import { specCoverage, coverageRatio } from "./specbook-coverage.js";
 /*  ==== Templates ====  */
 /*  the built-in Nunjucks templates for the HTML export  */
 const templates = {
@@ -154,9 +155,23 @@ const templates = {
             {{ Object.diagram }}
             {{ Object.properties }}
             {{ Object.description }}
+            {{ Object.coverage }}
             {{ Object.children }}
         </section>
     `,
+    /*  <Coverage/>  */
+    "Coverage": textframe `
+        <table class="coverage">
+            <thead>
+                <tr><th>Coverage</th><th>Covered</th><th>Total</th><th class="ratio">Ratio</th></tr>
+            </thead>
+            <tbody>
+                {% for entry in Coverage %}
+                <tr{% if entry.even %} class="even"{% endif %}><td>{{ entry.label }}</td><td>{{ entry.covered }}</td><td>{{ entry.total }}</td><td class="ratio"><span class="bar"><span style="width: {{ entry.ratio }}%"></span></span> {{ entry.ratio }}%</td></tr>
+                {% endfor %}
+            </tbody>
+        </table>
+    `,
     /*  <Properties/>  */
     "Properties": textframe `
         <table class="props"{% if Fold %} data-fold-height="{{ Fold }}"{% endif %}>
@@ -979,14 +994,15 @@ const render = (name, context) => {
 };
 /*  the active per-document reference expander, fully-qualified
     anchor paths, member-carrying property value constraints, object
-    schema nodes, pre-rendered diagram SVGs, description popup keys
-    of the schema nodes, and object parents of the description popup
-    title paths (all set during HTML rendering)  */
+    schema nodes, pre-rendered diagram SVGs, reference coverages,
+    description popup keys of the schema nodes, and object parents of
+    the description popup title paths (all set during HTML rendering)  */
 let linker = null;
 let anchors = null;
 let members = null;
 let schemas = null;
 let diagrams = null;
+let coverages = null;
 let infoKeys = null;
 let infoParents = null;
 /*  the object whose texts are currently rendered, scoping the
@@ -1292,6 +1308,30 @@ const diagramOf = (object) => {
     const diagram = diagrams?.get(object);
     return diagram !== undefined ? safe(`<div class="diagram">${diagram}</div>`) : "";
 };
+/*  the reference coverage of an object as a table: one row per
+    configured pattern, labeled by the kinds of the matching objects,
+    marked as object kinds and carrying the description popup of the
+    first matching object of each kind (by the bare pattern, if none
+    matches), with the counts and the ratio as a bar (empty for an
+    object without a configured coverage)  */
+const coverageOf = (object) => {
+    const coverage = coverages?.get(object);
+    if (coverage === undefined)
+        return "";
+    const kindLabel = (entry, kind) => {
+        const first = [...entry.covered, ...entry.uncovered].find((target) => target.kind === kind);
+        return `<span class="object-kind"${first !== undefined ? infoAttr(first) : ""}>${escapeHtml(kind)}</span>`;
+    };
+    return safe(render("Coverage", { Coverage: coverage.map((entry, i) => ({
+            label: entry.kinds.length > 0 ?
+                safe(entry.kinds.map((kind) => kindLabel(entry, kind)).join(", ")) :
+                entry.pattern.replace(/^\[\[(.*)\]\]$/s, "$1"),
+            covered: entry.covered.length,
+            total: entry.covered.length + entry.uncovered.length,
+            ratio: coverageRatio(entry.covered.length, entry.covered.length + entry.uncovered.length),
+            even: i % 2 === 1
+        })) }));
+};
 /*  render a single-kind group of children into one compact table:
     the name first, then the property columns, then the description;
     a group wider than maxColumns, or carrying diagrams, instead chunks
@@ -1386,6 +1426,7 @@ const renderObject = (object, level, concise) => {
                     Fold: formatOf(object)?.maxCellHeight })) : "",
             description: object.description !== undefined ?
                 safe(renderDescription(object.description)) : "",
+            coverage: coverageOf(object),
             children: safe(renderChildren(object, level + 1, concise))
         } }));
 };
@@ -1572,6 +1613,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
         members = config !== undefined ? collectMembers(config, new Map()) : null;
         schemas = config !== undefined ? collectSchemas(specification, config) : null;
         diagrams = rendered;
+        coverages = schemas !== null ? specCoverage(index, schemas) : null;
         /*  collect the schema descriptions for the description popups,
             plus the object parents composing their title paths  */
         let info = null;
@@ -1638,6 +1680,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
         members = null;
         schemas = null;
         diagrams = null;
+        coverages = null;
         infoKeys = null;
         infoParents = null;
     }

package/dst/specbook-format-schema.d.ts

@@ -10,6 +10,7 @@ export type SchemaObject = {
     refs?: string;
     optional?: boolean;
     referenced?: string[];
+    coverage?: string[];
     automaton?: SchemaAutomaton;
     diagram?: SchemaDiagram;
     format?: SchemaFormat;
@@ -36,6 +37,7 @@ export type SchemaDiagramCenterEdges = {
     outbound?: string;
     both?: string;
     labeled?: string;
+    via?: string;
 };
 export type SchemaDiagramNest = {
     properties?: string[];

package/dst/specbook-format-schema.js

@@ -48,7 +48,8 @@ const SchemaDiagramCenterEdges = v.strictObject({
     inbound: v.optional(v.string()),
     outbound: v.optional(v.string()),
     both: v.optional(v.string()),
-    labeled: v.optional(v.string())
+    labeled: v.optional(v.string()),
+    via: v.optional(v.string())
 });
 const SchemaDiagramNest = v.strictObject({
     properties: v.optional(v.array(v.string())),
@@ -93,6 +94,7 @@ const SchemaObject = v.strictObject({
     refs: v.optional(v.string()),
     optional: v.optional(v.boolean()),
     referenced: v.optional(v.pipe(v.array(v.string()), v.minLength(1))),
+    coverage: v.optional(v.pipe(v.array(v.string()), v.minLength(1))),
     automaton: v.optional(SchemaAutomaton),
     diagram: v.optional(SchemaDiagram),
     format: v.optional(SchemaFormat),

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"
@@ -235,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
@@ -319,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`),
@@ -595,6 +606,24 @@ 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
@@ -908,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)`);
@@ -967,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)
 

package/dst/specbook-format.yaml

@@ -711,6 +711,28 @@
                 several requirements otherwise) which is verifiable against its `METRIC`, written
                 with exactly one keyword `MUST`, `SHOULD`, or `COULD` matching its `PRIORITY`, plus
                 a 1-sentence rationale ("why").
+
+                The requirement is answered by the architecture, never the other way round: a
+                Quality Perspectives tactic addresses it through its mechanism, a Design Decisions
+                decision is driven by it as a force, and an Operations View concern fulfills it
+                through its procedure, so every requirement is referenced from at least one of
+                them (a `WONT` requirement, which the architecture rightly ignores, is the tolerated
+                exception the lint warning cannot tell apart) and its hub diagram shows what
+                answers it.
+            referenced:
+                -   "[[TACTIC:*]]"
+                -   "[[DECISION:*]]"
+                -   "[[CONCERN:*]]"
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[NR.REQUIREMENT:*]], [[FR.REQUIREMENT:*]], [[PREMISE:*]], [[RULE:*]],
+                    [[TACTIC:*]], [[DECISION:*]], [[CONCERN:*]], [[TEST-CASE:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
             props:
                 -   name: PRIORITY
                     desc: >
@@ -1077,7 +1099,8 @@
                 type: hub
                 center: self
                 nodes: "[[USE-CASE:*]], [[ROLE:*]], [[PERSONA:*]], [[STEP:*]], [[ACTIVITY:*]],
-                    [[FR.REQUIREMENT:*]], [[RULE:*]], [[TRANSITION:*]], [[PERMISSION:*]]"
+                    [[FR.REQUIREMENT:*]], [[RULE:*]], [[TRANSITION:*]], [[PERMISSION:*]],
+                    [[PRINCIPLE:*]], [[CV.ENTITY:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -2133,7 +2156,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[PRINCIPLE:*]], [[PERSONA:*]], [[STEP:*]], [[PATTERN:*]]"
+                nodes: "[[PRINCIPLE:*]], [[PERSONA:*]], [[STEP:*]], [[USE-CASE:*]], [[PATTERN:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -2151,16 +2174,32 @@
                     desc: >
                         Comma-separated references to the User Personas objects whose experience
                         the principle governs, omitted for a principle governing the experience of
-                        all users alike.
+                        all users alike; this scopes the principle only, its origin is the
+                        `MOTIVATED-BY` and its realization the `USE-CASES`.
                     value: list([[PERSONA:*]])
                     optional: true
                 -   name: MOTIVATED-BY
                     desc: >
                         Comma-separated references to the User Journey step objects whose
                         `PAIN-POINT` or `OPPORTUNITY` the principle answers, so that a principle is
-                        grounded in the observed experience rather than in taste alone.
+                        grounded in the observed experience rather than in taste alone; this is the
+                        origin of the principle (why it exists), while the `USE-CASES` are its
+                        realization (where it can be checked).
                     value: list([[STEP:*]])
                     optional: true
+                -   name: USE-CASES
+                    desc: >
+                        Comma-separated references to the USE-CASES objects whose scenario steps
+                        exhibit the behavior the principle prescribes (e.g. a `Moderation-Gated
+                        Visibility` surfaces in the step where the submitted message is acknowledged
+                        but not yet public), or, where not every scenario of a use case does so, to
+                        the very `SCENARIO` objects doing so, tracing the principle into the
+                        step-by-step flows against which its realization is checked, while the
+                        concrete user interface realizing it stays with the Dialog Patterns and the
+                        Dialog Storyboard; omitted for a principle governing no use case flow in
+                        particular.
+                    value: list([[USE-CASE:*]], [[SCENARIO:*]])
+                    optional: true
                 -   name: TRADE-OFF
                     desc: >
                         The competing concern the principle deliberately subordinates, stated so
@@ -2595,6 +2634,7 @@
             inbound:  Inbound
             outbound: Outbound
             both:     Bidirectional
+            via:      VIA
         qualified: true
         properties:
             -   KIND
@@ -2633,8 +2673,20 @@
                         sides initiate), independent of the direction the exchanged information
                         flows in, which the `DATA` property describes (e.g. a datastore the
                         solution reads from is `Outbound`, as the solution initiates, while the
-                        data flows in).
+                        data flows in). For a mediated entity (see `VIA`), where the mediator
+                        initiates every interaction, the direction of the data flow instead.
                     value: enum(Inbound,Outbound,Bidirectional)
+                -   name: VIA
+                    desc: >
+                        Reference to the entity mediating the exchange with this one, when the
+                        solution and the entity have no direct technical interaction at all,
+                        but a person or system in between carries the data (e.g. a manager
+                        uploading the file exported by an external system), so the context
+                        diagram marks the edge as `via` that entity instead of suggesting an
+                        online integration; omitted for a directly interacting entity.
+                    value: "[[CV.ENTITY:*]]"
+                    optional: true
+                    acyclic: true
                 -   name: TERMS
                     desc: >
                         Comma-separated references to the GLOSSARY terms the entity appears as in
@@ -2661,6 +2713,15 @@
                         re-stating them; omitted when no modeled role stands behind the entity.
                     value: list([[ROLE:*]])
                     optional: true
+                -   name: USE-CASES
+                    desc: >
+                        Comma-separated references to the USE-CASES objects whose interaction
+                        crosses the boundary at this entity (the use cases a `Person` entity
+                        performs, or the ones exchanging data with a `System` or `Service`
+                        entity), so the use case responsible for an entity is found without a
+                        text search; omitted when no modeled use case touches the entity.
+                    value: list([[USE-CASE:*]])
+                    optional: true
                 -   name: PREMISES
                     desc: >
                         Comma-separated references to the SOLUTION-PREMISES objects (usually of
@@ -2714,7 +2775,8 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[FV.COMPONENT:*]], [[FR.REQUIREMENT:*]], [[INTERFACE:*]], [[DM.ENTITY:*]]"
+                nodes: "[[FV.COMPONENT:*]], [[FR.REQUIREMENT:*]], [[INTERFACE:*]], [[DM.ENTITY:*]],
+                    [[TACTIC:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -2853,7 +2915,8 @@
                     diagram:
                         type: hub
                         center: self
-                        nodes: "[[TS.TIER:*.COMPONENT:*]], [[FV.COMPONENT:*]], [[DECISION:*]]"
+                        nodes: "[[TS.TIER:*.COMPONENT:*]], [[FV.COMPONENT:*]], [[TACTIC:*]],
+                            [[DECISION:*]]"
                         labeled: true
                         qualified: true
                         properties:
@@ -3176,7 +3239,22 @@
                 states the product choice), does not restate the runtime structure (a Functionality
                 View `Module` or `Subsystem` groups the logic), does not cover production
                 procedures (an Operations View concern does), and the trade-off that produced a
-                rule is a Design Decisions decision referencing the aspect through `AFFECTS`.
+                rule is a Design Decisions decision referencing the aspect through `AFFECTS`,
+                while the quality the rule protects (usually a `Maintainability` requirement) is
+                addressed by a Quality Perspectives tactic referencing the aspect through
+                `AFFECTS`, too, so the hub diagram of an aspect shows the decision and the tactic
+                behind it.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[ASPECT:*]], [[TACTIC:*]], [[DECISION:*]]"
+                labeled: true
+                qualified: true
+                properties:
+                    -   CATEGORY
+                config:
+                    size-node-width-max:    440
+                    size-node-height-scale: 1.75
             props:
                 -   name: CATEGORY
                     desc: >
@@ -3229,7 +3307,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[UNIT:*]], [[FV.COMPONENT:*]], [[NODE:*]]"
+                nodes: "[[UNIT:*]], [[FV.COMPONENT:*]], [[NODE:*]], [[TACTIC:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3330,7 +3408,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[DV.TIER:*]], [[NODE:*]]"
+                nodes: "[[DV.TIER:*]], [[NODE:*]], [[TACTIC:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3380,7 +3458,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[AREA:*]], [[NODE:*]]"
+                nodes: "[[AREA:*]], [[NODE:*]], [[TACTIC:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3407,7 +3485,7 @@
                 type: hub
                 center: self
                 nodes: "[[DV.TIER:*]], [[AREA:*]], [[NODE:*]], [[NETWORK:*]], [[FV.COMPONENT:*]],
-                    [[UNIT:*]]"
+                    [[UNIT:*]], [[TACTIC:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3504,7 +3582,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[NETWORK:*]], [[NODE:*]]"
+                nodes: "[[NETWORK:*]], [[NODE:*]], [[TACTIC:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3886,10 +3964,11 @@
                         Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS or
                         SOLUTION-PREMISES objects forcing the decision (e.g. the compliance
                         obligation, the budget constraint, the dependency taken as given), anchoring
-                        the forces `WHEN` describes in prose; omitted when no modeled requirement or
-                        premise drives the decision.
+                        the forces `WHEN` describes in prose: as a decision is the response to
+                        forces, at least one is always named, usually a Non-Functional Requirement
+                        and only exceptionally a premise alone, and a decision finding no
+                        requirement to name reveals a missing one rather than a needless reference.
                     value: list([[NR.*]], [[PREMISE:*]])
-                    optional: true
                 -   name: AFFECTS
                     desc: >
                         Comma-separated references to the objects of the DATA, APIS, UXUI, or ARCH
@@ -4014,6 +4093,11 @@
         or fail, and many test cases (e.g. of Non-Functional Requirements or of cross-session rules)
         have no use case counterpart at all.
     optional: true
+    coverage:
+        -   "[[USE-CASE:*]]"
+        -   "[[SCENARIO:*]]"
+        -   "[[REQUIREMENT:*]]"
+        -   "[[RULE:*]]"
     refs: >
         -   ISO/IEC/IEEE 29119-3:2021: Software and systems engineering -- Software testing -- Part 3: Test documentation (2021),
             https://www.iso.org/standard/79429.html

package/dst/specbook-parse-semantic.js

@@ -5,6 +5,7 @@
 */
 import { referenceRegex, resolveUnique, resolveSet, chainOf, plainText, assignId } from "./specbook-link.js";
 import { compileValueExpr, splitItems, anchored } from "./specbook-parse-value.js";
+import { referencedCoverage } from "./specbook-coverage.js";
 /*  the syntax of a value consisting of exactly one Wiki-style reference  */
 const singleReferenceRegex = /^\[\[([^[\]]+)\]\]$/;
 /*  match a full property value directly against a value expression
@@ -431,50 +432,13 @@ const checkRelations = (ctx, schemas) => {
     of the flag's reference patterns, itself or through an ancestor, while
     the references from within the subtree of the object itself do not
     count (a lapse is a warning only, as the specification stays valid)  */
-const checkReferenced = (ctx, specification, schemas) => {
-    /*  collect the referencing objects of every referenced object
-        (the references from within its own subtree excluded)  */
-    const referrers = new Map();
-    const walk = (object) => {
-        const chain = chainOf(ctx.linkIndex, object);
-        const texts = [object.name, ...object.properties.map((p) => p.value)];
-        if (object.description !== undefined)
-            texts.push(object.description.description, object.description.rationale ?? "");
-        for (const text of texts)
-            for (const m of plainText(text).matchAll(referenceRegex)) {
-                const target = resolveUnique(ctx.linkIndex, m[1].trim(), object).target;
-                if (target !== undefined && !chain.includes(target))
-                    referrers.set(target, (referrers.get(target) ?? new Set()).add(object));
-            }
-        object.children.forEach(walk);
-    };
-    for (const artifact of specification.artifacts)
-        artifact.objects.forEach(walk);
-    /*  resolve the reference patterns of every flagged kind into the
-        admissible referencing objects (once per shared schema node)  */
-    const sources = new Map();
-    for (const [object, schema] of schemas) {
-        if (schema.referenced === undefined)
-            continue;
-        let admissible = sources.get(schema);
-        if (admissible === undefined) {
-            admissible = new Set();
-            for (const entry of schema.referenced) {
-                const expr = compileValueExpr(entry);
-                if (expr.kind === "reference")
-                    for (const source of resolveSet(ctx.linkIndex, expr.pattern))
-                        admissible.add(source);
-            }
-            sources.set(schema, admissible);
-        }
-        const covered = Array.from(referrers.get(object) ?? [])
-            .some((referrer) => chainOf(ctx.linkIndex, referrer).some((o) => admissible.has(o)));
-        if (!covered) {
+const checkReferenced = (ctx, schemas) => {
+    for (const { schema, uncovered } of referencedCoverage(ctx.linkIndex, schemas))
+        for (const object of uncovered) {
             const meta = ctx.metaOf(object);
             ctx.diagnose(meta.file, meta.line, `${object.kind} "${object.name}" is not referenced from any object matching ` +
-                schema.referenced.map((entry) => `"${entry}"`).join(" or "), "warning");
+                (schema.referenced ?? []).map((entry) => `"${entry}"`).join(" or "), "warning");
         }
-    }
 };
 /*  validate the parsed specification against the configuration  */
 export const validate = (ctx, specification, config) => {
@@ -527,7 +491,7 @@ export const validate = (ctx, specification, config) => {
         been validated on its own  */
     checkRelations(ctx, schemas);
     checkAutomata(ctx, schemas);
-    checkReferenced(ctx, specification, schemas);
+    checkReferenced(ctx, schemas);
     /*  order the artifacts exactly along the schema definition  */
     specification.artifacts.sort((a, b) => (position.get(a) ?? config.length) - (position.get(b) ?? config.length));
 };

package/dst/specbook-parse.d.ts

@@ -2,7 +2,7 @@ import { Spec } from "./specbook-format-spec.js";
 import { type Schema } from "./specbook-format-schema.js";
 import { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
 export { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
-export { resolveArtifact } from "./specbook-parse-semantic.js";
+export { resolveArtifact, collectSchemas } from "./specbook-parse-semantic.js";
 export declare const parseSpecification: (sources: SourceFile[], config?: Schema) => ParseResult;
 export declare const specStatistics: (specification: Spec) => {
     objects: number;

package/dst/specbook-parse.js

@@ -10,7 +10,7 @@ import { ParseContext } from "./specbook-parse-common.js";
 import { parseFile } from "./specbook-parse-syntax.js";
 import { validate, validateReferences } from "./specbook-parse-semantic.js";
 import { validateDiagrams } from "./specbook-diagram.js";
-export { resolveArtifact } from "./specbook-parse-semantic.js";
+export { resolveArtifact, collectSchemas } from "./specbook-parse-semantic.js";
 /*  parse a set of specification Markdown files into the specification
     AST and optionally validate the result against a configuration  */
 export const parseSpecification = (sources, config) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.5",
+    "version":                             "1.2.6",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",