@rse/specbook 1.2.3 → 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,26 +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, a scroll progress meter (which
-    also scrolls back to the top on click), 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
 --------
@@ -101,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:
@@ -354,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):
@@ -369,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
@@ -413,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-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-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 ?? "")}`;
@@ -158,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  */
@@ -207,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
@@ -239,8 +239,8 @@ 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);
@@ -258,7 +258,7 @@ export const configStatistics = (config) => {
         for (const prop of object.props ?? [])
             if (prop.value !== undefined && admitsReferences(compileValueExpr(prop.value)))
                 links++;
-        for (const child of object.childs ?? [])
+        for (const child of object.children ?? [])
             walk(child);
     };
     for (const object of config)

package/dst/specbook-diagram.js

@@ -109,7 +109,7 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents,
         const walk = (object) => {
             objects.push(object);
             if (diagram.deep === true)
-                for (const child of object.childs)
+                for (const child of object.children)
                     if (!nodeSet.has(child))
                         walk(child);
         };
@@ -310,7 +310,7 @@ const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, parenProp
         /*  inject the synthetic center node into the node set, with a
             collision-free id ("@" never occurs in an anchor path)  */
         const center = { kind: centerCfg.kind ?? "",
-            id: `${anchors.get(object) ?? object.id}-@center`, name: label, properties: [], childs: [] };
+            id: `${anchors.get(object) ?? object.id}-@center`, name: label, properties: [], children: [] };
         nodes.unshift(center);
         nodeSet.add(center);
         return { center, centerUrl };
@@ -363,7 +363,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
         nodes = new Array();
         const walk = (o) => {
             nodes.push(o);
-            o.childs.forEach(walk);
+            o.children.forEach(walk);
         };
         walk(object);
     }

package/dst/specbook-export-ast.js

@@ -23,7 +23,7 @@ export const renderAst = (specification, format, config) => {
             const result = diagrams.get(object);
             if (result?.spec !== undefined && !isTitleObject(object))
                 node.diagram = result.spec;
-            object.childs.forEach((child, i) => walk(child, node.childs[i]));
+            object.children.forEach((child, i) => walk(child, node.children[i]));
         };
         specification.artifacts.forEach((artifact, i) => artifact.objects.forEach((object, j) => walk(object, plain.artifacts[i].objects[j])));
     }

package/dst/specbook-export-common.js

@@ -26,7 +26,7 @@ export const titleObject = (specification) => {
         for (const object of objects) {
             if (isTitleObject(object))
                 return object;
-            const found = search(object.childs);
+            const found = search(object.children);
             if (found !== undefined)
                 return found;
         }

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

@@ -4,7 +4,7 @@ import type { Verbose } from "./specbook-verbose.js";
 export type OutlineEntry = {
     title: string;
     anchor: string;
-    childs: OutlineEntry[];
+    children: OutlineEntry[];
 };
 export declare const htmlOutline: (specification: Spec, config?: Schema) => OutlineEntry[];
 export declare const titlePageObject: (specification: Spec) => SpecObject | undefined;