@rse/specbook 0.9.7 → 0.9.9

package/dst/specbook-mcp.js

@@ -27,7 +27,8 @@ export const serveMcp = async (verbose) => {
         description: "Initialize the configured specification artifact files below the base directory " +
             "with their frontmatter and artifact heading, skipping already existing files.",
         inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
+            config: z.string().optional().describe("YAML schema configuration file " +
+                "(default: the bundled standard schema configuration)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
         }
     }, async (args) => {
@@ -46,7 +47,8 @@ export const serveMcp = async (verbose) => {
         description: "Lint the specification Markdown files the YAML schema configuration references " +
             "below the base directory against this configuration and return all diagnostics.",
         inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
+            config: z.string().optional().describe("YAML schema configuration file " +
+                "(default: the bundled standard schema configuration)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
         }
     }, async (args) => {
@@ -68,7 +70,8 @@ export const serveMcp = async (verbose) => {
             "YAML, TOON, HTML, PDF, or normalized Markdown. The result is written to the output file " +
             "if an output path is given, else it is returned directly (PDF as a base64-encoded resource).",
         inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
+            config: z.string().optional().describe("YAML schema configuration file " +
+                "(default: the bundled standard schema configuration)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
             format: z.enum(formats).optional().describe("output format (default: inferred from the " +
                 "output file extension, else json)"),

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

@@ -22,6 +22,7 @@ export declare class ParseContext {
     linkIndex: LinkIndex;
     diagnose(file: string, line: number, message: string): void;
 }
+export declare const becauseRegex: RegExp;
 export declare const embeddingRegex: RegExp;
 export declare const embeddingThemes: readonly ["light", "dark"];
 export declare const embeddingVariants: (reference: string) => string[];

package/dst/specbook-parse-common.js

@@ -14,6 +14,8 @@ export class ParseContext {
         this.diagnostics.push({ file, line, column: 1, message });
     }
 }
+/*  the marker separating a statement from its rationale  */
+export const becauseRegex = /,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/;
 /*  the Markdown image embedding syntax ("![alt](file)")  */
 export const embeddingRegex = /!\[([^\]]*)\]\(([^()]+)\)/g;
 /*  the theme variants of a theme-aware image embedding  */

package/dst/specbook-parse-semantic.js

@@ -36,6 +36,15 @@ const matchAlternatives = (ctx, alternatives, item) => {
 };
 /*  find a property of an object by its key (case-sensitive)  */
 const findProp = (object, name) => object.properties.find((p) => p.key === name);
+/*  split a multi-valued property value into its items, reporting an
+    empty one -- stemming from an empty value or a stray comma -- once,
+    as such an item can never satisfy any constraint  */
+const splitPropItems = (ctx, prop, property, meta) => {
+    const items = splitItems(plainText(property.value));
+    if (items.some((item) => item === ""))
+        ctx.diagnose(meta.file, meta.line, `property "${prop.name}" value "${property.value}" contains an empty item`);
+    return items.filter((item) => item !== "");
+};
 /*  check a property value against the compiled value expression of its
     configured schema property  */
 const checkPropValue = (ctx, prop, expr, property, meta) => {
@@ -56,7 +65,7 @@ const checkPropValue = (ctx, prop, expr, property, meta) => {
         /*  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))) {
+        for (const item of splitPropItems(ctx, prop, property, meta)) {
             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))
@@ -67,7 +76,7 @@ const checkPropValue = (ctx, prop, expr, property, meta) => {
     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(plainText(property.value)))
+        for (const item of splitPropItems(ctx, prop, property, meta))
             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}"`);
     }
@@ -201,10 +210,19 @@ 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, schema] of schemas)
+    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 && object.anchor === undefined
-            && parenProp(object, schema.props ?? []) === undefined)
+            && parenProp(object, schemas.get(object)?.props ?? []) === undefined)
             object.id = object.paren;
+        object.childs.forEach(promote);
+    };
+    for (const artifact of specification.artifacts)
+        artifact.objects.forEach(promote);
     /*  check the ids for local uniqueness, now that all of them are final  */
     checkIds(ctx, specification.artifacts.flatMap((artifact) => artifact.objects));
     /*  validate every level 1 object against its artifact schema  */

package/dst/specbook-parse-syntax.js

@@ -6,9 +6,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { marked } from "marked";
-import { embeddingRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
-/*  the marker separating a statement from its rationale  */
-const becauseRegex = /,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/;
+import { becauseRegex, embeddingRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
 /*  split a description text into statement and optional rationale  */
 const splitDescription = (text) => {
     const m = text.match(becauseRegex);
@@ -268,7 +266,9 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
 };
 /*  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
-    (an artifact on level 1, a child of the enclosing object below)  */
+    (an artifact on level 1, a child of the enclosing object below); a heading
+    without a parent object detaches the current object, so the content below
+    it is reported, too, instead of being absorbed by the previous object  */
 const parseHeading = (ctx, token, state, stamps, file, line) => {
     const { depth, text } = token;
     const heading = parseHeadingText(text);
@@ -277,8 +277,10 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
         ctx.diagnose(file, line, `malformed anchor "${heading.malformed}" in heading`);
     if (heading.name === "" && depth > 1) {
         const parent = state.stack[depth - 2];
-        if (parent === undefined)
+        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;
@@ -306,6 +308,7 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
         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);
@@ -314,6 +317,15 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
     state.stack[depth - 1] = object;
     state.current = object;
 };
+/*  the block-level token types which carry content no description can
+    hold, mapped onto their diagnostic name (the only other unhandled
+    type is "space", which carries no content at all)  */
+const unsupportedTokens = {
+    table: "table",
+    html: "raw HTML",
+    hr: "horizontal rule",
+    def: "link definition"
+};
 /*  parse a single source file into its artifacts  */
 export const parseFile = (ctx, source) => {
     const { present, created, modified, body, offset } = parseFrontmatter(source.text);
@@ -380,8 +392,11 @@ export const parseFile = (ctx, source) => {
             else
                 collect(token.raw, line);
         }
-        else if (token.type === "table")
-            ctx.diagnose(source.file, line, "unsupported table content ignored");
+        else {
+            const unsupported = unsupportedTokens[token.type];
+            if (unsupported !== undefined)
+                ctx.diagnose(source.file, line, `unsupported ${unsupported} content ignored`);
+        }
         line += (token.raw.match(/\n/g) ?? []).length;
     }
     flush();

package/dst/specbook-parse-value.js

@@ -98,7 +98,8 @@ export const compileValueExpr = (source) => {
     return expr;
 };
 /*  split a property value at top-level commas, honoring double-quoted
-    sections and "[[...]]" reference bracketing  */
+    sections and "[[...]]" reference bracketing (empty items are kept,
+    as only the caller can decide whether to report or skip them)  */
 export const splitItems = (text) => {
     const parts = [""];
     let quoted = false;
@@ -128,5 +129,5 @@ export const splitItems = (text) => {
         const item = part.trim();
         const m = item.match(/^"((?:\\"|[^"])*)"$/);
         return m !== null ? m[1].replace(/\\"/g, "\"") : item;
-    }).filter((part) => part !== "");
+    });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "0.9.7",
+    "version":                             "0.9.9",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",