@rse/specbook 1.2.2 → 1.2.4

package/README.md

@@ -6,6 +6,9 @@ SpecBook
 
 **Markdown-based Specification Format**
 
+[![github (author stars)](https://img.shields.io/github/stars/rse?logo=github&label=author%20stars&color=%233377aa)](https://github.com/rse)
+[![github (author followers)](https://img.shields.io/github/followers/rse?label=author%20followers&logo=github&color=%234477aa)](https://github.com/rse)
+
 About
 -----
 
@@ -43,10 +46,15 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 -   **Strict Validation with Custom Schema**:
     The YAML schema configuration strictly defines the allowed object
     kinds, hierarchies, and properties, whose values are constrained by an
-    expression language (regex, enum, tags, list, and reference). Violations
-    are reported as file- and line-precise diagnostics, while the reference
-    coverage an object kind demands is reported as a warning only. A bundled
-    standard schema configuration applies if no particular one is given.
+    expression language (regex, enum, tags, list, and reference). Beyond the
+    plain values, it constrains the uniqueness and presence of a property
+    among the sibling objects and the shape of a reference-valued property
+    (local, symmetric, and/or acyclic), and it can declare the child objects
+    of an object kind a finite state machine, whose reachability, dead-ends,
+    and livelocks are then checked. Violations are reported as file- and
+    line-precise diagnostics, while the reference coverage an object kind
+    demands is reported as a warning only. A bundled standard schema
+    configuration applies if no particular one is given.
 
 -   **Object Model Diagram Visualisation**:
     Object kinds can declare "graph", "hub", or "grid" diagrams in the
@@ -63,25 +71,39 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 
 -   **AST Exports for AI/LLMs**:
     The parsed specification Abstract Syntax Tree (AST) can be exported in
-    JSON, JSON5, YAML, or TOON format for machine consumption. Together
-    with the `describe` command, which explains the models and formats,
-    this enables LLMs to both read and write specifications.
+    JSON, JSON5, YAML, or TOON format for machine consumption, with the
+    derived diagram of an object attached to it as a textual Gradia spec.
+    Together with the `describe` command, which explains the models and
+    formats, this enables LLMs to both read and write specifications.
 
 -   **HTML Export for Developers**:
-    The HTML export is a self-contained single document with a
-    table-of-contents (also as a slide-in side panel for quick navigation),
-    full-text search, embedded images, and a light/dark
-    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. The HTML export even can be
-    previewed in the browser with live updates.
+    The HTML export is a self-contained single document with a title page,
+    a table-of-contents (also as a slide-in side panel for quick navigation),
+    a diagram-of-contents, a fuzzy full-text search, embedded images, a
+    scroll progress meter (which also scrolls back to the top on click),
+    description popups (which show the schema and corpus description of
+    an object kind, property, or object instance on hover), and a
+    light/dark 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. 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
-    it with page numbers, headers/footers, and a hierarchical PDF outline.
-    It is intended as a polished, paginated offline document for handing
-    over to customers.
+    it with page numbers, headers/footers, a brand bar, and a hierarchical
+    PDF outline. The paper size (A4, Letter, or Legal) drives the pagination
+    and scales the diagrams down to fit onto a single page. It is intended
+    as a polished, paginated offline document for handing over to customers.
+
+-   **Document Theming and Typography**:
+    The title object of the specification drives the entire document:
+    its title, subtitle, author, version, and logo fill the title page
+    (with an optional light/dark variant of the logo), its language
+    selects the smart typography quote style, its color tone seeds the
+    theme color spreads of both the light and the dark theme, and its
+    character set subsets the embedded fonts down to the actually needed
+    glyphs.
 
 Overview
 --------
@@ -100,170 +122,6 @@ $ npm install -g @rse/specbook
 Usage
 -----
 
-### API
-
-```ts
-/*  the SpecBook API, providing all commands the CLI and MCP service expose  */
-export class SpecBook {
-    constructor (options?: SpecBookOptions)
-
-    /*  initialize the configured specification artifact files below the
-        base directory and return the list of the generated files  */
-    init (options: {
-        config?:  string[],        /*  YAML schema configuration files or glob patterns, merged
-                                       in order (default: bundled standard one, named "std")  */
-        basedir?: string           /*  base directory (default: ".")  */
-    }): Promise<string[]>
-
-    /*  parse and validate the specification Markdown files below the base directory  */
-    lint (options: {
-        config?:  string[],
-        basedir?: string
-    }): Promise<LintResult>
-
-    /*  export the specification, parsing the input just once and
-        returning one buffer per requested format (strict: any error
-        diagnostic rejects the export with an "Error", while the warnings
-        are surfaced as "notice" verbose messages)  */
-    export (options: {
-        config?:  string[],
-        basedir?: string,
-        formats?: ExportFormat[],  /*  requested output formats (default: [ "json" ])  */
-        realtime?: boolean         /*  inject the live preview script into the HTML  */
-    }): Promise<Buffer[]>
-
-    /*  export the specification like "export" and then keep it in sync by
-        re-exporting it on every change of a specification file (a failed
-        re-export is reported and leaves the observe loop intact)  */
-    watch (options: {
-        config?:  string[],
-        basedir?: string,
-        formats?: ExportFormat[],
-        realtime?: boolean,
-        outputs?: string[],        /*  paths "onExport" writes, refused if observed  */
-        onExport: (buffers: Buffer[]) => void | Promise<void>
-    }): Promise<void>
-
-    /*  serve the HTML export as a live preview on "http://<addr>:<port>/",
-        kept in sync like "watch" and updated in the browser on every change  */
-    preview (options: {
-        config?:  string[],
-        basedir?: string,
-        addr?:    string,          /*  listening IP address (default: "127.0.0.1")  */
-        port?:    number           /*  listening TCP port (default: 12345)  */
-    }): Promise<void>
-
-    /*  describe the SpecBook models and formats, optionally pointing to
-        the artifacts of the particular project  */
-    describe (options: {
-        config?:  string[],
-        basedir?: string,
-        embed?:   boolean,         /*  embed the schema configuration instead of referencing it  */
-        compress?: CompressLevel,  /*  compression level of the schema configuration (default: 1)  */
-        format?:  DescribeFormat,  /*  output format (default: "md")  */
-        part?:    DescribePart     /*  document part (default: "all")  */
-    }): Promise<string>
-}
-
-/*  the constructor options and the sink of the verbose messages,
-    receiving the emitting command and the message  */
-export interface SpecBookOptions {
-    verbose?:      VerboseSink
-}
-export type VerboseSink = (cmd: string, msg: string) => void
-
-/*  the result of the "lint" command and its file- and line-precise diagnostics  */
-export interface LintResult {
-    specification: Spec
-    diagnostics:   Diagnostic[]
-    config?:       Schema
-    files:         string[]    /*  the artifact files plus their embedded assets  */
-}
-export interface Diagnostic {
-    file:          string
-    line:          number
-    column:        number
-    severity:      "error" | "warning"
-    message:       string
-}
-
-/*  the supported export formats and describe formats/parts/compression levels  */
-export const formats:         readonly [ "json", "json5", "yaml", "toon", "html", "pdf", "md" ]
-export const describeFormats: readonly [ "md", "raw" ]
-export const describeParts:   readonly [ "all", "meta", "schema", "spec" ]
-export const compressLevels:  readonly [ 0, 1, 2, 3 ]
-export type  ExportFormat   = typeof formats[number]
-export type  DescribeFormat = typeof describeFormats[number]
-export type  DescribePart   = typeof describeParts[number]
-export type  CompressLevel  = typeof compressLevels[number]
-
-/*  the Abstract Syntax Tree (AST) of a parsed specification  */
-export type Spec = {
-    artifacts:     SpecArtifact[]
-}
-export type SpecArtifact = {
-    created:       Date
-    modified:      Date
-    objects:       SpecObject[]
-}
-export type SpecObject = {
-    kind:          string
-    id:            string
-    anchor?:       string
-    paren?:        string
-    name:          string
-    primary?:      boolean
-    description?:  SpecDescription
-    properties:    SpecProperty[]
-    childs:        SpecObject[]
-}
-export type SpecDescription = {
-    description:   string
-    rationale?:    string
-    embedding?:    string[]
-}
-export type SpecProperty = {
-    key:           string
-    value:         string
-    embedding?:    string[]
-}
-
-/*  the YAML schema configuration, where the nested "diagram" and
-    "format" structures are detailed in the "describe" output  */
-export type Schema = SchemaObject[]
-export type SchemaObject = {
-    kind:          string
-    name?:         string
-    id?:           string
-    file?:         string
-    desc?:         string
-    optional?:     boolean
-    diagram?:      SchemaDiagram
-    format?:       SchemaFormat
-    props?:        SchemaProperty[]
-    childs?:       SchemaObject[]
-}
-export type SchemaProperty = {
-    name:          string
-    desc?:         string
-    value?:        string
-    optional?:     boolean
-}
-```
-
-Example:
-
-```ts
-import { SpecBook } from "@rse/specbook"
-
-const specbook = new SpecBook({
-    verbose: (cmd, msg) => console.error(`specbook: ${cmd}: ${msg}`)
-})
-const result = await specbook.lint({
-    basedir: "smp/broadcast"
-})
-```
-
 ### CLI
 
 Commands:
@@ -353,13 +211,14 @@ Options:
 
 -   `-w|--watch` (`export` only):
     Keep the outputs in sync with their sources: after the regular export,
-    the referenced artifact files and all assets they embed are observed,
-    and every change re-exports the specification once the sources stayed
-    silent for one second. A failed re-export is reported and leaves the
-    observe loop intact, so a transiently invalid specification does not
-    end the watch. The outputs have to be regular files, as `-` (stdout)
-    cannot receive a repeated export, and none of them may be an observed
-    source file itself, as its own write would re-trigger the observation
+    the YAML schema configuration files, the referenced artifact files, and
+    all assets they embed are observed, and every change re-exports the
+    specification once the sources stayed silent for one second. 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 outputs have to be regular files, as `-` (stdout) cannot
+    receive a repeated export, and none of them may be an observed source
+    file itself, as its own write would re-trigger the observation
     endlessly.
 
 -   `-a|--addr <ip-addr>`, `-p|--port <tcp-port>` (`preview` only):
@@ -368,11 +227,13 @@ Options:
     `http://<ip-addr>:<tcp-port>/`, kept in sync with its sources exactly
     like `export --watch`, and updated in the browser after every change
     through a WebSocket connection the served page keeps open, where the
-    document is replaced in place, so the scroll position survives (a
-    failed re-export keeps the previous HTML in place). A status icon
-    left of the theme switcher shows the connection state: grey while
-    connected, in the search highlight color while disconnected, and
-    blinking for 2s after every update.
+    document is replaced in place, so the scroll position and the theme
+    choice survive (a failed re-export keeps the previous HTML in place,
+    and a request before the first successful export is answered with a
+    placeholder page which replaces itself with the document once that
+    export arrives). A status tab at the bottom of the brand bar shows
+    the connection state: its plug icon carries the search highlight
+    color while disconnected and blinks for 2s after every update.
 
 -   `-o|--output <output-file>` (`describe` only):
     The output file (default: `-` for stdout) receives the described
@@ -412,26 +273,74 @@ explicitly supplied option always wins. As `-c|--config` is repeatable,
 `SPECBOOK_CONFIG` carries a list of patterns separated by the path
 delimiter of the platform (`:` on Unix, `;` on Windows).
 
-Example:
+Example: Simple
+---------------
+
+Check out the *simple* specification of simple
+example data model:
+
+### Sources
+
+-   [Specification](smp/sample/sample.md)
+-   [Schema](smp/sample/sample.yaml)
+
+### Generation
 
 ```bash
-$ specbook lint -v -b smp/broadcast
+$ specbook lint -v \
+    -b smp/sample \
+    -o smp/sample/sample.html \
+    -o smp/sample/sample.pdf
 ```
 
-Rendering Examples
-------------------
+### HTML Rendering
+
+![screenshot-sample-light](etc/screenshot-sample-light.png)
+![screenshot-sample-dark](etc/screenshot-sample-dark.png)
 
-### HTML Rendering (Light Theme)
+Example: Complex
+----------------
 
-![screenshot-light](etc/screenshot-light.png)
+Check out the *complex* specification of the Broadcast
+application, based on **SpecBook**'s built-in "standard" schema:
 
-### HTML Rendering (Dark Theme)
+### Sources
 
-![screenshot-dark](etc/screenshot-dark.png)
+-   [Specification](smp/broadcast/)
+-   [Schema](src/specbook-format.d/)
+
+### Generation
+
+```bash
+$ specbook lint -v \
+    -b smp/broadcast \
+    -o smp/broadcast/broadcast.html \
+    -o smp/broadcast/broadcast.pdf
+```
+
+### HTML Rendering
+
+![screenshot-broadcast-light](etc/screenshot-broadcast-light.png)
+![screenshot-broadcast-dark](etc/screenshot-broadcast-dark.png)
 
 ### PDF Rendering
 
-![screenshot-print](etc/screenshot-print.png)
+![screenshot-broadcast-print](etc/screenshot-broadcast-print.png)
+
+See Also
+--------
+
+- [Gradia](https://github.com/rse/gradia)
+- [ASE](https://ase.tools)
+
+Support
+-------
+
+**SpecBook** is developed in the experience context of industrial Software
+Engineering at the [*msg group*](https://www.msg.group) and in the
+educational context of the *Software Engineering Academy (SEA)*. **SpecBook**
+development is supported by *msg Research* and *Software Engineering
+Academy (SEA)*.
 
 License
 -------

package/dst/specbook-api.js

@@ -7,7 +7,7 @@ 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 { loadConfig, configStatistics } 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";
@@ -69,6 +69,9 @@ export class SpecBook {
         if (config === undefined)
             throw new Error("invalid configuration:\n" +
                 diagnostics.map(renderDiagnostic).join("\n"));
+        const stats = configStatistics(config);
+        verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
+            `and ${literal(stats.links)} link relationship(s)`);
         return config;
     }
     /*  initialize the configured specification artifact files
@@ -112,8 +115,9 @@ export class SpecBook {
             export fail before the specification is even parsed  */
         if (requested.includes("pdf"))
             await requireBrowser(verbose);
-        return this.renderFormats(lint({ config: await this.configFiles(options.config),
-            basedir: options.basedir ?? ".", verbose }), requested, verbose, options.realtime === true);
+        const result = lint({ config: await this.configFiles(options.config),
+            basedir: options.basedir ?? ".", verbose });
+        return this.renderFormats(result, requested, verbose, options.realtime === true);
     }
     /*  keep an export in sync with its sources (the shared core of
         "watch" and "preview"): every change of a configuration file, of an

package/dst/specbook-cmd-describe.js

@@ -78,13 +78,13 @@ const schemaSection = (config, schema, embed, standard, 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";
+    `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n";
 };
 /*  render the reference to the specification Markdown files  */
 const specSection = (basedir) => textframe(`
         The **SpecBook SPEC Model** is the set of Markdown specification files in directory:
         @${basedir}
-    `) + "\n";
+    `);
 /*  describe the generic SpecBook models and formats as Markdown,
     optionally extended by the references to (or the embeddings of) the
     artifacts of the particular project instantiation, and optionally

package/dst/specbook-cmd-export.js

@@ -3,7 +3,10 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { watch } from "chokidar";
+/*  Chokidar is aliased in "package.json", as Nunjucks declares the
+    (unused) Chokidar 3 as an optional peer dependency and the current
+    Chokidar under its plain name would raise a peer warning on install  */
+import { watch } from "chokidar5";
 import { minify } from "@swc/html";
 import { documentTitle, documentLogo, documentCharset, documentThemeTone, subsetStylesheet, documentPaperSize, paperStylesheet, charsetCodepoints } from "./specbook-export-common.js";
 import { themeColors, themeStylesheet, themeMapping } from "./specbook-theme.js";

package/dst/specbook-cmd-lint.js

@@ -5,9 +5,9 @@
 */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { loadConfig } from "./specbook-config.js";
+import { loadConfig, configStatistics } from "./specbook-config.js";
 import { literal } from "./specbook-verbose.js";
-import { parseSpecification, resolveArtifact } from "./specbook-parse.js";
+import { parseSpecification, specStatistics, resolveArtifact } from "./specbook-parse.js";
 /*  collect the distinct artifact files the schema configuration
     references, in their declaration order, each mapped onto whether
     all of its artifacts are optional and hence the file may be absent  */
@@ -30,6 +30,11 @@ export const lint = (options) => {
     const loaded = loadConfig(options.config);
     diagnostics.push(...loaded.diagnostics);
     const config = loaded.config;
+    if (config !== undefined) {
+        const stats = configStatistics(config);
+        options.verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
+            `and ${literal(stats.links)} link relationship(s)`);
+    }
     /*  read the artifact files the configuration references, resolved
         against the base directory and tolerating an absent file if all
         its artifacts are optional  */
@@ -64,6 +69,9 @@ export const lint = (options) => {
     const result = parseSpecification(sources, config);
     diagnostics.push(...result.diagnostics);
     watched.push(...result.assets);
+    const stats = specStatistics(result.specification);
+    options.verbose(`parsed specification defining ${literal(stats.objects)} object(s) ` +
+        `and ${literal(stats.links)} link relationship(s)`);
     /*  report the non-optional artifacts absent from the specification,
         against their loaded artifact file (an absent or unreadable file
         is already reported above) or else against the configuration  */

package/dst/specbook-cmd-preview.js

@@ -10,11 +10,6 @@ import { literal } from "./specbook-verbose.js";
 /*  the default listening address and port of the preview server  */
 export const previewAddr = "127.0.0.1";
 export const previewPort = 12345;
-/*  the placeholder page answering a GET before the first successful
-    export: it still carries the live preview client, so the browser
-    subscribes to the "RELOAD" command right away and replaces itself
-    with the document once the first export arrives  */
-const placeholder = renderPlaceholder("no specification export available yet");
 /*  serve the live HTML preview: a plain GET on "/" answers with the
     most recent HTML export (or with the 503 placeholder page before the
     first successful one), while a WebSocket upgrade on "/" subscribes
@@ -24,16 +19,18 @@ export const servePreview = async (options) => {
     const clients = new Set();
     const fastify = Fastify();
     await fastify.register(fastifyWebsocket);
+    /*  the placeholder page answering a GET before the first successful
+        export: it still carries the live preview client, so the browser
+        subscribes to the "RELOAD" command right away and replaces itself
+        with the document once the first export arrives  */
+    const placeholder = renderPlaceholder("no specification export available yet");
     /*  answer a plain GET with the document and subscribe a WebSocket upgrade  */
     fastify.route({
         method: "GET",
         url: "/",
         handler: (_request, reply) => {
-            if (html === undefined)
-                return reply.code(503).type("text/html; charset=utf-8")
-                    .header("cache-control", "no-store").send(placeholder);
-            return reply.type("text/html; charset=utf-8")
-                .header("cache-control", "no-store").send(html);
+            reply.type("text/html; charset=utf-8").header("cache-control", "no-store");
+            return html === undefined ? reply.code(503).send(placeholder) : reply.send(html);
         },
         wsHandler: (socket, request) => {
             /*  identify the client by its remote address and port  */

package/dst/specbook-config.d.ts

@@ -1,5 +1,9 @@
 import { Schema } from "./specbook-format-schema.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
+export declare const configStatistics: (config: Schema) => {
+    objects: number;
+    links: number;
+};
 export declare const loadConfig: (files: string[]) => {
     config?: Schema;
     diagnostics: Diagnostic[];

package/dst/specbook-config.js

@@ -33,7 +33,7 @@ const identityOf = (item, list) => {
     const object = item;
     if (list === "props")
         return String(object.name ?? "");
-    else if (list === "childs")
+    else if (list === "children")
         return String(object.kind ?? "");
     else
         return `${String(object.kind ?? "")}:${String(object.id ?? object.name ?? "")}`;
@@ -48,14 +48,15 @@ const mergeConfig = (target, source, list) => {
     if (source === null || source === undefined)
         return target;
     else if (Array.isArray(target) && Array.isArray(source)) {
+        const items = target;
         for (const item of source) {
-            const i = target.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
+            const i = items.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
             if (i < 0)
-                target.push(item);
+                items.push(item);
             else
-                target[i] = mergeConfig(target[i], item, list);
+                items[i] = mergeConfig(items[i], item, list);
         }
-        return target;
+        return items;
     }
     else if (isPlainObject(target) && isPlainObject(source))
         return mergeWith(target, source, (t, s, key) => Array.isArray(t) && Array.isArray(s) ? mergeConfig(t, s, key) : undefined);
@@ -90,7 +91,10 @@ const posOfMergedPath = (docs, merged, path) => {
         for (const segment of path) {
             const key = typeof segment === "number" && Array.isArray(own) ?
                 own.findIndex((item) => identityOf(item, list) === identityOf(at(node, segment), list)) : segment;
-            if (typeof key === "number" ? !Array.isArray(own) || key < 0 : !isPlainObject(own) || !(key in own))
+            const reaches = typeof key === "number" ?
+                Array.isArray(own) && key >= 0 :
+                isPlainObject(own) && key in own;
+            if (!reaches)
                 break;
             translated.push(key);
             node = at(node, segment);
@@ -154,7 +158,7 @@ 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 childOf = (kind) => (object.children ?? []).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  */
@@ -203,7 +207,7 @@ const checkConstraints = (config, posOfPath) => {
         const seen = new Set();
         for (const [i, object] of objects.entries()) {
             const at = [...path, i];
-            const ident = identityOf(object, depth > 1 ? "childs" : undefined);
+            const ident = identityOf(object, depth > 1 ? "children" : undefined);
             if (seen.has(ident))
                 diagnose([...at, "kind"], `object "${ident}" collides with a preceding sibling object (the later one is unreachable)`);
             else
@@ -235,13 +239,32 @@ const checkConstraints = (config, posOfPath) => {
                         (err instanceof Error ? err.message : String(err)));
                 }
             }
-            if (object.childs !== undefined)
-                check(object.childs, [...at, "childs"], depth + 1);
+            if (object.children !== undefined)
+                check(object.children, [...at, "children"], depth + 1);
         }
     };
     check(config, [], 1);
     return diagnostics;
 };
+/*  the statistics of a schema configuration: the number of specified
+    object kinds (recursively) and of relationship kinds, i.e. the
+    reference-valued properties (whose expressions are valid, as the
+    configuration is validated before use)  */
+export const configStatistics = (config) => {
+    let objects = 0;
+    let links = 0;
+    const walk = (object) => {
+        objects++;
+        for (const prop of object.props ?? [])
+            if (prop.value !== undefined && admitsReferences(compileValueExpr(prop.value)))
+                links++;
+        for (const child of object.children ?? [])
+            walk(child);
+    };
+    for (const object of config)
+        walk(object);
+    return { objects, links };
+};
 /*  load and validate the YAML schema configuration, merged in order out
     of its files (the later ones into the earlier ones), where every file
     has to be readable and syntactically valid on its own, while the
@@ -282,10 +305,10 @@ export const loadConfig = (files) => {
     }
     if (diagnostics.length > 0)
         return { diagnostics };
-    /*  merge the documents in order, out of fresh and unshared
-        conversions, as the merge mutates its target while the raw ones
-        have to stay intact for the path translation  */
-    const merged = docs.map(({ doc }) => unshared(doc.toJS()))
+    /*  merge the documents in order, out of unshared deep copies of
+        the conversions, as the merge mutates its target while the raw
+        ones have to stay intact for the path translation  */
+    const merged = docs.map(({ raw }) => unshared(raw))
         .reduce((target, source) => mergeConfig(target, source));
     /*  semantically validate the merged result against the schema of the configuration  */
     const posOfPath = (path) => posOfMergedPath(docs, merged, path);