@rse/specbook 0.9.5 → 0.9.7

package/dst/specbook-link.d.ts

@@ -1,5 +1,6 @@
-import type { Specification, Object as SpecObject } from "./specbook-struct-spec.js";
+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;
@@ -9,7 +10,7 @@ export interface LinkTarget {
     target?: SpecObject;
     ambiguous: boolean;
 }
-export declare const buildLinkIndex: (specification: Specification) => LinkIndex;
+export declare const buildLinkIndex: (specification: Spec) => LinkIndex;
 export declare const resolveSet: (index: LinkIndex, reference: string) => SpecObject[];
 export declare const resolveUnique: (index: LinkIndex, reference: string) => LinkTarget;
 export declare const anchorPaths: (index: LinkIndex) => Map<SpecObject, string>;

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.d.ts

@@ -1 +1,2 @@
-export declare const serveMcp: (verbose: (msg: string) => void) => Promise<void>;
+import { type VerboseSink } from "./specbook-api.js";
+export declare const serveMcp: (verbose: VerboseSink) => Promise<void>;

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);
@@ -43,10 +43,10 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_lint", {
         title: "Lint Specification",
-        description: "Lint the specification Markdown files below the base directory against the " +
-            "optional YAML schema configuration and return all diagnostics.",
+        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().optional().describe("YAML schema configuration file"),
+            config: z.string().describe("YAML schema configuration file"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
         }
     }, async (args) => {
@@ -63,24 +63,32 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_export", {
         title: "Export Specification",
-        description: "Export the specification Markdown files below the base directory as JSON, JSON5, " +
+        description: "Export the specification Markdown files the YAML schema configuration references " +
+            "below the base directory as JSON, JSON5, " +
             "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().optional().describe("YAML schema configuration file"),
+            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") }
@@ -94,16 +102,20 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_describe", {
         title: "Describe Specification Format",
-        description: "Describe the specification format configured by the YAML schema configuration " +
-            "as a Markdown document.",
+        description: "Describe the SpecBook models and formats as a Markdown document. If the YAML " +
+            "schema configuration or the base directory is given, the description additionally points " +
+            "to the artifacts of that particular project.",
         inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
-            output: z.string().optional().describe("output file path (default: return description)")
+            config: z.string().optional().describe("YAML schema configuration file"),
+            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 (\"-\" 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}"` }] };
             }
@@ -113,49 +125,5 @@ export const serveMcp = async (verbose) => {
             return errorResult(err);
         }
     });
-    server.registerTool("specbook_import", {
-        title: "Import Foreign Sources",
-        description: "Import the information of foreign source files into the configured specification " +
-            "artifact files below the base directory, using an LLM.",
-        inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
-            inputs: z.array(z.string()).describe("foreign source files to import"),
-            provider: z.string().optional().describe("AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")"),
-            model: z.string().optional().describe("AI model")
-        }
-    }, async (args) => {
-        try {
-            const written = await specbook.import(args);
-            return { content: [{ type: "text", text: written.length > 0 ?
-                            `imported into artifact file(s): ${written.join(", ")}` :
-                            "no artifact files were changed" }] };
-        }
-        catch (err) {
-            return errorResult(err);
-        }
-    });
-    server.registerTool("specbook_edit", {
-        title: "Edit Specification",
-        description: "Apply a free-text edit request to the configured specification artifact files " +
-            "below the base directory, using an LLM.",
-        inputSchema: {
-            config: z.string().describe("YAML schema configuration file"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
-            query: z.string().describe("free-text edit request"),
-            provider: z.string().optional().describe("AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")"),
-            model: z.string().optional().describe("AI model")
-        }
-    }, async (args) => {
-        try {
-            const written = await specbook.edit(args);
-            return { content: [{ type: "text", text: written.length > 0 ?
-                            `edited artifact file(s): ${written.join(", ")}` :
-                            "no artifact files were changed" }] };
-        }
-        catch (err) {
-            return errorResult(err);
-        }
-    });
     await server.connect(new StdioServerTransport());
 };

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

@@ -1,4 +1,4 @@
-import { type Specification, type Object as SpecObject, type Property } from "./specbook-struct-spec.js";
+import { type Spec, type SpecObject, type SpecProperty } from "./specbook-format-spec.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
 import { type LinkIndex } from "./specbook-link.js";
 export interface SourceFile {
@@ -6,7 +6,7 @@ export interface SourceFile {
     text: string;
 }
 export interface ParseResult {
-    specification: Specification;
+    specification: Spec;
     diagnostics: Diagnostic[];
 }
 export interface ObjectMeta {
@@ -16,11 +16,13 @@ export interface ObjectMeta {
 export declare class ParseContext {
     diagnostics: Diagnostic[];
     objectMeta: WeakMap<SpecObject, ObjectMeta>;
-    propMeta: WeakMap<Property, {
+    propMeta: WeakMap<SpecProperty, {
         line: number;
     }>;
     linkIndex: LinkIndex;
     diagnose(file: string, line: number, message: string): void;
 }
 export declare const embeddingRegex: RegExp;
+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-common.js

@@ -16,6 +16,14 @@ export class ParseContext {
 }
 /*  the Markdown image embedding syntax ("![alt](file)")  */
 export const embeddingRegex = /!\[([^\]]*)\]\(([^()]+)\)/g;
+/*  the theme variants of a theme-aware image embedding  */
+export const embeddingThemes = ["light", "dark"];
+/*  expand an image embedding reference into its variants: a reference
+    carrying the "{theme}" placeholder yields one variant per theme,
+    while every other reference stays its own single variant  */
+export const embeddingVariants = (reference) => reference.includes("{theme}") ?
+    embeddingThemes.map((theme) => reference.replace(/\{theme\}/g, theme)) :
+    [reference];
 /*  the embeddable file types and their MIME types  */
 const embeddingTypes = {
     svg: "image/svg+xml",

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

@@ -1,5 +1,7 @@
-import { type Specification } from "./specbook-struct-spec.js";
-import { type SchemaSpecification } from "./specbook-struct-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 validate: (ctx: ParseContext, specification: Specification, config: SchemaSpecification) => void;
-export declare const validateReferences: (ctx: ParseContext, specification: Specification) => void;
+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,35 +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 a trailing parenthesized annotation from a
-    property key (e.g. "WHEN (Context)")  */
-const plainKey = (key) => key.replace(/\s*\([^)]*\)\s*$/, "").trim();
-/*  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);
-/*  match a single inline token against a value expression
-    (case-insensitively, as inline tokens are decorations)  */
-const tokenMatches = (expr, token) => expr.kind === "regex" ?
-    anchored(expr.source, "i").test(token) :
-    expr.kind === "enum" ?
-        expr.members.some((member) => member.toLowerCase() === token.toLowerCase()) :
-        false;
+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)
@@ -42,75 +26,27 @@ 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;
 };
 /*  find a property of an object by its key (case-sensitive)  */
-const findProp = (object, name) => object.properties.find((p) => plainKey(p.key) === name);
-/*  distribute the inline tokens split off the multi-token property values
-    of an object across its configured properties and report the
-    unassignable ones (the properties assigned a token are returned)  */
-const assignInlineTokens = (ctx, object, props, meta) => {
-    const tokens = new Array();
-    const tokenAssigned = new Set();
-    /*  explode a multi-token property value whose direct pattern check
-        fails: keep the token matching the own pattern and distribute
-        the remaining tokens across the sibling properties  */
-    for (const prop of props) {
-        if (prop.value === undefined)
-            continue;
-        const expr = compileValueExpr(prop.value);
-        if (expr.kind !== "regex" && expr.kind !== "enum")
-            continue;
-        const match = findProp(object, prop.name);
-        if (match === undefined || directMatches(expr, plainText(match.value)))
-            continue;
-        const parts = plainText(match.value).split(/\s+/);
-        if (parts.length < 2)
-            continue;
-        const idx = parts.findIndex((part) => tokenMatches(expr, part));
-        if (idx < 0)
-            continue;
-        match.value = parts[idx];
-        tokenAssigned.add(prop.name);
-        parts.splice(idx, 1);
-        tokens.push(...parts);
-    }
-    /*  assign the collected tokens to the still unset configured
-        properties whose pattern they match  */
-    for (const prop of props) {
-        if (prop.value === undefined || findProp(object, prop.name) !== undefined)
-            continue;
-        const expr = compileValueExpr(prop.value);
-        if (expr.kind !== "regex" && expr.kind !== "enum")
-            continue;
-        const idx = tokens.findIndex((token) => tokenMatches(expr, token));
-        if (idx >= 0) {
-            object.properties.push({ key: prop.name, value: tokens[idx] });
-            tokenAssigned.add(prop.name);
-            tokens.splice(idx, 1);
-        }
-    }
-    /*  report the tokens which no configured property accepts  */
-    for (const token of tokens)
-        ctx.diagnose(meta.file, meta.line, `unassignable inline token "${token}" on ${object.kind} "${object.name}"`);
-    return tokenAssigned;
-};
+const findProp = (object, name) => object.properties.find((p) => p.key === name);
 /*  check a property value against the compiled value expression of its
     configured schema property  */
 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}"`);
@@ -131,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}"`);
     }
@@ -140,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 };
@@ -152,35 +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}"`);
-    /*  distribute the inline tokens split off the multi-token property values  */
-    const tokenAssigned = assignInlineTokens(ctx, object, props, meta);
-    /*  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 && !tokenAssigned.has(prop.name))
-            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 === plainKey(property.key)))
+        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) {
@@ -206,27 +144,81 @@ const validateObject = (ctx, object, schema, level) => {
     };
     object.childs.sort((a, b) => kindPos(a.kind) - kindPos(b.kind));
     const propPos = (key) => {
-        const i = props.findIndex((p) => p.name === plainKey(key));
+        const i = props.findIndex((p) => p.name === key);
         return i >= 0 ? i : props.length;
     };
     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)

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

@@ -1,3 +1,3 @@
-import { type Artifact } from "./specbook-struct-spec.js";
+import { type SpecArtifact } from "./specbook-format-spec.js";
 import { ParseContext, type SourceFile } from "./specbook-parse-common.js";
-export declare const parseFile: (ctx: ParseContext, source: SourceFile) => Artifact[];
+export declare const parseFile: (ctx: ParseContext, source: SourceFile) => SpecArtifact[];