@rse/specbook 1.2.1 → 1.2.3

package/dst/specbook-link.d.ts

@@ -8,6 +8,7 @@ interface LinkNode {
     name: string;
 }
 export type LinkIndex = LinkNode[];
+export declare const assignId: (index: LinkIndex, object: SpecObject, id: string) => void;
 export declare const chainOf: (index: LinkIndex, object: SpecObject) => SpecObject[];
 export interface LinkTarget {
     target?: SpecObject;

package/dst/specbook-link.js

@@ -34,6 +34,13 @@ const lookup = (index) => {
     }
     return result;
 };
+/*  assign the id of an indexed object, dropping the lookup structures
+    of its index (and with them the memoized resolutions), as they are
+    keyed on the ids as of their build and would freeze the old one  */
+export const assignId = (index, object, id) => {
+    object.id = id;
+    lookups.delete(index);
+};
 /*  the ancestor-or-self chain of an object, root first
     (empty for an object unknown to the index)  */
 export const chainOf = (index, object) => {
@@ -127,16 +134,16 @@ export const resolveSet = (index, reference) => {
     subtree, which beats one in another artifact)  */
 const nearest = (index, matches, from) => {
     const chain = chainOf(index, from);
-    const distance = (object) => {
+    const proximity = (object) => {
         const other = chainOf(index, object);
         let i = 0;
         while (i < chain.length && i < other.length && chain[i] === other[i])
             i++;
         return i;
     };
-    const distances = matches.map((object) => distance(object));
-    const best = Math.max(...distances);
-    return matches.filter((_, i) => distances[i] === best);
+    const proximities = matches.map((object) => proximity(object));
+    const best = Math.max(...proximities);
+    return matches.filter((_, i) => proximities[i] === best);
 };
 /*  resolve a reference into a unique target: a single segment tries the
     ordered variants (1) id/anchor, (2) name, (3) "KIND:name-or-id", where

package/dst/specbook-parse-common.d.ts

@@ -24,6 +24,7 @@ export declare class ParseContext {
     parenProps: WeakMap<SpecObject, SpecProperty>;
     assets: Set<string>;
     diagnose(file: string, line: number, message: string, severity?: DiagnosticSeverity): void;
+    metaOf(object: SpecObject): ObjectMeta;
 }
 export declare const becauseRegex: RegExp;
 export declare const embeddingRegex: RegExp;

package/dst/specbook-parse-common.js

@@ -20,6 +20,11 @@ export class ParseContext {
     diagnose(file, line, message, severity = "error") {
         this.diagnostics.push({ file, line, column: 1, severity, message });
     }
+    /*  the source location of an object (defensively falling back onto
+        line 1 of no file for an object unknown to the syntactic phase)  */
+    metaOf(object) {
+        return this.objectMeta.get(object) ?? { file: "", line: 1 };
+    }
 }
 /*  the marker separating a statement from its rationale  */
 export const becauseRegex = /,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/;

package/dst/specbook-parse-semantic.d.ts

@@ -1,7 +1,8 @@
-import { type Spec, type SpecObject } from "./specbook-format-spec.js";
+import { type Spec, type SpecObject, type SpecProperty } from "./specbook-format-spec.js";
 import { type Schema, type SchemaObject } from "./specbook-format-schema.js";
 import { ParseContext } from "./specbook-parse-common.js";
 export declare const resolveArtifact: (config: Schema, object: SpecObject) => SchemaObject | undefined;
 export declare const collectSchemas: (specification: Spec, config: Schema) => Map<SpecObject, SchemaObject>;
+export declare const collectParenProps: (schemas: Map<SpecObject, SchemaObject>) => Map<SpecObject, SpecProperty>;
 export declare const validate: (ctx: ParseContext, specification: Spec, config: Schema) => void;
 export declare const validateReferences: (ctx: ParseContext, specification: Spec) => void;

package/dst/specbook-parse-semantic.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, plainText, assignId } from "./specbook-link.js";
 import { compileValueExpr, splitItems, anchored } from "./specbook-parse-value.js";
 /*  the syntax of a value consisting of exactly one Wiki-style reference  */
 const singleReferenceRegex = /^\[\[([^[\]]+)\]\]$/;
@@ -112,21 +112,23 @@ const checkPropValue = (ctx, object, prop, expr, property, meta) => {
             `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}"`);
 };
-/*  find the configured property whose value the trailing parenthesized
-    name token of an object is accepted for: the first still missing
+/*  derive the synthetic property the trailing parenthesized name token
+    of an object is consumed as: the first still missing configured
     property whose pattern the token matches  */
 const parenProp = (object, props) => {
     const paren = object.paren;
     if (paren === undefined)
         return undefined;
-    return props.find((prop) => prop.value !== undefined && !object.properties.some((p) => p.key === prop.name)
-        && directMatches(compileValueExpr(prop.value), paren));
+    const prop = props.find((p) => p.value !== undefined && !object.properties.some((q) => q.key === p.name)
+        && directMatches(compileValueExpr(p.value), paren));
+    return prop !== undefined ? { key: prop.name, value: paren } : undefined;
 };
 /*  check the property values flagged unique for distinctness among
     the sibling objects of the same kind and the ones flagged present
-    for occurring on at least one of the (existing) siblings (all
-    values, or only the values matching the regexp or enum expression
-    of the flag)  */
+    for occurring on at least one sibling (all values, or only the
+    values matching the regexp or enum expression of the flag), where
+    a kind without any sibling fails a present flag, too, but only for
+    an optional kind, as the missing-kind check reports a required one  */
 const checkSiblingFlags = (ctx, object, childs, meta) => {
     const marker = (flag) => flag === undefined || flag === false ? undefined :
         { filter: typeof flag === "string" ? compileValueExpr(flag) : undefined };
@@ -152,12 +154,12 @@ const checkSiblingFlags = (ctx, object, childs, meta) => {
                 if (first === undefined)
                     seen.set(value, sibling);
                 else {
-                    const siblingMeta = ctx.objectMeta.get(sibling) ?? { file: "", line: 1 };
+                    const siblingMeta = ctx.metaOf(sibling);
                     ctx.diagnose(siblingMeta.file, ctx.propMeta.get(property)?.line ?? siblingMeta.line, `value "${value}" of unique property "${prop.name}" on ${sibling.kind} "${sibling.name}" ` +
                         `already used by preceding ${sibling.kind} "${first.name}"`);
                 }
             }
-            if (present !== undefined && siblings.length > 0 && !found)
+            if (present !== undefined && (siblings.length > 0 || child.optional === true) && !found)
                 ctx.diagnose(meta.file, meta.line, `no ${child.kind} below ${object.kind} "${object.name}" carries property "${prop.name}"` +
                     (typeof prop.present === "string" ? ` with a value matching "${prop.present}"` : ""));
         }
@@ -165,7 +167,7 @@ const checkSiblingFlags = (ctx, object, childs, meta) => {
 };
 /*  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 meta = ctx.metaOf(object);
     const props = schema.props ?? [];
     /*  check the name convention (the configured name of non-artifact
         objects is a regular expression pattern)  */
@@ -199,7 +201,7 @@ const validateObject = (ctx, object, schema, level) => {
     /*  check the configured child objects  */
     const childs = schema.childs ?? [];
     for (const child of object.childs) {
-        const childMeta = ctx.objectMeta.get(child) ?? { file: "", line: 1 };
+        const childMeta = ctx.metaOf(child);
         const childSchema = childs.find((c) => c.kind === child.kind);
         if (childSchema === undefined) {
             ctx.diagnose(childMeta.file, childMeta.line, `unknown object kind "${child.kind}" below ${object.kind} "${object.name}"`);
@@ -255,6 +257,19 @@ export const collectSchemas = (specification, config) => {
     }
     return schemas;
 };
+/*  derive the synthetic properties supplied by the consumed parenthesized
+    name tokens of a schema mapping, so a consumer without a parsing
+    context -- the diagram derivation of an export -- sees exactly the
+    properties the validation sees  */
+export const collectParenProps = (schemas) => {
+    const parenProps = new Map();
+    for (const [object, schema] of schemas) {
+        const property = parenProp(object, schema.props ?? []);
+        if (property !== undefined)
+            parenProps.set(object, property);
+    }
+    return parenProps;
+};
 /*  report the objects colliding on kind and id among their siblings
     (recursively from the artifacts down), as such objects derive
     identical anchor paths and hence cannot be addressed distinctly  */
@@ -266,7 +281,7 @@ const checkIds = (ctx, objects) => {
         if (first === undefined)
             seen.set(key, object);
         else {
-            const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+            const meta = ctx.metaOf(object);
             ctx.diagnose(meta.file, meta.line, `id "${object.id}" of ${object.kind} "${object.name}" collides with preceding ${object.kind} "${first.name}"`);
         }
         checkIds(ctx, object.childs);
@@ -337,7 +352,7 @@ const checkAutomata = (ctx, schemas) => {
         const reachable = closure(initials, succs);
         const coreachable = closure(finals, preds);
         for (const node of nodes) {
-            const meta = ctx.objectMeta.get(node) ?? { file: "", line: 1 };
+            const meta = ctx.metaOf(node);
             const name = `${node.kind} "${node.name}" of ${object.kind} "${object.name}"`;
             if (initials.length > 0 && !reachable.has(node))
                 ctx.diagnose(meta.file, meta.line, `${name} is not reachable from the initial ${node.kind} through any ${automaton.edges}`);
@@ -368,7 +383,7 @@ const checkRelations = (ctx, schemas) => {
     for (const [prop, objects] of groups) {
         const members = new Set(objects);
         const locate = (object) => {
-            const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+            const meta = ctx.metaOf(object);
             const property = findProp(ctx, object, prop.name);
             const line = property !== undefined ? ctx.propMeta.get(property)?.line : undefined;
             return { file: meta.file, line: line ?? meta.line };
@@ -455,7 +470,7 @@ const checkReferenced = (ctx, specification, schemas) => {
         const covered = Array.from(referrers.get(object) ?? [])
             .some((referrer) => chainOf(ctx.linkIndex, referrer).some((o) => admissible.has(o)));
         if (!covered) {
-            const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+            const meta = ctx.metaOf(object);
             ctx.diagnose(meta.file, meta.line, `${object.kind} "${object.name}" is not referenced from any object matching ` +
                 schema.referenced.map((entry) => `"${entry}"`).join(" or "), "warning");
         }
@@ -469,19 +484,16 @@ export const validate = (ctx, specification, config) => {
         precedence), which has to happen before any property check, as
         those resolve references by id across all artifacts  */
     const schemas = collectSchemas(specification, config);
+    for (const [object, property] of collectParenProps(schemas))
+        ctx.parenProps.set(object, property);
     const promote = (object) => {
         /*  an object below an unresolved artifact or an unknown kind
             carries no schema and hence no property able to consume the
             token, so the token still acts as the id and a single
             unresolved heading no longer cascades into unresolvable
             references all over the corpus  */
-        if (object.paren !== undefined) {
-            const prop = parenProp(object, schemas.get(object)?.props ?? []);
-            if (prop !== undefined)
-                ctx.parenProps.set(object, { key: prop.name, value: object.paren });
-            else if (object.anchor === undefined)
-                object.id = object.paren;
-        }
+        if (object.paren !== undefined && object.anchor === undefined && !ctx.parenProps.has(object))
+            assignId(ctx.linkIndex, object, object.paren);
         object.childs.forEach(promote);
     };
     for (const artifact of specification.artifacts)
@@ -492,7 +504,7 @@ export const validate = (ctx, specification, config) => {
     const position = new Map();
     for (const artifact of specification.artifacts) {
         for (const object of artifact.objects) {
-            const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+            const meta = ctx.metaOf(object);
             const schema = schemas.get(object);
             if (schema === undefined) {
                 ctx.diagnose(meta.file, meta.line, `unknown artifact "${object.kind}: ${object.name}" (id "${object.id}")`);
@@ -533,7 +545,7 @@ export const validateReferences = (ctx, specification) => {
         }
     };
     const walk = (object) => {
-        const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+        const meta = ctx.metaOf(object);
         check(object, object.name, meta.file, meta.line);
         for (const property of object.properties)
             check(object, property.value, meta.file, ctx.propMeta.get(property)?.line ?? meta.line);

package/dst/specbook-parse-syntax.js

@@ -201,13 +201,15 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
     let kind;
     let name;
     if (group !== undefined) {
-        const nm = head.match(/^`([^`]+)`$|^([^`:]+)$/);
+        const nm = head.match(/^`([^`]+)`\s*([^`]*)$|^([^`:]+)$/);
         if (nm === null) {
             ctx.diagnose(file, line, `unrecognized ${group} item "${text}"`);
             return;
         }
         kind = group;
-        name = (nm[1] ?? nm[2]).trim();
+        /*  a backquoted name keeps its trailing decorations outside the
+            backquotes, so they are re-joined for the marker detection below  */
+        name = (nm[1] !== undefined ? `${nm[1]} ${nm[2]}` : nm[3]).trim();
     }
     else {
         const km = head.match(/^([^:]+):\s*(.*)$/);
@@ -278,17 +280,17 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
     state.group = null;
     if (heading.malformed !== undefined)
         ctx.diagnose(file, line, `malformed anchor "${heading.malformed}" in heading`);
-    if (heading.name === "" && depth > 1) {
-        const parent = state.stack[depth - 2];
-        if (parent === undefined) {
-            ctx.diagnose(file, line, `heading level ${depth} without parent object`);
-            state.current = null;
-        }
-        else {
-            state.group = { parent, kind: heading.kind };
-            state.current = parent;
-            state.stack.length = depth - 1;
-        }
+    /*  a nested heading requires the enclosing object one level above  */
+    const parent = depth > 1 ? state.stack[depth - 2] : undefined;
+    if (depth > 1 && parent === undefined) {
+        ctx.diagnose(file, line, `heading level ${depth} without parent object`);
+        state.current = null;
+        return;
+    }
+    if (parent !== undefined && heading.name === "") {
+        state.group = { parent, kind: heading.kind };
+        state.current = parent;
+        state.stack.length = depth - 1;
         return;
     }
     const object = {
@@ -305,17 +307,10 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
     if (heading.primary)
         object.primary = true;
     ctx.objectMeta.set(object, { file, line });
-    if (depth === 1)
+    if (parent === undefined)
         state.artifacts.push({ ...stamps, objects: [object] });
-    else {
-        const parent = state.stack[depth - 2];
-        if (parent === undefined) {
-            ctx.diagnose(file, line, `heading level ${depth} without parent object`);
-            state.current = null;
-            return;
-        }
+    else
         parent.childs.push(object);
-    }
     state.stack.length = depth - 1;
     state.stack[depth - 1] = object;
     state.current = object;
@@ -360,7 +355,9 @@ export const parseFile = (ctx, source) => {
     const flush = () => {
         const current = state.current;
         if (current !== null && parts.length > 0) {
-            if (current.description === undefined)
+            if (state.group !== null)
+                ctx.diagnose(source.file, partsLine, `content ignored below ${state.group.kind} container of ${current.kind} "${current.name}"`);
+            else if (current.description === undefined)
                 current.description = splitDescription(parts.join("\n\n").trim());
             else
                 ctx.diagnose(source.file, partsLine, `content ignored, as ${current.kind} "${current.name}" already carries a description`);

package/dst/specbook-parse.d.ts

@@ -1,5 +1,10 @@
+import { Spec } from "./specbook-format-spec.js";
 import { type Schema } from "./specbook-format-schema.js";
 import { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
 export { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
 export { resolveArtifact } from "./specbook-parse-semantic.js";
 export declare const parseSpecification: (sources: SourceFile[], config?: Schema) => ParseResult;
+export declare const specStatistics: (specification: Spec) => {
+    objects: number;
+    links: number;
+};

package/dst/specbook-parse.js

@@ -5,7 +5,7 @@
 */
 import * as v from "valibot";
 import { Spec } from "./specbook-format-spec.js";
-import { buildLinkIndex } from "./specbook-link.js";
+import { buildLinkIndex, referenceRegex, plainText } from "./specbook-link.js";
 import { ParseContext } from "./specbook-parse-common.js";
 import { parseFile } from "./specbook-parse-syntax.js";
 import { validate, validateReferences } from "./specbook-parse-semantic.js";
@@ -38,3 +38,22 @@ export const parseSpecification = (sources, config) => {
     }
     return { specification, diagnostics: ctx.diagnostics, assets: Array.from(ctx.assets) };
 };
+/*  the statistics of a specification: the number of defined objects
+    (recursively) and of relationships, i.e. the Wiki-style references
+    in the names, property values, descriptions, and rationales  */
+export const specStatistics = (specification) => {
+    let objects = 0;
+    let links = 0;
+    const walk = (object) => {
+        objects++;
+        const texts = [object.name, ...object.properties.map((p) => p.value)];
+        if (object.description !== undefined)
+            texts.push(object.description.description, object.description.rationale ?? "");
+        for (const text of texts)
+            links += (plainText(text).match(referenceRegex) ?? []).length;
+        object.childs.forEach(walk);
+    };
+    for (const artifact of specification.artifacts)
+        artifact.objects.forEach(walk);
+    return { objects, links };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.1",
+    "version":                             "1.2.3",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -24,7 +24,7 @@
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.7.0",
         "@rse/mrcs":                       "0.9.2",
-        "@rse/gradia":                     "1.1.7",
+        "@rse/gradia":                     "1.1.9",
         "@toon-format/toon":               "4.1.1",
         "valibot":                         "1.4.2",
         "nunjucks":                        "3.2.4",
@@ -39,7 +39,7 @@
         "chokidar":                        "5.0.0",
         "glob":                            "13.0.6",
         "es-toolkit":                      "1.52.0",
-        "fastify":                         "5.12.1",
+        "fastify":                         "5.12.3",
         "@fastify/websocket":              "11.3.0",
         "@modelcontextprotocol/sdk":       "1.30.0",
         "zod":                             "4.5.4"