@rse/specbook 0.9.6 → 0.9.7

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,8 +1,9 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
-import type { Schema } from "./specbook-format-schema.js";
-import { type ParseContext } from "./specbook-parse-common.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: Spec, config: Schema) => Map<SpecObject, DiagramResult>;

package/dst/specbook-diagram.js

@@ -3,13 +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, "");
+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  */
@@ -37,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;
@@ -57,10 +53,7 @@ const renderSpec = (diagram, type, center, nodes, edges, index, anchors) => {
         for (const key of diagram.properties ?? []) {
             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))}`);
             }
         }
@@ -78,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 "edgeSource"/"edgeTarget"/"edgeArity" (a "grid"
-        diagram is edge-less by definition, so no edges are derived 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);
@@ -188,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 ?? ""}`;
@@ -201,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 };
         }
@@ -248,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  */
@@ -286,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

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

@@ -1,4 +1,4 @@
 import type { Spec } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
 export type AstFormat = "json" | "json5" | "yaml" | "toon";
-export declare const renderAst: (specification: Spec, format: AstFormat, config?: Schema) => Promise<Buffer>;
+export declare const renderAst: (specification: Spec, format: AstFormat, config?: Schema) => Buffer;

package/dst/specbook-export-ast.js

@@ -8,7 +8,7 @@ import { stringify as stringifyYaml } from "yaml";
 import { encode as encodeToon } from "@toon-format/toon";
 import { specDiagrams } from "./specbook-diagram.js";
 /*  render the specification AST into a serialization format  */
-export const renderAst = async (specification, format, config) => {
+export const renderAst = (specification, format, config) => {
     /*  reduce the specification to plain JSON values (ISO date strings)  */
     const plain = JSON.parse(JSON.stringify(specification));
     /*  attach the Gradia specs of the diagram-configured objects as

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

@@ -1,8 +1,9 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
+import type { embeddingThemes } from "./specbook-parse-common.js";
 export declare const escapeHtml: (text: string) => string;
 export declare const stylesheet: () => string;
 export declare const searchScript: () => string;
-export declare const fallbackLogo: (theme: string) => string;
+export declare const fallbackLogo: (theme: (typeof embeddingThemes)[number]) => string;
 export declare const isTitleObject: (object: SpecObject) => boolean;
 export declare const titleObject: (specification: Spec) => SpecObject | undefined;
 export declare const documentLang: (specification: Spec) => string | undefined;

package/dst/specbook-export-common.js

@@ -3,20 +3,19 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import path from "node:path";
 import fs from "node:fs";
-import { fileURLToPath } from "node:url";
 /*  escape a text for embedding into template HTML (text and attributes)  */
 export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
     .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 /*  provide the build-time pre-assembled stylesheet (with the
     font faces already inlined as base64 data: URIs)  */
-export const stylesheet = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-html.css"), "utf8");
+export const stylesheet = () => fs.readFileSync(new URL("specbook-export-html.css", import.meta.url), "utf8");
 /*  provide the build-time bundled client-side fuzzy search script  */
-export const searchScript = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-html-search.js"), "utf8");
+export const searchScript = () => fs.readFileSync(new URL("specbook-export-html-search.js", import.meta.url), "utf8");
 /*  provide a theme variant of the build-time bundled fallback logo of
     SpecBook itself (as a self-contained data: URL, to keep its styles isolated)  */
-export const fallbackLogo = (theme) => "data:image/svg+xml;base64," + fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), `specbook-export-logo-${theme}.svg`)).toString("base64");
+export const fallbackLogo = (theme) => "data:image/svg+xml;base64," +
+    fs.readFileSync(new URL(`specbook-export-logo-${theme}.svg`, import.meta.url)).toString("base64");
 /*  check whether an object is the specification title object  */
 export const isTitleObject = (object) => object.kind === "META" && object.name.toUpperCase() === "TITLE";
 /*  determine the title object of the specification, searched at any
@@ -71,14 +70,15 @@ export const documentPaperSize = (specification) => {
             `(expected ${paperSizes.join(", ")})`);
     return paper;
 };
-/*  provide the paper-dependent print stylesheet: a diagram is scaled
-    down to still fit onto a single page (the paper height less the
-    print margins, the own vertical margins of the diagram, and the
-    room its introducing heading claims above it) and is never broken
-    across a page boundary; without the heading reserve a maximally
+/*  the vertical room (in rem) the introducing heading of a diagram
+    claims above it on the same page: without this reserve a maximally
     sized diagram could not share its page with the heading, which
     would defeat the "break-after: avoid" bundling of the stylesheet  */
 const headingReserve = 6;
+/*  provide the paper-dependent print stylesheet: a diagram is scaled
+    down to still fit onto a single page (the paper height less the
+    print margins, the own vertical margins of the diagram, and the
+    heading reserve above it) and is never broken across a page boundary  */
 export const paperStylesheet = (paper) => {
     const setup = paperSetup(paper);
     const avail = setup.height - setup.margin.top - setup.margin.bottom;
@@ -131,9 +131,7 @@ const typographyGlyphs = [
     glyphs (no charset or a full Unicode charset keeps the fonts complete)  */
 export const subsetStylesheet = async (charset) => {
     const css = stylesheet();
-    if (charset === undefined)
-        return css;
-    const codepoints = charsetCodepoints(charset);
+    const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
     if (codepoints === undefined)
         return css;
     const { default: subsetFont } = await import("subset-font");
@@ -162,7 +160,7 @@ export const documentTitle = (specification) => ({
 export const documentLogo = (specification) => {
     const content = titleObject(specification)
         ?.properties.find((property) => property.key === "LOGO")?.embedding?.[0];
-    if (content === undefined)
+    if (content === undefined || content === "")
         return fallbackLogo("light");
     return content.startsWith("data:") ? content :
         `data:image/svg+xml;base64,${Buffer.from(content, "utf8").toString("base64")}`;

package/dst/specbook-export-html-search.js

@@ -18,7 +18,7 @@
 
     /*  shortest word still eligible for fuzzy matching: below it the
         edit distance would equate it with almost any short word  */
-    const FUZZY_MIN = 4
+    const fuzzyMin = 4
 
     /*  the searchable units (paragraphs, list items, table rows, and
         headings), the corpus vocabulary, and the per-word cache of the
@@ -101,7 +101,7 @@
         if (result !== undefined)
             return result
         result = []
-        if (word.length >= FUZZY_MIN)
+        if (word.length >= fuzzyMin)
             vocab.forEach((given) => {
                 if (Math.abs(word.length - given.length) <= 1
                     && (diceCoefficient(word, given) >= 0.50
@@ -115,19 +115,21 @@
     /*  match a query word against a unit, as a literal substring or as
         a fuzzy variant, remembering the variants for the highlighting  */
     const wordMatch = (word, unit, variants) => {
-        if (unit.text.indexOf(word) >= 0)
+        if (unit.text.includes(word))
             return true
         const near = fuzzyWords(word).filter((v) => unit.words.has(v))
         near.forEach((v) => { variants.add(v) })
         return near.length > 0
     }
 
+    /*  escape a text for its literal use inside a regular expression  */
+    const escapeRegex = (s) =>
+        s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
     /*  the alternation matching everything worth highlighting: the
         query words as plain substrings plus the fuzzy variants as
         whole words, longest alternative first, so a variant is never
         cut short by a query word nested inside it  */
-    const escapeRegex = (s) =>
-        s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
     const buildRegex = (words, variants) => {
         const alts = words.map((w) => ({ len: w.length, src: escapeRegex(w) }))
             .concat(variants.map((v) => ({ len: v.length,
@@ -203,7 +205,7 @@
         units.forEach((unit) => { unit.keep = false })
         parts.forEach((part) => {
             let matched = units.filter((unit) =>
-                part.every((word) => unit.text.indexOf(word) >= 0))
+                part.every((word) => unit.text.includes(word)))
             if (matched.length === 0)
                 matched = units.filter((unit) =>
                     part.every((word) => wordMatch(word, unit, variants)))
@@ -226,7 +228,7 @@
                 const heading = section.firstElementChild
                 if (heading !== null && /^H[1-6]$/.test(heading.tagName))
                     heading.classList.add("search-keep")
-                section = section.parentElement !== null ? section.parentElement.closest("section") : null
+                section = section.parentElement?.closest("section") ?? null
             }
         })
 
@@ -244,13 +246,7 @@
         })
 
         /*  highlight every matched word within the kept units  */
-        const words = []
-        parts.forEach((part) => {
-            part.forEach((word) => {
-                if (!words.includes(word))
-                    words.push(word)
-            })
-        })
+        const words = Array.from(new Set(parts.flat()))
         const regex = buildRegex(words, Array.from(variants))
         units.forEach((unit) => {
             if (unit.el.classList.contains("search-keep"))