@rse/specbook 1.1.0 → 1.2.1

package/README.md

@@ -74,7 +74,8 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
     theme toggle. It is intended for the day-to-day online reading during
     development. The HTML export can map all object kinds to nested
     sections or compact tables, or an automatic mixture which collapses
-    only the deepest level into tables.
+    only the deepest level into tables. The HTML export even can be
+    previewed in the browser with live updates.
 
 -   **PDF Export for Customers**:
     The PDF export prints the HTML rendering via Chromium and post-processes

package/dst/specbook-api.js

@@ -4,16 +4,16 @@
 **  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 { glob } from "glob";
 import { loadConfig } from "./specbook-config.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
-import { exportSpecification, watchSpecification, parseOutputSpec, formats } from "./specbook-cmd-export.js";
+import { exportSpecification, watchSpecification, parseOutputSpec, formats, requireBrowser } from "./specbook-cmd-export.js";
 import { servePreview, previewAddr, previewPort } from "./specbook-cmd-preview.js";
 import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel } from "./specbook-cmd-describe.js";
-import { requireBrowser } from "./specbook-export-pdf.js";
 import { literal, renderVerbose } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
 export { literal, renderVerbose };
@@ -53,7 +53,8 @@ export class SpecBook {
                 files.push(standardConfig);
                 continue;
             }
-            const matches = await glob(pattern, { nodir: true });
+            const matches = await glob(pattern, { nodir: true,
+                windowsPathsNoEscape: process.platform === "win32" });
             if (matches.length === 0)
                 throw new Error(`no configuration file matches "${pattern}"`);
             files.push(...matches.sort());
@@ -87,7 +88,7 @@ export class SpecBook {
         invalid specification must never be emitted, while the warnings
         are just surfaced as notices), where "realtime" injects the
         client-side script of the live preview into the HTML  */
-    async renderFormats(result, formats, verbose, realtime) {
+    async renderFormats(result, requested, verbose, realtime) {
         if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
             throw new Error("invalid specification:\n" +
                 result.diagnostics.map(renderDiagnostic).join("\n"));
@@ -96,7 +97,7 @@ export class SpecBook {
         if (result.specification.artifacts.length === 0)
             throw new Error("unexportable specification: no artifacts found");
         const buffers = new Array();
-        for (const format of formats)
+        for (const format of requested)
             buffers.push(await exportSpecification(result.specification, format, verbose, result.config, realtime));
         return buffers;
     }
@@ -115,19 +116,21 @@ export class SpecBook {
             basedir: options.basedir ?? ".", verbose }), requested, verbose, options.realtime === true);
     }
     /*  keep an export in sync with its sources (the shared core of
-        "watch" and "preview"): every change of an artifact file or of one
-        of its embedded assets re-exports the specification and hands the
-        buffers to "onExport" once the sources fell silent again. A failed
-        re-export is reported and leaves the observe loop intact, so a
-        transiently invalid specification does not end the watch. The
-        returned promise settles once the initial export is done, while
-        the active watcher keeps the process alive afterwards  */
+        "watch" and "preview"): every change of a configuration file, of an
+        artifact file, or of one of its embedded assets re-exports the
+        specification and hands the buffers to "onExport" once the sources
+        fell silent again. A failed re-export is reported and leaves the
+        observe loop intact, so a transiently invalid specification (or
+        configuration) does not end the watch. The returned promise settles
+        once the initial export is done, while the active watcher keeps the
+        process alive afterwards  */
     async observe(options, verbose) {
         const config = await this.configFiles(options.config);
         return watchSpecification(async () => {
             /*  the lint result carries the files to observe even for an
-                invalid specification, so a failing export still keeps the
-                observe loop fed with an up-to-date file set  */
+                invalid specification, and the configuration files are
+                observed, too, so a failing export (even one due to an
+                invalid configuration) still keeps the observe loop fed  */
             const result = lint({ config, basedir: options.basedir ?? ".", verbose });
             try {
                 await options.onExport(await this.renderFormats(result, options.formats, verbose, options.realtime));
@@ -136,7 +139,7 @@ export class SpecBook {
                 verbose("export failed: " +
                     (err instanceof Error ? err.message : String(err)), "notice");
             }
-            return result.files;
+            return [...config.map((file) => path.resolve(file)), ...result.files];
         }, verbose);
     }
     /*  export the specification like "export" and then keep the export
@@ -175,7 +178,7 @@ export class SpecBook {
             they fall back onto the bundled standard one, which is always
             embedded, as its bundled file is no meaningful reference  */
         const given = options.config !== undefined && options.config.length > 0;
-        const standard = !given && (part === "all" || part === "schema" || options.embed === true);
+        const standard = !given && (part === "all" || part === "schema");
         const config = given || standard ? await this.configFiles(options.config) : undefined;
         const embed = options.embed === true || standard;
         const basedir = options.basedir ?? (part === "spec" ? "." : undefined);

package/dst/specbook-cli.js

@@ -25,16 +25,14 @@ const verboseOf = (opts, ...scope) => (cmd, msg, level) => {
 /*  write a buffer to a standard stream, awaiting the write callback
     which only fires once the data has been flushed to the underlying
     pipe, so a subsequent "process.exit" cannot truncate the output  */
-const writeStream = (stream, data) => {
-    return new Promise((resolve, reject) => {
-        stream.write(data, (err) => {
-            if (err)
-                reject(err);
-            else
-                resolve();
-        });
+const writeStream = (stream, data) => new Promise((resolve, reject) => {
+    stream.write(data, (err) => {
+        if (err)
+            reject(err);
+        else
+            resolve();
     });
-};
+});
 const writeStdout = (data) => writeStream(process.stdout, data);
 const writeStderr = (data) => writeStream(process.stderr, data);
 /*  write a command result to the output file or stdout  */
@@ -48,7 +46,10 @@ const writeOutput = async (output, data, cmd, verbose) => {
 };
 /*  determine an option default value, overridable via a
     corresponding SPECBOOK_<OPTION> environment variable  */
-const envDefault = (name, fallback) => process.env[`SPECBOOK_${name.toUpperCase().replace(/-/g, "_")}`] ?? fallback;
+const envDefault = (name, fallback) => {
+    const value = process.env[`SPECBOOK_${name.toUpperCase().replace(/-/g, "_")}`];
+    return value !== undefined && value !== "" ? value : fallback;
+};
 /*  determine a flag option default value, overridable via a
     corresponding SPECBOOK_<OPTION> environment variable  */
 const envDefaultFlag = (name, fallback) => {
@@ -160,15 +161,15 @@ withCommonOptions(program.command("preview"))
     .option("-p, --port <tcp-port>", "TCP port to listen on", envDefault("port", String(previewPort)))
     .action(async (opts) => {
     const port = Number(opts.port);
-    if (!Number.isInteger(port))
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new Error(`invalid TCP port "${opts.port}"`);
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     await specbook.preview({ config: configOf(opts), basedir: opts.basedir, addr: opts.addr, port });
 });
 /*  the describe command also describes the generic SpecBook models and
     formats alone, so its YAML schema configuration stays optional  */
-withConfigOption(withVerboseOption(program.command("describe"))
-    .description("describe the SpecBook models and formats as Markdown"), "the bundled standard schema configuration, embedded")
+withConfigOption(withVerboseOption(program.command("describe")), "the bundled standard schema configuration, embedded")
+    .description("describe the SpecBook models and formats as Markdown")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir"))
     .option("-e, --embed", "embed the given YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
     .option("-z, --compress [level]", "compression level of the emitted YAML schema configuration " +

package/dst/specbook-cmd-describe.js

@@ -26,7 +26,8 @@ export const compressLevels = [0, 1, 2, 3];
 /*  parse and validate a compression level specification,
     where a bare flag selects the plain re-emitting  */
 export const parseCompressLevel = (value) => {
-    const level = typeof value === "boolean" ? (value ? 1 : 0) : Number(value);
+    const level = typeof value === "boolean" ? (value ? 1 : 0) :
+        typeof value === "string" && !(/^\d+$/).test(value) ? NaN : Number(value);
     if (!compressLevels.includes(level))
         throw new Error(`unknown compress level "${value}" ` +
             `(supported: ${compressLevels.join(", ")})`);
@@ -39,6 +40,8 @@ const description = () => fs.readFileSync(new URL("specbook-format.md", import.m
     document (block scalar styles retained) with 2-space indentation and
     unwrapped lines, dropping all comments and the fields the level demands  */
 const compressYaml = (yaml, level) => {
+    if (level === 0)
+        return yaml;
     const doc = parseDocument(yaml);
     const drop = ["refs", "desc"].slice(0, level - 1);
     doc.commentBefore = null;
@@ -55,9 +58,13 @@ const compressYaml = (yaml, level) => {
 /*  provide the YAML text of the schema configuration: the verbatim
     content of its single file, or the merged configuration re-emitted
     for several files (as no single file carries their merge)  */
-const schemaYaml = (config, schema) => config.length > 1 && schema !== undefined ?
-    stringify(schema, { indent: 2, lineWidth: 0 }) :
-    fs.readFileSync(config[0], "utf8");
+const schemaYaml = (config, schema) => {
+    if (config.length === 1)
+        return fs.readFileSync(config[0], "utf8");
+    if (schema === undefined)
+        throw new Error("re-emitting the merged YAML schema configuration requires its loaded configuration");
+    return stringify(schema, { indent: 2, lineWidth: 0 });
+};
 /*  render the reference to (or the embedding of) the YAML schema configuration,
     where the bundled standard one is embedded without its leading comment block  */
 const schemaSection = (config, schema, embed, standard, compress) => {
@@ -68,8 +75,7 @@ const schemaSection = (config, schema, embed, standard, compress) => {
     let yaml = schemaYaml(config, schema);
     if (standard)
         yaml = yaml.replace(/^(?:[ \t]*##.*\n)+\s*/, "");
-    if (compress > 0)
-        yaml = compressYaml(yaml, compress);
+    yaml = compressYaml(yaml, compress);
     return textframe(`
         The **SpecBook SCHEMA Model** is the following YAML schema configuration:
     `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n\n";
@@ -89,13 +95,9 @@ const specSection = (basedir) => textframe(`
     embedding several files), and where "compress" emits the
     configuration compressed by the given level instead of verbatim  */
 export const describeFormat = (options) => {
-    const format = options.format ?? "md";
-    const part = options.part ?? "all";
-    const compress = options.compress ?? 1;
-    if (!describeFormats.includes(format))
-        throw new Error(`unknown describe format "${format}"`);
-    if (!describeParts.includes(part))
-        throw new Error(`unknown describe part "${part}"`);
+    const format = parseDescribeFormat(options.format ?? "md");
+    const part = parseDescribePart(options.part ?? "all");
+    const compress = parseCompressLevel(options.compress ?? 1);
     /*  the raw format emits the original file content of a single part,
         so it is available for the file-backed parts only  */
     if (format === "raw") {
@@ -108,7 +110,7 @@ export const describeFormat = (options) => {
             throw new Error("format \"raw\" for part \"schema\" requires a YAML schema configuration");
         else {
             const yaml = schemaYaml(options.config, options.schema);
-            return compress > 0 ? compressYaml(yaml, compress) : yaml;
+            return compressYaml(yaml, compress);
         }
     }
     /*  the md format renders a single part standalone  */
@@ -129,13 +131,13 @@ export const describeFormat = (options) => {
         artifacts of the project instantiation and hence are always
         placed under their own section  */
     const sections = [description()];
-    const schema = options.config !== undefined ?
+    const schemaText = options.config !== undefined ?
         schemaSection(options.config, options.schema, options.embed === true, options.standard === true, compress) : undefined;
-    if (schema !== undefined || options.basedir !== undefined) {
+    if (schemaText !== undefined || options.basedir !== undefined) {
         sections.push("SpecBook Project Instantiation\n" +
             "==============================\n");
-        if (schema !== undefined)
-            sections.push(schema);
+        if (schemaText !== undefined)
+            sections.push(schemaText);
         if (options.basedir !== undefined)
             sections.push(specSection(options.basedir));
     }

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

@@ -1,6 +1,8 @@
 import type { Spec } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
-import type { Verbose } from "./specbook-verbose.js";
+import { requireBrowser } from "./specbook-export-pdf.js";
+import { type Verbose } from "./specbook-verbose.js";
+export { requireBrowser };
 export declare const formats: readonly ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
 export type ExportFormat = typeof formats[number];
 export declare const parseOutputSpec: (spec: string) => {

package/dst/specbook-cmd-export.js

@@ -9,9 +9,12 @@ import { documentTitle, documentLogo, documentCharset, documentThemeTone, subset
 import { themeColors, themeStylesheet, themeMapping } from "./specbook-theme.js";
 import { renderAst } from "./specbook-export-ast.js";
 import { renderMarkdown } from "./specbook-export-md.js";
-import { renderHtml, htmlOutline } from "./specbook-export-html.js";
-import { htmlToPdf } from "./specbook-export-pdf.js";
+import { renderHtml, htmlOutline, titlePageObject } from "./specbook-export-html.js";
+import { htmlToPdf, requireBrowser } from "./specbook-export-pdf.js";
 import { literal } from "./specbook-verbose.js";
+/*  re-export the browser pre-check of the PDF renderer, so the API
+    facade reaches the renderers through this command module only  */
+export { requireBrowser };
 /*  the supported export formats  */
 export const formats = ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
 /*  the format names and filename extensions mapping onto the export formats  */
@@ -62,6 +65,12 @@ export const watchSpecification = async (run, verbose) => {
     let observed = await run();
     const watcher = watch(observed, { ignoreInitial: true });
     verbose(`observing ${literal(observed.length)} specification file(s) for changes`);
+    /*  report the failures of the observation itself, as an unhandled
+        "error" event would otherwise terminate the process  */
+    watcher.on("error", (err) => {
+        verbose("observing failed: " +
+            (err instanceof Error ? err.message : String(err)), "notice");
+    });
     /*  perform a re-export and re-synchronize the observed files  */
     const cycle = async () => {
         const files = await run();
@@ -88,12 +97,9 @@ export const watchSpecification = async (run, verbose) => {
         }, watchDelay);
     });
 };
-/*  export a specification into the requested format, where "realtime"
+/*  render a specification into the requested format, where "realtime"
     injects the client-side script of the live preview into the HTML  */
-export const exportSpecification = async (specification, format, verbose, config, realtime = false) => {
-    if (!formats.includes(format))
-        throw new Error(`unknown export format "${format}"`);
-    verbose(`exporting specification as "${literal(format)}"`);
+const renderFormat = async (specification, format, verbose, config, realtime = false) => {
     if (format === "json" || format === "json5" || format === "yaml" || format === "toon")
         return renderAst(specification, format, config);
     else if (format === "md")
@@ -114,7 +120,7 @@ export const exportSpecification = async (specification, format, verbose, config
     const css = themeStylesheet(colors) + await subsetStylesheet(charset) + paperStylesheet(paper);
     if (format === "html") {
         /*  compress the rendered HTML (whitespace, comments, and inline CSS/JS)  */
-        const html = await renderHtml(specification, config, undefined, css, realtime);
+        const html = await renderHtml(specification, config, undefined, css, realtime, verbose);
         const minified = await minify(Buffer.from(html, "utf8"), {
             collapseWhitespaces: "smart",
             removeComments: true,
@@ -126,5 +132,17 @@ export const exportSpecification = async (specification, format, verbose, config
     else
         /*  the PDF export (like print in general) always uses the light
             theme, so its decoration colors are the light mapping, too  */
-        return htmlToPdf((tocPages) => renderHtml(specification, config, tocPages, css), { ...documentTitle(specification), logo: documentLogo(specification) }, htmlOutline(specification, config), verbose, css, themeMapping(colors, "light"), paper);
+        return htmlToPdf((tocPages) => renderHtml(specification, config, tocPages, css, false, verbose), { ...documentTitle(specification), logo: documentLogo(specification) }, htmlOutline(specification, config), titlePageObject(specification) !== undefined, verbose, css, themeMapping(colors, "light"), paper);
+};
+/*  export a specification into the requested format (see "renderFormat"),
+    reporting the duration of the rendering in the verbose output  */
+export const exportSpecification = async (specification, format, verbose, config, realtime = false) => {
+    if (!formats.includes(format))
+        throw new Error(`unknown export format "${format}"`);
+    verbose(`exporting specification as "${literal(format)}"`);
+    const started = performance.now();
+    const buffer = await renderFormat(specification, format, verbose, config, realtime);
+    const seconds = ((performance.now() - started) / 1000).toFixed(3);
+    verbose(`exported specification as "${literal(format)}" in ${literal(seconds)}s`);
+    return buffer;
 };

package/dst/specbook-cmd-preview.js

@@ -18,6 +18,7 @@ export const servePreview = async (options) => {
     const clients = new Set();
     const fastify = Fastify();
     await fastify.register(fastifyWebsocket);
+    /*  answer a plain GET with the document and subscribe a WebSocket upgrade  */
     fastify.route({
         method: "GET",
         url: "/",
@@ -25,7 +26,8 @@ export const servePreview = async (options) => {
             if (html === undefined)
                 return reply.code(503).type("text/plain; charset=utf-8")
                     .send("no specification export available yet\n");
-            return reply.type("text/html; charset=utf-8").send(html);
+            return reply.type("text/html; charset=utf-8")
+                .header("cache-control", "no-store").send(html);
         },
         wsHandler: (socket, request) => {
             /*  identify the client by its remote address and port  */
@@ -37,10 +39,17 @@ export const servePreview = async (options) => {
                 clients.delete(socket);
                 options.verbose(`client ${literal(client)} disconnected`, "notice");
             });
+            /*  report a failing client, as an unhandled "error" event
+                would otherwise terminate the process  */
+            socket.on("error", (err) => {
+                options.verbose(`client ${literal(client)} failed: ${err.message}`, "notice");
+            });
         }
     });
+    /*  start listening and hand out the export feed  */
     await fastify.listen({ host: options.addr, port: options.port });
-    const url = `http://${options.addr}:${options.port}/`;
+    const host = options.addr.includes(":") ? `[${options.addr}]` : options.addr;
+    const url = `http://${host}:${options.port}/`;
     options.verbose(`listening on ${literal(url)}`, "notice");
     return {
         update: (buffer) => {

package/dst/specbook-config.js

@@ -67,7 +67,7 @@ const mergeConfig = (target, source, list) => {
 const posOfMergedPath = (docs, merged, path) => {
     const at = (value, key) => value?.[key];
     let best = { file: docs[docs.length - 1].file, line: 1, column: 1, path, depth: -1 };
-    for (const { file, doc, lines, raw } of docs.slice().reverse()) {
+    for (const { file, doc, lines, raw } of docs.toReversed()) {
         const translated = [];
         let node = merged;
         let own = raw;
@@ -89,6 +89,84 @@ const posOfMergedPath = (docs, merged, path) => {
     return { file: best.file, line: best.line, column: best.column,
         path: best.depth === path.length ? best.path : path };
 };
+/*  check the properties of an object: the value expressions have to be
+    syntactically valid, the relation shape flags apply to
+    reference-valued properties only, and the sibling marker flags
+    optionally carry a regexp or enum expression  */
+const checkProperties = (props, at, diagnose) => {
+    for (const [j, prop] of props.entries()) {
+        /*  the sibling marker flags optionally carry a regexp or
+            enum expression selecting the values they apply to  */
+        for (const flag of ["unique", "present"]) {
+            const marker = prop[flag];
+            if (typeof marker !== "string")
+                continue;
+            let kind;
+            try {
+                kind = compileValueExpr(marker).kind;
+            }
+            catch (err) {
+                diagnose([...at, "props", j, flag], `invalid "${flag}" expression "${marker}": ` +
+                    (err instanceof Error ? err.message : String(err)));
+            }
+            if (kind !== undefined && kind !== "regex" && kind !== "enum")
+                diagnose([...at, "props", j, flag], `"${flag}" expression "${marker}" is neither a regexp nor an enum`);
+        }
+        /*  the relation shape flags apply to reference-valued
+            properties only (an invalid expression is reported on
+            its own, without a cascading flag diagnostic)  */
+        let expr;
+        if (prop.value !== undefined) {
+            try {
+                expr = compileValueExpr(prop.value);
+            }
+            catch (err) {
+                diagnose([...at, "props", j, "value"], `invalid value expression "${prop.value}": ` +
+                    (err instanceof Error ? err.message : String(err)));
+                continue;
+            }
+        }
+        for (const flag of ["local", "symmetric", "acyclic"])
+            if (prop[flag] === true && (expr === undefined || !admitsReferences(expr)))
+                diagnose([...at, "props", j, flag], `"${flag}" flag requires a reference-valued property`);
+    }
+};
+/*  check the automaton of an object (if any): it names the child kinds
+    acting as nodes and edges, the reference-valued edge properties
+    referencing the source and target nodes, and the node properties
+    flagging the initial and final nodes  */
+const checkAutomaton = (object, at, diagnose) => {
+    if (object.automaton === undefined)
+        return;
+    const automaton = object.automaton;
+    const childOf = (kind) => (object.childs ?? []).find((c) => c.kind === kind);
+    const propOf = (child, name) => (child?.props ?? []).find((p) => p.name === name);
+    /*  an invalid value expression is reported on its own (see
+        "checkProperties"), so it must not cascade into a shape diagnostic  */
+    const isReference = (prop) => {
+        try {
+            return prop.value !== undefined && admitsReferences(compileValueExpr(prop.value));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const nodes = childOf(automaton.nodes);
+    const edges = childOf(automaton.edges);
+    for (const [field, child] of [["nodes", nodes], ["edges", edges]])
+        if (child === undefined)
+            diagnose([...at, "automaton", field], `"automaton" ${field} kind "${automaton[field]}" is not a child object kind`);
+    for (const field of ["source", "target"]) {
+        const prop = propOf(edges, automaton[field]);
+        if (edges !== undefined && prop === undefined)
+            diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not a property of "${automaton.edges}"`);
+        else if (prop !== undefined && isReference(prop) === false)
+            diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not reference-valued`);
+    }
+    for (const field of ["initial", "final"])
+        if (nodes !== undefined && propOf(nodes, automaton[field]) === undefined)
+            diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not a property of "${automaton.nodes}"`);
+};
 /*  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
@@ -110,81 +188,15 @@ const checkConstraints = (config, posOfPath) => {
         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 ?? ""}`;
+            const ident = identityOf(object, depth > 1 ? "childs" : undefined);
             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()) {
-                /*  the relation shape flags apply to reference-valued
-                    properties only (an invalid expression is reported on
-                    its own, without a cascading flag diagnostic)  */
-                let expr;
-                if (prop.value !== undefined) {
-                    try {
-                        expr = compileValueExpr(prop.value);
-                    }
-                    catch (err) {
-                        diagnose([...at, "props", j, "value"], `invalid value expression "${prop.value}": ` +
-                            (err instanceof Error ? err.message : String(err)));
-                        continue;
-                    }
-                }
-                for (const flag of ["local", "symmetric", "acyclic"])
-                    if (prop[flag] === true && (expr === undefined || !admitsReferences(expr)))
-                        diagnose([...at, "props", j, flag], `"${flag}" flag requires a reference-valued property`);
-                /*  the sibling marker flags optionally carry a regexp or
-                    enum expression selecting the values they apply to  */
-                for (const flag of ["unique", "present"]) {
-                    const marker = prop[flag];
-                    if (typeof marker !== "string")
-                        continue;
-                    let kind;
-                    try {
-                        kind = compileValueExpr(marker).kind;
-                    }
-                    catch (err) {
-                        diagnose([...at, "props", j, flag], `invalid "${flag}" expression "${marker}": ` +
-                            (err instanceof Error ? err.message : String(err)));
-                    }
-                    if (kind !== undefined && kind !== "regex" && kind !== "enum")
-                        diagnose([...at, "props", j, flag], `"${flag}" expression "${marker}" is neither a regexp nor an enum`);
-                }
-            }
-            if (object.automaton !== undefined) {
-                /*  an automaton names the child kinds acting as nodes and
-                    edges, the reference-valued edge properties referencing
-                    the source and target nodes, and the node properties
-                    flagging the initial and final nodes  */
-                const automaton = object.automaton;
-                const childOf = (kind) => (object.childs ?? []).find((c) => c.kind === kind);
-                const propOf = (child, name) => (child?.props ?? []).find((p) => p.name === name);
-                const isReference = (prop) => {
-                    try {
-                        return prop.value !== undefined && admitsReferences(compileValueExpr(prop.value));
-                    }
-                    catch {
-                        return false;
-                    }
-                };
-                const nodes = childOf(automaton.nodes);
-                const edges = childOf(automaton.edges);
-                for (const [field, child] of [["nodes", nodes], ["edges", edges]])
-                    if (child === undefined)
-                        diagnose([...at, "automaton", field], `"automaton" ${field} kind "${automaton[field]}" is not a child object kind`);
-                for (const field of ["source", "target"]) {
-                    const prop = propOf(edges, automaton[field]);
-                    if (edges !== undefined && prop === undefined)
-                        diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not a property of "${automaton.edges}"`);
-                    else if (prop !== undefined && !isReference(prop))
-                        diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not reference-valued`);
-                }
-                for (const field of ["initial", "final"])
-                    if (nodes !== undefined && propOf(nodes, automaton[field]) === undefined)
-                        diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not a property of "${automaton.nodes}"`);
-            }
+            checkProperties(object.props ?? [], at, diagnose);
+            checkAutomaton(object, at, diagnose);
             for (const [j, entry] of (object.referenced ?? []).entries()) {
                 /*  a reference coverage entry has to be a single
                     (usually wildcard) reference expression  */
@@ -220,6 +232,8 @@ const checkConstraints = (config, posOfPath) => {
     has to be readable and syntactically valid on its own, while the
     merged result alone is validated  */
 export const loadConfig = (files) => {
+    if (files.length === 0)
+        throw new Error("no configuration files given");
     const diagnostics = new Array();
     /*  read and syntactically parse every configuration file into its
         document, keeping the line positions for the diagnostics  */
@@ -253,12 +267,14 @@ export const loadConfig = (files) => {
     }
     if (diagnostics.length > 0)
         return { diagnostics };
-    /*  merge the documents in order  */
-    const obj = docs.map(({ doc }) => doc.toJS())
+    /*  merge the documents in order, out of fresh conversions, as the
+        merge mutates its target while the raw ones have to stay intact
+        for the path translation  */
+    const merged = docs.map(({ doc }) => doc.toJS())
         .reduce((target, source) => mergeConfig(target, source));
     /*  semantically validate the merged result against the schema of the configuration  */
-    const posOfPath = (path) => posOfMergedPath(docs, obj, path);
-    const result = v.safeParse(Schema, obj);
+    const posOfPath = (path) => posOfMergedPath(docs, merged, path);
+    const result = v.safeParse(Schema, merged);
     if (!result.success) {
         for (const issue of result.issues) {
             /*  the path is rendered as it is in the positioned file  */

package/dst/specbook-diagnostic.js

@@ -23,6 +23,7 @@ export const renderDiagnosticVerbose = (diagnostic, colors = false) => {
     }
     if (code === "")
         return `${renderDiagnostic(diagnostic)}\n`;
-    return sourceCodeError({ message: renderMessage(diagnostic), filename: diagnostic.file,
+    return sourceCodeError({ type: diagnostic.severity === "warning" ? "WARNING" : "ERROR",
+        message: diagnostic.message, filename: diagnostic.file,
         code, line: diagnostic.line, column: diagnostic.column, colors });
 };

package/dst/specbook-diagram.d.ts

@@ -1,6 +1,7 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
 import type { Schema, SchemaDiagram } from "./specbook-format-schema.js";
 import type { ParseContext } from "./specbook-parse-common.js";
+import { type Verbose } from "./specbook-verbose.js";
 export interface DiagramError {
     reason: string;
     object?: SpecObject;
@@ -12,4 +13,7 @@ export interface DiagramResult {
     errors: DiagramError[];
 }
 export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;
+export declare const renderDiagrams: (specification: Spec, config: Schema, verbose?: Verbose) => Promise<Map<SpecObject, DiagramResult & {
+    svg: string;
+}>>;
 export declare const validateDiagrams: (ctx: ParseContext, specification: Spec, config: Schema) => void;