@rse/specbook 0.9.3 → 0.9.4

package/README.md

@@ -131,7 +131,7 @@ with the (optionally backquoted) name directly:
 
 The heading kind is singularized by stripping one trailing `S`, so both
 `### STATES` and `### STATE` group objects of kind `STATE`. The grouped
-objects become childs of the object the heading is nested under. An
+objects become children of the object the heading is nested under. An
 unquoted name must not contain a `:` (else the item would look like a
 key/value pair) -- backquote it in this case.
 
@@ -238,7 +238,7 @@ constrain reference-valued properties (e.g. `[[PERSONA:*]]` or
 
 A Markdown image `![<alt/>](<file/>)` inside a description or property
 value embeds a local image file, resolved relative to the artifact file:
-SVG files are inlined as-is, PNG/JPEG files are embedded as base64
+SVG files are inlined as-is; PNG/JPEG files are embedded as base64
 `data:` URLs. URLs and other file types are left untouched.
 
 ### Normalization
@@ -285,7 +285,7 @@ descriptions as well. As the *nesting* of the objects carries no such
 reference, `hierarchy: true` additionally derives a containment edge
 from every node object to each of its child objects which is part of the
 node set. This is what turns a parent object into the hub of its own
-childs, as the `TIER` objects of the sample schema configuration
+children, as the `TIER` objects of the sample schema configuration
 demonstrate:
 
 ```yaml
@@ -304,7 +304,7 @@ how the HTML/PDF export renders the child objects of every object of
 that kind. Its `type` selects the rendering: `complex` (nested
 sections), `concise` (compact per-kind tables), or the default `auto`,
 which collapses only the deepest level into tables. Below a `concise`
-object, unconfigured childs implicitly stay `concise` and render as
+object, unconfigured children implicitly stay `concise` and render as
 sub-tables inside the description cells, while an explicitly configured
 `type` is always honored, even a `complex` rendering pressed into a
 cell. `maxTableColumns` (default: `4`) bounds the columns of the compact

package/dst/specbook-api.d.ts

@@ -6,6 +6,7 @@ export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic };
 export { type LintResult };
 export type { Specification, Artifact, Object, Description, Property } from "./specbook-struct-spec.js";
 export type { SchemaSpecification, SchemaObject, SchemaProperty } from "./specbook-struct-schema.js";
+export declare const version: string;
 export interface SpecBookOptions {
     verbose?: (msg: string) => void;
 }

package/dst/specbook-api.js

@@ -3,6 +3,9 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadConfig } from "./specbook-config.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
@@ -14,6 +17,12 @@ import { editSpecification } from "./specbook-cmd-edit.js";
 /*  re-export the central types for API consumers  */
 export { formats, parseOutputSpec };
 export { renderDiagnostic, renderDiagnosticVerbose };
+/*  the own version, taken from the package manifest, which resides one
+    level above both the source and the compiled module directory  */
+export const version = (() => {
+    const manifest = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    return JSON.parse(fs.readFileSync(manifest, "utf8")).version;
+})();
 /*  the SpecBook API  */
 export class SpecBook {
     verbose;
@@ -53,7 +62,7 @@ export class SpecBook {
         if (result.specification.artifacts.length === 0)
             throw new Error("unexportable specification:\n" +
                 result.diagnostics.map(renderDiagnostic).join("\n"));
-        const buffers = [];
+        const buffers = new Array();
         for (const format of options.formats ?? ["json"])
             buffers.push(await exportSpecification(result.specification, format, this.verbose, result.config));
         return buffers;

package/dst/specbook-cli.js

@@ -6,7 +6,7 @@
 */
 import * as fs from "node:fs";
 import { Command } from "commander";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, parseOutputSpec } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, parseOutputSpec, version } from "./specbook-api.js";
 import { serveMcp } from "./specbook-mcp.js";
 /*  route verbose messages to stderr, keeping stdout reserved
     for the command outputs and the MCP protocol  */
@@ -33,7 +33,7 @@ const writeOutput = async (output, data, verbose) => {
         await writeStdout(data);
     else {
         await fs.promises.writeFile(output, data);
-        verbose(`wrote "${output}" (${data.length} bytes)`);
+        verbose(`wrote "${output}" (${Buffer.byteLength(data)} bytes)`);
     }
 };
 /*  determine an option default value, overridable via a
@@ -46,14 +46,14 @@ const envDefaultFlag = (name, fallback) => {
     return value !== undefined ? !(/^(?:|0|false|no|off)$/i).test(value) : fallback;
 };
 /*  provide the common options of all sub-commands  */
-const common = (command) => command
+const withCommonOptions = (command) => command
     .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false))
     .option("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"));
 /*  parse the command line  */
 const program = new Command();
 program.name("specbook")
     .description("Markdown-based Specification Format")
-    .version("0.9.0")
+    .version(version)
     .action(() => {
     program.help();
 });
@@ -64,24 +64,24 @@ program.command("mcp")
     verboseOf(opts)("starting MCP server on stdio");
     await serveMcp(verboseOf(opts));
 });
-common(program.command("init"))
+withCommonOptions(program.command("init"))
     .description("initialize the configured specification artifact files below the base directory")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const created = await specbook.init({ config: opts.config, basedir: opts.basedir });
-    process.stdout.write(created.length > 0 ?
+    await writeStdout(created.length > 0 ?
         `initialized artifact file(s): ${created.join(", ")}\n` :
         "no artifact files were created\n");
 });
-common(program.command("lint"))
+withCommonOptions(program.command("lint"))
     .description("lint the specification Markdown files below the base directory")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const result = await specbook.lint({ config: opts.config, basedir: opts.basedir });
     for (const diagnostic of result.diagnostics)
-        process.stdout.write(opts.verbose ?
+        await writeStdout(opts.verbose ?
             renderDiagnosticVerbose(diagnostic, process.stdout.isTTY === true) :
             `${renderDiagnostic(diagnostic)}\n`);
     if (result.diagnostics.length > 0)
@@ -89,7 +89,7 @@ common(program.command("lint"))
     else
         verboseOf(opts)("specification valid");
 });
-common(program.command("export"))
+withCommonOptions(program.command("export"))
     .description("export the specification Markdown files below the base directory " +
     "as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
@@ -106,7 +106,7 @@ common(program.command("export"))
     for (const { format, output } of outputs)
         await writeOutput(output, buffers[distinct.indexOf(format)], verboseOf(opts));
 });
-common(program.command("describe"))
+withCommonOptions(program.command("describe"))
     .description("describe the configured specification format as Markdown")
     .option("-o, --output <markdown-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
     .action(async (opts) => {
@@ -114,7 +114,7 @@ common(program.command("describe"))
     const text = await specbook.describe({ config: opts.config });
     await writeOutput(opts.output, text, verboseOf(opts));
 });
-common(program.command("import"))
+withCommonOptions(program.command("import"))
     .description("import foreign sources into the specification artifact files below the base directory")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
@@ -124,11 +124,11 @@ common(program.command("import"))
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const written = await specbook.import({ config: opts.config, basedir: opts.basedir,
         inputs, provider: opts.provider, model: opts.model });
-    process.stdout.write(written.length > 0 ?
+    await writeStdout(written.length > 0 ?
         `imported into artifact file(s): ${written.join(", ")}\n` :
         "no artifact files were changed\n");
 });
-common(program.command("edit"))
+withCommonOptions(program.command("edit"))
     .description("apply a free-text edit request to the specification artifact files below the base directory")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
@@ -138,7 +138,7 @@ common(program.command("edit"))
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const written = await specbook.edit({ config: opts.config, basedir: opts.basedir,
         query, provider: opts.provider, model: opts.model });
-    process.stdout.write(written.length > 0 ?
+    await writeStdout(written.length > 0 ?
         `edited artifact file(s): ${written.join(", ")}\n` :
         "no artifact files were changed\n");
 });

package/dst/specbook-cmd-describe.js

@@ -84,11 +84,13 @@ export const describeConfiguration = (config) => {
     const sections = new Array();
     for (const artifact of config) {
         const lines = new Array();
-        lines.push(`### ${artifact.kind}: ${artifact.name} (${artifact.kind}-${artifact.id})`);
+        lines.push(`### ${artifact.kind}: ${artifact.name ?? ""} (${artifact.kind}-${artifact.id ?? ""})`);
         lines.push("");
         if (artifact.file !== undefined)
             lines.push(`-   file: \`${artifact.file}\``);
         lines.push(`-   description: ${collapse(artifact.desc)}`);
+        for (const prop of artifact.props ?? [])
+            lines.push(describeProperty(prop, ""));
         for (const child of artifact.childs ?? [])
             lines.push(describeObject(child, 2, ""));
         sections.push(lines.join("\n"));

package/dst/specbook-cmd-edit.js

@@ -42,6 +42,9 @@ const instruction = (description, now) => textframe `
 export const editSpecification = async (options) => {
     const basedir = options.basedir ?? ".";
     const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
+    /*  ensure a non-empty edit request was given  */
+    if (options.query.trim() === "")
+        throw new Error("no edit request given");
     /*  gather the existing artifact files  */
     const existing = files
         .filter((file) => fs.existsSync(path.join(basedir, file)))
@@ -61,7 +64,9 @@ export const editSpecification = async (options) => {
             options.verbose(`ignoring unconfigured file "${block.name}"`);
             continue;
         }
-        fs.writeFileSync(path.join(basedir, block.name), block.content, "utf8");
+        const file = path.join(basedir, block.name);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, block.content, "utf8");
         options.verbose(`wrote artifact file "${block.name}"`);
         written.push(block.name);
     }

package/dst/specbook-cmd-export.js

@@ -32,8 +32,9 @@ export const parseOutputSpec = (spec) => {
     if (spec === "-")
         return { format: "json", output: spec };
     const ext = spec.match(/\.([a-zA-Z0-9]+)$/);
-    if (ext !== null && extensions[ext[1].toLowerCase()] !== undefined)
-        return { format: extensions[ext[1].toLowerCase()], output: spec };
+    const format = ext !== null ? extensions[ext[1].toLowerCase()] : undefined;
+    if (format !== undefined)
+        return { format, output: spec };
     throw new Error(`unable to infer export format from output "${spec}" ` +
         "(use an explicit \"<format>:<filename>\" specification)");
 };

package/dst/specbook-cmd-import.js

@@ -46,6 +46,9 @@ const instruction = (description, now) => textframe `
 export const importSpecification = async (options) => {
     const basedir = options.basedir ?? ".";
     const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
+    /*  ensure at least one foreign source was given  */
+    if (options.inputs.length === 0)
+        throw new Error("no foreign sources given to import");
     /*  gather the existing artifact files and the foreign sources  */
     const existing = files
         .filter((file) => fs.existsSync(path.join(basedir, file)))
@@ -65,7 +68,9 @@ export const importSpecification = async (options) => {
             options.verbose(`ignoring unconfigured file "${block.name}"`);
             continue;
         }
-        fs.writeFileSync(path.join(basedir, block.name), block.content, "utf8");
+        const file = path.join(basedir, block.name);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, block.content, "utf8");
         options.verbose(`wrote artifact file "${block.name}"`);
         written.push(block.name);
     }

package/dst/specbook-cmd-init.js

@@ -21,14 +21,16 @@ export const initSpecification = (options) => {
             options.verbose(`skipping existing artifact file "${artifact.file}"`);
             continue;
         }
-        const name = (artifact.name ?? "").toUpperCase();
+        const name = artifact.name ?? "";
+        const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
         const text = "---\n" +
             `Created:  ${now}\n` +
             `Modified: ${now}\n` +
             "---\n" +
             "\n" +
-            `#   ${artifact.kind}: ${name} (${artifact.kind}-${artifact.id})\n` +
+            `#   ${artifact.kind}: ${name}${paren}\n` +
             "\n";
+        fs.mkdirSync(path.dirname(file), { recursive: true });
         fs.writeFileSync(file, text, "utf8");
         options.verbose(`created artifact file "${artifact.file}"`);
         created.push(artifact.file);

package/dst/specbook-cmd-lint.js

@@ -25,11 +25,13 @@ export const lint = (options) => {
         config = loaded.config ?? undefined;
     }
     /*  parse and validate the specification Markdown files  */
-    const files = scanMarkdown(options.basedir);
+    const exists = fs.existsSync(options.basedir) && fs.statSync(options.basedir).isDirectory();
+    const files = exists ? scanMarkdown(options.basedir) : [];
     options.verbose(`parsing ${files.length} specification file(s) below "${options.basedir}"`);
     if (files.length === 0)
         diagnostics.push({ file: options.basedir, line: 1, column: 1,
-            message: "no Markdown files found below base directory" });
+            message: exists ? "no Markdown files found below base directory" :
+                "base directory does not exist" });
     const sources = new Array();
     for (const file of files) {
         try {

package/dst/specbook-config.js

@@ -24,7 +24,17 @@ const lineColOfPath = (yaml, cst, path) => {
 /*  load and validate a YAML schema configuration file  */
 export const loadConfig = (file) => {
     const diagnostics = [];
-    const yaml = fs.readFileSync(file, "utf8");
+    /*  read the configuration file  */
+    let yaml;
+    try {
+        yaml = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        diagnostics.push({ file, line: 1, column: 1,
+            message: "cannot read configuration file: " +
+                (err instanceof Error ? err.message : String(err)) });
+        return { config: null, diagnostics };
+    }
     /*  syntactically parse the YAML content  */
     let obj;
     try {
@@ -37,17 +47,22 @@ export const loadConfig = (file) => {
             line: e?.linePos?.[0]?.line ?? 1,
             column: e?.linePos?.[0]?.col ?? 1,
             message: "invalid YAML syntax: " +
-                (err instanceof Error ? err.message.replace(/:(?:.|\r?\n)*$/, "") : String(err))
+                (err instanceof Error ? err.message.replace(/:[\s\S]*$/, "") : String(err))
         });
         return { config: null, diagnostics };
     }
-    /*  semantically validate against the schema of the configuration  */
-    const cst = parseDocument(yaml);
+    /*  semantically validate against the schema of the configuration
+        (the CST is parsed lazily, as it is needed for positions only)  */
+    let cst;
+    const posOfPath = (path) => {
+        cst ??= parseDocument(yaml);
+        return lineColOfPath(yaml, cst, path);
+    };
     const result = v.safeParse(SchemaSpecification, obj);
     if (!result.success) {
         for (const issue of result.issues) {
             const path = (issue.path ?? []).map((item) => item.key);
-            const pos = lineColOfPath(yaml, cst, path);
+            const pos = posOfPath(path);
             diagnostics.push({ file, line: pos.line, column: pos.column,
                 message: `invalid configuration: ${path.join(".")}: ${issue.message}` });
         }
@@ -57,7 +72,7 @@ export const loadConfig = (file) => {
     const checkFileField = (objects, path, depth) => {
         objects.forEach((object, i) => {
             if (depth > 1 && object.file !== undefined) {
-                const pos = lineColOfPath(yaml, cst, [...path, i, "file"]);
+                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})` });
             }
@@ -76,7 +91,7 @@ export const loadConfig = (file) => {
                     compileValueExpr(prop.value);
                 }
                 catch (err) {
-                    const pos = lineColOfPath(yaml, cst, [...path, i, "props", j, "value"]);
+                    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)) });

package/dst/specbook-diagram.js

@@ -4,6 +4,9 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths } from "./specbook-link.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, "");
@@ -27,7 +30,56 @@ const arityToken = (text) => /^[^\s[\]"]+$/.test(text) ? text : quoted(text);
     collapsed, as a directive is a single line)  */
 const configValue = (value) => {
     const text = String(value).replace(/\s+/g, " ").trim();
-    return /^\S+$/.test(text) ? text : quoted(text);
+    return /^[^\s"]+$/.test(text) ? text : quoted(text);
+};
+/*  generate the Gradia spec text of a derived diagram, opened by a
+    "#type" directive and the configured "#config" directives so every
+    embedded spec is self-contained: one node statement per object (the
+    unique anchor path as the node id, the object name as the displayed
+    label) and one edge statement per derived edge  */
+const renderSpec = (diagram, type, center, nodes, edges, index, anchors) => {
+    const lines = [`#type ${type}`];
+    const config = diagram.config ?? {};
+    for (const key of Object.keys(config)) {
+        const value = config[key];
+        if (value !== undefined)
+            lines.push(`#config ${key} ${configValue(value)}`);
+    }
+    lines.push("");
+    for (const node of nodes) {
+        const anchor = anchors.get(node) ?? node.id;
+        const attrs = [`url: ${atom(`#${anchor}`)}`];
+        if (diagram.qualified === true && node.kind !== "")
+            attrs.push(`type: ${atom(node.kind)}`);
+        if (type === "hub" ? node === center : node.primary === true)
+            attrs.push("primary: true");
+        /*  attach the values of the configured properties as Gradia
+            key/value attributes (a node lacking a property is fine, as
+            the node set can mix objects of different kinds), with every
+            "[[...]]" reference stripped to its target object name  */
+        for (const key of diagram.properties ?? []) {
+            const value = node.properties.find((property) => plainKey(property.key) === key)?.value;
+            if (value !== undefined) {
+                const text = value.replace(referenceRegex, (_, reference) => {
+                    const target = resolveUnique(index, reference.trim()).target;
+                    return target !== undefined ? target.name : reference.trim();
+                });
+                attrs.push(`${atom(key)}: ${atom(plainText(text))}`);
+            }
+        }
+        lines.push(`${atom(anchor)}: ${atom(plainText(node.name))} [ ${attrs.join(", ")} ]`);
+    }
+    if (edges.length > 0) {
+        lines.push("");
+        for (const edge of edges) {
+            const op = "--" +
+                (edge.name !== undefined && edge.name !== "" ? `(${nameToken(edge.name)})--` : "") + ">" +
+                (edge.arity !== undefined && edge.arity !== "" ? `[${arityToken(edge.arity)}]` : "");
+            lines.push(`${atom(anchors.get(edge.source) ?? edge.source.id)} ${op} ` +
+                atom(anchors.get(edge.target) ?? edge.target.id));
+        }
+    }
+    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
@@ -69,7 +121,8 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         walk(object);
     }
     const edgeObjects = diagram.edges !== undefined ? resolvePatterns(diagram.edges, "edges") : [];
-    nodes = nodes.filter((node) => !edgeObjects.includes(node));
+    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
@@ -98,8 +151,8 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
             const value = diagram.edgeTarget !== undefined ?
                 edgeObject.properties.find((property) => plainKey(property.key) === diagram.edgeTarget)?.value :
                 edgeObject.properties.map((property) => property.value)
-                    .find((v) => /\[\[[^[\]]+\]\]/.test(v));
-            const reference = value?.match(/\[\[([^[\]]+)\]\]/)?.[1].trim();
+                    .find((v) => referenceOnce.test(v));
+            const reference = value?.match(referenceOnce)?.[1].trim();
             const target = reference !== undefined ? resolveUnique(index, reference).target : undefined;
             if (source === undefined) {
                 errors.push(`diagram edge object "${edgeObject.name}" has no parent object as source`);
@@ -124,15 +177,18 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
                     edges.push({ source: parent, target: node });
             }
     }
-    else if (diagram.edges !== undefined)
-        errors.push("\"grid\" diagram cannot carry an \"edges\" configuration");
-    else if (diagram.hierarchy === true)
-        errors.push("\"grid\" diagram cannot carry a \"hierarchy\" configuration");
+    else {
+        if (diagram.edges !== undefined)
+            errors.push("\"grid\" diagram cannot carry an \"edges\" configuration");
+        if (diagram.hierarchy === true)
+            errors.push("\"grid\" diagram cannot carry a \"hierarchy\" 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) => {
-        const key = `${anchors.get(edge.source)}\u0000${anchors.get(edge.target)}` +
+        const key = `${anchors.get(edge.source) ?? edge.source.id}` +
+            `\u0000${anchors.get(edge.target) ?? edge.target.id}` +
             `\u0000${edge.name ?? ""}\u0000${edge.arity ?? ""}`;
         if (seenEdges.has(key))
             return false;
@@ -144,7 +200,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         resolved object of an explicit "[[...]]" reference otherwise  */
     let center = object;
     if (type === "hub" && diagram.center !== undefined && diagram.center !== "self") {
-        const reference = diagram.center.match(/\[\[([^[\]]+)\]\]/)?.[1].trim();
+        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"}` +
@@ -190,53 +246,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         diagram carries no information beyond the object itself  */
     if (diagram.collapse !== false && nodes.length === 1 && edges.length === 0)
         return { errors };
-    /*  generate the Gradia spec text, opened by a "#type" directive and
-        the configured "#config" directives so every embedded spec is
-        self-contained: one node statement per object (the unique anchor
-        path as the node id, the object name as the displayed label)
-        and one edge statement per derived edge  */
-    const lines = [`#type ${type}`];
-    const config = diagram.config ?? {};
-    for (const key of Object.keys(config)) {
-        const value = config[key];
-        if (value !== undefined)
-            lines.push(`#config ${key} ${configValue(value)}`);
-    }
-    lines.push("");
-    for (const node of nodes) {
-        const anchor = anchors.get(node) ?? node.id;
-        const attrs = [`url: ${atom(`#${anchor}`)}`];
-        if (diagram.qualified === true && node.kind !== "")
-            attrs.push(`type: ${atom(node.kind)}`);
-        if (type === "hub" ? node === center : node.primary === true)
-            attrs.push("primary: true");
-        /*  attach the values of the configured properties as Gradia
-            key/value attributes (a node lacking a property is fine, as
-            the node set can mix objects of different kinds), with every
-            "[[...]]" reference stripped to its target object name  */
-        for (const key of diagram.properties ?? []) {
-            const value = node.properties.find((property) => plainKey(property.key) === key)?.value;
-            if (value !== undefined) {
-                const text = value.replace(referenceRegex, (_, reference) => {
-                    const target = resolveUnique(index, reference.trim()).target;
-                    return target !== undefined ? target.name : reference.trim();
-                });
-                attrs.push(`${atom(key)}: ${atom(plainText(text))}`);
-            }
-        }
-        lines.push(`${atom(anchor)}: ${atom(plainText(node.name))} [ ${attrs.join(", ")} ]`);
-    }
-    if (edges.length > 0) {
-        lines.push("");
-        for (const edge of edges) {
-            const op = "--" +
-                (edge.name !== undefined && edge.name !== "" ? `(${nameToken(edge.name)})--` : "") + ">" +
-                (edge.arity !== undefined && edge.arity !== "" ? `[${arityToken(edge.arity)}]` : "");
-            lines.push(`${atom(anchors.get(edge.source) ?? edge.source.id)} ${op} ` +
-                atom(anchors.get(edge.target) ?? edge.target.id));
-        }
-    }
-    return { spec: lines.join("\n") + "\n", 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)  */

package/dst/specbook-export-ast.js

@@ -25,10 +25,13 @@ export const renderAst = async (specification, format, config) => {
         };
         specification.artifacts.forEach((artifact, i) => artifact.objects.forEach((object, j) => walk(object, plain.artifacts[i].objects[j])));
     }
+    /*  serialize the plain specification into the target format
+        (JSON and JSON5 in compressed form, as they are intended
+        for machine consumption only)  */
     if (format === "json")
-        return Buffer.from(JSON.stringify(plain, null, 4) + "\n", "utf8");
+        return Buffer.from(JSON.stringify(plain) + "\n", "utf8");
     else if (format === "json5")
-        return Buffer.from(JSON5.stringify(plain, null, 4) + "\n", "utf8");
+        return Buffer.from(JSON5.stringify(plain) + "\n", "utf8");
     else if (format === "yaml")
         return Buffer.from(stringifyYaml(plain), "utf8");
     else

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

@@ -18,7 +18,6 @@ export type PaperSetup = {
         right: number;
     };
 };
-export declare const paperSizes: string[];
 export declare const paperSizeDefault = "A4";
 export declare const paperSetup: (paper: string) => PaperSetup;
 export declare const paperLength: (setup: PaperSetup, value: number) => string;