@rse/specbook 1.2.1 → 1.2.3

package/README.md

@@ -70,7 +70,8 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 -   **HTML Export for Developers**:
     The HTML export is a self-contained single document with a
     table-of-contents (also as a slide-in side panel for quick navigation),
-    full-text search, embedded images, and a light/dark
+    full-text search, embedded images, a scroll progress meter (which
+    also scrolls back to the top on click), and a light/dark
     theme toggle. It is intended for the day-to-day online reading during
     development. The HTML export can map all object kinds to nested
     sections or compact tables, or an automatic mixture which collapses
@@ -140,6 +141,7 @@ export class SpecBook {
         basedir?: string,
         formats?: ExportFormat[],
         realtime?: boolean,
+        outputs?: string[],        /*  paths "onExport" writes, refused if observed  */
         onExport: (buffers: Buffer[]) => void | Promise<void>
     }): Promise<void>
 
@@ -357,7 +359,9 @@ Options:
     silent for one second. A failed re-export is reported and leaves the
     observe loop intact, so a transiently invalid specification does not
     end the watch. The outputs have to be regular files, as `-` (stdout)
-    cannot receive a repeated export.
+    cannot receive a repeated export, and none of them may be an observed
+    source file itself, as its own write would re-trigger the observation
+    endlessly.
 
 -   `-a|--addr <ip-addr>`, `-p|--port <tcp-port>` (`preview` only):
     The IP address (default: `127.0.0.1`) and TCP port (default: `12345`)

package/dst/specbook-api.d.ts

@@ -47,6 +47,7 @@ export declare class SpecBook {
         basedir?: string;
         formats?: ExportFormat[];
         realtime?: boolean;
+        outputs?: string[];
         onExport: (buffers: Buffer[]) => void | Promise<void>;
     }): Promise<void>;
     preview(options: {

package/dst/specbook-api.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { glob } from "glob";
-import { loadConfig } from "./specbook-config.js";
+import { loadConfig, configStatistics } from "./specbook-config.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
@@ -69,6 +69,9 @@ export class SpecBook {
         if (config === undefined)
             throw new Error("invalid configuration:\n" +
                 diagnostics.map(renderDiagnostic).join("\n"));
+        const stats = configStatistics(config);
+        verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
+            `and ${literal(stats.links)} link relationship(s)`);
         return config;
     }
     /*  initialize the configured specification artifact files
@@ -112,8 +115,9 @@ export class SpecBook {
             export fail before the specification is even parsed  */
         if (requested.includes("pdf"))
             await requireBrowser(verbose);
-        return this.renderFormats(lint({ config: await this.configFiles(options.config),
-            basedir: options.basedir ?? ".", verbose }), requested, verbose, options.realtime === true);
+        const result = lint({ config: await this.configFiles(options.config),
+            basedir: options.basedir ?? ".", verbose });
+        return this.renderFormats(result, requested, verbose, options.realtime === true);
     }
     /*  keep an export in sync with its sources (the shared core of
         "watch" and "preview"): every change of a configuration file, of an
@@ -132,6 +136,14 @@ export class SpecBook {
                 observed, too, so a failing export (even one due to an
                 invalid configuration) still keeps the observe loop fed  */
             const result = lint({ config, basedir: options.basedir ?? ".", verbose });
+            const files = [...config.map((file) => path.resolve(file)), ...result.files];
+            /*  an output which is itself an observed source would re-trigger
+                the observation with its own write and hence feed an endless
+                re-export loop, so refuse it before it is ever written  */
+            const collision = options.outputs?.find((output) => files.includes(path.resolve(output)));
+            if (collision !== undefined)
+                throw new Error(`the output "${collision}" is an observed source file, ` +
+                    "which would re-trigger the observation endlessly");
             try {
                 await options.onExport(await this.renderFormats(result, options.formats, verbose, options.realtime));
             }
@@ -139,11 +151,13 @@ export class SpecBook {
                 verbose("export failed: " +
                     (err instanceof Error ? err.message : String(err)), "notice");
             }
-            return [...config.map((file) => path.resolve(file)), ...result.files];
+            return files;
         }, verbose);
     }
     /*  export the specification like "export" and then keep the export
-        in sync with its sources (see "observe")  */
+        in sync with its sources (see "observe"), where "outputs" names the
+        files "onExport" writes, so an output which is itself an observed
+        source can be refused  */
     async watch(options) {
         const verbose = this.verboseOf("export");
         const requested = options.formats ?? ["json"];

package/dst/specbook-cli.js

@@ -148,7 +148,7 @@ withCommonOptions(program.command("export"))
     };
     if (opts.watch)
         await specbook.watch({ config: configOf(opts), basedir: opts.basedir,
-            formats: distinct, onExport: write });
+            formats: distinct, outputs: outputs.map(({ output }) => output), onExport: write });
     else
         await write(await specbook.export({ config: configOf(opts), basedir: opts.basedir,
             formats: distinct }));

package/dst/specbook-cmd-describe.js

@@ -78,13 +78,13 @@ const schemaSection = (config, schema, embed, standard, compress) => {
     yaml = compressYaml(yaml, compress);
     return textframe(`
         The **SpecBook SCHEMA Model** is the following YAML schema configuration:
-    `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n\n";
+    `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n";
 };
 /*  render the reference to the specification Markdown files  */
 const specSection = (basedir) => textframe(`
         The **SpecBook SPEC Model** is the set of Markdown specification files in directory:
         @${basedir}
-    `) + "\n";
+    `);
 /*  describe the generic SpecBook models and formats as Markdown,
     optionally extended by the references to (or the embeddings of) the
     artifacts of the particular project instantiation, and optionally

package/dst/specbook-cmd-lint.js

@@ -5,9 +5,9 @@
 */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { loadConfig } from "./specbook-config.js";
+import { loadConfig, configStatistics } from "./specbook-config.js";
 import { literal } from "./specbook-verbose.js";
-import { parseSpecification, resolveArtifact } from "./specbook-parse.js";
+import { parseSpecification, specStatistics, 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  */
@@ -30,6 +30,11 @@ export const lint = (options) => {
     const loaded = loadConfig(options.config);
     diagnostics.push(...loaded.diagnostics);
     const config = loaded.config;
+    if (config !== undefined) {
+        const stats = configStatistics(config);
+        options.verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
+            `and ${literal(stats.links)} link relationship(s)`);
+    }
     /*  read the artifact files the configuration references, resolved
         against the base directory and tolerating an absent file if all
         its artifacts are optional  */
@@ -64,6 +69,9 @@ export const lint = (options) => {
     const result = parseSpecification(sources, config);
     diagnostics.push(...result.diagnostics);
     watched.push(...result.assets);
+    const stats = specStatistics(result.specification);
+    options.verbose(`parsed specification defining ${literal(stats.objects)} object(s) ` +
+        `and ${literal(stats.links)} link relationship(s)`);
     /*  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

@@ -5,29 +5,32 @@
 */
 import Fastify from "fastify";
 import fastifyWebsocket from "@fastify/websocket";
+import { renderPlaceholder } from "./specbook-export-html.js";
 import { literal } from "./specbook-verbose.js";
 /*  the default listening address and port of the preview server  */
 export const previewAddr = "127.0.0.1";
 export const previewPort = 12345;
 /*  serve the live HTML preview: a plain GET on "/" answers with the
-    most recent HTML export (or with 503 before the first successful
-    one), while a WebSocket upgrade on "/" subscribes the client to the
-    "RELOAD" command every fresh export broadcasts  */
+    most recent HTML export (or with the 503 placeholder page before the
+    first successful one), while a WebSocket upgrade on "/" subscribes
+    the client to the "RELOAD" command every fresh export broadcasts  */
 export const servePreview = async (options) => {
     let html;
     const clients = new Set();
     const fastify = Fastify();
     await fastify.register(fastifyWebsocket);
+    /*  the placeholder page answering a GET before the first successful
+        export: it still carries the live preview client, so the browser
+        subscribes to the "RELOAD" command right away and replaces itself
+        with the document once the first export arrives  */
+    const placeholder = renderPlaceholder("no specification export available yet");
     /*  answer a plain GET with the document and subscribe a WebSocket upgrade  */
     fastify.route({
         method: "GET",
         url: "/",
         handler: (_request, reply) => {
-            if (html === undefined)
-                return reply.code(503).type("text/plain; charset=utf-8")
-                    .send("no specification export available yet\n");
-            return reply.type("text/html; charset=utf-8")
-                .header("cache-control", "no-store").send(html);
+            reply.type("text/html; charset=utf-8").header("cache-control", "no-store");
+            return html === undefined ? reply.code(503).send(placeholder) : reply.send(html);
         },
         wsHandler: (socket, request) => {
             /*  identify the client by its remote address and port  */
@@ -53,7 +56,7 @@ export const servePreview = async (options) => {
     options.verbose(`listening on ${literal(url)}`, "notice");
     return {
         update: (buffer) => {
-            /*  the first export turns the 503 answers into the document  */
+            /*  the first export turns the 503 placeholder into the document  */
             if (html === undefined)
                 options.verbose(`serving ${literal(url)}`, "notice");
             html = buffer;

package/dst/specbook-config.d.ts

@@ -1,5 +1,9 @@
 import { Schema } from "./specbook-format-schema.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
+export declare const configStatistics: (config: Schema) => {
+    objects: number;
+    links: number;
+};
 export declare const loadConfig: (files: string[]) => {
     config?: Schema;
     diagnostics: Diagnostic[];

package/dst/specbook-config.js

@@ -43,21 +43,37 @@ const identityOf = (item, list) => {
     matched by their identity, so a matching element is merged into its
     counterpart and an unmatched one is appended  */
 const mergeConfig = (target, source, list) => {
-    if (Array.isArray(target) && Array.isArray(source)) {
+    /*  an empty or comment-only YAML document carries no content at
+        all, so it leaves the target intact instead of discarding it  */
+    if (source === null || source === undefined)
+        return target;
+    else if (Array.isArray(target) && Array.isArray(source)) {
+        const items = target;
         for (const item of source) {
-            const i = target.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
+            const i = items.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
             if (i < 0)
-                target.push(item);
+                items.push(item);
             else
-                target[i] = mergeConfig(target[i], item, list);
+                items[i] = mergeConfig(items[i], item, list);
         }
-        return target;
+        return items;
     }
     else if (isPlainObject(target) && isPlainObject(source))
         return mergeWith(target, source, (t, s, key) => Array.isArray(t) && Array.isArray(s) ? mergeConfig(t, s, key) : undefined);
     else
         return source;
 };
+/*  deep copy a converted YAML document, as the conversion resolves all
+    aliases of an anchor onto one shared object, which the in-place
+    merge otherwise would alter through every alias at once  */
+const unshared = (value) => {
+    if (Array.isArray(value))
+        return value.map((item) => unshared(item));
+    else if (isPlainObject(value))
+        return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, unshared(val)]));
+    else
+        return value;
+};
 /*  determine file and line/column of a path into the merged
     configuration by translating the path into every document (from the
     last to the first one, as a later document overrides an earlier one),
@@ -75,7 +91,10 @@ const posOfMergedPath = (docs, merged, path) => {
         for (const segment of path) {
             const key = typeof segment === "number" && Array.isArray(own) ?
                 own.findIndex((item) => identityOf(item, list) === identityOf(at(node, segment), list)) : segment;
-            if (typeof key === "number" ? !Array.isArray(own) || key < 0 : !isPlainObject(own) || !(key in own))
+            const reaches = typeof key === "number" ?
+                Array.isArray(own) && key >= 0 :
+                isPlainObject(own) && key in own;
+            if (!reaches)
                 break;
             translated.push(key);
             node = at(node, segment);
@@ -227,6 +246,25 @@ const checkConstraints = (config, posOfPath) => {
     check(config, [], 1);
     return diagnostics;
 };
+/*  the statistics of a schema configuration: the number of specified
+    object kinds (recursively) and of relationship kinds, i.e. the
+    reference-valued properties (whose expressions are valid, as the
+    configuration is validated before use)  */
+export const configStatistics = (config) => {
+    let objects = 0;
+    let links = 0;
+    const walk = (object) => {
+        objects++;
+        for (const prop of object.props ?? [])
+            if (prop.value !== undefined && admitsReferences(compileValueExpr(prop.value)))
+                links++;
+        for (const child of object.childs ?? [])
+            walk(child);
+    };
+    for (const object of config)
+        walk(object);
+    return { objects, links };
+};
 /*  load and validate the YAML schema configuration, merged in order out
     of its files (the later ones into the earlier ones), where every file
     has to be readable and syntactically valid on its own, while the
@@ -267,10 +305,10 @@ export const loadConfig = (files) => {
     }
     if (diagnostics.length > 0)
         return { diagnostics };
-    /*  merge the documents in order, out of fresh conversions, as the
-        merge mutates its target while the raw ones have to stay intact
-        for the path translation  */
-    const merged = docs.map(({ doc }) => doc.toJS())
+    /*  merge the documents in order, out of unshared deep copies of
+        the conversions, as the merge mutates its target while the raw
+        ones have to stay intact for the path translation  */
+    const merged = docs.map(({ raw }) => unshared(raw))
         .reduce((target, source) => mergeConfig(target, source));
     /*  semantically validate the merged result against the schema of the configuration  */
     const posOfPath = (path) => posOfMergedPath(docs, merged, path);

package/dst/specbook-diagram.js

@@ -5,7 +5,7 @@
 */
 import { Gradia } from "@rse/gradia";
 import { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths, expandReferences, plainText } from "./specbook-link.js";
-import { collectSchemas } from "./specbook-parse-semantic.js";
+import { collectSchemas, collectParenProps } from "./specbook-parse-semantic.js";
 import { literal } from "./specbook-verbose.js";
 /*  the single Wiki-style reference match (the non-global sibling of
     the imported, global "referenceRegex")  */
@@ -29,12 +29,19 @@ const configValue = (value) => {
     const text = String(value).replace(/\s+/g, " ").trim();
     return /^[^\s"]+$/.test(text) ? text : quoted(text);
 };
+/*  the properties of an object, the synthetic one included  */
+const propsOf = (parenProps, object) => {
+    const synthetic = parenProps.get(object);
+    return synthetic !== undefined ? [...object.properties, synthetic] : object.properties;
+};
+/*  the value of a single property of an object, by its key  */
+const propValue = (parenProps, object, key) => propsOf(parenProps, object).find((property) => property.key === key)?.value;
 /*  generate the Gradia spec text of a derived diagram, opened by a
     "#type" directive and the configured "#config" directives so every
     embedded spec is self-contained: one node statement per object (the
     unique anchor path as the node id, the object name as the displayed
     label) and one edge statement per derived edge  */
-const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, anchors) => {
+const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, anchors, parenProps) => {
     const lines = [`#type ${type}`];
     const config = diagram.config ?? {};
     for (const [key, value] of Object.entries(config))
@@ -58,7 +65,7 @@ const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, ancho
             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) => property.key === key)?.value;
+            const value = propValue(parenProps, node, key);
             if (value !== undefined) {
                 const text = expandReferences(value, (reference) => resolveUnique(index, reference, node).target?.name ?? reference);
                 attrs.push(`${atom(key)}: ${atom(plainText(text))}`);
@@ -84,7 +91,7 @@ const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, ancho
     property key when "labeled", and for a "deep" diagram also of their
     descendants, with every target lifted to its nearest node and the
     reference count as the arity)  */
-const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents) => {
+const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents, parenProps) => {
     const edges = new Array();
     /*  lift an object to its nearest ancestor-or-self within the
         node set, as a "deep" diagram attributes the references of
@@ -109,7 +116,7 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents)
         walk(node);
         const counts = new Map();
         for (const object of objects) {
-            const texts = object.properties.map((property) => ({
+            const texts = propsOf(parenProps, object).map((property) => ({
                 text: property.value,
                 name: diagram.labeled === true ? property.key.toLowerCase() : undefined
             }));
@@ -141,15 +148,15 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents)
     convention (source: parent object, target: first reference in the
     property values, name: object name, arity: "ARITY" property),
     overridable via "edgeSource"/"edgeTarget"/"edgeArity"  */
-const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, errors) => {
+const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, parenProps, errors) => {
     const edges = new Array();
     /*  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)
+            propValue(parenProps, edgeObject, key) :
+            propsOf(parenProps, edgeObject).filter((property) => property.key !== diagram.edgeSource)
                 .map((property) => property.value).find((v) => referenceOnce.test(v));
         const reference = value?.match(referenceOnce)?.[1].trim();
         return reference !== undefined ? resolveUnique(index, reference, edgeObject).target : undefined;
@@ -170,7 +177,7 @@ const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, errors
         }
         if (!nodeSet.has(source) || !nodeSet.has(target))
             continue;
-        const arity = edgeObject.properties.find((property) => property.key === (diagram.edgeArity ?? "ARITY"))?.value;
+        const arity = propValue(parenProps, edgeObject, diagram.edgeArity ?? "ARITY");
         edges.push({ source, target, name: plainText(edgeObject.name),
             arity: arity !== undefined ? plainText(arity) : undefined });
     }
@@ -180,11 +187,11 @@ const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, errors
     objects, the object edges of the edge objects, and the containment
     edges of the object hierarchy (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 deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, parenProps, errors) => {
     const edges = new Array();
     if (type !== "grid") {
-        edges.push(...deriveReferenceEdges(diagram, nodes, nodeSet, index, anchors, parents));
-        edges.push(...deriveObjectEdges(diagram, nodeSet, edgeObjects, index, parents, errors));
+        edges.push(...deriveReferenceEdges(diagram, nodes, nodeSet, index, anchors, parents, parenProps));
+        edges.push(...deriveObjectEdges(diagram, nodeSet, edgeObjects, index, parents, parenProps, errors));
         /*  derive the containment edges from the object hierarchy, as
             the nesting of the objects carries no "[[...]]" reference  */
         if (diagram.hierarchy === true)
@@ -206,9 +213,12 @@ const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors,
         if (diagram.onlyConnected === true)
             errors.push({ reason: "\"grid\" diagram cannot carry an \"onlyConnected\" configuration" });
     }
-    /*  deduplicate the edges (a containment or object edge can coincide
-        with a reference edge, and several edge objects can describe
-        the very same edge)  */
+    return edges;
+};
+/*  deduplicate the edges (a containment, object, or center edge can
+    coincide with a reference edge, and several edge objects can
+    describe the very same edge)  */
+const dedupEdges = (edges, anchors) => {
     const seenEdges = new Set();
     return edges.filter((edge) => {
         const key = `${anchors.get(edge.source) ?? edge.source.id}` +
@@ -253,7 +263,7 @@ const resolvePatterns = (index, errors, value, field) => {
     itself, e.g., is no specification object, yet a context
     diagram places it in the middle) and injected into the node
     set (the center is absent whenever the configuration is invalid)  */
-const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, errors) => {
+const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, parenProps, errors) => {
     if (typeof diagram.center === "string" && diagram.center !== "self") {
         const reference = diagram.center.match(referenceOnce)?.[1].trim();
         const resolved = reference !== undefined ? resolveUnique(index, reference, object) : undefined;
@@ -283,7 +293,7 @@ const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, errors) =
             }
             centerUrl = `#${anchors.get(source) ?? source.id}`;
             if (centerCfg.property !== undefined) {
-                const value = source.properties.find((property) => property.key === centerCfg.property)?.value;
+                const value = propValue(parenProps, source, centerCfg.property);
                 if (value === undefined) {
                     errors.push({ reason: `diagram "center" source lacks the property "${centerCfg.property}"` });
                     return undefined;
@@ -312,12 +322,12 @@ const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, errors) =
     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)  */
-const deriveCenterEdges = (cfg, nodes, center, index, errors) => {
+const deriveCenterEdges = (cfg, nodes, center, index, parenProps, errors) => {
     const edges = new Array();
     for (const node of nodes) {
         if (node === center)
             continue;
-        const value = node.properties.find((property) => property.key === cfg.property)?.value;
+        const value = propValue(parenProps, node, cfg.property);
         const inbound = cfg.inbound !== undefined && value === cfg.inbound;
         const outbound = cfg.outbound !== undefined && value === cfg.outbound;
         const both = cfg.both !== undefined && value === cfg.both;
@@ -328,7 +338,7 @@ const deriveCenterEdges = (cfg, nodes, center, index, errors) => {
             continue;
         }
         const label = cfg.labeled !== undefined ?
-            node.properties.find((property) => property.key === cfg.labeled)?.value : undefined;
+            propValue(parenProps, node, cfg.labeled) : undefined;
         const name = label !== undefined ? plainText(expandReferences(label, (reference) => resolveUnique(index, reference, node).target?.name ?? reference)) : undefined;
         if (inbound || both)
             edges.push({ source: node, target: center, name });
@@ -340,7 +350,7 @@ const deriveCenterEdges = (cfg, nodes, center, index, errors) => {
 /*  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 deriveDiagram = (object, diagram, index, anchors, parents, parenProps) => {
     const type = diagram.type ?? "graph";
     const errors = new Array();
     /*  determine the node objects (default: the current object plus
@@ -361,8 +371,8 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
     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);
+    /*  derive the edges of the diagram  */
+    let edges = deriveEdges(diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, parenProps, errors);
     /*  determine the center of a "hub" diagram (the only shape
         carrying a center at all)  */
     if (type !== "hub") {
@@ -372,14 +382,17 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
             errors.push({ reason: `"${type}" diagram cannot carry a "centerEdges" configuration` });
     }
     const derived = type === "hub" ?
-        deriveCenter(object, diagram, nodes, nodeSet, index, anchors, errors) : { center: object };
+        deriveCenter(object, diagram, nodes, nodeSet, index, anchors, parenProps, errors) : { center: object };
     if (derived === undefined)
         return { errors };
     const { center, centerUrl } = derived;
     /*  synthesize the center edges of a "hub" diagram, as the nodes
-        carry no "[[...]]" reference to a synthetic center  */
+        carry no "[[...]]" reference to a synthetic center, and only
+        then deduplicate all edges, as a center edge of a real center
+        can coincide with a reference edge of a node onto it  */
     if (type === "hub" && diagram.centerEdges !== undefined)
-        edges.push(...deriveCenterEdges(diagram.centerEdges, nodes, center, index, errors));
+        edges.push(...deriveCenterEdges(diagram.centerEdges, nodes, center, index, parenProps, errors));
+    edges = dedupEdges(edges, anchors);
     /*  a "hub" diagram is the hub-projection onto its center object:
         only the edges incident to the center and only the nodes
         connected through them remain, with self-loops dropped, as
@@ -415,16 +428,17 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         }
         nodes = nodes.filter((node) => connected.has(node));
     }
-    if (nodes.length === 0)
-        errors.push({ reason: "diagram yields no nodes" });
     if (errors.length > 0)
         return { errors };
-    /*  the "collapse" handling (enabled by default) silently omits 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)
+    /*  an empty node set silently omits the diagram, as a wildcard
+        "nodes" pattern legitimately matches nothing when an optional
+        kind is absent, and the "collapse" handling (enabled by default)
+        does the same for the degenerate diagram of a single node, as
+        such a diagram carries no information beyond the object itself  */
+    if (nodes.length === 0
+        || (diagram.collapse !== false && nodes.length === 1 && edges.length === 0))
         return { errors };
-    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, index, anchors),
+    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, index, anchors, parenProps),
         config: diagram.config, columns, errors };
 };
 /*  the memoized diagram derivations, keyed by specification, as the
@@ -442,10 +456,15 @@ export const specDiagrams = (specification, config) => {
     const parents = new Map();
     for (const node of index)
         parents.set(node.object, node.parent?.object);
+    const schemas = collectSchemas(specification, config);
+    /*  re-derive the synthetic properties of the consumed parenthesized
+        name tokens, as the derivation sees the AST alone, while the
+        parsing context holding them is long gone by export time  */
+    const parenProps = collectParenProps(schemas);
     const results = new Map();
-    for (const [object, schema] of collectSchemas(specification, config))
+    for (const [object, schema] of schemas)
         if (schema.diagram !== undefined)
-            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, parents));
+            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, parents, parenProps));
     derivations.set(specification, { config, results });
     return results;
 };
@@ -500,11 +519,11 @@ export const validateDiagrams = (ctx, specification, config) => {
                 object itself and report it just once, as a wildcard
                 "edges" pattern lets every diagram walk the very same
                 edge objects again  */
-            const meta = ctx.objectMeta.get(error.object ?? object) ?? { file: "", line: 1 };
+            const meta = ctx.metaOf(error.object ?? object);
             const message = error.object !== undefined ?
                 `invalid diagram edge on ${error.object.kind} "${error.object.name}": ${error.reason}` :
                 `invalid diagram on ${object.kind} "${object.name}": ${error.reason}`;
-            const key = `${meta.file}${meta.line}${message}`;
+            const key = `${meta.file}\u0000${meta.line}\u0000${message}`;
             if (seen.has(key))
                 continue;
             seen.add(key);