@rse/specbook 1.2.2 → 1.2.3

package/dst/specbook-link.js

@@ -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

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

@@ -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}"`);
                 }
@@ -167,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)  */
@@ -201,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}"`);
@@ -281,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);
@@ -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 };
@@ -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");
         }
@@ -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);

package/dst/specbook-parse-syntax.js

@@ -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 = {
@@ -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;
-        }
+    else
         parent.childs.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.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.2",
+    "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"