@rse/specbook 0.9.6 → 0.9.8

package/dst/specbook-config.js

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

package/dst/specbook-diagnostic.js

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

package/dst/specbook-diagram.d.ts

@@ -1,9 +1,14 @@
 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 DiagramError {
+    reason: string;
+    object?: SpecObject;
+}
 export interface DiagramResult {
     spec?: string;
-    errors: string[];
+    config?: SchemaDiagram["config"];
+    errors: DiagramError[];
 }
 export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;
 export declare const validateDiagrams: (ctx: ParseContext, specification: Spec, config: Schema) => void;

package/dst/specbook-diagram.js

@@ -3,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);
@@ -159,13 +110,13 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
                 edgeNode(edgeObject, diagram.edgeSource) : parents.get(edgeObject);
             const target = edgeNode(edgeObject, diagram.edgeTarget);
             if (source === undefined) {
-                errors.push(diagram.edgeSource !== undefined ?
-                    `diagram edge object "${edgeObject.name}" carries no resolvable source reference` :
-                    `diagram edge object "${edgeObject.name}" has no parent object as source`);
+                errors.push({ object: edgeObject, reason: diagram.edgeSource !== undefined ?
+                        "carries no resolvable source reference" :
+                        "has no parent object as source" });
                 continue;
             }
             if (target === undefined) {
-                errors.push(`diagram edge object "${edgeObject.name}" carries no resolvable target reference`);
+                errors.push({ object: edgeObject, reason: "carries no resolvable target reference" });
                 continue;
             }
             if (!nodeSet.has(source) || !nodeSet.has(target))
@@ -185,14 +136,16 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
     }
     else {
         if (diagram.edges !== undefined)
-            errors.push("\"grid\" diagram cannot carry an \"edges\" configuration");
+            errors.push({ reason: "\"grid\" diagram cannot carry an \"edges\" configuration" });
         if (diagram.hierarchy === true)
-            errors.push("\"grid\" diagram cannot carry a \"hierarchy\" configuration");
+            errors.push({ reason: "\"grid\" diagram cannot carry a \"hierarchy\" configuration" });
+        if (diagram.onlyConnected === true)
+            errors.push({ reason: "\"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,16 +154,69 @@ 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({ reason: `unresolvable diagram "${field}" pattern "[[${pattern}]]"` });
+        for (const match of set) {
+            if (!seen.has(match)) {
+                seen.add(match);
+                matches.push(match);
+            }
+        }
+    }
+    if (!found)
+        errors.push({ reason: `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({ reason: `"${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"}` +
-                ` diagram "center" reference "${diagram.center}"`);
+            errors.push({ reason: (resolved?.ambiguous === true ? "ambiguous" : "unresolvable") +
+                    ` diagram "center" reference "${diagram.center}"` });
             return { errors };
         }
         center = resolved.target;
@@ -221,7 +227,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         Gradia requires exactly this constrained topology  */
     if (type === "hub") {
         if (!nodeSet.has(center))
-            errors.push(`"hub" diagram center "${center.name}" is not part of the node set`);
+            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)
                 && edge.source !== edge.target);
@@ -244,38 +250,15 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         nodes = nodes.filter((node) => connected.has(node));
     }
     if (nodes.length === 0)
-        errors.push("diagram yields no nodes");
+        errors.push({ reason: "diagram yields no nodes" });
     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,16 +269,29 @@ 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
     every invalid diagram situation as a file/line-precise diagnostic  */
 export const validateDiagrams = (ctx, specification, config) => {
-    for (const [object, result] of specDiagrams(specification, config)) {
-        const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
-        for (const error of result.errors)
-            ctx.diagnose(meta.file, meta.line, `invalid diagram on ${object.kind} "${object.name}": ${error}`);
-    }
+    const seen = new Set();
+    for (const [object, result] of specDiagrams(specification, config))
+        for (const error of result.errors) {
+            /*  attribute an edge object situation to the offending edge
+                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 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}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            ctx.diagnose(meta.file, meta.line, message);
+        }
 };

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")}`;