@rse/specbook 1.0.2 → 1.0.4

package/dst/specbook-link.d.ts

@@ -6,13 +6,14 @@ interface LinkNode {
     parent?: LinkNode;
 }
 export type LinkIndex = LinkNode[];
+export declare const chainOf: (index: LinkIndex, object: SpecObject) => SpecObject[];
 export interface LinkTarget {
     target?: SpecObject;
     ambiguous: boolean;
 }
 export declare const buildLinkIndex: (specification: Spec) => LinkIndex;
 export declare const resolveSet: (index: LinkIndex, reference: string) => SpecObject[];
-export declare const resolveUnique: (index: LinkIndex, reference: string) => LinkTarget;
+export declare const resolveUnique: (index: LinkIndex, reference: string, from?: SpecObject) => LinkTarget;
 export declare const anchorPaths: (index: LinkIndex) => Map<SpecObject, string>;
 export declare const expandReferences: (text: string, replace: (reference: string) => string) => string;
 export {};

package/dst/specbook-link.js

@@ -8,6 +8,25 @@ export const referenceRegex = /\[\[([^[\]]+)\]\]/g;
 /*  strip the inline code markup of a name or property value
     (preserved in the AST for rendering) for matching and labeling  */
 export const plainText = (text) => text.replace(/`/g, "");
+/*  the per-index lookup of the nodes by their objects, built lazily on
+    the first scoped resolution (as the index itself stays a plain list)  */
+const lookups = new WeakMap();
+const lookup = (index, object) => {
+    let nodes = lookups.get(index);
+    if (nodes === undefined) {
+        nodes = new Map(index.map((node) => [node.object, node]));
+        lookups.set(index, nodes);
+    }
+    return nodes.get(object);
+};
+/*  the ancestor-or-self chain of an object, root first
+    (empty for an object unknown to the index)  */
+export const chainOf = (index, object) => {
+    const chain = new Array();
+    for (let node = lookup(index, object); node !== undefined; node = node.parent)
+        chain.unshift(node.object);
+    return chain;
+};
 /*  build the resolution index over all objects of a specification  */
 export const buildLinkIndex = (specification) => {
     const index = [];
@@ -74,11 +93,30 @@ export const resolveSet = (index, reference) => {
         return true;
     }).map((node) => node.object);
 };
+/*  narrow several matches down to the ones nearest to the referencing
+    object, i.e. sharing the longest ancestor chain with it (the lexical
+    scoping rule: a match within the same parent beats one in a sibling
+    subtree, which beats one in another artifact)  */
+const nearest = (index, matches, from) => {
+    const chain = chainOf(index, from);
+    const distance = (object) => {
+        const other = chainOf(index, object);
+        let i = 0;
+        while (i < chain.length && i < other.length && chain[i] === other[i])
+            i++;
+        return i;
+    };
+    const distances = matches.map((object) => distance(object));
+    const best = Math.max(...distances);
+    return matches.filter((_, i) => distances[i] === best);
+};
 /*  resolve a reference into a unique target: a single segment tries the
     ordered variants (1) id/anchor, (2) name, (3) "KIND:name-or-id", where
-    the first variant yielding matches decides (several matches are an
-    ambiguity), while a hierarchical path resolves via its full match set  */
-export const resolveUnique = (index, reference) => {
+    the first variant yielding matches decides, while a hierarchical path
+    resolves via its full match set; several matches are narrowed down to
+    the ones nearest to the referencing object (if known) and remain an
+    ambiguity only if still more than one remains  */
+export const resolveUnique = (index, reference, from) => {
     const segments = segmentsOf(reference);
     let matches = [];
     if (segments.length === 1) {
@@ -97,6 +135,8 @@ export const resolveUnique = (index, reference) => {
     }
     else
         matches = resolveSet(index, reference);
+    if (matches.length > 1 && from !== undefined)
+        matches = nearest(index, matches, from);
     return { target: matches.length === 1 ? matches[0] : undefined, ambiguous: matches.length > 1 };
 };
 /*  derive the fully-qualified anchor path of every object: the

package/dst/specbook-mcp.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, formats, parseOutputSpec, describeFormats, describeParts, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, parseCompressLevel, version } from "./specbook-api.js";
 /*  render an error with its cause chain into a tool error result  */
 const errorResult = (err) => {
     let msg = err instanceof Error ? err.message : String(err);
@@ -15,7 +15,7 @@ const errorResult = (err) => {
         msg += `: ${cause.message}`;
     return {
         isError: true,
-        content: [{ type: "text", text: `ERROR: ${msg}` }]
+        content: [{ type: "text", text: `ERROR: ${renderVerbose(msg)}` }]
     };
 };
 /*  serve the SpecBook functionality as "specbook_<cmd>" MCP tools over stdio  */
@@ -27,8 +27,9 @@ export const serveMcp = async (verbose) => {
         description: "Initialize the configured specification artifact files below the base directory " +
             "with their frontmatter and artifact heading, skipping already existing files.",
         inputSchema: {
-            config: z.string().optional().describe("YAML schema configuration file " +
-                "(default: the bundled standard schema configuration)"),
+            config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
+                "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
+                "default: the bundled standard schema configuration)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
         }
     }, async (args) => {
@@ -47,8 +48,9 @@ export const serveMcp = async (verbose) => {
         description: "Lint the specification Markdown files the YAML schema configuration references " +
             "below the base directory against this configuration and return all diagnostics.",
         inputSchema: {
-            config: z.string().optional().describe("YAML schema configuration file " +
-                "(default: the bundled standard schema configuration)"),
+            config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
+                "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
+                "default: the bundled standard schema configuration)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
         }
     }, async (args) => {
@@ -70,8 +72,9 @@ export const serveMcp = async (verbose) => {
             "YAML, TOON, HTML, PDF, or normalized Markdown. The result is written to the output file " +
             "if an output path is given, else it is returned directly (PDF as a base64-encoded resource).",
         inputSchema: {
-            config: z.string().optional().describe("YAML schema configuration file " +
-                "(default: the bundled standard schema configuration)"),
+            config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
+                "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
+                "default: the bundled standard schema configuration)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
             format: z.enum(formats).optional().describe("output format (default: inferred from the " +
                 "output file extension, else json)"),
@@ -111,11 +114,16 @@ export const serveMcp = async (verbose) => {
             "points to the artifacts of that particular project. The description can be reduced to a " +
             "single part and emitted as the raw original file content instead of Markdown.",
         inputSchema: {
-            config: z.string().optional().describe("YAML schema configuration file " +
-                "(default: the bundled standard schema configuration, embedded verbatim)"),
+            config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
+                "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
+                "default: the bundled standard schema configuration, embedded)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files"),
             embed: z.boolean().optional().describe("embed the given YAML schema configuration instead " +
                 "of just referencing it (default: false; the bundled standard one is always embedded)"),
+            compress: z.number().int().min(0).max(3).optional().describe("compression level of the emitted " +
+                "YAML schema configuration (embedded or raw): 0 for verbatim, 1 for re-emitted with 2-space " +
+                "indentation and without comments, 2 for additionally without its \"refs\" fields, or 3 for " +
+                "additionally without its \"desc\" fields (default: 1)"),
             format: z.enum(describeFormats).optional().describe("output format: \"md\" for Markdown or " +
                 "\"raw\" for the raw original file content of the part (default: \"md\")"),
             part: z.enum(describeParts).optional().describe("document part: \"all\" for the entire " +
@@ -126,7 +134,8 @@ export const serveMcp = async (verbose) => {
         }
     }, async (args) => {
         try {
-            const text = await specbook.describe(args);
+            const text = await specbook.describe({ ...args,
+                compress: args.compress !== undefined ? parseCompressLevel(args.compress) : undefined });
             if (args.output !== undefined && args.output !== "-") {
                 await fs.promises.writeFile(args.output, text, "utf8");
                 return { content: [{ type: "text", text: `described specification format into "${args.output}"` }] };

package/dst/specbook-parse-common.d.ts

@@ -1,5 +1,5 @@
 import { type Spec, type SpecObject, type SpecProperty } from "./specbook-format-spec.js";
-import { type Diagnostic } from "./specbook-diagnostic.js";
+import { type Diagnostic, type DiagnosticSeverity } from "./specbook-diagnostic.js";
 import { type LinkIndex } from "./specbook-link.js";
 export interface SourceFile {
     file: string;
@@ -8,6 +8,7 @@ export interface SourceFile {
 export interface ParseResult {
     specification: Spec;
     diagnostics: Diagnostic[];
+    assets: string[];
 }
 export interface ObjectMeta {
     file: string;
@@ -20,7 +21,8 @@ export declare class ParseContext {
         line: number;
     }>;
     linkIndex: LinkIndex;
-    diagnose(file: string, line: number, message: string): void;
+    assets: Set<string>;
+    diagnose(file: string, line: number, message: string, severity?: DiagnosticSeverity): void;
 }
 export declare const becauseRegex: RegExp;
 export declare const embeddingRegex: RegExp;

package/dst/specbook-parse-common.js

@@ -9,9 +9,12 @@ export class ParseContext {
     objectMeta = new WeakMap();
     propMeta = new WeakMap();
     linkIndex = [];
-    /*  record a single diagnostic  */
-    diagnose(file, line, message) {
-        this.diagnostics.push({ file, line, column: 1, message });
+    /*  the resolved paths of the embedded asset files, recorded even for
+        an unreadable one, as a watching consumer has to observe it, too  */
+    assets = new Set();
+    /*  record a single diagnostic (an error, unless flagged otherwise)  */
+    diagnose(file, line, message, severity = "error") {
+        this.diagnostics.push({ file, line, column: 1, severity, message });
     }
 }
 /*  the marker separating a statement from its rationale  */

package/dst/specbook-parse-semantic.js

@@ -3,7 +3,7 @@
 **  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, plainText } from "./specbook-link.js";
+import { referenceRegex, resolveUnique, resolveSet, chainOf, plainText } from "./specbook-link.js";
 import { compileValueExpr, splitItems, anchored } from "./specbook-parse-value.js";
 /*  the syntax of a value consisting of exactly one Wiki-style reference  */
 const singleReferenceRegex = /^\[\[([^[\]]+)\]\]$/;
@@ -11,18 +11,25 @@ const singleReferenceRegex = /^\[\[([^[\]]+)\]\]$/;
     (defined for the regex and enum kinds only)  */
 const directMatches = (expr, text) => (expr.kind === "regex" && expr.regex.test(text))
     || (expr.kind === "enum" && expr.members.includes(text));
-/*  match a single list item against the alternatives of a list
-    constraint (a reference item resolves leniently, as unresolvable
-    and ambiguous ones are already reported by the reference pass)  */
-const matchAlternatives = (ctx, alternatives, item) => {
-    const rm = item.match(singleReferenceRegex);
+/*  resolve a text consisting of exactly one Wiki-style reference from
+    its carrying object (leniently, as unresolvable and ambiguous
+    references are already reported by the reference pass)  */
+const singleTarget = (ctx, object, text) => {
+    const rm = text.match(singleReferenceRegex);
+    if (rm === null)
+        return undefined;
+    const ref = rm[1].trim();
+    return { ref, target: resolveUnique(ctx.linkIndex, ref, object).target };
+};
+/*  match a single list item against the alternatives of a list constraint  */
+const matchAlternatives = (ctx, object, alternatives, item) => {
+    const single = singleTarget(ctx, object, item);
     for (const alternative of alternatives) {
         if (alternative.kind === "reference") {
-            if (rm === null)
+            if (single === undefined)
                 continue;
-            const target = resolveUnique(ctx.linkIndex, rm[1].trim()).target;
-            if (target === undefined
-                || resolveSet(ctx.linkIndex, alternative.pattern).includes(target))
+            if (single.target === undefined
+                || resolveSet(ctx.linkIndex, alternative.pattern).includes(single.target))
                 return true;
         }
         else if (alternative.kind === "tags") {
@@ -45,20 +52,32 @@ const splitPropItems = (ctx, prop, property, meta) => {
         ctx.diagnose(meta.file, meta.line, `property "${prop.name}" value "${property.value}" contains an empty item`);
     return items.filter((item) => item !== "");
 };
-/*  check a property value against the compiled value expression of its
-    configured schema property  */
-const checkPropValue = (ctx, prop, expr, property, meta) => {
+/*  check a resolved reference of a property flagged "local": the
+    referenced object has to lie below the parent object of the
+    referencing object (a top-level object has no parent, and hence
+    no locality to keep)  */
+const checkLocal = (ctx, object, prop, single, meta) => {
+    if (prop.local !== true || single?.target === undefined)
+        return;
+    const chain = chainOf(ctx.linkIndex, object);
+    const parent = chain.length >= 2 ? chain[chain.length - 2] : undefined;
+    if (parent !== undefined && !chainOf(ctx.linkIndex, single.target).includes(parent))
+        ctx.diagnose(meta.file, meta.line, `link reference "[[${single.ref}]]" of local property "${prop.name}" ` +
+            `leaves the enclosing ${parent.kind} "${parent.name}"`);
+};
+/*  check a property value of an object against the compiled value
+    expression of its configured schema property  */
+const checkPropValue = (ctx, object, prop, expr, property, meta) => {
     if (expr.kind === "reference") {
         /*  a reference constraint: the value has to be exactly one
             reference resolving into the constraint's wildcard match set  */
-        const rm = plainText(property.value).trim().match(singleReferenceRegex);
-        if (rm === null)
+        const single = singleTarget(ctx, object, plainText(property.value).trim());
+        if (single === undefined)
             ctx.diagnose(meta.file, meta.line, `property "${prop.name}" value "${property.value}" is not a single link reference`);
         else {
-            const ref = rm[1].trim();
-            const target = resolveUnique(ctx.linkIndex, ref).target;
-            if (target !== undefined && !resolveSet(ctx.linkIndex, expr.pattern).includes(target))
-                ctx.diagnose(meta.file, meta.line, `link reference "[[${ref}]]" does not match constraint "${prop.value}"`);
+            if (single.target !== undefined && !resolveSet(ctx.linkIndex, expr.pattern).includes(single.target))
+                ctx.diagnose(meta.file, meta.line, `link reference "[[${single.ref}]]" does not match constraint "${prop.value}"`);
+            checkLocal(ctx, object, prop, single, meta);
         }
     }
     else if (expr.kind === "tags") {
@@ -76,9 +95,12 @@ const checkPropValue = (ctx, prop, expr, property, meta) => {
     else if (expr.kind === "list") {
         /*  a list constraint: the value is a comma-separated list
             of items, each matching at least one alternative  */
-        for (const item of splitPropItems(ctx, prop, property, meta))
-            if (!matchAlternatives(ctx, expr.alternatives, item))
+        for (const item of splitPropItems(ctx, prop, property, meta)) {
+            if (!matchAlternatives(ctx, object, expr.alternatives, item))
                 ctx.diagnose(meta.file, meta.line, `list item "${item}" of property "${prop.name}" does not match constraint "${prop.value}"`);
+            else
+                checkLocal(ctx, object, prop, singleTarget(ctx, object, item), meta);
+        }
     }
     else if (!directMatches(expr, plainText(property.value)))
         ctx.diagnose(meta.file, meta.line, expr.kind === "enum" ?
@@ -121,7 +143,7 @@ const validateObject = (ctx, object, schema, level) => {
             if (i > 0)
                 ctx.diagnose(meta.file, line, `duplicate property "${prop.name}" on ${object.kind} "${object.name}"`);
             if (expr !== undefined)
-                checkPropValue(ctx, prop, expr, match, { file: meta.file, line });
+                checkPropValue(ctx, object, prop, expr, match, { file: meta.file, line });
         }
     }
     /*  report the properties not configured by the schema  */
@@ -139,6 +161,45 @@ const validateObject = (ctx, object, schema, level) => {
         }
         validateObject(ctx, child, childSchema, level + 1);
     }
+    /*  check the property values flagged unique for distinctness among
+        the sibling objects of the same kind and the ones flagged present
+        for occurring on at least one of the (existing) siblings (all
+        values, or only the values matching the regexp or enum expression
+        of the flag)  */
+    for (const child of childs) {
+        const siblings = object.childs.filter((c) => c.kind === child.kind);
+        for (const prop of child.props ?? []) {
+            const marker = (flag) => flag === undefined || flag === false ? undefined :
+                { filter: typeof flag === "string" ? compileValueExpr(flag) : undefined };
+            const unique = marker(prop.unique);
+            const present = marker(prop.present);
+            if (unique === undefined && present === undefined)
+                continue;
+            const seen = new Map();
+            let found = false;
+            for (const sibling of siblings) {
+                const property = findProp(sibling, prop.name);
+                if (property === undefined)
+                    continue;
+                const value = plainText(property.value).trim();
+                if (present !== undefined && (present.filter === undefined || directMatches(present.filter, value)))
+                    found = true;
+                if (unique === undefined || (unique.filter !== undefined && !directMatches(unique.filter, value)))
+                    continue;
+                const first = seen.get(value);
+                if (first === undefined)
+                    seen.set(value, sibling);
+                else {
+                    const siblingMeta = ctx.objectMeta.get(sibling) ?? { file: "", line: 1 };
+                    ctx.diagnose(siblingMeta.file, ctx.propMeta.get(property)?.line ?? siblingMeta.line, `value "${value}" of unique property "${prop.name}" on ${sibling.kind} "${sibling.name}" ` +
+                        `already used by preceding ${sibling.kind} "${first.name}"`);
+                }
+            }
+            if (present !== undefined && siblings.length > 0 && !found)
+                ctx.diagnose(meta.file, meta.line, `no ${child.kind} below ${object.kind} "${object.name}" carries property "${prop.name}"` +
+                    (typeof prop.present === "string" ? ` with a value matching "${prop.present}"` : ""));
+        }
+    }
     /*  report the configured child object kinds which are missing  */
     for (const child of childs)
         if (child.optional !== true
@@ -202,6 +263,198 @@ const checkIds = (ctx, objects) => {
         checkIds(ctx, object.childs);
     }
 };
+/*  the objects a property of an object references (resolved and
+    distinct, in document order), leniently skipping the unresolvable
+    ones, as those are already reported by the reference pass  */
+const referencedObjects = (ctx, object, name) => {
+    const property = findProp(object, name);
+    if (property === undefined)
+        return [];
+    const targets = new Array();
+    for (const m of plainText(property.value).matchAll(referenceRegex)) {
+        const target = resolveUnique(ctx.linkIndex, m[1].trim(), object).target;
+        if (target !== undefined && !targets.includes(target))
+            targets.push(target);
+    }
+    return targets;
+};
+/*  check the object kinds configured with an "automaton": the child
+    objects of the node kind form a finite state machine through the
+    child objects of the edge kind (each connecting the nodes its source
+    and target properties reference), in which every node has to be
+    reachable from an initial node, every node without outgoing edge has
+    to be a final node (else it is a dead-end), and a final node has to
+    be reachable from every node (else it is a livelock), where the
+    initial and final nodes carry the value "true" in the respective flag
+    property (a machine lacking initial or final nodes altogether skips
+    the reachability checks, as the "present" flag reports the lack)  */
+const checkAutomata = (ctx, schemas) => {
+    for (const [object, schema] of schemas) {
+        const automaton = schema.automaton;
+        if (automaton === undefined)
+            continue;
+        const nodes = object.childs.filter((child) => child.kind === automaton.nodes);
+        const nodeSet = new Set(nodes);
+        const flagged = (node, name) => {
+            const property = findProp(node, name);
+            return property !== undefined && plainText(property.value).trim() === "true";
+        };
+        const initials = nodes.filter((node) => flagged(node, automaton.initial));
+        const finals = nodes.filter((node) => flagged(node, automaton.final));
+        /*  the successors and predecessors of every node (an edge leaving
+            the node set is skipped, as the property checks report it)  */
+        const succs = new Map(nodes.map((node) => [node, new Set()]));
+        const preds = new Map(nodes.map((node) => [node, new Set()]));
+        for (const edge of object.childs.filter((child) => child.kind === automaton.edges)) {
+            const source = referencedObjects(ctx, edge, automaton.source)[0];
+            const target = referencedObjects(ctx, edge, automaton.target)[0];
+            if (source !== undefined && target !== undefined && nodeSet.has(source) && nodeSet.has(target)) {
+                succs.get(source)?.add(target);
+                preds.get(target)?.add(source);
+            }
+        }
+        /*  the transitive closure of a node set along a neighbor map  */
+        const closure = (starts, next) => {
+            const seen = new Set(starts);
+            const queue = [...starts];
+            for (let node = queue.shift(); node !== undefined; node = queue.shift())
+                for (const other of next.get(node) ?? [])
+                    if (!seen.has(other)) {
+                        seen.add(other);
+                        queue.push(other);
+                    }
+            return seen;
+        };
+        const reachable = closure(initials, succs);
+        const coreachable = closure(finals, preds);
+        for (const node of nodes) {
+            const meta = ctx.objectMeta.get(node) ?? { file: "", line: 1 };
+            const name = `${node.kind} "${node.name}" of ${object.kind} "${object.name}"`;
+            if (initials.length > 0 && !reachable.has(node))
+                ctx.diagnose(meta.file, meta.line, `${name} is not reachable from the initial ${node.kind} through any ${automaton.edges}`);
+            if ((succs.get(node)?.size ?? 0) === 0 && !finals.includes(node))
+                ctx.diagnose(meta.file, meta.line, `${name} has no outgoing ${automaton.edges} but is not flagged "${automaton.final}" (dead-end)`);
+            else if (finals.length > 0 && !coreachable.has(node))
+                ctx.diagnose(meta.file, meta.line, `${name} reaches no final ${node.kind} through any ${automaton.edges} (livelock)`);
+        }
+    }
+};
+/*  check the reference properties flagged symmetric or acyclic across
+    all objects of their kind: a symmetric property has to be referenced
+    back by every referenced object through the same property, while an
+    acyclic property must never lead from an object back to itself  */
+const checkRelations = (ctx, schemas) => {
+    /*  group the objects by their flagged schema properties (a schema
+        property is shared by all objects of its kind)  */
+    const groups = new Map();
+    for (const [object, schema] of schemas)
+        for (const prop of schema.props ?? [])
+            if (prop.symmetric === true || prop.acyclic === true)
+                groups.set(prop, [...(groups.get(prop) ?? []), object]);
+    for (const [prop, objects] of groups) {
+        const members = new Set(objects);
+        const locate = (object) => {
+            const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+            const property = findProp(object, prop.name);
+            const line = property !== undefined ? ctx.propMeta.get(property)?.line : undefined;
+            return { file: meta.file, line: line ?? meta.line };
+        };
+        if (prop.symmetric === true)
+            for (const object of objects)
+                for (const target of referencedObjects(ctx, object, prop.name)) {
+                    const { file, line } = locate(object);
+                    if (target === object)
+                        ctx.diagnose(file, line, `symmetric property "${prop.name}" on ${object.kind} "${object.name}" references itself`);
+                    else if (!referencedObjects(ctx, target, prop.name).includes(object))
+                        ctx.diagnose(file, line, `symmetric property "${prop.name}" on ${object.kind} "${object.name}" references ` +
+                            `${target.kind} "${target.name}", which does not reference it back`);
+                }
+        if (prop.acyclic === true) {
+            /*  depth-first search along the references: an edge onto an
+                object still on the current path closes a cycle, which is
+                reported once, at the object closing it, with its path
+                (objects outside the group act as leaves)  */
+            const done = new Set();
+            const path = new Array();
+            const walk = (object) => {
+                path.push(object);
+                for (const target of referencedObjects(ctx, object, prop.name)) {
+                    const at = path.indexOf(target);
+                    if (at >= 0) {
+                        const { file, line } = locate(object);
+                        const cycle = [...path.slice(at), target].map((o) => plainText(o.name)).join(" -> ");
+                        ctx.diagnose(file, line, `acyclic property "${prop.name}" on ${object.kind} "${object.name}" forms a cycle: ${cycle}`);
+                    }
+                    else if (members.has(target) && !done.has(target))
+                        walk(target);
+                }
+                path.pop();
+                done.add(object);
+            };
+            for (const object of objects)
+                if (!done.has(object))
+                    walk(object);
+        }
+    }
+};
+/*  check the object kinds flagged "referenced": every object of such a
+    kind has to be referenced from at least one object which matches one
+    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,
+        together with the parent of every object for the ancestor walk  */
+    const referrers = new Map();
+    const parents = new Map();
+    const walk = (object, chain) => {
+        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));
+            }
+        for (const child of object.childs) {
+            parents.set(child, object);
+            walk(child, [...chain, child]);
+        }
+    };
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            walk(object, [object]);
+    /*  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) => {
+            for (let o = referrer; o !== undefined; o = parents.get(o))
+                if (admissible.has(o))
+                    return true;
+            return false;
+        });
+        if (!covered) {
+            const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+            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");
+        }
+    }
+};
 /*  validate the parsed specification against the configuration  */
 export const validate = (ctx, specification, config) => {
     /*  map all objects onto their schema nodes and assign the implicit
@@ -246,16 +499,23 @@ export const validate = (ctx, specification, config) => {
             validateObject(ctx, object, schema, 1);
         }
     }
+    /*  check the relation shapes of the flagged reference properties, the
+        state machines of the configured object kinds, and the reference
+        coverage of the flagged object kinds, now that every object has
+        been validated on its own  */
+    checkRelations(ctx, schemas);
+    checkAutomata(ctx, schemas);
+    checkReferenced(ctx, specification, schemas);
     /*  order the artifacts exactly along the schema definition  */
     specification.artifacts.sort((a, b) => (position.get(a) ?? config.length) - (position.get(b) ?? config.length));
 };
-/*  validate every Wiki-style reference for unique resolvability,
-    independent of any configuration  */
+/*  validate every Wiki-style reference for unique resolvability (from
+    its carrying object), independent of any configuration  */
 export const validateReferences = (ctx, specification) => {
-    const check = (text, file, line) => {
+    const check = (object, text, file, line) => {
         for (const m of text.matchAll(referenceRegex)) {
             const ref = m[1].trim();
-            const resolution = resolveUnique(ctx.linkIndex, ref);
+            const resolution = resolveUnique(ctx.linkIndex, ref, object);
             if (resolution.ambiguous)
                 ctx.diagnose(file, line, `ambiguous link reference "[[${ref}]]"`);
             else if (resolution.target === undefined)
@@ -264,13 +524,13 @@ export const validateReferences = (ctx, specification) => {
     };
     const walk = (object) => {
         const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
-        check(object.name, meta.file, meta.line);
+        check(object, object.name, meta.file, meta.line);
         for (const property of object.properties)
-            check(property.value, meta.file, ctx.propMeta.get(property)?.line ?? meta.line);
+            check(object, property.value, meta.file, ctx.propMeta.get(property)?.line ?? meta.line);
         if (object.description !== undefined) {
-            check(object.description.description, meta.file, meta.line);
+            check(object, object.description.description, meta.file, meta.line);
             if (object.description.rationale !== undefined)
-                check(object.description.rationale, meta.file, meta.line);
+                check(object, object.description.rationale, meta.file, meta.line);
         }
         object.childs.forEach(walk);
     };

package/dst/specbook-parse-syntax.js

@@ -129,8 +129,10 @@ const embed = (ctx, object, file) => {
                 continue;
             for (const variant of embeddingVariants(reference)) {
                 target.embedding ??= [];
+                const asset = path.resolve(path.dirname(file), variant);
+                ctx.assets.add(asset);
                 try {
-                    const data = fs.readFileSync(path.resolve(path.dirname(file), variant));
+                    const data = fs.readFileSync(asset);
                     target.embedding.push(type === "image/svg+xml" ?
                         data.toString("utf8") : `data:${type};base64,${data.toString("base64")}`);
                 }

package/dst/specbook-parse-value.d.ts

@@ -16,4 +16,5 @@ export type ValueExpr = {
 };
 export declare const anchored: (pattern: string) => RegExp;
 export declare const compileValueExpr: (source: string) => ValueExpr;
+export declare const admitsReferences: (expr: ValueExpr) => boolean;
 export declare const splitItems: (text: string) => string[];