@rse/specbook 1.2.5 → 1.2.7

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
@@ -128,17 +131,17 @@ Commands:
 
 ```bash
 $ specbook init \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>]
 
 $ specbook lint \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>]
 
 $ specbook export \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
   [-o|--output [<format>:]<output-file>] \
@@ -146,14 +149,14 @@ $ specbook export \
   [...]
 
 $ specbook preview \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
   [-a|--addr <ip-addr>] \
   [-p|--port <tcp-port>]
 
 $ specbook describe \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
   [-e|--embed] \
@@ -163,13 +166,17 @@ $ specbook describe \
   [-o|--output <output-file>]
 
 $ specbook mcp \
-  [-v|--verbose]
+  [-v|--verbose [<level>]]
 ```
 
 Options:
 
--   `-v|--verbose`:
-    Enable verbose logging of processing information to `stderr`.
+-   `-v|--verbose [<level>]`:
+    Enable verbose logging of processing information to `stderr` at the
+    given verbosity level: `0` (the default) logs the notices only, `1`
+    (the bare flag) also the regular processing information, `2` also
+    the reference coverage ratios, and `3` also the unreferenced objects
+    of a reference coverage.
 
 -   `-c|--config <schema-yaml-file>`:
     The YAML schema configuration (default: the bundled standard schema
@@ -182,7 +189,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 at verbosity level
+    `2` 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 at level `3`.
     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-api.d.ts

@@ -3,8 +3,9 @@ import { type LintResult } from "./specbook-cmd-lint.js";
 import { parseOutputSpec, formats, type ExportFormat } from "./specbook-cmd-export.js";
 import { previewAddr, previewPort } from "./specbook-cmd-preview.js";
 import { describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel, type DescribeFormat, type DescribePart, type CompressLevel } from "./specbook-cmd-describe.js";
-import { literal, renderVerbose, type Verbose, type VerboseLevel } from "./specbook-verbose.js";
-export { literal, renderVerbose, type Verbose, type VerboseLevel };
+import { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity, type Verbose, type VerboseLevel, type Verbosity } from "./specbook-verbose.js";
+export { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity };
+export { type Verbose, type VerboseLevel, type Verbosity };
 export { formats, parseOutputSpec, type ExportFormat };
 export { previewAddr, previewPort };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };

package/dst/specbook-api.js

@@ -14,9 +14,9 @@ import { lint } from "./specbook-cmd-lint.js";
 import { exportSpecification, watchSpecification, parseOutputSpec, formats, requireBrowser } from "./specbook-cmd-export.js";
 import { servePreview, previewAddr, previewPort } from "./specbook-cmd-preview.js";
 import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel } from "./specbook-cmd-describe.js";
-import { literal, renderVerbose } from "./specbook-verbose.js";
+import { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
-export { literal, renderVerbose };
+export { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity };
 export { formats, parseOutputSpec };
 export { previewAddr, previewPort };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
@@ -37,7 +37,7 @@ export class SpecBook {
     }
     /*  bind the verbose sink to a particular command  */
     verboseOf(cmd) {
-        return (msg, level = "debug") => this.verbose(cmd, msg, level);
+        return (msg, level = "notice") => this.verbose(cmd, msg, level);
     }
     /*  determine the files of the YAML schema configuration out of the
         glob patterns, in the order of the patterns and alphabetically
@@ -96,7 +96,7 @@ export class SpecBook {
             throw new Error("invalid specification:\n" +
                 result.diagnostics.map(renderDiagnostic).join("\n"));
         for (const diagnostic of result.diagnostics)
-            verbose(renderDiagnostic(diagnostic), "notice");
+            verbose(renderDiagnostic(diagnostic), "none");
         if (result.specification.artifacts.length === 0)
             throw new Error("unexportable specification: no artifacts found");
         const buffers = new Array();
@@ -149,7 +149,7 @@ export class SpecBook {
             }
             catch (err) {
                 verbose("export failed: " +
-                    (err instanceof Error ? err.message : String(err)), "notice");
+                    (err instanceof Error ? err.message : String(err)), "none");
             }
             return files;
         }, verbose);

package/dst/specbook-cli.js

@@ -8,19 +8,23 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Command, CommanderError } from "commander";
 import chalk from "chalk";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, parseVerbosity, verbosityOf, version } from "./specbook-api.js";
 import { serveMcp } from "./specbook-mcp.js";
 /*  route verbose messages to stderr, keeping stdout reserved for the
     command outputs and the MCP protocol, and qualify every message with
     the tool name plus the scope path of the emitting command, where
     Chalk styles the output only if the terminal supports colors; the
-    "notice" messages pass regardless of the verbose option, as they
+    verbosity of the verbose option gates the messages by their level,
+    so the "none" messages pass regardless of the option, as they
     report environment problems the user has to see  */
-const verboseOf = (opts, ...scope) => (cmd, msg, level) => {
-    if (opts.verbose || level === "notice") {
-        const scopePath = [...scope, cmd].map((segment) => chalk.bold(segment)).join(": ");
-        process.stderr.write(`specbook: ${scopePath}: ${renderVerbose(msg, chalk.blue)}\n`);
-    }
+const verboseOf = (opts, ...scope) => {
+    const verbosity = parseVerbosity(opts.verbose);
+    return (cmd, msg, level) => {
+        if (verbosityOf[level] <= verbosity) {
+            const scopePath = [...scope, cmd].map((segment) => chalk.bold(segment)).join(": ");
+            process.stderr.write(`specbook: ${scopePath}: ${renderVerbose(msg, chalk.blue)}\n`);
+        }
+    };
 };
 /*  write a buffer to a standard stream, awaiting the write callback
     which only fires once the data has been flushed to the underlying
@@ -41,7 +45,7 @@ const writeOutput = async (output, data, cmd, verbose) => {
         await writeStdout(data);
     else {
         await fs.promises.writeFile(output, data);
-        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`, "debug");
+        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`, "notice");
     }
 };
 /*  determine an option default value, overridable via a
@@ -56,9 +60,13 @@ const envDefaultFlag = (name, fallback) => {
     const value = process.env[`SPECBOOK_${name.toUpperCase().replace(/-/g, "_")}`];
     return value !== undefined ? !(/^(?:|0|false|no|off)$/i).test(value) : fallback;
 };
-/*  provide the verbose option of all sub-commands  */
+/*  provide the verbose option of all sub-commands, whose optional level
+    selects the verbosity (where the environment default carries a level
+    or a boolean word)  */
 const withVerboseOption = (command) => command
-    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false));
+    .option("-v, --verbose [level]", "print verbose processing information to stderr " +
+    "(0: none, 1: notices, 2: also the details like the coverage ratios, " +
+    "3: also the traces like the unreferenced objects; default: 0, bare flag: 1)", envDefault("verbose", "0"));
 /*  provide the repeatable schema configuration option, whose files or
     glob patterns are merged in order (with "std" naming the bundled
     standard one), and determine its value, where the environment default
@@ -96,7 +104,7 @@ program.name("specbook")
 withVerboseOption(program.command("mcp"))
     .description("run as MCP stdio server")
     .action(async (opts) => {
-    verboseOf(opts)("mcp", "starting MCP server on stdio", "debug");
+    verboseOf(opts)("mcp", "starting MCP server on stdio", "notice");
     await serveMcp(verboseOf(opts, "mcp"));
 });
 /*  the init command creates the configured artifact files  */
@@ -116,13 +124,13 @@ withCommonOptions(program.command("lint"))
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const result = await specbook.lint({ config: configOf(opts), basedir: opts.basedir });
     for (const diagnostic of result.diagnostics)
-        await writeStdout(opts.verbose ?
+        await writeStdout(parseVerbosity(opts.verbose) > 0 ?
             renderDiagnosticVerbose(diagnostic, process.stdout.isTTY === true) :
             `${renderDiagnostic(diagnostic)}\n`);
     if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
         process.exitCode = 1;
     else
-        verboseOf(opts)("lint", "specification valid", "debug");
+        verboseOf(opts)("lint", "specification valid", "notice");
 });
 /*  the export command parses the input once and writes every output  */
 withCommonOptions(program.command("export"))

package/dst/specbook-cmd-export.js

@@ -72,7 +72,7 @@ export const watchSpecification = async (run, verbose) => {
         "error" event would otherwise terminate the process  */
     watcher.on("error", (err) => {
         verbose("observing failed: " +
-            (err instanceof Error ? err.message : String(err)), "notice");
+            (err instanceof Error ? err.message : String(err)), "none");
     });
     /*  perform a re-export and re-synchronize the observed files  */
     const cycle = async () => {
@@ -95,7 +95,7 @@ export const watchSpecification = async (run, verbose) => {
             timer = undefined;
             chain = chain.then(cycle).catch((err) => {
                 verbose("re-export failed: " +
-                    (err instanceof Error ? err.message : String(err)), "notice");
+                    (err instanceof Error ? err.message : String(err)), "none");
             });
         }, watchDelay);
     });

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,33 @@ 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 as
+        additional figures, the unreferenced objects of the latter by
+        name as a lengthy detail (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])}` : ""), "detail");
+        }
+        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)`, "detail");
+                if (uncovered.length > 0)
+                    options.verbose(`${label(object)} leaves ${literal(uncovered.length)} ` +
+                        `"${literal(pattern)}" object(s) unreferenced: ` +
+                        uncovered.map(label).join(", "), "trace");
+            }
+    }
     /*  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-cmd-preview.js

@@ -36,16 +36,16 @@ export const servePreview = async (options) => {
             /*  identify the client by its remote address and port  */
             const addr = request.socket.remoteAddress ?? "unknown";
             const client = `${addr.includes(":") ? `[${addr}]` : addr}:${request.socket.remotePort ?? 0}`;
-            options.verbose(`client ${literal(client)} connected`, "notice");
+            options.verbose(`client ${literal(client)} connected`, "none");
             clients.add(socket);
             socket.on("close", () => {
                 clients.delete(socket);
-                options.verbose(`client ${literal(client)} disconnected`, "notice");
+                options.verbose(`client ${literal(client)} disconnected`, "none");
             });
             /*  report a failing client, as an unhandled "error" event
                 would otherwise terminate the process  */
             socket.on("error", (err) => {
-                options.verbose(`client ${literal(client)} failed: ${err.message}`, "notice");
+                options.verbose(`client ${literal(client)} failed: ${err.message}`, "none");
             });
         }
     });
@@ -53,12 +53,12 @@ export const servePreview = async (options) => {
     await fastify.listen({ host: options.addr, port: options.port });
     const host = options.addr.includes(":") ? `[${options.addr}]` : options.addr;
     const url = `http://${host}:${options.port}/`;
-    options.verbose(`listening on ${literal(url)}`, "notice");
+    options.verbose(`listening on ${literal(url)}`, "none");
     return {
         update: (buffer) => {
             /*  the first export turns the 503 placeholder into the document  */
             if (html === undefined)
-                options.verbose(`serving ${literal(url)}`, "notice");
+                options.verbose(`serving ${literal(url)}`, "none");
             html = buffer;
             options.verbose(`notifying ${literal(clients.size)} preview client(s)`);
             for (const client of clients)

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