@rse/specbook 1.5.2 → 1.6.1

package/dst/specbook-cmd-query.js

@@ -0,0 +1,165 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import ASTQ from "astq";
+import { Marked } from "marked";
+import JSON5 from "json5";
+import { stringify as stringifyYaml } from "yaml";
+import { encode as encodeToon } from "@toon-format/toon";
+import { buildLinkIndex, referenceTargets, resolveUnique, expandReferences } from "./specbook-link.js";
+import { parseOutputSpec } from "./specbook-cmd-export.js";
+/*  the fixed attributes of an object node, which win over
+    the same-named property keys  */
+const objectFields = ["kind", "id", "anchor", "paren", "name", "primary",
+    "description", "rationale", "elaboration"];
+/*  the private Markdown renderer of the text helpers, as the
+    "marked" singleton is shared with the application  */
+const marked = new Marked();
+/*  render Markdown tokens into plain text: the blocks joined by the
+    separator, the inline markup dropped, and the code kept verbatim  */
+const plainOf = (tokens, separator) => tokens.map((generic) => {
+    const token = generic;
+    if (token.type === "space" || token.type === "hr" || token.type === "html" || token.type === "def")
+        return "";
+    else if (token.type === "code" || token.type === "codespan")
+        return token.text;
+    else if (token.type === "br")
+        return "\n";
+    else if (token.type === "blockquote")
+        return plainOf(token.tokens, "\n\n");
+    else if (token.type === "list")
+        return token.items.map((item) => plainOf(item.tokens, "\n")).join("\n");
+    else if (token.type === "table")
+        return [token.header, ...token.rows].map((row) => row.map((cell) => plainOf(cell.tokens, "")).join(" | ")).join("\n");
+    else if ("tokens" in token && token.tokens !== undefined)
+        return plainOf(token.tokens, "");
+    else
+        return "text" in token ? token.text : "";
+}).filter((part) => part !== "").join(separator);
+/*  the serialization formats of the query results (the AST export ones)  */
+export const queryFormats = ["json", "json5", "yaml", "toon"];
+/*  determine the format and file of a query output: an explicit format
+    wins, else it is inferred exactly like the one of an export output
+    (a "<format>:" prefix, else the filename extension, "-" being JSON),
+    where only the serialization formats apply  */
+export const parseQueryOutput = (output, format) => {
+    const spec = format !== undefined ? { format, output } : parseOutputSpec(output);
+    if (!queryFormats.includes(spec.format))
+        throw new Error(`unsupported query format "${spec.format}" (supported: ${queryFormats.join(", ")})`);
+    return { format: spec.format, output: spec.output };
+};
+/*  render query result nodes in a serialization format: their subtrees
+    included, the embedded file contents dropped (the bulk no consumer
+    can use), and the dates as ISO strings  */
+export const renderNodes = (nodes, format = "json") => {
+    const plain = JSON.parse(JSON.stringify(nodes, (key, value) => key === "embedding" ? undefined : value));
+    if (format === "json")
+        return JSON.stringify(plain, null, 4) + "\n";
+    else if (format === "json5")
+        return JSON5.stringify(plain, null, 4) + "\n";
+    else if (format === "yaml")
+        return stringifyYaml(plain);
+    else
+        return encodeToon(plain) + "\n";
+};
+/*  a loaded specification, queryable through the XPath-like ASTq
+    selectors: the root node (type "specification") holds the artifacts
+    (type "artifact"), which hold the object trees (typed by their kind,
+    whitespace dashed), and the pre-registered function "refs()" yields
+    the objects the references of the current object resolve to  */
+export class SpecBookDocument {
+    specification;
+    config;
+    diagnostics;
+    astq = new ASTQ();
+    parents = new WeakMap();
+    attrs = new WeakMap();
+    index;
+    constructor(specification, config, diagnostics, origins) {
+        this.specification = specification;
+        this.config = config;
+        this.diagnostics = diagnostics;
+        this.index = buildLinkIndex(specification);
+        /*  index the parents once, as the objects carry no parent reference  */
+        const walk = (object, parent) => {
+            this.parents.set(object, parent);
+            for (const child of object.children)
+                walk(child, object);
+        };
+        for (const artifact of specification.artifacts) {
+            this.parents.set(artifact, specification);
+            for (const object of artifact.objects)
+                walk(object, artifact);
+        }
+        /*  determine the attributes of a node once: the timestamps and
+            source file of an artifact, and the fixed fields of an object
+            followed by its properties (the first of duplicate keys winning)  */
+        const attributesOf = (node) => {
+            let attrs = this.attrs.get(node);
+            if (attrs === undefined) {
+                attrs = new Map();
+                if ("objects" in node) {
+                    attrs.set("created", node.created.toISOString());
+                    attrs.set("modified", node.modified.toISOString());
+                    attrs.set("file", origins.get(node));
+                }
+                else if ("kind" in node) {
+                    const fields = [node.kind, node.id, node.anchor, node.paren, node.name, node.primary,
+                        node.description?.description, node.description?.rationale, node.description?.elaboration];
+                    for (const [i, value] of fields.entries())
+                        if (value !== undefined)
+                            attrs.set(objectFields[i], value);
+                    for (const property of node.properties)
+                        if (!objectFields.includes(property.key) && !attrs.has(property.key))
+                            attrs.set(property.key, property.value);
+                }
+                this.attrs.set(node, attrs);
+            }
+            return attrs;
+        };
+        /*  access the specification tree exclusively, as the plain AST
+            objects would otherwise be tasted by the built-in JSON adapter  */
+        const adapter = {
+            taste: (node) => node === specification || this.parents.has(node),
+            getParentNode: (node) => this.parents.get(node) ?? null,
+            getChildNodes: (node) => "artifacts" in node ? node.artifacts :
+                "objects" in node ? node.objects : node.children,
+            getNodeType: (node) => "artifacts" in node ? "specification" :
+                "objects" in node ? "artifact" : node.kind.replace(/\s+/g, "-"),
+            getNodeAttrNames: (node) => Array.from(attributesOf(node).keys()),
+            getNodeAttrValue: (node, attr) => attributesOf(node).get(attr)
+        };
+        this.astq.adapter(adapter, true);
+        this.astq.func("refs", (_adapter, node) => "kind" in node ? referenceTargets(this.index, node) : []);
+    }
+    /*  query the nodes an ASTq selector matches, starting at the root,
+        with the values of the "{name}" parameters of the selector  */
+    query(selector, params) {
+        return this.astq.query(this.specification, selector, params);
+    }
+    /*  the parent of a node (undefined for the root)  */
+    parent(node) {
+        return this.parents.get(node);
+    }
+    /*  register a custom query function (or replace a registered one)  */
+    func(name, fn) {
+        this.astq.func(name, fn);
+        return this;
+    }
+    /*  replace the references of a Markdown text (outside its code) by
+        the names of their targets, resolved nearest to the referencing
+        object (if given), an unresolvable one keeping its reference text  */
+    expand(text, from) {
+        return expandReferences(text, (reference) => resolveUnique(this.index, reference, from).target?.name ?? reference);
+    }
+    /*  render a Markdown text (a description part or property value) into plain text  */
+    plain(text, from) {
+        return plainOf(marked.lexer(this.expand(text, from)), "\n\n");
+    }
+    /*  render a Markdown text (a description part or property value) into an HTML fragment  */
+    html(text, from) {
+        return marked.parse(this.expand(text, from), { async: false });
+    }
+}

package/dst/specbook-config.d.ts

@@ -1,11 +1,17 @@
 import { LineCounter, type Document } from "yaml";
-import { Schema } from "./specbook-format-schema.js";
+import { Schema, type SchemaObject, type SchemaProperty } from "./specbook-format-schema.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
 type YamlPath = (string | number)[];
 export declare const lineColOfPath: (doc: Document, lines: LineCounter, path: YamlPath) => {
     line: number;
     column: number;
 };
+export interface ConfigOverlap {
+    artifact: string;
+    files: string[];
+}
+export type ConfigOrigins = Map<string, string[]>;
+export declare const originKey: (chain: SchemaObject[], prop?: SchemaProperty) => string;
 export declare const configStatistics: (config: Schema) => {
     objects: number;
     links: number;
@@ -13,5 +19,7 @@ export declare const configStatistics: (config: Schema) => {
 export declare const loadConfig: (files: string[]) => {
     config?: Schema;
     diagnostics: Diagnostic[];
+    overlaps: ConfigOverlap[];
+    origins: ConfigOrigins;
 };
 export {};

package/dst/specbook-config.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import { parseDocument, isNode, LineCounter } from "yaml";
 import * as v from "valibot";
 import { mergeWith, isPlainObject } from "es-toolkit";
-import { Schema } from "./specbook-format-schema.js";
+import { Schema, diagramsOf, reservedAttributes } from "./specbook-format-schema.js";
 import { compileValueExpr, anchored, admitsReferences } from "./specbook-parse-value.js";
 /*  determine line/column of a YAML document path via the node ranges
     of the parsed document, falling back to the closest ancestor node  */
@@ -25,14 +25,16 @@ export const lineColOfPath = (doc, lines, path) => {
 /*  the identity by which the elements of the lists of the configuration
     are matched on merging: the artifacts by their kind plus id or name
     and the nested objects by their kind alone (exactly like the sibling
-    resolution), the properties by their name, and the scalar entries
-    by their value  */
+    resolution), the properties by their name, the diagrams by their
+    type, and the scalar entries by their value  */
 const identityOf = (item, list) => {
     if (!isPlainObject(item))
         return String(item);
     const object = item;
     if (list === "props")
         return String(object.name ?? "");
+    else if (list === "diagram")
+        return String(object.type ?? "graph");
     else if (list === "children")
         return String(object.kind ?? "");
     else
@@ -60,7 +62,15 @@ const mergeConfig = (target, source, list) => {
         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);
+        return mergeWith(target, source, (t, s, key) => {
+            if (Array.isArray(t) && Array.isArray(s))
+                return mergeConfig(t, s, key);
+            /*  a single diagram and a list of diagrams merge as lists  */
+            if (key === "diagram" && (Array.isArray(t) || Array.isArray(s))
+                && t !== undefined && t !== null && s !== undefined && s !== null)
+                return mergeConfig(Array.isArray(t) ? t : [t], Array.isArray(s) ? s : [s], key);
+            return undefined;
+        });
     else
         return source;
 };
@@ -75,6 +85,59 @@ const unshared = (value) => {
     else
         return value;
 };
+/*  the key of a node of the merged configuration in its origins: the
+    identities of the object kinds along its path (the artifact first),
+    plus the identity of a property of the last one  */
+export const originKey = (chain, prop) => chain.map((object, i) => identityOf(object, i > 0 ? "children" : undefined)).join("/") +
+    (prop !== undefined ? `#${identityOf(prop, "props")}` : "");
+/*  determine the configuration files contributing every object kind
+    and property, by walking the raw documents along the very identities
+    the merge matches the list elements with  */
+const originsOf = (docs) => {
+    const origins = new Map();
+    const add = (key, file) => {
+        const files = origins.get(key) ?? [];
+        if (!files.includes(file))
+            files.push(file);
+        origins.set(key, files);
+    };
+    const walk = (items, prefix, depth, file) => {
+        if (!Array.isArray(items))
+            return;
+        for (const item of items) {
+            if (!isPlainObject(item))
+                continue;
+            const object = item;
+            const key = (prefix !== "" ? `${prefix}/` : "") + identityOf(item, depth > 1 ? "children" : undefined);
+            add(key, file);
+            if (Array.isArray(object.props))
+                for (const prop of object.props)
+                    if (isPlainObject(prop))
+                        add(`${key}#${identityOf(prop, "props")}`, file);
+            walk(object.children, key, depth + 1, file);
+        }
+    };
+    for (const { file, raw } of docs)
+        walk(raw, "", 1, file);
+    return origins;
+};
+/*  determine the artifacts several configuration files define  */
+const overlapsOf = (docs) => {
+    const defined = new Map();
+    for (const { file, raw } of docs)
+        if (Array.isArray(raw))
+            for (const item of raw) {
+                if (!isPlainObject(item))
+                    continue;
+                const object = item;
+                const kind = String(object.kind ?? "");
+                const label = object.id !== undefined ? `${kind} (${String(object.id)})` : `${kind}: ${String(object.name ?? "")}`;
+                const overlap = defined.get(identityOf(item)) ?? { artifact: label, files: [] };
+                overlap.files.push(file);
+                defined.set(identityOf(item), overlap);
+            }
+    return Array.from(defined.values()).filter((overlap) => overlap.files.length > 1);
+};
 /*  determine file and line/column of a path into the merged
     configuration by translating the path into every document (from the
     last to the first one, as a later document overrides an earlier one),
@@ -190,6 +253,58 @@ const checkAutomaton = (object, at, diagnose) => {
         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 diagrams of an object (if any): a displayed property must
+    not be named like a node attribute Gradia consumes instead of
+    displaying it (e.g. "mark" or "layer"), as it would silently alter
+    the node instead of annotating it  */
+const checkDiagrams = (object, at, diagnose) => {
+    for (const [i, diagram] of diagramsOf(object).entries()) {
+        const base = Array.isArray(object.diagram) ? [...at, "diagram", i] : [...at, "diagram"];
+        for (const [j, key] of (diagram.properties ?? []).entries())
+            if (reservedAttributes.includes(key))
+                diagnose([...base, "properties", j], `diagram property "${key}" collides with the reserved Gradia node attribute "${key}"`);
+    }
+};
+/*  check the multiplicity of an object (if any): it names a property
+    of the object kind and a valid regular expression  */
+const checkMultiple = (object, at, diagnose) => {
+    const multiple = object.multiple;
+    if (multiple === undefined)
+        return;
+    if (!(object.props ?? []).some((p) => p.name === multiple.property))
+        diagnose([...at, "multiple", "property"], `"multiple" property "${multiple.property}" is not a property of "${object.kind}"`);
+    try {
+        RegExp(multiple.pattern);
+    }
+    catch (err) {
+        diagnose([...at, "multiple", "pattern"], `invalid "multiple" pattern "${multiple.pattern}": ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+};
+/*  check the property-driven badge of an object (if any): it names a
+    property of the object kind, and for an "enum" valued one each mapped
+    value is a member of it (else the mapping would never apply)  */
+const checkBadge = (object, at, diagnose) => {
+    const badge = object.badge;
+    if (badge === undefined || typeof badge === "string")
+        return;
+    const prop = (object.props ?? []).find((p) => p.name === badge.property);
+    if (prop === undefined) {
+        diagnose([...at, "badge", "property"], `"badge" property "${badge.property}" is not a property of "${object.kind}"`);
+        return;
+    }
+    let expr;
+    try {
+        expr = prop.value !== undefined ? compileValueExpr(prop.value) : undefined;
+    }
+    catch {
+        /*  an invalid value expression is reported on its own  */
+    }
+    if (expr?.kind === "enum")
+        for (const value of Object.keys(badge.map))
+            if (!expr.members.includes(value))
+                diagnose([...at, "badge", "map", value], `"badge" map value "${value}" is not a member of "${prop.value}"`);
+};
 /*  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
@@ -197,8 +312,12 @@ const checkAutomaton = (object, at, diagnose) => {
     property value and marker expressions have to be syntactically
     valid, "referenced" and "coverage" entries have to be reference
     expressions, an "automaton" has to name existing child kinds and
-    properties, and the names of non-artifact objects have to be valid
-    patterns (as they are compiled into regular expressions)  */
+    properties, a "badge" has to name an existing property and its
+    members, a "multiple" an existing property and a valid regular
+    expression, a diagram must not display a property named like a
+    reserved Gradia node attribute, and the names of non-artifact
+    objects have to be valid patterns (as they are compiled into
+    regular expressions)  */
 const checkConstraints = (config, posOfPath) => {
     const diagnostics = new Array();
     const diagnose = (path, message) => {
@@ -226,6 +345,9 @@ const checkConstraints = (config, posOfPath) => {
                 diagnose([...at, "file"], `"file" field "${object.file}" is not a relative path below the base directory`);
             checkProperties(object.props ?? [], at, diagnose);
             checkAutomaton(object, at, diagnose);
+            checkBadge(object, at, diagnose);
+            checkMultiple(object, at, diagnose);
+            checkDiagrams(object, at, diagnose);
             for (const field of ["referenced", "coverage"])
                 for (const [j, entry] of (object[field] ?? []).entries()) {
                     /*  a reference coverage entry has to be a single
@@ -279,7 +401,8 @@ export const configStatistics = (config) => {
 /*  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
-    merged result alone is validated  */
+    merged result alone is validated, and report the artifacts several
+    files define plus the files contributing every node  */
 export const loadConfig = (files) => {
     if (files.length === 0)
         throw new Error("no configuration files given");
@@ -314,8 +437,10 @@ export const loadConfig = (files) => {
         if (doc.errors.length === 0)
             docs.push({ file, doc, lines, raw: doc.toJS() });
     }
+    const overlaps = overlapsOf(docs);
+    const origins = originsOf(docs);
     if (diagnostics.length > 0)
-        return { diagnostics };
+        return { diagnostics, overlaps, origins };
     /*  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  */
@@ -332,9 +457,9 @@ export const loadConfig = (files) => {
             diagnostics.push({ file, line, column, severity: "error",
                 message: `invalid configuration: ${where}${issue.message}` });
         }
-        return { diagnostics };
+        return { diagnostics, overlaps, origins };
     }
     /*  check the constraints beyond the structural schema  */
     diagnostics.push(...checkConstraints(result.output, posOfPath));
-    return { config: diagnostics.length === 0 ? result.output : undefined, diagnostics };
+    return { config: diagnostics.length === 0 ? result.output : undefined, diagnostics, overlaps, origins };
 };

package/dst/specbook-coverage.js

@@ -3,7 +3,7 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { referenceRegex, resolveUnique, resolveSet, chainOf, plainText } from "./specbook-link.js";
+import { referenceRegex, resolveUnique, resolveSet, chainOf, referenceText } from "./specbook-link.js";
 import { compileValueExpr } from "./specbook-parse-value.js";
 /*  the referencing objects of every referenced object, resolved from
     the names, property values, descriptions, and rationales of all
@@ -19,7 +19,7 @@ const referrerIndex = (index) => {
         if (object.description !== undefined)
             texts.push(object.description.description, object.description.rationale ?? "", object.description.elaboration ?? "");
         for (const text of texts)
-            for (const m of plainText(text).matchAll(referenceRegex)) {
+            for (const m of referenceText(text).matchAll(referenceRegex)) {
                 const target = resolveUnique(index, m[1].trim(), object).target;
                 if (target !== undefined && !chain.includes(target))
                     referrers.set(target, (referrers.get(target) ?? new Set()).add(object));

package/dst/specbook-diagram.d.ts

@@ -1,5 +1,5 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
-import type { Schema, SchemaDiagram } from "./specbook-format-schema.js";
+import { type Schema, type SchemaDiagram } from "./specbook-format-schema.js";
 import type { ParseContext } from "./specbook-parse-common.js";
 import type { OmitAspect } from "./specbook-export-common.js";
 import { type Verbose } from "./specbook-verbose.js";
@@ -8,14 +8,16 @@ export interface DiagramError {
     object?: SpecObject;
 }
 export interface DiagramResult {
+    type: DiagramType;
     spec?: string;
     config?: SchemaDiagram["config"];
     columns?: number;
     errors: DiagramError[];
 }
-export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;
-export declare const omittedDiagrams: (specification: Spec, config: Schema, omit: Set<OmitAspect>) => Set<SpecObject>;
-export declare const renderDiagrams: (specification: Spec, config: Schema, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:code" | "diagram:image" | "diagram:listing" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Map<SpecObject, DiagramResult & {
+export type DiagramType = NonNullable<SchemaDiagram["type"]>;
+export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult[]>;
+export declare const omittedDiagrams: (specification: Spec, config: Schema, omit: Set<OmitAspect>) => Set<DiagramResult>;
+export declare const renderDiagrams: (specification: Spec, config: Schema, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:state" | "diagram:layer" | "diagram:slice" | "diagram:tree" | "diagram:matrix" | "diagram:sequence" | "diagram:petri" | "diagram:gantt" | "diagram:code" | "diagram:image" | "diagram:listing" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Map<SpecObject, (DiagramResult & {
     svg: string;
-}>>;
+})[]>>;
 export declare const validateDiagrams: (ctx: ParseContext, specification: Spec, config: Schema) => void;