@rse/specbook 0.9.5 → 0.9.7

package/dst/specbook-cmd-lint.d.ts

@@ -1,15 +1,14 @@
 import { type Diagnostic } from "./specbook-diagnostic.js";
-import { type Specification } from "./specbook-struct-spec.js";
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type Spec } from "./specbook-format-spec.js";
+import { type Schema } from "./specbook-format-schema.js";
 export interface LintOptions {
-    config?: string;
+    config: string;
     basedir: string;
     verbose: (msg: string) => void;
 }
 export interface LintResult {
-    specification: Specification;
+    specification: Spec;
     diagnostics: Diagnostic[];
-    config?: SchemaSpecification;
+    config?: Schema;
 }
-export declare const scanMarkdown: (basedir: string) => string[];
 export declare const lint: (options: LintOptions) => LintResult;

package/dst/specbook-cmd-lint.js

@@ -6,43 +6,80 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadConfig } from "./specbook-config.js";
-import { parseSpecification } from "./specbook-parse.js";
-/*  recursively scan a base directory for Markdown files  */
-export const scanMarkdown = (basedir) => fs.readdirSync(basedir, { recursive: true, withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
-    .map((entry) => path.join(entry.parentPath, entry.name))
-    .sort();
+import { literal } from "./specbook-verbose.js";
+import { parseSpecification, resolveArtifact } from "./specbook-parse.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  */
+const schemaFiles = (config) => {
+    const files = new Map();
+    for (const artifact of config) {
+        if (artifact.file === undefined)
+            continue;
+        files.set(artifact.file, (files.get(artifact.file) ?? true) && artifact.optional === true);
+    }
+    return files;
+};
 /*  lint the specification Markdown files below the base directory
-    against the optional configuration  */
+    against the configuration  */
 export const lint = (options) => {
     const diagnostics = new Array();
-    /*  load the optional YAML schema configuration  */
-    let config;
-    if (options.config !== undefined) {
-        options.verbose(`loading configuration "${options.config}"`);
-        const loaded = loadConfig(options.config);
-        diagnostics.push(...loaded.diagnostics);
-        config = loaded.config ?? undefined;
-    }
-    /*  parse and validate the specification Markdown files  */
-    const exists = fs.existsSync(options.basedir) && fs.statSync(options.basedir).isDirectory();
-    const files = exists ? scanMarkdown(options.basedir) : [];
-    options.verbose(`parsing ${files.length} specification file(s) below "${options.basedir}"`);
-    if (files.length === 0)
-        diagnostics.push({ file: options.basedir, line: 1, column: 1,
-            message: exists ? "no Markdown files found below base directory" :
-                "base directory does not exist" });
+    /*  load the mandatory YAML schema configuration  */
+    options.verbose(`loading configuration "${literal(options.config)}"`);
+    const loaded = loadConfig(options.config);
+    diagnostics.push(...loaded.diagnostics);
+    const config = loaded.config;
+    /*  read the artifact files the configuration references, resolved
+        against the base directory and tolerating an absent file if all
+        its artifacts are optional  */
+    const files = config !== undefined ? schemaFiles(config) : new Map();
+    if (config !== undefined && files.size === 0)
+        diagnostics.push({ file: options.config, line: 1, column: 1,
+            message: "no artifact files configured" });
     const sources = new Array();
-    for (const file of files) {
+    const present = new Set();
+    for (const [name, optional] of files) {
+        const file = path.join(options.basedir, name);
+        if (!fs.existsSync(file)) {
+            if (!optional)
+                diagnostics.push({ file, line: 1, column: 1,
+                    message: "missing artifact file" });
+            continue;
+        }
         try {
             sources.push({ file, text: fs.readFileSync(file, "utf8") });
+            present.add(name);
         }
         catch (err) {
             diagnostics.push({ file, line: 1, column: 1,
                 message: `unreadable file: ${err instanceof Error ? err.message : String(err)}` });
         }
     }
+    /*  parse and validate the artifact files against the configuration  */
+    options.verbose(`parsing ${literal(sources.length)} specification file(s) ` +
+        `below "${literal(options.basedir)}"`);
     const result = parseSpecification(sources, config);
     diagnostics.push(...result.diagnostics);
+    /*  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  */
+    if (config !== undefined) {
+        const found = new Set();
+        for (const artifact of result.specification.artifacts)
+            for (const object of artifact.objects) {
+                const schema = resolveArtifact(config, object);
+                if (schema !== undefined)
+                    found.add(schema);
+            }
+        for (const schema of config) {
+            if (schema.optional === true || found.has(schema)
+                || (schema.file !== undefined && !present.has(schema.file)))
+                continue;
+            const file = schema.file !== undefined ? path.join(options.basedir, schema.file) : options.config;
+            const paren = schema.id !== undefined ? ` (${schema.id})` : "";
+            diagnostics.push({ file, line: 1, column: 1,
+                message: `missing artifact "${schema.kind}: ${schema.name ?? ""}${paren}"` });
+        }
+    }
     return { specification: result.specification, diagnostics, config };
 };

package/dst/specbook-config.d.ts

@@ -1,6 +1,6 @@
-import { SchemaSpecification } from "./specbook-struct-schema.js";
+import { Schema } from "./specbook-format-schema.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
 export declare const loadConfig: (file: string) => {
-    config: SchemaSpecification | null;
+    config?: Schema;
     diagnostics: Diagnostic[];
 };

package/dst/specbook-config.js

@@ -4,26 +4,69 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import * as fs from "node:fs";
-import { parse as parseYaml, parseDocument, YAMLParseError } from "yaml";
+import { parseDocument, isNode, LineCounter } from "yaml";
 import * as v from "valibot";
-import { SchemaSpecification } from "./specbook-struct-schema.js";
-import { compileValueExpr } from "./specbook-parse-value.js";
-/*  determine line/column of a YAML document path via the CST  */
-const lineColOfPath = (yaml, cst, path) => {
+import { Schema } from "./specbook-format-schema.js";
+import { compileValueExpr, anchored } from "./specbook-parse-value.js";
+/*  determine line/column of a YAML document path via the node ranges
+    of the parsed document, falling back to the closest ancestor node  */
+const lineColOfPath = (doc, lines, path) => {
     for (let i = path.length; i >= 0; i--) {
-        const node = cst.getIn(path.slice(0, i), true);
-        if (typeof node === "object" && node !== null
-            && "range" in node && Array.isArray(node.range)) {
-            const start = node.range[0];
-            const lines = yaml.slice(0, start).split("\n");
-            return { line: lines.length, column: lines[lines.length - 1].length + 1 };
+        const node = doc.getIn(path.slice(0, i), true);
+        const start = isNode(node) ? node.range?.[0] : undefined;
+        if (start !== undefined) {
+            const pos = lines.linePos(start);
+            return { line: pos.line, column: pos.col };
         }
     }
     return { line: 1, column: 1 };
 };
+/*  check the constraints of a structurally valid configuration which
+    are beyond its schema: "file" fields are allowed on the first
+    (artifact) level only, property value expressions have to be
+    syntactically valid, and the names of non-artifact objects have to
+    be valid patterns (as they are compiled into regular expressions)  */
+const checkConstraints = (config, file, posOfPath) => {
+    const diagnostics = new Array();
+    const diagnose = (path, message) => {
+        const pos = posOfPath(path);
+        diagnostics.push({ file, line: pos.line, column: pos.column, message });
+    };
+    const check = (objects, path, depth) => {
+        for (const [i, object] of objects.entries()) {
+            const at = [...path, i];
+            if (depth > 1 && object.file !== undefined)
+                diagnose([...at, "file"], `"file" field is only allowed on the first (artifact) level (found on level ${depth})`);
+            for (const [j, prop] of (object.props ?? []).entries()) {
+                if (prop.value === undefined)
+                    continue;
+                try {
+                    compileValueExpr(prop.value);
+                }
+                catch (err) {
+                    diagnose([...at, "props", j, "value"], `invalid value expression "${prop.value}": ` +
+                        (err instanceof Error ? err.message : String(err)));
+                }
+            }
+            if (depth > 1 && object.name !== undefined) {
+                try {
+                    anchored(object.name);
+                }
+                catch (err) {
+                    diagnose([...at, "name"], `invalid name pattern "${object.name}": ` +
+                        (err instanceof Error ? err.message : String(err)));
+                }
+            }
+            if (object.childs !== undefined)
+                check(object.childs, [...at, "childs"], depth + 1);
+        }
+    };
+    check(config, [], 1);
+    return diagnostics;
+};
 /*  load and validate a YAML schema configuration file  */
 export const loadConfig = (file) => {
-    const diagnostics = [];
+    const diagnostics = new Array();
     /*  read the configuration file  */
     let yaml;
     try {
@@ -33,74 +76,40 @@ export const loadConfig = (file) => {
         diagnostics.push({ file, line: 1, column: 1,
             message: "cannot read configuration file: " +
                 (err instanceof Error ? err.message : String(err)) });
-        return { config: null, diagnostics };
+        return { diagnostics };
     }
-    /*  syntactically parse the YAML content  */
-    let obj;
-    try {
-        obj = parseYaml(yaml);
-    }
-    catch (err) {
-        const e = err instanceof YAMLParseError ? err : null;
-        diagnostics.push({
-            file,
-            line: e?.linePos?.[0]?.line ?? 1,
-            column: e?.linePos?.[0]?.col ?? 1,
-            message: "invalid YAML syntax: " +
-                (err instanceof Error ? err.message.replace(/:[\s\S]*$/, "") : String(err))
-        });
-        return { config: null, diagnostics };
+    /*  syntactically parse the YAML content into its document, keeping
+        the line positions for the diagnostics  */
+    const lines = new LineCounter();
+    const doc = parseDocument(yaml, { lineCounter: lines });
+    if (doc.errors.length > 0) {
+        /*  strip the position and the source snippet the YAML parser
+            appends to its message, as the diagnostic carries the
+            position itself  */
+        for (const err of doc.errors)
+            diagnostics.push({
+                file,
+                line: err.linePos?.[0].line ?? 1,
+                column: err.linePos?.[0].col ?? 1,
+                message: "invalid YAML syntax: " + err.message.replace(/ at line \d+, column \d+(?::\n[\s\S]*)?$/, "")
+            });
+        return { diagnostics };
     }
-    /*  semantically validate against the schema of the configuration
-        (the CST is parsed lazily, as it is needed for positions only)  */
-    let cst;
-    const posOfPath = (path) => {
-        cst ??= parseDocument(yaml);
-        return lineColOfPath(yaml, cst, path);
-    };
-    const result = v.safeParse(SchemaSpecification, obj);
+    const obj = doc.toJS();
+    /*  semantically validate against the schema of the configuration  */
+    const posOfPath = (path) => lineColOfPath(doc, lines, path);
+    const result = v.safeParse(Schema, obj);
     if (!result.success) {
         for (const issue of result.issues) {
             const path = (issue.path ?? []).map((item) => item.key);
             const pos = posOfPath(path);
+            const where = path.length > 0 ? `${path.join(".")}: ` : "";
             diagnostics.push({ file, line: pos.line, column: pos.column,
-                message: `invalid configuration: ${path.join(".")}: ${issue.message}` });
+                message: `invalid configuration: ${where}${issue.message}` });
         }
-        return { config: null, diagnostics };
+        return { diagnostics };
     }
-    /*  reject "file" fields below the first (artifact) level  */
-    const checkFileField = (objects, path, depth) => {
-        objects.forEach((object, i) => {
-            if (depth > 1 && object.file !== undefined) {
-                const pos = posOfPath([...path, i, "file"]);
-                diagnostics.push({ file, line: pos.line, column: pos.column,
-                    message: `"file" field is only allowed on the first (artifact) level (found on level ${depth})` });
-            }
-            if (object.childs !== undefined)
-                checkFileField(object.childs, [...path, i, "childs"], depth + 1);
-        });
-    };
-    checkFileField(result.output, [], 1);
-    /*  reject syntactically invalid property value expressions  */
-    const checkValueExpr = (objects, path) => {
-        objects.forEach((object, i) => {
-            (object.props ?? []).forEach((prop, j) => {
-                if (prop.value === undefined)
-                    return;
-                try {
-                    compileValueExpr(prop.value);
-                }
-                catch (err) {
-                    const pos = posOfPath([...path, i, "props", j, "value"]);
-                    diagnostics.push({ file, line: pos.line, column: pos.column,
-                        message: `invalid value expression "${prop.value}": ` +
-                            (err instanceof Error ? err.message : String(err)) });
-                }
-            });
-            if (object.childs !== undefined)
-                checkValueExpr(object.childs, [...path, i, "childs"]);
-        });
-    };
-    checkValueExpr(result.output, []);
-    return { config: diagnostics.length === 0 ? result.output : null, diagnostics };
+    /*  check the constraints beyond the structural schema  */
+    diagnostics.push(...checkConstraints(result.output, file, posOfPath));
+    return { config: diagnostics.length === 0 ? result.output : undefined, diagnostics };
 };

package/dst/specbook-diagnostic.js

@@ -9,7 +9,8 @@ import sourceCodeError from "source-code-error";
 export const renderDiagnostic = (diagnostic) => `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}: ${diagnostic.message}`;
 /*  render a diagnostic as a multi-line message with the affected
     source snippet, falling back to the single-line message when the
-    source file is unreadable (e.g. the file is a directory)  */
+    source file is unreadable (e.g. the file is a directory) or empty
+    (as there is no snippet to show and sourceCodeError rejects it)  */
 export const renderDiagnosticVerbose = (diagnostic, colors = false) => {
     let code;
     try {
@@ -18,6 +19,8 @@ export const renderDiagnosticVerbose = (diagnostic, colors = false) => {
     catch {
         return `${renderDiagnostic(diagnostic)}\n`;
     }
+    if (code === "")
+        return `${renderDiagnostic(diagnostic)}\n`;
     return sourceCodeError({ message: diagnostic.message, filename: diagnostic.file,
         code, line: diagnostic.line, column: diagnostic.column, colors });
 };

package/dst/specbook-diagram.d.ts

@@ -1,9 +1,10 @@
-import type { Specification, Object as SpecObject } from "./specbook-struct-spec.js";
-import type { SchemaSpecification } from "./specbook-struct-schema.js";
-import { type ParseContext } from "./specbook-parse-common.js";
+import type { Spec, SpecObject } from "./specbook-format-spec.js";
+import type { Schema, SchemaDiagram } from "./specbook-format-schema.js";
+import type { ParseContext } from "./specbook-parse-common.js";
 export interface DiagramResult {
     spec?: string;
+    config?: SchemaDiagram["config"];
     errors: string[];
 }
-export declare const specDiagrams: (specification: Specification, config: SchemaSpecification) => Map<SpecObject, DiagramResult>;
-export declare const validateDiagrams: (ctx: ParseContext, specification: Specification, config: SchemaSpecification) => void;
+export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;
+export declare const validateDiagrams: (ctx: ParseContext, specification: Spec, config: Schema) => void;

package/dst/specbook-diagram.js

@@ -3,16 +3,11 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths } from "./specbook-link.js";
+import { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths, expandReferences, plainText } from "./specbook-link.js";
+import { collectSchemas } from "./specbook-parse-semantic.js";
 /*  the single Wiki-style reference match (the non-global sibling of
     the imported, global "referenceRegex")  */
-const referenceOnce = /\[\[([^[\]]+)\]\]/;
-/*  strip the inline code markup of a name or property value
-    (preserved in the AST for rendering) for labeling purposes  */
-const plainText = (text) => text.replace(/`/g, "");
-/*  strip a trailing parenthesized annotation from a
-    property key (e.g. "WHEN (Context)")  */
-const plainKey = (key) => key.replace(/\s*\([^)]*\)\s*$/, "").trim();
+const referenceOnce = new RegExp(referenceRegex.source);
 /*  render a text as a Gradia atom: a bareword where possible
     (no whitespace, no special characters, no "--"), a quoted
     string otherwise  */
@@ -40,11 +35,9 @@ const configValue = (value) => {
 const renderSpec = (diagram, type, center, nodes, edges, index, anchors) => {
     const lines = [`#type ${type}`];
     const config = diagram.config ?? {};
-    for (const key of Object.keys(config)) {
-        const value = config[key];
+    for (const [key, value] of Object.entries(config))
         if (value !== undefined)
             lines.push(`#config ${key} ${configValue(value)}`);
-    }
     lines.push("");
     for (const node of nodes) {
         const anchor = anchors.get(node) ?? node.id;
@@ -58,12 +51,9 @@ const renderSpec = (diagram, type, center, nodes, edges, index, anchors) => {
             the node set can mix objects of different kinds), with every
             "[[...]]" reference stripped to its target object name  */
         for (const key of diagram.properties ?? []) {
-            const value = node.properties.find((property) => plainKey(property.key) === key)?.value;
+            const value = node.properties.find((property) => property.key === key)?.value;
             if (value !== undefined) {
-                const text = value.replace(referenceRegex, (_, reference) => {
-                    const target = resolveUnique(index, reference.trim()).target;
-                    return target !== undefined ? target.name : reference.trim();
-                });
+                const text = expandReferences(value, (reference) => resolveUnique(index, reference).target?.name ?? reference);
                 attrs.push(`${atom(key)}: ${atom(plainText(text))}`);
             }
         }
@@ -81,56 +71,14 @@ const renderSpec = (diagram, type, center, nodes, edges, index, anchors) => {
     }
     return lines.join("\n") + "\n";
 };
-/*  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) => {
-    const type = diagram.type ?? "graph";
-    const errors = new Array();
-    /*  resolve a comma-separated "[[...]]" reference pattern string
-        into its (deduplicated, order-preserving) object match set  */
-    const resolvePatterns = (value, field) => {
-        const matches = new Array();
-        const seen = new Set();
-        for (const m of value.matchAll(referenceRegex)) {
-            const pattern = m[1].trim();
-            const set = resolveSet(index, pattern);
-            if (set.length === 0)
-                errors.push(`unresolvable diagram "${field}" pattern "[[${pattern}]]"`);
-            for (const match of set) {
-                if (!seen.has(match)) {
-                    seen.add(match);
-                    matches.push(match);
-                }
-            }
-        }
-        return matches;
-    };
-    /*  determine the node objects (default: the current object plus
-        all objects below it) and the edge objects (default: none),
-        with the edge objects never acting as nodes themselves  */
-    let nodes;
-    if (diagram.nodes !== undefined)
-        nodes = resolvePatterns(diagram.nodes, "nodes");
-    else {
-        nodes = new Array();
-        const walk = (o) => {
-            nodes.push(o);
-            o.childs.forEach(walk);
-        };
-        walk(object);
-    }
-    const edgeObjects = diagram.edges !== undefined ? resolvePatterns(diagram.edges, "edges") : [];
-    const edgeSet = new Set(edgeObjects);
-    nodes = nodes.filter((node) => !edgeSet.has(node));
-    const nodeSet = new Set(nodes);
-    /*  derive the edges: from the "[[...]]" references of the node
-        objects (per the "links" selection) and from the edge objects by
-        convention (source: parent object, target: first reference in the
-        property values, name: object name, arity: "ARITY" property),
-        overridable via "edgeTarget"/"edgeArity" (a "grid" diagram is
-        edge-less by definition, so no edges are derived for it at all)  */
-    let edges = new Array();
+/*  derive the edges of a diagram: from the "[[...]]" references of the
+    node objects (per the "links" selection) and from the edge objects by
+    convention (source: parent object, target: first reference in the
+    property values, name: object name, arity: "ARITY" property),
+    overridable via "edgeSource"/"edgeTarget"/"edgeArity" (a "grid"
+    diagram is edge-less by definition, so no edges are derived at all)  */
+const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, errors) => {
+    const edges = new Array();
     if (type !== "grid") {
         for (const node of nodes) {
             const texts = node.properties.map((property) => property.value);
@@ -146,16 +94,25 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
                         edges.push({ source: node, target });
                 }
         }
-        for (const edgeObject of edgeObjects) {
-            const source = parents.get(edgeObject);
-            const value = diagram.edgeTarget !== undefined ?
-                edgeObject.properties.find((property) => plainKey(property.key) === diagram.edgeTarget)?.value :
-                edgeObject.properties.map((property) => property.value)
-                    .find((v) => referenceOnce.test(v));
+        /*  resolve the node an edge object references through a named
+            property, or through its first single-reference property when
+            no name is configured (skipping the source property)  */
+        const edgeNode = (edgeObject, key) => {
+            const value = key !== undefined ?
+                edgeObject.properties.find((property) => property.key === key)?.value :
+                edgeObject.properties.filter((property) => property.key !== diagram.edgeSource)
+                    .map((property) => property.value).find((v) => referenceOnce.test(v));
             const reference = value?.match(referenceOnce)?.[1].trim();
-            const target = reference !== undefined ? resolveUnique(index, reference).target : undefined;
+            return reference !== undefined ? resolveUnique(index, reference).target : undefined;
+        };
+        for (const edgeObject of edgeObjects) {
+            const source = diagram.edgeSource !== undefined ?
+                edgeNode(edgeObject, diagram.edgeSource) : parents.get(edgeObject);
+            const target = edgeNode(edgeObject, diagram.edgeTarget);
             if (source === undefined) {
-                errors.push(`diagram edge object "${edgeObject.name}" has no parent object as source`);
+                errors.push(diagram.edgeSource !== undefined ?
+                    `diagram edge object "${edgeObject.name}" carries no resolvable source reference` :
+                    `diagram edge object "${edgeObject.name}" has no parent object as source`);
                 continue;
             }
             if (target === undefined) {
@@ -164,7 +121,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
             }
             if (!nodeSet.has(source) || !nodeSet.has(target))
                 continue;
-            const arity = edgeObject.properties.find((property) => plainKey(property.key) === (diagram.edgeArity ?? "ARITY"))?.value;
+            const arity = edgeObject.properties.find((property) => property.key === (diagram.edgeArity ?? "ARITY"))?.value;
             edges.push({ source, target, name: plainText(edgeObject.name),
                 arity: arity !== undefined ? plainText(arity) : undefined });
         }
@@ -182,11 +139,13 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
             errors.push("\"grid\" diagram cannot carry an \"edges\" configuration");
         if (diagram.hierarchy === true)
             errors.push("\"grid\" diagram cannot carry a \"hierarchy\" configuration");
+        if (diagram.onlyConnected === true)
+            errors.push("\"grid\" diagram cannot carry an \"onlyConnected\" configuration");
     }
     /*  deduplicate the edges (the same reference can occur in
         multiple texts of the same node object)  */
     const seenEdges = new Set();
-    edges = edges.filter((edge) => {
+    return edges.filter((edge) => {
         const key = `${anchors.get(edge.source) ?? edge.source.id}` +
             `\u0000${anchors.get(edge.target) ?? edge.target.id}` +
             `\u0000${edge.name ?? ""}\u0000${edge.arity ?? ""}`;
@@ -195,15 +154,68 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         seenEdges.add(key);
         return true;
     });
+};
+/*  resolve a comma-separated "[[...]]" reference pattern string into
+    its (deduplicated, order-preserving) object match set, reporting
+    every unresolvable pattern as an error  */
+const resolvePatterns = (index, errors, value, field) => {
+    const matches = new Array();
+    const seen = new Set();
+    let found = false;
+    for (const m of value.matchAll(referenceRegex)) {
+        found = true;
+        const pattern = m[1].trim();
+        const set = resolveSet(index, pattern);
+        if (set.length === 0)
+            errors.push(`unresolvable diagram "${field}" pattern "[[${pattern}]]"`);
+        for (const match of set) {
+            if (!seen.has(match)) {
+                seen.add(match);
+                matches.push(match);
+            }
+        }
+    }
+    if (!found)
+        errors.push(`diagram "${field}" carries no "[[...]]" reference pattern`);
+    return matches;
+};
+/*  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) => {
+    const type = diagram.type ?? "graph";
+    const errors = new Array();
+    /*  determine the node objects (default: the current object plus
+        all objects below it) and the edge objects (default: none),
+        with the edge objects never acting as nodes themselves  */
+    let nodes;
+    if (diagram.nodes !== undefined)
+        nodes = resolvePatterns(index, errors, diagram.nodes, "nodes");
+    else {
+        nodes = new Array();
+        const walk = (o) => {
+            nodes.push(o);
+            o.childs.forEach(walk);
+        };
+        walk(object);
+    }
+    const edgeObjects = diagram.edges !== undefined ? resolvePatterns(index, errors, diagram.edges, "edges") : [];
+    const edgeSet = new Set(edgeObjects);
+    nodes = nodes.filter((node) => !edgeSet.has(node));
+    const nodeSet = new Set(nodes);
+    /*  derive the (deduplicated) edges of the diagram  */
+    let edges = deriveEdges(diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, errors);
     /*  determine the center object of a "hub" diagram: the current
         object for the default "self" configuration, the uniquely
         resolved object of an explicit "[[...]]" reference otherwise  */
     let center = object;
+    if (type !== "hub" && diagram.center !== undefined)
+        errors.push(`"${type}" diagram cannot carry a "center" configuration`);
     if (type === "hub" && diagram.center !== undefined && diagram.center !== "self") {
         const reference = diagram.center.match(referenceOnce)?.[1].trim();
         const resolved = reference !== undefined ? resolveUnique(index, reference) : undefined;
         if (resolved?.target === undefined) {
-            errors.push(`${resolved?.ambiguous === true ? "ambiguous" : "unresolvable"}` +
+            errors.push((resolved?.ambiguous === true ? "ambiguous" : "unresolvable") +
                 ` diagram "center" reference "${diagram.center}"`);
             return { errors };
         }
@@ -242,34 +254,11 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
     if (errors.length > 0)
         return { errors };
     /*  the "collapse" handling (enabled by default) silently omits a
-        degenerated diagram, consisting of a single node only, as such a
+        degenerate diagram, consisting of a single node only, as such a
         diagram carries no information beyond the object itself  */
     if (diagram.collapse !== false && nodes.length === 1 && edges.length === 0)
         return { errors };
-    return { spec: renderSpec(diagram, type, center, nodes, edges, index, anchors), errors };
-};
-/*  collect the objects whose schema configuration carries a "diagram:"
-    field (the schema resolution mirrors the semantic validation)  */
-const collectDiagrams = (specification, config) => {
-    const diagrams = new Map();
-    const walk = (object, schema) => {
-        if (schema.diagram !== undefined)
-            diagrams.set(object, schema.diagram);
-        for (const child of object.childs) {
-            const childSchema = (schema.childs ?? []).find((c) => c.kind === child.kind);
-            if (childSchema !== undefined)
-                walk(child, childSchema);
-        }
-    };
-    for (const artifact of specification.artifacts) {
-        for (const object of artifact.objects) {
-            const schema = config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
-                config.find((s) => (s.name ?? "").toUpperCase() === plainText(object.name).toUpperCase());
-            if (schema !== undefined)
-                walk(object, schema);
-        }
-    }
-    return diagrams;
+    return { spec: renderSpec(diagram, type, center, nodes, edges, index, anchors), config: diagram.config, errors };
 };
 /*  derive the Gradia specs of all diagram-configured objects
     of a specification  */
@@ -280,8 +269,9 @@ export const specDiagrams = (specification, config) => {
     for (const node of index)
         parents.set(node.object, node.parent?.object);
     const results = new Map();
-    for (const [object, diagram] of collectDiagrams(specification, config))
-        results.set(object, deriveDiagram(object, diagram, index, anchors, parents));
+    for (const [object, schema] of collectSchemas(specification, config))
+        if (schema.diagram !== undefined)
+            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, parents));
     return results;
 };
 /*  validate all configured diagrams of a specification, reporting