@rse/specbook 0.9.6 → 0.9.7

package/dst/specbook-format.md

@@ -56,7 +56,8 @@ SpecBook SCHEMA Meta Model
 This meta model defines which domain-specific objects are allowed in
 a *Schema*: the object kinds with their `file` mapping on the first
 level, the object kinds of the deeper levels, and their properties
-with optional value constraints: regular expressions `/xxx/`,
+with optional value constraints: regular expressions `/xxx/` (implicitly
+anchored, so they have to match the value as a whole),
 object references `[[xxx]]`, enumerations `enum(xxx,yyy)`, tag sets
 `tags(xxx,yyy)`, and lists `list(xxx[, ...])` of such alternatives.
 
@@ -180,7 +181,8 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE it guides the authors and instructs the AI
 
 -   `SchemaObject.optional?: boolean`:
-    whether the kind may be absent below its parent (default: `false`),
+    whether the kind may be absent below its parent or, for a level 1
+    artifact, from its file (default: `false`),
     BECAUSE not every kind is mandatory below every parent object
 
 -   `SchemaObject.diagram?: SchemaDiagram`:
@@ -502,6 +504,7 @@ type SpecProperty = {
 
 -   `SpecDescription.embedding?: string[]`:
     image files embedded via `![xxx](yyy)`, inlined at parse time,
+    one entry per file in markup order (empty for an unreadable file),
     BECAUSE the exports have to stand alone, without the image files
 
 -   `SpecProperty`:
@@ -518,6 +521,7 @@ type SpecProperty = {
 
 -   `SpecProperty.embedding?: string[]`:
     image files embedded in the value, inlined at parse time,
+    one entry per file in markup order (empty for an unreadable file),
     BECAUSE the exports have to stand alone, without the image files
 
 SpecBook SCHEMA Model
@@ -556,12 +560,12 @@ headings (`<text/>` underlined with `===` or `---`) are supported.
 ### Object Model
 
 An artifact carries a tree of *objects*. Every object has a mandatory
-*kind* (e.g. `ENTITY`), a mandatory *name*, a unique anchor *id*
-(explicitly given or derived from the name), an optional *primary*
-marker, optional *properties* (key/value pairs), an optional
-*description* statement with an optional rationale, and optional *child*
-objects. Which kinds, properties, and nestings are allowed is defined by
-the schema.
+*kind* (e.g. `ENTITY`), a mandatory *name*, an anchor *id* (explicitly
+given or derived from the name, and unique among the sibling objects of
+its kind), an optional *primary* marker, optional *properties* (key/value
+pairs), an optional *description* statement with an optional rationale,
+and optional *child* objects. Which kinds, properties, and nestings are
+allowed is defined by the schema.
 
 ### Format Variant: Complex Format
 
@@ -599,11 +603,14 @@ multiple (indented) lines:
 
 A list item is recognized as a Concise Format object (instead of a
 property of the enclosing object) by carrying at least one `;` on its
-first line. Every segment of the form `<key/>: <value/>` becomes a
-property (unless it contains a ` BECAUSE `); all remaining segments are
-joined into the description. Child objects nest as indented list items
-below their parent item, where key/value items become properties and
-concise items become child objects of that parent:
+first line. Every segment of the form `<key/>: <value/>` (with a
+possibly empty value) becomes a property, unless it contains a
+` BECAUSE ` or is the last segment of a `.`-terminated item (as a
+description like `Note: xxx` has to survive the round-trip through
+exported Markdown); all remaining segments are joined into the
+description. Child objects nest as indented list items below their
+parent item, where key/value items become properties and concise items
+become child objects of that parent:
 
 ```
 -   <kind/>: <name/>; <key/>: <value/>;
@@ -637,8 +644,13 @@ the item would look like a key/value pair) -- backquote it in this case.
 
 When **SpecBook** itself generates specification Markdown, it emits
 the Complex Format on levels 1-3 and the Concise Format from level 4
-upwards. When **SpecBook** edits existing files, it mirrors the format
-each existing object already uses.
+upwards -- unless a descendant of an object carries a multi-line
+description (a fenced code block, an ordered list, a blockquote, or
+multiple paragraphs), which no single list item can carry: all child
+objects of such an object then stay in the Complex Format (as sibling
+objects have to share the format), with headings reaching down to level
+6. When **SpecBook** edits existing files, it mirrors the format each
+existing object already uses.
 
 ### Names, Anchors, and Ids
 
@@ -666,9 +678,13 @@ explicitly written in the input, via either `{{<id/>}}` or `(<id/>)`.
 In the Complex Format, each property is an unordered list item of the
 form `<key/>: <value/>`, whose value may continue on the following
 indented lines of the item (joined with spaces). In the Concise Format,
-each property is a `<key/>: <value/>` segment. The key is matched
-against the schema exactly as written, and the value has to satisfy the
-configured constraint as a whole.
+each property is a `<key/>: <value/>` segment. A value carrying a `;`
+cannot be a segment and has to start on a continuation line of a
+key/value item, as a `;` on the first line of a list item marks a
+Concise Format object. The key is matched
+against the schema exactly as written and may occur only once per
+object, and the value has to satisfy the configured constraint as a
+whole.
 
 ### Descriptions and Rationales
 

package/dst/specbook-link.d.ts

@@ -1,5 +1,6 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
 export declare const referenceRegex: RegExp;
+export declare const plainText: (text: string) => string;
 interface LinkNode {
     object: SpecObject;
     parent?: LinkNode;

package/dst/specbook-link.js

@@ -5,6 +5,9 @@
 */
 /*  the Wiki-style reference syntax ("[[xxx]]")  */
 export const referenceRegex = /\[\[([^[\]]+)\]\]/g;
+/*  strip the inline code markup of a name or property value
+    (preserved in the AST for rendering) for matching and labeling  */
+export const plainText = (text) => text.replace(/`/g, "");
 /*  build the resolution index over all objects of a specification  */
 export const buildLinkIndex = (specification) => {
     const index = [];
@@ -40,7 +43,7 @@ const unquote = (part) => part.replace(/^"(.*)"$/s, "$1");
 const matchesPart = (object, part) => part === "*"
     || object.id === part
     || object.anchor === part
-    || object.name.replace(/`/g, "") === part;
+    || plainText(object.name) === part;
 /*  match a single reference segment ("id", "name", "KIND:name-or-id",
     "KIND:*", or "*", each part optionally double-quoted to allow
     spaces, dots, and colons) against a single object  */
@@ -80,10 +83,10 @@ export const resolveUnique = (index, reference) => {
     let matches = [];
     if (segments.length === 1) {
         const segment = segments[0];
-        const plain = unquote(segment);
+        const unquoted = unquote(segment);
         const variants = [
-            (object) => object.id === plain || object.anchor === plain,
-            (object) => object.name.replace(/`/g, "") === plain,
+            (object) => object.id === unquoted || object.anchor === unquoted,
+            (object) => plainText(object.name) === unquoted,
             (object) => matchesSegment(object, segment)
         ];
         for (const variant of variants) {

package/dst/specbook-mcp.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, formats, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, formats, parseOutputSpec, version } from "./specbook-api.js";
 /*  render an error with its cause chain into a tool error result  */
 const errorResult = (err) => {
     let msg = err instanceof Error ? err.message : String(err);
@@ -70,18 +70,25 @@ export const serveMcp = async (verbose) => {
         inputSchema: {
             config: z.string().describe("YAML schema configuration file"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
-            format: z.enum(formats).optional().describe("output format (default: json)"),
-            output: z.string().optional().describe("output file path")
+            format: z.enum(formats).optional().describe("output format (default: inferred from the " +
+                "output file extension, else json)"),
+            output: z.string().optional().describe("output file path (\"-\" returns the result directly)")
         }
     }, async (args) => {
         try {
+            /*  an explicit format takes the output as a plain file path, while
+                otherwise the output is an "[<format>:]<file>" specification
+                (the "-" stdout sentinel returns the result directly)  */
+            const spec = args.format !== undefined || args.output === undefined ?
+                { format: args.format ?? "json", output: args.output } :
+                parseOutputSpec(args.output);
             const [data] = await specbook.export({ config: args.config, basedir: args.basedir,
-                formats: [args.format ?? "json"] });
-            if (args.output !== undefined) {
-                await fs.promises.writeFile(args.output, data);
-                return { content: [{ type: "text", text: `exported specification into "${args.output}" (${data.length} bytes)` }] };
+                formats: [spec.format] });
+            if (spec.output !== undefined && spec.output !== "-") {
+                await fs.promises.writeFile(spec.output, data);
+                return { content: [{ type: "text", text: `exported specification into "${spec.output}" (${data.length} bytes)` }] };
             }
-            else if ((args.format ?? "json") === "pdf")
+            else if (spec.format === "pdf")
                 return { content: [{
                             type: "resource",
                             resource: { uri: "specbook:export.pdf", mimeType: "application/pdf", blob: data.toString("base64") }
@@ -103,12 +110,12 @@ export const serveMcp = async (verbose) => {
             basedir: z.string().optional().describe("base directory of the specification Markdown files"),
             embed: z.boolean().optional().describe("embed the YAML schema configuration instead of " +
                 "just referencing it (default: false)"),
-            output: z.string().optional().describe("output file path (default: return description)")
+            output: z.string().optional().describe("output file path (\"-\" or omitted returns the description directly)")
         }
     }, async (args) => {
         try {
             const text = await specbook.describe(args);
-            if (args.output !== undefined) {
+            if (args.output !== undefined && args.output !== "-") {
                 await fs.promises.writeFile(args.output, text, "utf8");
                 return { content: [{ type: "text", text: `described specification format into "${args.output}"` }] };
             }

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

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

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

@@ -1,5 +1,7 @@
-import { type Spec } from "./specbook-format-spec.js";
-import { type Schema } from "./specbook-format-schema.js";
+import { type Spec, type SpecObject } 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 validate: (ctx: ParseContext, specification: Spec, config: Schema) => void;
 export declare const validateReferences: (ctx: ParseContext, specification: Spec) => void;

package/dst/specbook-parse-semantic.js

@@ -3,25 +3,19 @@
 **  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 } from "./specbook-link.js";
-import { compileValueExpr, splitItems } from "./specbook-parse-value.js";
-/*  strip the inline code markup of a name or property value
-    (preserved in the AST for rendering) for matching purposes  */
-const plainText = (text) => text.replace(/`/g, "");
-/*  compile a configured pattern into an anchored regular expression  */
-const anchored = (pattern, flags = "") => new RegExp(`^(?:${pattern})$`, flags);
+import { referenceRegex, resolveUnique, resolveSet, plainText } 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 = /^\[\[([^[\]]+)\]\]$/;
 /*  match a full property value directly against a value expression
     (defined for the regex and enum kinds only)  */
-const directMatches = (expr, text) => expr.kind === "regex" ?
-    expr.regex.test(text) :
-    expr.kind === "enum" ?
-        expr.members.includes(text) :
-        false;
+const directMatches = (expr, text) => (expr.kind === "regex" && expr.regex.test(text))
+    || (expr.kind === "enum" && expr.members.includes(text));
 /*  match a single list item against the alternatives of a list
     constraint (a reference item resolves leniently, as unresolvable
     and ambiguous ones are already reported by the reference pass)  */
 const matchAlternatives = (ctx, alternatives, item) => {
-    const rm = item.match(/^\[\[([^[\]]+)\]\]$/);
+    const rm = item.match(singleReferenceRegex);
     for (const alternative of alternatives) {
         if (alternative.kind === "reference") {
             if (rm === null)
@@ -32,10 +26,10 @@ const matchAlternatives = (ctx, alternatives, item) => {
                 return true;
         }
         else if (alternative.kind === "tags") {
-            if (alternative.members.includes(plainText(item)))
+            if (alternative.members.includes(item))
                 return true;
         }
-        else if (directMatches(alternative, plainText(item)))
+        else if (directMatches(alternative, item))
             return true;
     }
     return false;
@@ -48,10 +42,11 @@ 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()))
+        const rm = plainText(property.value).trim().match(singleReferenceRegex);
+        if (rm === null)
             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 ref = rm[1].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}"`);
@@ -72,7 +67,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(property.value))
+        for (const item of splitItems(plainText(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}"`);
     }
@@ -81,6 +76,16 @@ const checkPropValue = (ctx, 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
+    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 && findProp(object, prop.name) === undefined
+        && directMatches(compileValueExpr(prop.value), paren));
+};
 /*  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 };
@@ -93,33 +98,27 @@ const validateObject = (ctx, object, schema, level) => {
         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}"`);
-    /*  check the configured properties  */
-    let parenConsumed = false;
+    /*  check every occurrence of the configured properties (a trailing
+        parenthesized name token is accepted as the value of a still
+        missing property, and a repeated key is reported as duplicate)  */
+    const consumed = parenProp(object, props);
     for (const prop of props) {
         const expr = prop.value !== undefined ? compileValueExpr(prop.value) : undefined;
-        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  */
-            if (object.paren !== undefined && expr !== undefined
-                && directMatches(expr, object.paren)) {
-                parenConsumed = true;
-                continue;
-            }
-            if (prop.optional !== true)
-                ctx.diagnose(meta.file, meta.line, `required property "${prop.name}" missing on ${object.kind} "${object.name}"`);
+        const matches = object.properties.filter((p) => p.key === prop.name);
+        if (matches.length === 0 && prop !== consumed && prop.optional !== true)
+            ctx.diagnose(meta.file, meta.line, `required property "${prop.name}" missing on ${object.kind} "${object.name}"`);
+        for (const [i, match] of matches.entries()) {
+            const line = ctx.propMeta.get(match)?.line ?? meta.line;
+            if (i > 0)
+                ctx.diagnose(meta.file, line, `duplicate property "${prop.name}" on ${object.kind} "${object.name}"`);
+            if (expr !== undefined)
+                checkPropValue(ctx, prop, expr, match, { file: meta.file, line });
         }
-        else if (expr !== undefined)
-            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 === property.key))
             ctx.diagnose(meta.file, ctx.propMeta.get(property)?.line ?? meta.line, `unknown property "${property.key}" on ${object.kind} "${object.name}"`);
-    /*  a parenthesized token not consumed as a property value acts as
-        the implicit anchor (an explicit "{{...}}" anchor takes precedence)  */
-    if (object.paren !== undefined && !parenConsumed && object.anchor === undefined)
-        object.id = object.paren;
     /*  check the configured child objects  */
     const childs = schema.childs ?? [];
     for (const child of object.childs) {
@@ -150,22 +149,76 @@ const validateObject = (ctx, object, schema, level) => {
     };
     object.properties.sort((a, b) => propPos(a.key) - propPos(b.key));
 };
+/*  resolve a level 1 object onto its configured artifact, deliberately
+    leniently by kind and id first and by case-insensitive name second,
+    so deviations of the heading can still be precisely reported  */
+export const resolveArtifact = (config, object) => config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
+    config.find((s) => s.name !== undefined
+        && s.name.toUpperCase() === plainText(object.name).toUpperCase());
+/*  map the specification objects onto their schema configuration
+    nodes (the artifact resolution is shared with the validation)  */
+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);
+            if (childSchema !== undefined)
+                walk(child, childSchema);
+        }
+    };
+    for (const artifact of specification.artifacts) {
+        for (const object of artifact.objects) {
+            const schema = resolveArtifact(config, object);
+            if (schema !== undefined)
+                walk(object, schema);
+        }
+    }
+    return schemas;
+};
+/*  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  */
+const checkIds = (ctx, objects) => {
+    const seen = new Map();
+    for (const object of objects) {
+        const key = `${object.kind}:${object.id}`;
+        const first = seen.get(key);
+        if (first === undefined)
+            seen.set(key, object);
+        else {
+            const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+            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);
+    }
+};
 /*  validate the parsed specification against the configuration  */
 export const validate = (ctx, specification, config) => {
+    /*  map all objects onto their schema nodes and assign the implicit
+        ids up-front: a parenthesized token not consumed as a property
+        value acts as the id (an explicit "{{...}}" anchor takes
+        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)
+        if (object.paren !== undefined && object.anchor === undefined
+            && parenProp(object, schema.props ?? []) === undefined)
+            object.id = object.paren;
+    /*  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  */
     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 schema = config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
-                config.find((s) => s.name !== undefined
-                    && s.name.toUpperCase() === plainText(object.name).toUpperCase());
+            const schema = schemas.get(object);
             if (schema === undefined) {
                 ctx.diagnose(meta.file, meta.line, `unknown artifact "${object.kind}: ${object.name}" (id "${object.id}")`);
                 continue;
             }
             /*  the artifact heading must carry the configured kind and
-                name verbatim (the resolution above is deliberately
-                lenient, so deviations are still precisely reported)  */
+                name verbatim (the resolution is lenient on purpose)  */
             if (object.kind !== schema.kind)
                 ctx.diagnose(meta.file, meta.line, `artifact kind "${object.kind}" does not match configured kind "${schema.kind}"`);
             if (schema.name !== undefined && plainText(object.name) !== schema.name)