@rse/specbook 1.3.0 → 1.3.1

package/dst/specbook-api.d.ts

@@ -28,6 +28,17 @@ export interface ProjectOptions {
     basedir?: string;
     cwd?: string;
 }
+export interface ExportRequest extends ProjectOptions {
+    formats?: ExportFormat[];
+    realtime?: boolean;
+    omit?: string[];
+    gitignore?: boolean;
+    rebase?: (string | undefined)[];
+}
+export interface WatchRequest extends ExportRequest {
+    outputs?: string[];
+    onExport: (buffers: Buffer[]) => void | Promise<void>;
+}
 export declare class SpecBook {
     private verbose;
     constructor(options?: SpecBookOptions);
@@ -40,24 +51,10 @@ export declare class SpecBook {
         gitignore?: boolean;
     }): Promise<LintResult>;
     private renderFormats;
-    export(options: ProjectOptions & {
-        formats?: ExportFormat[];
-        realtime?: boolean;
-        omit?: string[];
-        gitignore?: boolean;
-        rebase?: (string | undefined)[];
-    }): Promise<Buffer[]>;
     private rebaseOf;
+    export(options: ExportRequest): Promise<Buffer[]>;
     private observe;
-    watch(options: ProjectOptions & {
-        formats?: ExportFormat[];
-        realtime?: boolean;
-        omit?: string[];
-        gitignore?: boolean;
-        outputs?: string[];
-        rebase?: (string | undefined)[];
-        onExport: (buffers: Buffer[]) => void | Promise<void>;
-    }): Promise<void>;
+    watch(options: WatchRequest): Promise<void>;
     preview(options: ProjectOptions & {
         addr?: string;
         port?: number;

package/dst/specbook-api.js

@@ -144,6 +144,12 @@ export class SpecBook {
         }
         return buffers;
     }
+    /*  anchor the given relative re-basing directories
+        at a given working directory  */
+    rebaseOf(options) {
+        const cwd = options.cwd;
+        return cwd === undefined ? options.rebase : options.rebase?.map((dir) => dir !== undefined ? path.resolve(cwd, dir) : dir);
+    }
     /*  export the specification Markdown files below the base directory
         as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown,
         parsing the input just once and returning one buffer per
@@ -165,12 +171,6 @@ export class SpecBook {
             basedir: project.basedir ?? ".", gitignore: options.gitignore === true, verbose });
         return this.renderFormats(result, requested, verbose, { realtime: options.realtime === true, omit }, this.rebaseOf(options));
     }
-    /*  anchor the given relative re-basing directories
-        at a given working directory  */
-    rebaseOf(options) {
-        const cwd = options.cwd;
-        return cwd === undefined ? options.rebase : options.rebase?.map((dir) => dir !== undefined ? path.resolve(cwd, dir) : dir);
-    }
     /*  keep an export in sync with its sources (the shared core of
         "watch" and "preview"): every change of a configuration file, of an
         artifact file, or of one of its embedded assets re-exports the
@@ -184,6 +184,11 @@ export class SpecBook {
         const omit = parseOmit(options.omit);
         const project = this.project(options, verbose);
         const config = await this.configFiles(project.config);
+        /*  a missing browser is an environment problem, so let the PDF
+            export fail before the specification is even parsed, but
+            after the usage problems (exactly like "export")  */
+        if (options.formats.includes("pdf"))
+            await requireBrowser(verbose);
         return watchSpecification(async () => {
             /*  the lint result carries the files to observe even for an
                 invalid specification, and the configuration files are
@@ -214,12 +219,8 @@ export class SpecBook {
         files "onExport" writes, so an output which is itself an observed
         source can be refused, and "rebase" and "omit" are the ones of "export"  */
     async watch(options) {
-        const verbose = this.verboseOf("export");
-        const requested = options.formats ?? ["json"];
-        if (requested.includes("pdf"))
-            await requireBrowser(verbose);
-        return this.observe({ ...options, formats: requested,
-            realtime: options.realtime === true }, verbose);
+        return this.observe({ ...options, formats: options.formats ?? ["json"],
+            realtime: options.realtime === true }, this.verboseOf("export"));
     }
     /*  serve the HTML export of the specification as a live preview on
         "http://<addr>:<port>/": the export is kept in sync with its
@@ -229,11 +230,24 @@ export class SpecBook {
         where "omit" is the one of "export"  */
     async preview(options) {
         const verbose = this.verboseOf("preview");
+        /*  an invalid omit aspect is a usage problem, so let the preview
+            fail before the server is even bound to its port  */
+        parseOmit(options.omit);
         const server = await servePreview({ addr: options.addr ?? previewAddr,
             port: options.port ?? previewPort, verbose });
-        return this.observe({ config: options.config, basedir: options.basedir, cwd: options.cwd,
-            formats: ["html"], realtime: true, omit: options.omit, gitignore: options.gitignore,
-            onExport: ([html]) => server.update(html) }, verbose);
+        /*  a preview which fails to start observing (an invalid project
+            configuration, an unmatched configuration pattern) releases
+            the already bound server again  */
+        try {
+            return await this.observe({ config: options.config, basedir: options.basedir, cwd: options.cwd,
+                formats: ["html"], realtime: true, omit: options.omit, gitignore: options.gitignore,
+                onExport: ([html]) => server.update(html) }, verbose);
+        }
+        catch (err) {
+            /*  a failing release must not mask the primary error  */
+            await server.close().catch(() => { });
+            throw err;
+        }
     }
     /*  describe the generic SpecBook models and formats as Markdown (or
         as the raw original file content), either entirely or reduced to
@@ -247,10 +261,12 @@ export class SpecBook {
         const project = this.project(options, verbose);
         /*  the schema-bearing parts require a schema configuration, so
             they fall back onto the bundled standard one, which is always
-            embedded, as its bundled file is no meaningful reference  */
+            embedded (also when named explicitly through "std"), as its
+            bundled file is no meaningful reference  */
         const given = project.config !== undefined;
-        const standard = !given && (part === "all" || part === "schema");
-        const config = given || standard ? await this.configFiles(project.config) : undefined;
+        const config = given || part === "all" || part === "schema" ?
+            await this.configFiles(project.config) : undefined;
+        const standard = config !== undefined && config.every((file) => file === standardConfig);
         const embed = options.embed === true || standard;
         const basedir = project.basedir ?? (part === "spec" ? "." : undefined);
         const schema = config !== undefined ? this.requireConfig(config, verbose) : undefined;

package/dst/specbook-cli.js

@@ -110,7 +110,7 @@ const omitOf = (opts) => {
     created, so they are inherited by all of them  */
 let commanderOut = "";
 let commanderErr = "";
-/*  parse the command line  */
+/*  set up the command line program  */
 const program = new Command();
 program.name("specbook")
     .description("Markdown-based Specification Format")
@@ -144,7 +144,8 @@ withCommonOptions(program.command("init"))
 withGitignoreOption(withCommonOptions(program.command("lint")))
     .description("lint the specification Markdown files below the base directory")
     .action(async (opts) => {
-    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const verbose = verboseOf(opts);
+    const specbook = new SpecBook({ verbose });
     const result = await specbook.lint({ config: configOf(opts), basedir: opts.basedir,
         gitignore: opts.gitignore });
     const detailed = parseVerbosity(opts.verbose) > 0;
@@ -155,7 +156,7 @@ withGitignoreOption(withCommonOptions(program.command("lint")))
     if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
         process.exitCode = 1;
     else
-        verboseOf(opts)("lint", "specification valid", "notice");
+        verbose("lint", "specification valid", "notice");
 });
 /*  the export command parses the input once and writes every output  */
 withOmitOption(withGitignoreOption(withCommonOptions(program.command("export"))))
@@ -205,7 +206,7 @@ withOmitOption(withGitignoreOption(withCommonOptions(program.command("preview"))
     .option("-a, --addr <ip-addr>", "IP address to listen on", envDefault("addr", previewAddr))
     .option("-p, --port <tcp-port>", "TCP port to listen on", envDefault("port", String(previewPort)))
     .action(async (opts) => {
-    const port = Number(opts.port);
+    const port = (/^\d+$/).test(opts.port) ? Number(opts.port) : NaN;
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new Error(`invalid TCP port "${opts.port}"`);
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
@@ -225,11 +226,12 @@ withBasedirOption(withConfigOption(withVerboseOption(program.command("describe")
     .option("-p, --part <part>", `document part (${describeParts.join(", ")})`, envDefault("part", "all"))
     .option("-o, --output <markdown-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
     .action(async (opts) => {
-    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const verbose = verboseOf(opts);
+    const specbook = new SpecBook({ verbose });
     const text = await specbook.describe({ config: configOf(opts), basedir: opts.basedir,
         embed: opts.embed, compress: parseCompressLevel(opts.compress),
         format: parseDescribeFormat(opts.format), part: parseDescribePart(opts.part) });
-    await writeOutput(opts.output, text, "describe", verboseOf(opts));
+    await writeOutput(opts.output, text, "describe", verbose);
 });
 /*  run the command line program  */
 try {

package/dst/specbook-cmd-describe.js

@@ -11,10 +11,11 @@ export const describeFormats = ["md", "raw"];
 export const describeParts = ["all", "meta", "schema", "spec"];
 /*  parse and validate an output format or document part specification  */
 const parseChoice = (choices, kind, value) => {
-    if (!choices.includes(value))
+    const choice = choices.find((known) => known === value);
+    if (choice === undefined)
         throw new Error(`unknown describe ${kind} "${value}" ` +
             `(supported: ${choices.join(", ")})`);
-    return value;
+    return choice;
 };
 export const parseDescribeFormat = (value) => parseChoice(describeFormats, "format", value);
 export const parseDescribePart = (value) => parseChoice(describeParts, "part", value);
@@ -25,14 +26,17 @@ export const parseDescribePart = (value) => parseChoice(describeParts, "part", v
     objects and properties (3)  */
 export const compressLevels = [0, 1, 2, 3];
 /*  parse and validate a compression level specification,
-    where a bare flag selects the plain re-emitting  */
+    where a bare flag (or a boolean word) selects the plain re-emitting  */
 export const parseCompressLevel = (value) => {
-    const level = typeof value === "boolean" ? (value ? 1 : 0) :
-        typeof value === "string" && !(/^\d+$/).test(value) ? NaN : Number(value);
-    if (!compressLevels.includes(level))
+    const text = String(value);
+    const level = (/^(?:true|yes|on)$/i).test(text) ? 1 :
+        (/^(?:false|no|off)$/i).test(text) ? 0 :
+            (/^\d+$/).test(text) ? Number(text) : NaN;
+    const compress = compressLevels.find((n) => n === level);
+    if (compress === undefined)
         throw new Error(`unknown compress level "${value}" ` +
             `(supported: ${compressLevels.join(", ")})`);
-    return level;
+    return compress;
 };
 /*  provide the build-time bundled description of the generic
     SpecBook models and formats  */

package/dst/specbook-cmd-export.js

@@ -89,6 +89,7 @@ const snapshot = (files) => {
     process alive afterwards  */
 export const watchSpecification = async (run, verbose) => {
     /*  perform the regular export before entering the observe loop  */
+    const started = Date.now();
     let observed = await run();
     let times = snapshot(observed);
     const watcher = watch(observed, { ignoreInitial: true });
@@ -128,6 +129,11 @@ export const watchSpecification = async (run, verbose) => {
         }, watchDelay);
     };
     watcher.on("all", schedule);
+    /*  a change during the initial export escaped both the not yet
+        established watcher and the snapshot taken after it, so its
+        modification time alone reveals it  */
+    if (Array.from(times.values()).some((time) => time > started))
+        schedule();
     /*  compare the modification times regularly, so a change the
         watcher never reported still reaches the export, and re-establish
         the watchers on such a miss, as a watcher which lost a file never

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

@@ -8,5 +8,6 @@ export interface PreviewOptions {
 }
 export interface PreviewServer {
     update: (html: Buffer) => void;
+    close: () => Promise<void>;
 }
 export declare const servePreview: (options: PreviewOptions) => Promise<PreviewServer>;

package/dst/specbook-cmd-preview.js

@@ -61,9 +61,10 @@ export const servePreview = async (options) => {
                 options.verbose(`serving ${literal(url)}`, "none");
             html = buffer;
             options.verbose(`notifying ${literal(clients.size)} preview client(s)`);
-            for (const client of clients)
-                if (client.readyState === client.OPEN)
-                    client.send("RELOAD");
-        }
+            for (const socket of clients)
+                if (socket.readyState === socket.OPEN)
+                    socket.send("RELOAD");
+        },
+        close: () => fastify.close()
     };
 };

package/dst/specbook-config.js

@@ -50,7 +50,8 @@ const mergeConfig = (target, source, list) => {
     else if (Array.isArray(target) && Array.isArray(source)) {
         const items = target;
         for (const item of source) {
-            const i = items.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
+            const ident = identityOf(item, list);
+            const i = items.findIndex((existing) => identityOf(existing, list) === ident);
             if (i < 0)
                 items.push(item);
             else
@@ -89,8 +90,11 @@ const posOfMergedPath = (docs, merged, path) => {
         let own = raw;
         let list;
         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;
+            let key = segment;
+            if (typeof segment === "number" && Array.isArray(own)) {
+                const ident = identityOf(at(node, segment), list);
+                key = own.findIndex((item) => identityOf(item, list) === ident);
+            }
             const reaches = typeof key === "number" ?
                 Array.isArray(own) && key >= 0 :
                 isPlainObject(own) && key in own;
@@ -189,7 +193,8 @@ const checkAutomaton = (object, at, diagnose) => {
 /*  check the constraints of a structurally valid configuration which
     are beyond its schema: sibling objects have to stay distinctly
     resolvable, "file" fields are allowed on the first (artifact) level
-    only, property value and marker expressions have to be syntactically
+    only and have to be relative paths below the base directory,
+    property value and marker expressions have to be syntactically
     valid, "referenced" and "coverage" entries have to be reference
     expressions, an "automaton" has to name existing child kinds and
     properties, and the names of non-artifact objects have to be valid
@@ -216,8 +221,8 @@ const checkConstraints = (config, posOfPath) => {
                 diagnose([...at, "file"], `"file" field is only allowed on the first (artifact) level (found on level ${depth})`);
             /*  an artifact file is placed below the base directory, so
                 it must neither be absolute nor escape that directory  */
-            if (object.file !== undefined
-                && ((/^[/\\]/).test(object.file) || (/(?:^|[/\\])\.\.(?:[/\\]|$)/).test(object.file)))
+            if (depth === 1 && object.file !== undefined
+                && ((/^(?:[/\\]|[A-Za-z]:)/).test(object.file) || (/(?:^|[/\\])\.\.(?:[/\\]|$)/).test(object.file)))
                 diagnose([...at, "file"], `"file" field "${object.file}" is not a relative path below the base directory`);
             checkProperties(object.props ?? [], at, diagnose);
             checkAutomaton(object, at, diagnose);

package/dst/specbook-diagnostic.js

@@ -19,7 +19,7 @@ export const renderDiagnosticVerbose = (diagnostic, colors = false) => {
         code = fs.readFileSync(diagnostic.file, "utf8");
     }
     catch {
-        return `${renderDiagnostic(diagnostic)}\n`;
+        code = "";
     }
     if (code === "")
         return `${renderDiagnostic(diagnostic)}\n`;

package/dst/specbook-diagram.js

@@ -75,7 +75,8 @@ const propValue = (parenProps, object, key) => propsOf(parenProps, object).find(
     unique anchor path as the node id, the object name as the displayed
     label, the container node as the parent) and one edge statement per
     derived edge  */
-const renderSpec = (diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps) => {
+const renderSpec = (ctx, diagram, type, center, centerUrl, nodes, edges, nesting) => {
+    const { index, anchors, positions, parenProps } = ctx;
     const lines = [`#type ${type}`];
     const config = { ...diagramPresets, ...diagram.config };
     for (const [key, value] of Object.entries(config))
@@ -145,7 +146,8 @@ const renderSpec = (diagram, type, center, centerUrl, nodes, edges, nesting, ind
     property key when "labeled", and for a "deep" diagram also of their
     descendants, with the reference count as the arity), with every
     target lifted to its nearest node  */
-const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents, parenProps) => {
+const deriveReferenceEdges = (ctx, diagram, nodes, nodeSet) => {
+    const { index, anchors, parents, parenProps } = ctx;
     const edges = new Array();
     /*  lift an object to its nearest ancestor-or-self within the
         node set, as a reference onto a descendant of a node object
@@ -180,9 +182,9 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents,
                     texts.push({ text: object.description.rationale });
             }
             for (const { text, name } of texts)
-                for (const m of text.matchAll(referenceRegex)) {
+                for (const m of plainText(text).matchAll(referenceRegex)) {
                     const target = lift(resolveUnique(index, m[1].trim(), object).target);
-                    if (target !== undefined && target !== node && nodeSet.has(target)) {
+                    if (target !== undefined && target !== node) {
                         const key = `${anchors.get(target) ?? target.id}\u0000${name ?? ""}`;
                         const entry = counts.get(key) ?? { target, name, count: 0 };
                         entry.count++;
@@ -200,7 +202,8 @@ 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, parenProps, errors) => {
+const deriveObjectEdges = (ctx, diagram, nodeSet, edgeObjects, errors) => {
+    const { index, parents, parenProps } = ctx;
     const edges = new Array();
     /*  resolve the node an edge object references through a named
         property, or through its first single-reference property when
@@ -210,7 +213,7 @@ const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, parenP
             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();
+        const reference = value !== undefined ? plainText(value).match(referenceOnce)?.[1].trim() : undefined;
         return reference !== undefined ? resolveUnique(index, reference, edgeObject).target : undefined;
     };
     for (const edgeObject of edgeObjects) {
@@ -239,16 +242,16 @@ const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, parenP
     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, parenProps, errors) => {
+const deriveEdges = (ctx, diagram, type, nodes, nodeSet, edgeObjects, errors) => {
     const edges = new Array();
     if (type !== "grid") {
-        edges.push(...deriveReferenceEdges(diagram, nodes, nodeSet, index, anchors, parents, parenProps));
-        edges.push(...deriveObjectEdges(diagram, nodeSet, edgeObjects, index, parents, parenProps, errors));
+        edges.push(...deriveReferenceEdges(ctx, diagram, nodes, nodeSet));
+        edges.push(...deriveObjectEdges(ctx, diagram, nodeSet, edgeObjects, errors));
         /*  derive the containment edges from the object hierarchy, as
             the nesting of the objects carries no "[[...]]" reference  */
         if (diagram.hierarchy === true)
             for (const node of nodes) {
-                const parent = parents.get(node);
+                const parent = ctx.parents.get(node);
                 if (parent !== undefined && nodeSet.has(parent))
                     edges.push({ source: parent, target: node });
             }
@@ -309,7 +312,8 @@ 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, parenProps, errors) => {
+const deriveCenter = (ctx, object, diagram, nodes, nodeSet, errors) => {
+    const { index, anchors, parenProps } = ctx;
     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;
@@ -370,7 +374,8 @@ const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, parenProp
     Gradia renders as an input node plus an output "ghost" node),
     named by the "labeled" property and/or by the mediating object
     the "via" property references (as "via <name>")  */
-const deriveCenterEdges = (cfg, nodes, center, index, parenProps, errors) => {
+const deriveCenterEdges = (ctx, cfg, nodes, center, errors) => {
+    const { index, parenProps } = ctx;
     const edges = new Array();
     for (const node of nodes) {
         if (node === center)
@@ -409,7 +414,8 @@ const deriveCenterEdges = (cfg, nodes, center, index, parenProps, errors) => {
     on its own in turn), else its parent object when part of the node
     set, else a synthetic container per object kind; a node nested into
     itself or into a cycle stays un-nested and is reported  */
-const deriveNesting = (nest, nodes, nodeSet, index, parents, parenProps, errors) => {
+const deriveNesting = (ctx, nest, nodes, nodeSet, errors) => {
+    const { index, parents, parenProps } = ctx;
     const parentOf = new Map();
     const byKind = new Map();
     /*  the iteration also visits the containers appended underway  */
@@ -417,7 +423,7 @@ const deriveNesting = (nest, nodes, nodeSet, index, parents, parenProps, errors)
         let container;
         for (const key of nest.properties ?? []) {
             const value = propValue(parenProps, node, key);
-            const refs = value !== undefined ? Array.from(value.matchAll(referenceRegex)) : [];
+            const refs = value !== undefined ? Array.from(plainText(value).matchAll(referenceRegex)) : [];
             if (refs.length !== 1)
                 continue;
             container = resolveUnique(index, refs[0][1].trim(), node).target;
@@ -444,7 +450,7 @@ const deriveNesting = (nest, nodes, nodeSet, index, parents, parenProps, errors)
         while (ancestor !== undefined && ancestor !== node)
             ancestor = parentOf.get(ancestor);
         if (ancestor === node) {
-            errors.push({ reason: `node "${plainText(node.name)}" is nested into itself` });
+            errors.push({ reason: `node "${node.name}" is nested into itself` });
             continue;
         }
         parentOf.set(node, container);
@@ -497,32 +503,56 @@ const liftEdges = (edges, parentOf, mode, anchors) => {
     }
     return Array.from(merged.values());
 };
+/*  determine the node objects of a diagram: the objects matching its
+    "nodes" patterns, or by default the current object plus all
+    objects below it  */
+const deriveNodes = (index, object, diagram, errors) => {
+    if (diagram.nodes !== undefined)
+        return resolvePatterns(index, errors, diagram.nodes, "nodes");
+    const nodes = new Array();
+    const walk = (o) => {
+        nodes.push(o);
+        o.children.forEach(walk);
+    };
+    walk(object);
+    return nodes;
+};
+/*  project a "hub" diagram onto its center object: only the edges
+    incident to the center and only the nodes connected through them
+    remain, as Gradia requires exactly this constrained topology, and
+    the occupied columns are the center plus the input column, when an
+    edge of another node targets the center, plus the output column,
+    when an edge originates from the center, where Gradia places the
+    target of its self-loop, too  */
+const projectHub = (nodes, edges, center) => {
+    const incident = edges.filter((edge) => edge.source === center || edge.target === center);
+    const connected = new Set([center]);
+    for (const edge of incident) {
+        connected.add(edge.source);
+        connected.add(edge.target);
+    }
+    const columns = 1 +
+        (incident.some((edge) => edge.target === center && edge.source !== center) ? 1 : 0) +
+        (incident.some((edge) => edge.source === center) ? 1 : 0);
+    return { nodes: nodes.filter((node) => connected.has(node)), edges: incident, columns };
+};
 /*  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, positions, parents, parenProps) => {
+    configured diagram situation is invalid, the node set is empty,
+    or the diagram collapses onto a single node)  */
+const deriveDiagram = (ctx, object, diagram) => {
+    const { index, anchors } = ctx;
     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),
+    /*  determine the node objects 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.children.forEach(walk);
-        };
-        walk(object);
-    }
+    let nodes = deriveNodes(index, object, diagram, errors);
     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 edges of the diagram  */
-    let edges = deriveEdges(diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, parenProps, errors);
+    let edges = deriveEdges(ctx, diagram, type, nodes, nodeSet, edgeObjects, errors);
     /*  determine the center of a "hub" diagram (the only shape
         carrying a center at all)  */
     if (type !== "hub") {
@@ -532,7 +562,7 @@ const deriveDiagram = (object, diagram, index, anchors, positions, parents, pare
             errors.push({ reason: `"${type}" diagram cannot carry a "centerEdges" configuration` });
     }
     const derived = type === "hub" ?
-        deriveCenter(object, diagram, nodes, nodeSet, index, anchors, parenProps, errors) : { center: object };
+        deriveCenter(ctx, object, diagram, nodes, nodeSet, errors) : { center: object };
     if (derived === undefined)
         return { errors };
     const { center, centerUrl } = derived;
@@ -541,31 +571,16 @@ const deriveDiagram = (object, diagram, index, anchors, positions, parents, pare
         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, parenProps, errors));
+        edges.push(...deriveCenterEdges(ctx, diagram.centerEdges, nodes, center, 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, as Gradia requires exactly this
-        constrained topology (and the occupied columns are the center
-        plus the input column, when an edge of another node targets the
-        center, plus the output column, when an edge originates from the
-        center, where Gradia places the target of its self-loop, too)  */
+    /*  project a "hub" diagram onto its center object, which has
+        to be part of the node set  */
     let columns;
     if (type === "hub") {
         if (!nodeSet.has(center))
             errors.push({ reason: `"hub" diagram center "${center.name}" is not part of the node set` });
-        else {
-            edges = edges.filter((edge) => edge.source === center || edge.target === center);
-            const connected = new Set([center]);
-            for (const edge of edges) {
-                connected.add(edge.source);
-                connected.add(edge.target);
-            }
-            nodes = nodes.filter((node) => connected.has(node));
-            columns = 1 +
-                (edges.some((edge) => edge.target === center && edge.source !== center) ? 1 : 0) +
-                (edges.some((edge) => edge.source === center) ? 1 : 0);
-        }
+        else
+            ({ nodes, edges, columns } = projectHub(nodes, edges, center));
     }
     /*  nest the nodes into container nodes (except in a "hub" diagram,
         where every container would need a primary node of its own),
@@ -576,7 +591,7 @@ const deriveDiagram = (object, diagram, index, anchors, positions, parents, pare
         if (type === "hub")
             errors.push({ reason: "\"hub\" diagram cannot carry a \"nest\" configuration" });
         else {
-            nesting = deriveNesting(diagram.nest, nodes, nodeSet, index, parents, parenProps, errors);
+            nesting = deriveNesting(ctx, diagram.nest, nodes, nodeSet, errors);
             if (diagram.nest.crossing !== undefined && diagram.nest.crossing !== "nodes")
                 edges = liftEdges(edges, nesting.parentOf, diagram.nest.crossing, anchors);
             edges = edges.filter((edge) => nesting.parentOf.get(edge.source) !== edge.target
@@ -604,7 +619,8 @@ const deriveDiagram = (object, diagram, index, anchors, positions, parents, pare
     if (nodes.length === 0
         || (diagram.collapse !== false && nodes.length === 1 && edges.length === 0))
         return { errors };
-    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps), config: { ...diagramPresets, ...diagram.config }, columns, errors };
+    return { spec: renderSpec(ctx, diagram, type, center, centerUrl, nodes, edges, nesting),
+        config: { ...diagramPresets, ...diagram.config }, columns, errors };
 };
 /*  the memoized diagram derivations, keyed by specification, as the
     lint validation and every renderer of an export derive the very
@@ -628,11 +644,11 @@ export const specDiagrams = (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 ctx = { index, anchors, positions, parents, parenProps: collectParenProps(schemas) };
     const results = new Map();
     for (const [object, schema] of schemas)
         if (schema.diagram !== undefined)
-            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, positions, parents, parenProps));
+            results.set(object, deriveDiagram(ctx, object, schema.diagram));
     derivations.set(specification, { config, results });
     return results;
 };
@@ -687,8 +703,8 @@ export const renderDiagrams = async (specification, config, verbose, omit = new
                 svg = await Gradia.render(result.spec, { format: "svg:embedded", config: result.config });
             }
             catch (err) {
-                verbose?.(`rendering diagram of ${object.kind} "${object.name}" failed: ` +
-                    (err instanceof Error ? err.message : String(err)), "notice");
+                verbose?.(`rendering diagram of ${object.kind} "${literal(plainText(object.name))}" failed: ` +
+                    (err instanceof Error ? err.message : String(err)));
                 continue;
             }
         }

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

@@ -1,5 +1,5 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
-import type { embeddingThemes } from "./specbook-parse-common.js";
+import { embeddingThemes } from "./specbook-parse-common.js";
 export declare const escapeHtml: (text: string) => string;
 export declare const stylesheet: () => string;
 export declare const searchScript: () => string;
@@ -15,7 +15,7 @@ export declare const isTitleObject: (object: SpecObject) => boolean;
 export declare const titleObject: (specification: Spec) => SpecObject | undefined;
 export declare const documentLang: (specification: Spec) => string | undefined;
 export declare const documentCharset: (specification: Spec) => string | undefined;
-export declare const documentThemeStyle: (specification: Spec) => string | undefined;
+export declare const documentThemeStyle: (specification: Spec) => (typeof embeddingThemes)[number] | undefined;
 export declare const documentThemeTone: (specification: Spec) => string | undefined;
 export type PaperSetup = {
     unit: "mm" | "in";