@rse/specbook 1.2.4 → 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
@@ -273,6 +279,18 @@ explicitly supplied option always wins. As `-c|--config` is repeatable,
 `SPECBOOK_CONFIG` carries a list of patterns separated by the path
 delimiter of the platform (`:` on Unix, `;` on Windows).
 
+Beyond those, the option-less `SPECBOOK_BROWSER` selects the browser
+printing the PDF export: a value carrying a path separator is taken as
+an executable path and any other one as a Playwright channel name
+(`chromium`, `chromium-headless-shell`, `chrome`, `chrome-beta`,
+`chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`,
+or `msedge-canary`). The variable itself has no default value: when it
+is unset, the downloaded Playwright Chromium is used (the equivalent of
+`chromium`) and only if that one is absent a system-installed *Google
+Chrome* (the equivalent of `chrome`). An explicitly configured browser
+failing to launch fails the export instead of falling back onto another
+browser.
+
 Example: Simple
 ---------------
 

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

@@ -40,26 +40,47 @@ const propValue = (parenProps, object, key) => propsOf(parenProps, object).find(
     "#type" directive and the configured "#config" directives so every
     embedded spec is self-contained: one node statement per object (the
     unique anchor path as the node id, the object name as the displayed
-    label) and one edge statement per derived edge  */
-const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, anchors, parenProps) => {
+    label, the container node as the parent) and one edge statement per
+    derived edge  */
+const renderSpec = (diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps) => {
     const lines = [`#type ${type}`];
     const config = diagram.config ?? {};
     for (const [key, value] of Object.entries(config))
         if (value !== undefined)
             lines.push(`#config ${key} ${configValue(value)}`);
     lines.push("");
+    /*  the explicit top-down order of an "ordered" diagram: the members
+        of a container share one row (which Gradia wraps), while the
+        top-level nodes stack in document order, a synthetic container
+        taking the position of its first member  */
+    const orderOf = (node) => {
+        if (nesting.parentOf.has(node))
+            return 0;
+        let order = positions.get(node) ?? Number.MAX_SAFE_INTEGER;
+        for (const [member, container] of nesting.parentOf)
+            if (container === node)
+                order = Math.min(order, positions.get(member) ?? order);
+        return order;
+    };
     for (const node of nodes) {
         const anchor = anchors.get(node);
         const attrs = new Array();
-        /*  a synthetic center node (the only node without an anchor
-            path) links to its source object, or nowhere at all  */
-        const url = anchor !== undefined ? `#${anchor}` : centerUrl;
+        /*  a synthetic center or container node (the only nodes without
+            an anchor path) links to its source object, or nowhere at all  */
+        const url = anchor !== undefined ? `#${anchor}` : (node === center ? centerUrl : undefined);
         if (url !== undefined)
             attrs.push(`url: ${atom(url)}`);
         if (diagram.qualified === true && node.kind !== "")
             attrs.push(`type: ${atom(node.kind)}`);
         if (type === "hub" ? node === center : node.primary === true)
             attrs.push("primary: true");
+        const container = nesting.parentOf.get(node);
+        if (container !== undefined)
+            attrs.push(`parent: ${atom(anchors.get(container) ?? container.id)}`);
+        if (diagram.nest?.layout !== undefined && nesting.containers.has(node))
+            attrs.push(`container: ${diagram.nest.layout}`);
+        if (diagram.ordered === true)
+            attrs.push(`order: ${orderOf(node)}`);
         /*  attach the values of the configured properties as Gradia
             key/value attributes (a node lacking a property is fine, as
             the node set can mix objects of different kinds), with every
@@ -89,13 +110,13 @@ const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, ancho
 /*  derive the reference edges of a diagram from the "[[...]]" references
     of the node objects (per the "links" selection, named with the
     property key when "labeled", and for a "deep" diagram also of their
-    descendants, with every target lifted to its nearest node and the
-    reference count as the arity)  */
+    descendants, with the reference count as the arity), with every
+    target lifted to its nearest node  */
 const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents, parenProps) => {
     const edges = new Array();
     /*  lift an object to its nearest ancestor-or-self within the
-        node set, as a "deep" diagram attributes the references of
-        the descendants to their nearest node object  */
+        node set, as a reference onto a descendant of a node object
+        (like the scenario of a use case) is a reference onto the node  */
     const lift = (object) => {
         while (object !== undefined && !nodeSet.has(object))
             object = parents.get(object);
@@ -127,9 +148,7 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents,
             }
             for (const { text, name } of texts)
                 for (const m of text.matchAll(referenceRegex)) {
-                    let target = resolveUnique(index, m[1].trim(), object).target;
-                    if (diagram.deep === true)
-                        target = lift(target);
+                    const target = lift(resolveUnique(index, m[1].trim(), object).target);
                     if (target !== undefined && target !== node && nodeSet.has(target)) {
                         const key = `${anchors.get(target) ?? target.id}\u0000${name ?? ""}`;
                         const entry = counts.get(key) ?? { target, name, count: 0 };
@@ -321,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) {
@@ -337,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)
@@ -347,10 +376,104 @@ const deriveCenterEdges = (cfg, nodes, center, index, parenProps, errors) => {
     }
     return edges;
 };
+/*  derive the nesting of the nodes into container nodes: per node the
+    first configured property carrying exactly one resolvable reference
+    names its container (added to the node set when absent, and nested
+    on its own in turn), else its parent object when part of the node
+    set, else a synthetic container per object kind; a node nested into
+    itself or into a cycle stays un-nested and is reported  */
+const deriveNesting = (nest, nodes, nodeSet, index, parents, parenProps, errors) => {
+    const parentOf = new Map();
+    const byKind = new Map();
+    /*  the iteration also visits the containers appended underway  */
+    for (const node of nodes) {
+        let container;
+        for (const key of nest.properties ?? []) {
+            const value = propValue(parenProps, node, key);
+            const refs = value !== undefined ? Array.from(value.matchAll(referenceRegex)) : [];
+            if (refs.length !== 1)
+                continue;
+            container = resolveUnique(index, refs[0][1].trim(), node).target;
+            if (container !== undefined)
+                break;
+        }
+        if (container === undefined && nest.parent === true) {
+            const parent = parents.get(node);
+            if (parent !== undefined && nodeSet.has(parent))
+                container = parent;
+        }
+        if (container === undefined && nest.kind === true && node.kind !== "") {
+            container = byKind.get(node.kind);
+            if (container === undefined) {
+                container = { kind: "", id: `@kind-${node.kind}`, name: node.kind, properties: [], children: [] };
+                byKind.set(node.kind, container);
+            }
+        }
+        if (container === undefined)
+            continue;
+        /*  a container chain leading back to the node would close a
+            cycle, which Gradia rejects exactly like a self-nesting  */
+        let ancestor = container;
+        while (ancestor !== undefined && ancestor !== node)
+            ancestor = parentOf.get(ancestor);
+        if (ancestor === node) {
+            errors.push({ reason: `node "${plainText(node.name)}" is nested into itself` });
+            continue;
+        }
+        parentOf.set(node, container);
+        if (!nodeSet.has(container)) {
+            nodes.push(container);
+            nodeSet.add(container);
+        }
+    }
+    return { parentOf, containers: new Set(parentOf.values()) };
+};
+/*  lift the edges crossing a container boundary onto the containers:
+    an end is replaced by its outermost ancestor container not enclosing
+    the other end as well (the target end only, or both ends), and the
+    edges coinciding afterwards merge into one, with their arities summed
+    where numeric, so a bundle of references into a container becomes a
+    single edge onto it  */
+const liftEdges = (edges, parentOf, mode, anchors) => {
+    const ancestors = (object) => {
+        const chain = new Array();
+        for (let p = parentOf.get(object); p !== undefined; p = parentOf.get(p))
+            chain.push(p);
+        return chain;
+    };
+    const lift = (end, other) => {
+        const enclosing = new Set([other, ...ancestors(other)]);
+        let lifted = end;
+        for (const ancestor of ancestors(end)) {
+            if (enclosing.has(ancestor))
+                break;
+            lifted = ancestor;
+        }
+        return lifted;
+    };
+    const merged = new Map();
+    for (const edge of edges) {
+        const target = lift(edge.target, edge.source);
+        const source = mode === "both" ? lift(edge.source, edge.target) : edge.source;
+        if (source === target)
+            continue;
+        const key = `${anchors.get(source) ?? source.id}${anchors.get(target) ?? target.id}` +
+            `${edge.name ?? ""}`;
+        const known = merged.get(key);
+        if (known === undefined)
+            merged.set(key, { source, target, name: edge.name, arity: edge.arity });
+        else if (known.arity !== undefined && edge.arity !== undefined
+            && /^\d+$/.test(known.arity) && /^\d+$/.test(edge.arity))
+            known.arity = String(Number(known.arity) + Number(edge.arity));
+        else if (known.arity !== edge.arity)
+            known.arity = undefined;
+    }
+    return Array.from(merged.values());
+};
 /*  derive the Gradia spec of a single object from its "diagram:"
     schema configuration (the returned spec is absent whenever the
     configured diagram situation is invalid)  */
-const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) => {
+const deriveDiagram = (object, diagram, index, anchors, positions, parents, parenProps) => {
     const type = diagram.type ?? "graph";
     const errors = new Array();
     /*  determine the node objects (default: the current object plus
@@ -418,15 +541,32 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
                 (edges.some((edge) => edge.source === center) ? 1 : 0);
         }
     }
+    /*  nest the nodes into container nodes (except in a "hub" diagram,
+        where every container would need a primary node of its own),
+        dropping the edges between a container and its own members,
+        which Gradia rejects, as the nesting already shows them  */
+    let nesting = { parentOf: new Map(), containers: new Set() };
+    if (diagram.nest !== undefined) {
+        if (type === "hub")
+            errors.push({ reason: "\"hub\" diagram cannot carry a \"nest\" configuration" });
+        else {
+            nesting = deriveNesting(diagram.nest, nodes, nodeSet, index, parents, parenProps, errors);
+            if (diagram.nest.crossing !== undefined && diagram.nest.crossing !== "nodes")
+                edges = liftEdges(edges, nesting.parentOf, diagram.nest.crossing, anchors);
+            edges = edges.filter((edge) => nesting.parentOf.get(edge.source) !== edge.target
+                && nesting.parentOf.get(edge.target) !== edge.source);
+        }
+    }
     /*  the "onlyConnected" filtering keeps only the nodes with at
-        least one incident edge (sensible for "graph" diagrams only)  */
+        least one incident edge (sensible for "graph" diagrams only),
+        and the container nodes, whose members connect them  */
     if (diagram.onlyConnected === true && type === "graph") {
         const connected = new Set();
         for (const edge of edges) {
             connected.add(edge.source);
             connected.add(edge.target);
         }
-        nodes = nodes.filter((node) => connected.has(node));
+        nodes = nodes.filter((node) => connected.has(node) || nesting.containers.has(node));
     }
     if (errors.length > 0)
         return { errors };
@@ -438,8 +578,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
     if (nodes.length === 0
         || (diagram.collapse !== false && nodes.length === 1 && edges.length === 0))
         return { errors };
-    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, index, anchors, parenProps),
-        config: diagram.config, columns, errors };
+    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps), config: diagram.config, columns, errors };
 };
 /*  the memoized diagram derivations, keyed by specification, as the
     lint validation and every renderer of an export derive the very
@@ -454,8 +593,11 @@ export const specDiagrams = (specification, config) => {
     const index = buildLinkIndex(specification);
     const anchors = anchorPaths(index);
     const parents = new Map();
-    for (const node of index)
+    const positions = new Map();
+    index.forEach((node, position) => {
         parents.set(node.object, node.parent?.object);
+        positions.set(node.object, position);
+    });
     const schemas = collectSchemas(specification, config);
     /*  re-derive the synthetic properties of the consumed parenthesized
         name tokens, as the derivation sees the AST alone, while the
@@ -464,7 +606,7 @@ export const specDiagrams = (specification, config) => {
     const results = new Map();
     for (const [object, schema] of schemas)
         if (schema.diagram !== undefined)
-            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, parents, parenProps));
+            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, positions, parents, parenProps));
     derivations.set(specification, { config, results });
     return results;
 };

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])));