@rse/specbook 1.2.2 → 1.2.4

package/dst/specbook-link.js

@@ -55,7 +55,7 @@ export const buildLinkIndex = (specification) => {
     const walk = (object, parent) => {
         const node = { object, parent, pos: index.length, name: plainText(object.name) };
         index.push(node);
-        for (const child of object.childs)
+        for (const child of object.children)
             walk(child, node);
     };
     for (const artifact of specification.artifacts)
@@ -134,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
@@ -173,7 +173,7 @@ export const resolveUnique = (index, reference, from) => {
 };
 /*  derive the fully-qualified anchor path of every object: the
     "<kind>-<id>" segments (whitespace in kinds dashed) of the ancestor
-    chain joined with "." (the index lists parents before childs)  */
+    chain joined with "." (the index lists parents before children)  */
 export const anchorPaths = (index) => {
     const paths = new Map();
     for (const node of index) {

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.js

@@ -129,11 +129,11 @@ const parenProp = (object, props) => {
     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 checkSiblingFlags = (ctx, object, children, meta) => {
     const marker = (flag) => flag === undefined || flag === false ? undefined :
         { filter: typeof flag === "string" ? compileValueExpr(flag) : undefined };
-    for (const child of childs) {
-        const siblings = object.childs.filter((c) => c.kind === child.kind);
+    for (const child of children) {
+        const siblings = object.children.filter((c) => c.kind === child.kind);
         for (const prop of child.props ?? []) {
             const unique = marker(prop.unique);
             const present = marker(prop.present);
@@ -154,7 +154,7 @@ 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}"`);
                 }
@@ -165,9 +165,9 @@ const checkSiblingFlags = (ctx, object, childs, meta) => {
         }
     }
 };
-/*  validate a single object (and recursively its childs) against its schema  */
+/*  validate a single object (and recursively its children) 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,10 +199,10 @@ const validateObject = (ctx, object, schema, level) => {
         if (!props.some((p) => p.name === property.key))
             ctx.diagnose(meta.file, ctx.propMeta.get(property)?.line ?? meta.line, `unknown property "${property.key}" on ${object.kind} "${object.name}"`);
     /*  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 childSchema = childs.find((c) => c.kind === child.kind);
+    const children = schema.children ?? [];
+    for (const child of object.children) {
+        const childMeta = ctx.metaOf(child);
+        const childSchema = children.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}"`);
             continue;
@@ -210,20 +210,20 @@ const validateObject = (ctx, object, schema, level) => {
         validateObject(ctx, child, childSchema, level + 1);
     }
     /*  check the sibling-scoped property flags of the child kinds  */
-    checkSiblingFlags(ctx, object, childs, meta);
+    checkSiblingFlags(ctx, object, children, meta);
     /*  report the configured child object kinds which are missing  */
-    for (const child of childs)
+    for (const child of children)
         if (child.optional !== true
-            && !object.childs.some((c) => c.kind === child.kind))
+            && !object.children.some((c) => c.kind === child.kind))
             ctx.diagnose(meta.file, meta.line, `required object kind "${child.kind}" missing below ${object.kind} "${object.name}"`);
-    /*  order the childs and properties exactly along the schema
+    /*  order the children and properties exactly along the schema
         definition (the sort is stable, so objects of the same kind
         and unknown items keep their document order)  */
     const kindPos = (kind) => {
-        const i = childs.findIndex((c) => c.kind === kind);
-        return i >= 0 ? i : childs.length;
+        const i = children.findIndex((c) => c.kind === kind);
+        return i >= 0 ? i : children.length;
     };
-    object.childs.sort((a, b) => kindPos(a.kind) - kindPos(b.kind));
+    object.children.sort((a, b) => kindPos(a.kind) - kindPos(b.kind));
     const propPos = (key) => {
         const i = props.findIndex((p) => p.name === key);
         return i >= 0 ? i : props.length;
@@ -242,8 +242,8 @@ export const collectSchemas = (specification, config) => {
     const schemas = new Map();
     const walk = (object, schema) => {
         schemas.set(object, schema);
-        for (const child of object.childs) {
-            const childSchema = (schema.childs ?? []).find((c) => c.kind === child.kind);
+        for (const child of object.children) {
+            const childSchema = (schema.children ?? []).find((c) => c.kind === child.kind);
             if (childSchema !== undefined)
                 walk(child, childSchema);
         }
@@ -281,10 +281,10 @@ 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);
+        checkIds(ctx, object.children);
     }
 };
 /*  the objects a property of an object references (resolved and
@@ -317,7 +317,7 @@ const checkAutomata = (ctx, schemas) => {
         const automaton = schema.automaton;
         if (automaton === undefined)
             continue;
-        const nodes = object.childs.filter((child) => child.kind === automaton.nodes);
+        const nodes = object.children.filter((child) => child.kind === automaton.nodes);
         const nodeSet = new Set(nodes);
         const flagged = (node, name) => {
             const property = findProp(ctx, node, name);
@@ -329,7 +329,7 @@ const checkAutomata = (ctx, schemas) => {
             the node set is skipped, as the property checks report it)  */
         const succs = new Map(nodes.map((node) => [node, new Set()]));
         const preds = new Map(nodes.map((node) => [node, new Set()]));
-        for (const edge of object.childs.filter((child) => child.kind === automaton.edges)) {
+        for (const edge of object.children.filter((child) => child.kind === automaton.edges)) {
             const source = referencedObjects(ctx, edge, automaton.source)[0];
             const target = referencedObjects(ctx, edge, automaton.target)[0];
             if (source !== undefined && target !== undefined && nodeSet.has(source) && nodeSet.has(target)) {
@@ -352,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}`);
@@ -383,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 };
@@ -446,7 +446,7 @@ const checkReferenced = (ctx, specification, schemas) => {
                 if (target !== undefined && !chain.includes(target))
                     referrers.set(target, (referrers.get(target) ?? new Set()).add(object));
             }
-        object.childs.forEach(walk);
+        object.children.forEach(walk);
     };
     for (const artifact of specification.artifacts)
         artifact.objects.forEach(walk);
@@ -470,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");
         }
@@ -494,7 +494,7 @@ export const validate = (ctx, specification, config) => {
             references all over the corpus  */
         if (object.paren !== undefined && object.anchor === undefined && !ctx.parenProps.has(object))
             assignId(ctx.linkIndex, object, object.paren);
-        object.childs.forEach(promote);
+        object.children.forEach(promote);
     };
     for (const artifact of specification.artifacts)
         artifact.objects.forEach(promote);
@@ -504,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}")`);
@@ -545,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);
@@ -554,7 +554,7 @@ export const validateReferences = (ctx, specification) => {
             if (object.description.rationale !== undefined)
                 check(object, object.description.rationale, meta.file, meta.line);
         }
-        object.childs.forEach(walk);
+        object.children.forEach(walk);
     };
     for (const artifact of specification.artifacts)
         artifact.objects.forEach(walk);

package/dst/specbook-parse-syntax.js

@@ -150,7 +150,7 @@ const embed = (ctx, object, file) => {
         load(object.description, object.description.description, line);
     for (const property of object.properties)
         load(property, property.value, ctx.propMeta.get(property)?.line ?? line);
-    for (const child of object.childs)
+    for (const child of object.children)
         embed(ctx, child, file);
 };
 /*  parse an unordered list of key-values and/or concise-format objects  */
@@ -229,7 +229,7 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
         id: anchor ?? slugify(name),
         name,
         properties: [],
-        childs: []
+        children: []
     };
     if (anchor !== undefined)
         object.anchor = anchor;
@@ -267,7 +267,7 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
             ctx.diagnose(file, subLine, `nested ordered list below ${kind} "${name}" ignored`);
         subLine += (sub.raw.match(/\n/g) ?? []).length;
     }
-    parent.childs.push(object);
+    parent.children.push(object);
 };
 /*  parse a heading token into either a grouping container (e.g. "### STATE",
     collecting objects of its kind below the parent object) or a new object
@@ -280,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 = {
@@ -298,7 +298,7 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
         id: heading.id ?? (depth === 1 ? heading.paren : undefined) ?? slugify(heading.name),
         name: heading.name,
         properties: [],
-        childs: []
+        children: []
     };
     if (heading.id !== undefined)
         object.anchor = heading.id;
@@ -307,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;
-        }
-        parent.childs.push(object);
-    }
+    else
+        parent.children.push(object);
     state.stack.length = depth - 1;
     state.stack[depth - 1] = object;
     state.current = object;
@@ -362,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.children.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.2",
+    "version":                             "1.2.4",
     "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",
@@ -36,10 +36,10 @@
         "source-code-error":               "1.2.0",
         "commander":                       "15.0.0",
         "chalk":                           "6.0.0",
-        "chokidar":                        "5.0.0",
+        "chokidar5":                       "npm: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"