@rse/specbook 0.9.2 → 0.9.4

package/dst/specbook-parse-semantic.js

@@ -50,22 +50,12 @@ const matchAlternatives = (ctx, alternatives, item) => {
     }
     return false;
 };
-/*  validate a single object (and recursively its childs) against its schema  */
-const validateObject = (ctx, object, schema, level) => {
-    const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
-    const props = schema.props ?? [];
-    /*  check the name convention (the configured name of non-artifact
-        objects is a regular expression pattern)  */
-    if (level > 1 && schema.name !== undefined && !anchored(schema.name).test(plainText(object.name)))
-        ctx.diagnose(meta.file, meta.line, `${object.kind} name "${object.name}" does not match pattern "${schema.name}"`);
-    /*  a configured id has to be explicitly specified 1:1 in the
-        input, via either "{{<id>}}" or "(<id>)"  */
-    if (schema.id !== undefined && (object.anchor ?? object.paren) !== schema.id)
-        ctx.diagnose(meta.file, meta.line, `configured id "${schema.id}" not explicitly specified on ${object.kind} "${object.name}"`);
-    /*  find a property by its key (case-sensitive)  */
-    const findProp = (name) => object.properties.find((p) => plainKey(p.key) === name);
-    /*  the tokens split off multi-token property values below, assigned
-        to the still unset configured properties by matching their patterns  */
+/*  find a property of an object by its key (case-sensitive)  */
+const findProp = (object, name) => object.properties.find((p) => plainKey(p.key) === name);
+/*  distribute the inline tokens split off the multi-token property values
+    of an object across its configured properties and report the
+    unassignable ones (the properties assigned a token are returned)  */
+const assignInlineTokens = (ctx, object, props, meta) => {
     const tokens = new Array();
     const tokenAssigned = new Set();
     /*  explode a multi-token property value whose direct pattern check
@@ -77,7 +67,7 @@ const validateObject = (ctx, object, schema, level) => {
         const expr = compileValueExpr(prop.value);
         if (expr.kind !== "regex" && expr.kind !== "enum")
             continue;
-        const match = findProp(prop.name);
+        const match = findProp(object, prop.name);
         if (match === undefined || directMatches(expr, plainText(match.value)))
             continue;
         const parts = plainText(match.value).split(/\s+/);
@@ -91,8 +81,10 @@ const validateObject = (ctx, object, schema, level) => {
         parts.splice(idx, 1);
         tokens.push(...parts);
     }
+    /*  assign the collected tokens to the still unset configured
+        properties whose pattern they match  */
     for (const prop of props) {
-        if (prop.value === undefined || findProp(prop.name) !== undefined)
+        if (prop.value === undefined || findProp(object, prop.name) !== undefined)
             continue;
         const expr = compileValueExpr(prop.value);
         if (expr.kind !== "regex" && expr.kind !== "enum")
@@ -104,13 +96,69 @@ const validateObject = (ctx, object, schema, level) => {
             tokens.splice(idx, 1);
         }
     }
+    /*  report the tokens which no configured property accepts  */
     for (const token of tokens)
         ctx.diagnose(meta.file, meta.line, `unassignable inline token "${token}" on ${object.kind} "${object.name}"`);
+    return tokenAssigned;
+};
+/*  check a property value against the compiled value expression of its
+    configured schema property  */
+const checkPropValue = (ctx, prop, expr, property, meta) => {
+    if (expr.kind === "reference") {
+        /*  a reference constraint: the value has to be exactly one
+            reference resolving into the constraint's wildcard match set  */
+        if (!/^\[\[[^[\]]+\]\]$/.test(property.value.trim()))
+            ctx.diagnose(meta.file, meta.line, `property "${prop.name}" value "${property.value}" is not a single link reference`);
+        else {
+            const ref = property.value.trim().slice(2, -2).trim();
+            const target = resolveUnique(ctx.linkIndex, ref).target;
+            if (target !== undefined && !resolveSet(ctx.linkIndex, expr.pattern).includes(target))
+                ctx.diagnose(meta.file, meta.line, `link reference "[[${ref}]]" does not match constraint "${prop.value}"`);
+        }
+    }
+    else if (expr.kind === "tags") {
+        /*  a tags constraint: the value is a comma-separated set of
+            configured tags, each occurring at most once  */
+        const seen = new Set();
+        for (const item of splitItems(plainText(property.value))) {
+            if (!expr.members.includes(item))
+                ctx.diagnose(meta.file, meta.line, `tag "${item}" of property "${prop.name}" not allowed by constraint "${prop.value}"`);
+            else if (seen.has(item))
+                ctx.diagnose(meta.file, meta.line, `duplicate tag "${item}" on property "${prop.name}"`);
+            seen.add(item);
+        }
+    }
+    else if (expr.kind === "list") {
+        /*  a list constraint: the value is a comma-separated list
+            of items, each matching at least one alternative  */
+        for (const item of splitItems(property.value))
+            if (!matchAlternatives(ctx, expr.alternatives, item))
+                ctx.diagnose(meta.file, meta.line, `list item "${item}" of property "${prop.name}" does not match constraint "${prop.value}"`);
+    }
+    else if (!directMatches(expr, plainText(property.value)))
+        ctx.diagnose(meta.file, meta.line, expr.kind === "enum" ?
+            `property "${prop.name}" value "${property.value}" is not a member of "${prop.value}"` :
+            `property "${prop.name}" value "${property.value}" does not match pattern "${prop.value}"`);
+};
+/*  validate a single object (and recursively its childs) against its schema  */
+const validateObject = (ctx, object, schema, level) => {
+    const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+    const props = schema.props ?? [];
+    /*  check the name convention (the configured name of non-artifact
+        objects is a regular expression pattern)  */
+    if (level > 1 && schema.name !== undefined && !anchored(schema.name).test(plainText(object.name)))
+        ctx.diagnose(meta.file, meta.line, `${object.kind} name "${object.name}" does not match pattern "${schema.name}"`);
+    /*  a configured id has to be explicitly specified 1:1 in the
+        input, via either "{{<id>}}" or "(<id>)"  */
+    if (schema.id !== undefined && (object.anchor ?? object.paren) !== schema.id)
+        ctx.diagnose(meta.file, meta.line, `configured id "${schema.id}" not explicitly specified on ${object.kind} "${object.name}"`);
+    /*  distribute the inline tokens split off the multi-token property values  */
+    const tokenAssigned = assignInlineTokens(ctx, object, props, meta);
     /*  check the configured properties  */
     let parenConsumed = false;
     for (const prop of props) {
         const expr = prop.value !== undefined ? compileValueExpr(prop.value) : undefined;
-        const match = findProp(prop.name);
+        const match = findProp(object, prop.name);
         if (match === undefined) {
             /*  accept a trailing parenthesized name token as the value of a
                 still missing property when it matches the property pattern  */
@@ -122,45 +170,10 @@ const validateObject = (ctx, object, schema, level) => {
             if (prop.optional !== true)
                 ctx.diagnose(meta.file, meta.line, `required property "${prop.name}" missing on ${object.kind} "${object.name}"`);
         }
-        else if (expr !== undefined) {
-            const line = ctx.propMeta.get(match)?.line ?? meta.line;
-            if (expr.kind === "reference") {
-                /*  a reference constraint: the value has to be exactly one
-                    reference resolving into the constraint's wildcard match set  */
-                if (!/^\[\[[^[\]]+\]\]$/.test(match.value.trim()))
-                    ctx.diagnose(meta.file, line, `property "${prop.name}" value "${match.value}" is not a single link reference`);
-                else {
-                    const ref = match.value.trim().slice(2, -2).trim();
-                    const target = resolveUnique(ctx.linkIndex, ref).target;
-                    if (target !== undefined && !resolveSet(ctx.linkIndex, expr.pattern).includes(target))
-                        ctx.diagnose(meta.file, line, `link reference "[[${ref}]]" does not match constraint "${prop.value}"`);
-                }
-            }
-            else if (expr.kind === "tags") {
-                /*  a tags constraint: the value is a comma-separated set of
-                    configured tags, each occurring at most once  */
-                const seen = new Set();
-                for (const item of splitItems(plainText(match.value))) {
-                    if (!expr.members.includes(item))
-                        ctx.diagnose(meta.file, line, `tag "${item}" of property "${prop.name}" not allowed by constraint "${prop.value}"`);
-                    else if (seen.has(item))
-                        ctx.diagnose(meta.file, line, `duplicate tag "${item}" on property "${prop.name}"`);
-                    seen.add(item);
-                }
-            }
-            else if (expr.kind === "list") {
-                /*  a list constraint: the value is a comma-separated list
-                    of items, each matching at least one alternative  */
-                for (const item of splitItems(match.value))
-                    if (!matchAlternatives(ctx, expr.alternatives, item))
-                        ctx.diagnose(meta.file, line, `list item "${item}" of property "${prop.name}" does not match constraint "${prop.value}"`);
-            }
-            else if (!tokenAssigned.has(prop.name) && !directMatches(expr, plainText(match.value)))
-                ctx.diagnose(meta.file, line, expr.kind === "enum" ?
-                    `property "${prop.name}" value "${match.value}" is not a member of "${prop.value}"` :
-                    `property "${prop.name}" value "${match.value}" does not match pattern "${prop.value}"`);
-        }
+        else if (expr !== undefined && !tokenAssigned.has(prop.name))
+            checkPropValue(ctx, prop, expr, match, { file: meta.file, line: ctx.propMeta.get(match)?.line ?? meta.line });
     }
+    /*  report the properties not configured by the schema  */
     for (const property of object.properties)
         if (!props.some((p) => p.name === plainKey(property.key)))
             ctx.diagnose(meta.file, ctx.propMeta.get(property)?.line ?? meta.line, `unknown property "${property.key}" on ${object.kind} "${object.name}"`);
@@ -179,6 +192,7 @@ const validateObject = (ctx, object, schema, level) => {
         }
         validateObject(ctx, child, childSchema, level + 1);
     }
+    /*  report the configured child object kinds which are missing  */
     for (const child of childs)
         if (child.optional !== true
             && !object.childs.some((c) => c.kind === child.kind))
@@ -204,7 +218,8 @@ export const validate = (ctx, specification, config) => {
         for (const object of artifact.objects) {
             const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
             const schema = config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
-                config.find((s) => (s.name ?? "").toUpperCase() === plainText(object.name).toUpperCase());
+                config.find((s) => s.name !== undefined
+                    && s.name.toUpperCase() === plainText(object.name).toUpperCase());
             if (schema === undefined) {
                 ctx.diagnose(meta.file, meta.line, `unknown artifact "${object.kind}: ${object.name}" (id "${object.id}")`);
                 continue;

package/dst/specbook-parse-syntax.js

@@ -3,8 +3,8 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import fs from "node:fs";
-import path from "node:path";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { marked } from "marked";
 import { embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
 /*  split a description text into statement and optional rationale  */
@@ -89,7 +89,7 @@ const parseFrontmatter = (text) => {
         const line = 2 + (m[1].slice(0, km.index).match(/\n/g) ?? []).length;
         const value = km[1].trim();
         const date = new Date(value);
-        return { date: isNaN(date.getTime()) ? null : date, line, value };
+        return { date: Number.isNaN(date.getTime()) ? null : date, line, value };
     };
     return {
         present: true,
@@ -137,8 +137,7 @@ const parseList = (ctx, list, object, file, line) => {
         /*  a concise-format item carries a further segment on its first
             line, or ends it with the segment terminator (the case of an
             object without properties, whose description follows below)  */
-        const cm = first.match(/^([^:;]+):\s+(.+;.*)$/);
-        if (cm !== null)
+        if (/^[^:;]+:\s+.+;.*$/.test(first))
             parseConcise(ctx, item, object, file, line);
         else {
             const km = first.match(/^([^:;]+):\s*(.*)$/);
@@ -234,7 +233,7 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
     const statements = new Array();
     for (const segment of segments) {
         const km = segment.match(/^([^:;]+):\s+(.+)$/);
-        if (km !== null && !(/\sBECAUSE\s/.test(segment))) {
+        if (km !== null && !(/\s(?:\*\*BECAUSE\*\*|BECAUSE)\s/.test(segment))) {
             const property = { key: km[1].trim(), value: km[2].trim() };
             ctx.propMeta.set(property, { line });
             object.properties.push(property);
@@ -261,6 +260,7 @@ export const parseFile = (ctx, source) => {
                 ctx.diagnose(source.file, info.line, info.value === null ?
                     `missing "${key}:" frontmatter key` :
                     `invalid "${key}:" frontmatter timestamp "${info.value}"`);
+    /*  the state tracked while walking the Markdown tokens  */
     const artifacts = new Array();
     const stack = new Array();
     let current = null;
@@ -278,15 +278,16 @@ export const parseFile = (ctx, source) => {
         if (token.type === "heading") {
             flush();
             group = null;
-            const heading = parseHeadingText(token.text);
+            const { depth, text } = token;
+            const heading = parseHeadingText(text);
             if (heading.malformed !== undefined)
                 ctx.diagnose(source.file, line, `malformed anchor "${heading.malformed}" in heading`);
-            if (heading.name === "" && token.depth > 1) {
+            if (heading.name === "" && depth > 1) {
                 /*  a grouping container heading (e.g. "### STATES") collects
                     objects of its singular kind below the parent object  */
-                const parent = stack[token.depth - 2];
+                const parent = stack[depth - 2];
                 if (parent === undefined)
-                    ctx.diagnose(source.file, line, `heading level ${token.depth} without parent object`);
+                    ctx.diagnose(source.file, line, `heading level ${depth} without parent object`);
                 else {
                     group = { parent, kind: heading.kind.replace(/S$/, "") };
                     current = parent;
@@ -295,7 +296,7 @@ export const parseFile = (ctx, source) => {
             else {
                 const object = {
                     kind: heading.kind,
-                    id: heading.id ?? (token.depth === 1 ? heading.paren : undefined) ?? slugify(heading.name),
+                    id: heading.id ?? (depth === 1 ? heading.paren : undefined) ?? slugify(heading.name),
                     name: heading.name,
                     properties: [],
                     childs: []
@@ -307,7 +308,7 @@ export const parseFile = (ctx, source) => {
                 if (heading.primary)
                     object.primary = true;
                 ctx.objectMeta.set(object, { file: source.file, line });
-                if (token.depth === 1) {
+                if (depth === 1) {
                     artifacts.push({
                         created: created.date ?? new Date(),
                         modified: modified.date ?? new Date(),
@@ -316,16 +317,16 @@ export const parseFile = (ctx, source) => {
                     stack.length = 0;
                 }
                 else {
-                    const parent = stack[token.depth - 2];
+                    const parent = stack[depth - 2];
                     if (parent === undefined) {
-                        ctx.diagnose(source.file, line, `heading level ${token.depth} without parent object`);
+                        ctx.diagnose(source.file, line, `heading level ${depth} without parent object`);
                         line += (token.raw.match(/\n/g) ?? []).length;
                         continue;
                     }
                     parent.childs.push(object);
                 }
-                stack.length = token.depth - 1;
-                stack[token.depth - 1] = object;
+                stack.length = depth - 1;
+                stack[depth - 1] = object;
                 current = object;
             }
         }

package/dst/specbook-parse-value.js

@@ -119,5 +119,11 @@ export const splitItems = (text) => {
         else
             parts[parts.length - 1] += char;
     }
-    return parts.map((part) => part.trim()).filter((part) => part !== "");
+    return parts.map((part) => {
+        /*  unquote a fully double-quoted item, mirroring the member
+            quoting of the value expression lexer  */
+        const item = part.trim();
+        const m = item.match(/^"((?:\\"|[^"])*)"$/);
+        return m !== null ? m[1].replace(/\\"/g, "\"") : item;
+    }).filter((part) => part !== "");
 };

package/dst/specbook-parse.js

@@ -18,10 +18,14 @@ export class Parser {
     /*  parse all source files into the specification AST and
         optionally validate the result against a configuration  */
     parse(sources, config) {
+        /*  reset the parsing context to allow a reuse of the parser  */
+        this.ctx = new ParseContext();
+        /*  parse all source files into their artifacts  */
         const artifacts = new Array();
         for (const source of sources)
             artifacts.push(...parseFile(this.ctx, source));
         const specification = { artifacts };
+        /*  validate the resulting specification AST  */
         if (artifacts.length > 0) {
             this.ctx.linkIndex = buildLinkIndex(specification);
             if (config !== undefined)

package/dst/specbook-struct-schema.d.ts

@@ -9,6 +9,7 @@ export type SchemaObject = {
     desc?: string;
     optional?: boolean;
     diagram?: SchemaDiagram;
+    format?: SchemaFormat;
     props?: SchemaProperty[];
     childs?: SchemaObject[];
 };
@@ -24,8 +25,14 @@ export type SchemaDiagram = {
     onlyConnected?: boolean;
     collapse?: boolean;
     qualified?: boolean;
+    properties?: string[];
     config?: Partial<GradiaConfig>;
 };
+export type SchemaFormat = {
+    type?: "auto" | "complex" | "concise";
+    maxTableColumns?: number;
+    withUnusedProps?: boolean;
+};
 export type SchemaProperty = {
     name: string;
     desc?: string;

package/dst/specbook-struct-schema.js

@@ -13,13 +13,13 @@ const GradiaConfigSchemas = Object.fromEntries(Object.entries(Gradia.config).map
     typeof value === "boolean" ? v.boolean() : typeof value === "number" ? v.number() : v.string()]));
 const SchemaDiagramConfig = v.partial(v.strictObject(GradiaConfigSchemas, (issue) => issue.expected === "never" ? "unknown Gradia rendering option" :
     "expected a map of Gradia rendering options"));
-const SchemaProperty = v.object({
+const SchemaProperty = v.strictObject({
     name: v.string(),
     desc: v.optional(v.string()),
     value: v.optional(v.string()),
     optional: v.optional(v.boolean())
 });
-const SchemaDiagram = v.object({
+const SchemaDiagram = v.strictObject({
     type: v.optional(v.picklist(["graph", "hub", "grid"])),
     nodes: v.optional(v.string()),
     edges: v.optional(v.string()),
@@ -31,9 +31,15 @@ const SchemaDiagram = v.object({
     onlyConnected: v.optional(v.boolean()),
     collapse: v.optional(v.boolean()),
     qualified: v.optional(v.boolean()),
+    properties: v.optional(v.array(v.string())),
     config: v.optional(SchemaDiagramConfig)
 });
-const SchemaObject = v.object({
+const SchemaFormat = v.strictObject({
+    type: v.optional(v.picklist(["auto", "complex", "concise"])),
+    maxTableColumns: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+    withUnusedProps: v.optional(v.boolean())
+});
+const SchemaObject = v.strictObject({
     kind: v.string(),
     name: v.optional(v.string()),
     id: v.optional(v.string()),
@@ -41,6 +47,7 @@ const SchemaObject = v.object({
     desc: v.optional(v.string()),
     optional: v.optional(v.boolean()),
     diagram: v.optional(SchemaDiagram),
+    format: v.optional(SchemaFormat),
     props: v.optional(v.array(SchemaProperty)),
     childs: v.optional(v.array(v.lazy(() => SchemaObject)))
 });

package/dst/specbook-theme.js

@@ -26,7 +26,7 @@ export const themeStylesheet = (colors) => ":root {\n" +
     aligned with the layer-2 CSS mapping of the HTML rendering  */
 export const themeMapping = (colors, style) => {
     const idx = style === "dark" ?
-        { text: 28, muted: 22, symbol: 20, border: 16, accent: 24 } :
+        { text: 29, muted: 22, symbol: 20, border: 16, accent: 24 } :
         { text: 5, muted: 22, symbol: 24, border: 28, accent: 12 };
     return {
         text: colors.base[idx.text - 1],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "0.9.2",
+    "version":                             "0.9.4",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -23,8 +23,8 @@
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.5.0",
-        "@rse/mrcs":                       "0.9.1",
-        "@rse/gradia":                     "0.9.4",
+        "@rse/mrcs":                       "0.9.2",
+        "@rse/gradia":                     "1.0.0",
         "@toon-format/toon":               "4.1.1",
         "valibot":                         "1.4.2",
         "nunjucks":                        "3.2.4",
@@ -33,7 +33,7 @@
         "@swc/html":                       "1.16.1",
         "tokenizr":                        "2.2.1",
         "playwright":                      "1.62.1",
-        "ai":                              "7.0.68",
+        "ai":                              "7.0.69",
         "@ai-sdk/anthropic":               "4.0.39",
         "@ai-sdk/openai":                  "4.0.43",
         "@openrouter/ai-sdk-provider":     "3.0.0",