@rse/specbook 0.9.3 → 0.9.5

package/dst/specbook-export-common.js

@@ -6,8 +6,9 @@
 import path from "node:path";
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
-/*  escape a text for embedding into template HTML  */
-export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/*  escape a text for embedding into template HTML (text and attributes)  */
+export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 /*  provide the build-time pre-assembled stylesheet (with the
     font faces already inlined as base64 data: URIs)  */
 export const stylesheet = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-html.css"), "utf8");
@@ -18,9 +19,10 @@ export const searchScript = () => fs.readFileSync(path.join(path.dirname(fileURL
 export const fallbackLogo = () => "data:image/svg+xml;base64," + fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-logo.svg")).toString("base64");
 /*  check whether an object is the specification title object  */
 export const isTitleObject = (object) => object.kind === "META" && object.name.toUpperCase() === "TITLE";
+/*  determine the title object of the specification  */
+const titleObject = (specification) => specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject);
 /*  determine a property value of the title object  */
-const titleProperty = (specification, name) => specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject)
-    ?.properties.find((property) => property.key === name)?.value;
+const titleProperty = (specification, name) => titleObject(specification)?.properties.find((property) => property.key === name)?.value;
 /*  determine the document language (LANG) from the title object  */
 export const documentLang = (specification) => titleProperty(specification, "LANG")?.trim();
 /*  determine the document character set (CHARSET) from the title object  */
@@ -37,28 +39,39 @@ const papers = {
     "Letter": { unit: "in", height: 11, margin: { top: 1, bottom: 1, left: 0.8, right: 0.8 } },
     "Legal": { unit: "in", height: 14, margin: { top: 1, bottom: 1, left: 0.8, right: 0.8 } }
 };
-export const paperSizes = Object.keys(papers);
+const paperSizes = Object.keys(papers);
 export const paperSizeDefault = "A4";
 /*  provide the setup of a paper size, falling back onto the default  */
 export const paperSetup = (paper) => papers[paper] ?? papers[paperSizeDefault];
 /*  render a paper dimension as its CSS length  */
 export const paperLength = (setup, value) => `${value}${setup.unit}`;
 /*  determine the document paper size (PAPER-SIZE) from the title object,
-    matched case-insensitively and falling back onto the default  */
+    matched case-insensitively, falling back onto the default if unset
+    and rejecting an unknown size  */
 export const documentPaperSize = (specification) => {
-    const value = titleProperty(specification, "PAPER-SIZE")?.trim().toLowerCase();
-    return paperSizes.find((name) => name.toLowerCase() === value) ?? paperSizeDefault;
+    const value = titleProperty(specification, "PAPER-SIZE")?.trim();
+    if (value === undefined)
+        return paperSizeDefault;
+    const paper = paperSizes.find((name) => name.toLowerCase() === value.toLowerCase());
+    if (paper === undefined)
+        throw new Error(`unknown paper size "${value}" ` +
+            `(expected ${paperSizes.join(", ")})`);
+    return paper;
 };
 /*  provide the paper-dependent print stylesheet: a diagram is scaled
     down to still fit onto a single page (the paper height less the
-    print margins and the own vertical margins of the diagram) and is
-    never broken across a page boundary  */
+    print margins, the own vertical margins of the diagram, and the
+    room its introducing heading claims above it) and is never broken
+    across a page boundary; without the heading reserve a maximally
+    sized diagram could not share its page with the heading, which
+    would defeat the "break-after: avoid" bundling of the stylesheet  */
+const headingReserve = 6;
 export const paperStylesheet = (paper) => {
     const setup = paperSetup(paper);
     const avail = setup.height - setup.margin.top - setup.margin.bottom;
     return "@media print {\n" +
         "div.diagram { break-inside: avoid; }\n" +
-        `div.diagram svg { max-height: calc(${paperLength(setup, avail)} - 2rem);` +
+        `div.diagram svg { max-height: calc(${paperLength(setup, avail)} - ${headingReserve}rem);` +
         " width: auto; height: auto; }\n" +
         "}\n";
 };
@@ -87,7 +100,7 @@ export const charsetCodepoints = (charset) => {
     else if (name === "utf8" || name === "utf16" || name === "unicode")
         return undefined;
     throw new Error(`unknown charset "${charset}" ` +
-        "(expected US-ASCII, ISO-8859-1/ISO-Latin-1, ISO-8859-15/ISO-Latin-15, or UTF-8)");
+        "(expected US-ASCII, ISO-8859-1/ISO-Latin-1, ISO-8859-15/ISO-Latin-9, or UTF-8)");
 };
 /*  the symbol glyphs used by the HTML/PDF rendering (kind and property
     bullets, link symbol, primary marker, theme switch icon, anchor
@@ -123,18 +136,18 @@ export const subsetStylesheet = async (charset) => {
     return result + css.slice(last);
 };
 /*  determine the document title and subtitle from the title object  */
-export const documentTitle = (specification) => {
-    const object = specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject);
-    const prop = (name) => object?.properties.find((property) => property.key === name)?.value;
-    return { title: prop("TITLE") ?? object?.name ?? "Specification", subtitle: prop("SUBTITLE") };
-};
+export const documentTitle = (specification) => ({
+    title: titleProperty(specification, "TITLE") ??
+        titleObject(specification)?.name ?? "Specification",
+    subtitle: titleProperty(specification, "SUBTITLE")
+});
 /*  determine the document logo as a self-contained data: URL, taken from the
     embedded image of the LOGO property of the title object, and falling back
     onto the built-in SpecBook logo (for use in isolated rendering contexts,
     like the print header/footer, which load no external resources)  */
 export const documentLogo = (specification) => {
-    const object = specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject);
-    const content = object?.properties.find((property) => property.key === "LOGO")?.embedding?.[0];
+    const content = titleObject(specification)
+        ?.properties.find((property) => property.key === "LOGO")?.embedding?.[0];
     if (content === undefined)
         return fallbackLogo();
     return content.startsWith("data:") ? content :

package/dst/specbook-export-html-search.js

@@ -45,7 +45,7 @@
                             return
                         parent = parent.parentElement
                     }
-                    const text  = (el.textContent || "").toLowerCase()
+                    const text  = (el.textContent ?? "").toLowerCase()
                     const words = new Set(text.split(/[^\p{L}\p{N}]+/u).filter((w) => w !== ""))
                     words.forEach((w) => { vocab.add(w) })
                     units.push({ el, text, words, keep: false })
@@ -141,7 +141,7 @@
         keeps the tags and attributes untouched  */
     const highlight = (el, regex) => {
         const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT)
-        const nodes = []
+        const nodes  = []
         let node
         while ((node = walker.nextNode()) !== null)
             nodes.push(node)
@@ -231,13 +231,15 @@
         })
 
         /*  hide the units not kept, plus the objects and tables which
-            ran entirely empty in the process  */
+            ran entirely empty in the process (a table nested inside a
+            kept unit, like a chunked property table, stays visible)  */
         units.forEach((unit) => {
             if (!unit.el.classList.contains("search-keep"))
                 unit.el.classList.add("search-hide")
         })
         document.querySelectorAll("article section, article table").forEach((el) => {
-            if (el.querySelector(".search-keep") === null)
+            if (el.querySelector(".search-keep") === null
+                && el.closest(".search-keep") === null)
                 el.classList.add("search-hide")
         })
 

package/dst/specbook-export-html.css

@@ -137,6 +137,13 @@ section                     { margin: 0.5rem 0; }
 h1                          { margin: 3.0rem 0 2.0rem 0; border-bottom: 1px solid var(--theme-color-specbook-border); }
 h2, h3, h4                  { margin: 2.0rem 0 1.0rem 0; }
 
+/*  bundle a heading with the content it introduces (diagram, property
+    table, description), so no heading is left orphaned at the very
+    bottom of a page while its content starts on the next one  */
+@media print {
+h1, h2, h3, h4, h5, h6      { page-break-after: avoid; break-after: avoid; }
+}
+
 body                        { counter-reset: sec1; }
 article h1                  { counter-increment: sec1; counter-reset: sec2; }
 article h2                  { counter-increment: sec2; counter-reset: sec3; }

package/dst/specbook-export-html.js

@@ -3,7 +3,7 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { marked } from "marked";
+import { Marked } from "marked";
 import { markedSmartypants } from "marked-smartypants";
 import nunjucks from "nunjucks";
 import nunjucksAddons from "@rse/nunjucks-addons";
@@ -30,7 +30,8 @@ const templates = {
                 <script>
                     (function () {
                         let style = null
-                        try { style = localStorage.getItem("specbook-theme") } catch (ex) {}
+                        try { style = localStorage.getItem("specbook-theme") }
+                        catch { /*  an inaccessible storage just means no stored choice  */ }
                         if (style === null) {
                             const m = document.documentElement.className.match(/theme-(light|dark)/)
                             style = m !== null ? m[1] : null
@@ -42,7 +43,8 @@ const templates = {
                     function themeSwitch () {
                         const style = document.documentElement.className === "theme-dark" ? "light" : "dark"
                         document.documentElement.className = "theme-" + style
-                        try { localStorage.setItem("specbook-theme", style) } catch (ex) {}
+                        try { localStorage.setItem("specbook-theme", style) }
+                        catch { /*  an inaccessible storage just loses the choice  */ }
                     }
                 </script>
             </head>
@@ -194,6 +196,10 @@ const quoteStyles = {
 };
 /*  the active double quote style (set per document during rendering)  */
 let quotes = quoteStyles.en;
+/*  the private Markdown renderer instance, as the hooks below must not
+    leak into the "marked" singleton shared with the parser and with the
+    application embedding SpecBook as a library  */
+const marked = new Marked();
 /*  improve the typography of all rendered Markdown text (curly quotes,
     "--" as the em dash, ellipsis); as smartypants requires unescaped text,
     the extension switches off the text escaping of marked, so the stray
@@ -209,6 +215,7 @@ const env = new nunjucks.Environment(null, { autoescape: true });
 nunjucksAddons(env);
 /*  mark pre-rendered HTML as safe for template interpolation  */
 const safe = (html) => new nunjucks.runtime.SafeString(html);
+/*  render one of the built-in Nunjucks templates with a context  */
 const render = (name, context) => env.renderString(templates[name], context);
 /*  the active per-document reference expander, fully-qualified
     anchor paths, enum/tags property value kinds, object schema nodes,
@@ -218,6 +225,9 @@ let anchors = null;
 let members = null;
 let schemas = null;
 let diagrams = null;
+/*  the cache of the pre-rendered diagram SVGs, keyed by specification,
+    as the PDF export renders the very same document multiple times  */
+const diagramCache = new WeakMap();
 /*  determine the fully-qualified anchor path of an object  */
 const anchorOf = (object) => anchors?.get(object) ?? object.id;
 /*  expand the inline Markdown of a text (code spans, emphasis, etc.),
@@ -308,7 +318,7 @@ const plainKey = (key) => key.replace(/\s*\([^)]*\)\s*$/, "").trim();
 /*  render a property value, badging the individual members of an
     "enum(...)" (a single member) or "tags(...)" (a member set) value  */
 const inlineValue = (kind, key, value) => {
-    const member = members?.get(`${kind}${key.replace(/\s*\([^)]*\)\s*$/, "").trim()}`);
+    const member = members?.get(`${kind}${plainKey(key)}`);
     if (member === undefined)
         return inline(value);
     const items = member === "tags" ? splitItems(value) : [value.trim()];
@@ -319,8 +329,9 @@ const inlineProperties = (kind, properties) => properties.map((property) => ({ k
     value: inlineValue(kind, property.key, property.value) }));
 /*  resolve the format configuration of an object  */
 const formatOf = (object) => schemas?.get(object)?.format;
-/*  determine the maximum table columns configured on an object  */
-const maxColumnsOf = (object) => formatOf(object)?.maxTableColumns ?? 4;
+/*  determine the maximum table columns configured on an object (at
+    least two, as a single column cannot carry a name and a value)  */
+const maxColumnsOf = (object) => Math.max(2, formatOf(object)?.maxTableColumns ?? 4);
 /*  determine the effective properties of an object, with
     "withUnusedProps" injecting the defined but still unused schema
     properties (in schema order) as empty key/value entries  */
@@ -470,6 +481,10 @@ const renderObject = (object, level, concise) => {
 /*  render the title object into a title page  */
 const renderTitlePage = (object, created, modified) => {
     const prop = (name) => object.properties.find((property) => property.key === name)?.value;
+    const inlineProp = (name) => {
+        const value = prop(name);
+        return value !== undefined ? inline(value) : "";
+    };
     const rest = object.properties.filter((property) => !["LOGO", "TITLE", "SUBTITLE", "AUTHOR", "VERSION",
         "LANG", "CHARSET", "PAPER-SIZE", "THEME-STYLE", "THEME-TONE"].includes(property.key));
     /*  the logo is rendered above the title, from the embedded image content
@@ -481,9 +496,9 @@ const renderTitlePage = (object, created, modified) => {
             logo: logo === undefined ? safe(`<img src="${fallbackLogo()}" alt="SpecBook"/>`) :
                 (image.length > 0 ? safe(image.join("")) : inline(logo.value)),
             title: inline(prop("TITLE") ?? object.name),
-            subtitle: prop("SUBTITLE") !== undefined ? inline(prop("SUBTITLE") ?? "") : "",
-            author: prop("AUTHOR") !== undefined ? inline(prop("AUTHOR") ?? "") : "",
-            version: prop("VERSION") !== undefined ? inline(prop("VERSION") ?? "") : "",
+            subtitle: inlineProp("SUBTITLE"),
+            author: inlineProp("AUTHOR"),
+            version: inlineProp("VERSION"),
             description: object.description !== undefined ?
                 safe(renderDescription(object.description)) : "",
             properties: rest.length > 0 ?
@@ -515,9 +530,6 @@ export const htmlOutline = (specification, config) => {
     artifact timestamps aggregated into min(Created)/max(Modified), and
     optional per-anchor page numbers attached to the ToC entries  */
 export const renderHtml = async (specification, config, tocPages, css) => {
-    /*  the document language selects the smart typography quote style  */
-    const lang = documentLang(specification);
-    quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
     /*  pre-render the configured diagrams as embeddable SVGs (a runtime
         rendering failure omits the diagram, as the statically detectable
         invalid situations are already reported as lint diagnostics),
@@ -525,8 +537,11 @@ export const renderHtml = async (specification, config, tocPages, css) => {
         (node boxes, font sizes) is dimensioned for a stand-alone
         canvas and would dwarf the document text at 1:1  */
     const scale = 0.75;
+    const cached = diagramCache.get(specification);
     diagrams = null;
-    if (config !== undefined) {
+    if (cached !== undefined && cached.config === config)
+        diagrams = cached.diagrams;
+    else if (config !== undefined) {
         diagrams = new Map();
         for (const [object, result] of specDiagrams(specification, config)) {
             if (result.spec === undefined)
@@ -539,7 +554,11 @@ export const renderHtml = async (specification, config, tocPages, css) => {
                 /*  intentionally omitted  */
             }
         }
+        diagramCache.set(specification, { config, diagrams });
     }
+    /*  the document language selects the smart typography quote style  */
+    const lang = documentLang(specification);
+    quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
     /*  expand "[[xxx]]" references into hyperlinks (an unresolvable or
         ambiguous reference stays literal, marked as broken), targeting
         the fully-qualified anchor paths of the objects  */

package/dst/specbook-export-md.js

@@ -31,7 +31,12 @@ const renderConciseMd = (object, level) => {
     segments.push(...object.properties.map((property) => `${property.key}: ${property.value}`));
     if (object.description !== undefined)
         segments.push(renderDescriptionMd(object.description));
-    const item = `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}`;
+    /*  a description terminates the item with ".", while without one the
+        ";" segment terminator has to remain, as only it lets the item be
+        recognized as a concise object again on re-parsing  */
+    const item = object.description !== undefined ?
+        `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}` :
+        `${indent}-   ${segments.join("; ")};`;
     return [item, ...object.childs.map((child) => renderConciseMd(child, level + 1))].join("\n");
 };
 /*  render an object in the Complex Format (levels 1-3),
@@ -39,9 +44,8 @@ const renderConciseMd = (object, level) => {
     and the optionally derived Gradia diagram spec embedded
     as a "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
-    const heading = level === 1 ?
-        `#   ${object.kind}: ${object.name}${nameSuffixMd(object)}` :
-        `${"#".repeat(level)}${" ".repeat(4 - level)}${object.kind}: ${object.name}${nameSuffixMd(object)}`;
+    const heading = `${"#".repeat(level)}${" ".repeat(4 - level)}` +
+        `${object.kind}: ${object.name}${nameSuffixMd(object)}`;
     const parts = [heading];
     const spec = diagrams?.get(object);
     if (spec !== undefined)
@@ -66,9 +70,9 @@ export const renderMarkdown = async (specification, config) => {
         for (const [object, result] of specDiagrams(specification, config))
             if (result.spec !== undefined)
                 diagrams.set(object, result.spec);
-    return specification.artifacts.map((artifact) => artifact.objects.map((object) => "---\n" +
+    return specification.artifacts.map((artifact) => "---\n" +
         `Created:  ${formatTimestamp(artifact.created)}\n` +
         `Modified: ${formatTimestamp(artifact.modified)}\n` +
         "---\n\n" +
-        renderObjectMd(object, 1, diagrams)).join("\n\n")).join("\n\n") + "\n";
+        artifact.objects.map((object) => renderObjectMd(object, 1, diagrams)).join("\n\n")).join("\n\n") + "\n";
 };

package/dst/specbook-export-pdf.js

@@ -153,7 +153,7 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
                 "padding-bottom: 1mm; display: flex; justify-content: space-between; " +
                 "align-items: flex-end;\">" +
                 `<span>${headText}</span>` +
-                `<img src="${heading.logo}" alt="" style="height: 3.5mm;"/>` +
+                `<img src="${escapeHtml(heading.logo)}" alt="" style="height: 3.5mm;"/>` +
                 "</div></div>",
             footerTemplate: `<style>${fontFace}</style>` +
                 "<div style=\"width: 100%; margin-bottom: 0.8cm;\">" +
@@ -185,8 +185,9 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
         /*  draw the vertical brand bar onto the left edge of the
             physical paper of every page, as Chromium clips print
             content to the page box (0.6rem at the 9pt print root)  */
-        const [r, g, b] = (theme.accent.match(/[0-9a-f]{2}/gi) ?? [])
-            .map((hex) => parseInt(hex, 16) / 255);
+        const hex = theme.accent.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+        const [r, g, b] = (hex !== null ? hex.slice(1) : ["00", "00", "00"])
+            .map((component) => parseInt(component, 16) / 255);
         for (const pdfPage of merged.getPages())
             pdfPage.drawRectangle({ x: 0, y: 0, width: 5.4,
                 height: pdfPage.getHeight(), color: rgb(r, g, b) });

package/dst/specbook-llm.js

@@ -3,40 +3,30 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { generateText } from "ai";
-/*  the default model per supported provider  */
-const defaults = {
-    anthropic: "claude-sonnet-5",
-    openai: "gpt-5.6-luna",
-    openrouter: "anthropic/claude-sonnet-5",
-    ollama: "qwen3"
+/*  the supported AI providers  */
+const providers = {
+    anthropic: { model: "claude-sonnet-5",
+        create: async (id) => (await import("@ai-sdk/anthropic")).createAnthropic()(id) },
+    openai: { model: "gpt-5.6-luna",
+        create: async (id) => (await import("@ai-sdk/openai")).createOpenAI()(id) },
+    openrouter: { model: "anthropic/claude-sonnet-5",
+        create: async (id) => (await import("@openrouter/ai-sdk-provider")).createOpenRouter()(id) },
+    ollama: { model: "qwen3",
+        create: async (id) => (await import("ollama-ai-provider-v2")).createOllama()(id) }
 };
 /*  resolve the AI provider and model into a language model handle  */
 export const resolveModel = async (options) => {
-    const provider = options.provider ?? process.env.SPECBOOK_AI_PROVIDER ?? "anthropic";
-    const model = options.model ?? process.env.SPECBOOK_AI_MODEL ?? defaults[provider];
-    if (provider === "anthropic") {
-        const { createAnthropic } = await import("@ai-sdk/anthropic");
-        return createAnthropic()(model);
-    }
-    else if (provider === "openai") {
-        const { createOpenAI } = await import("@ai-sdk/openai");
-        return createOpenAI()(model);
-    }
-    else if (provider === "openrouter") {
-        const { createOpenRouter } = await import("@openrouter/ai-sdk-provider");
-        return createOpenRouter()(model);
-    }
-    else if (provider === "ollama") {
-        const { createOllama } = await import("ollama-ai-provider-v2");
-        return createOllama()(model);
-    }
-    else
-        throw new Error(`unknown AI provider "${provider}" ` +
-            "(expected \"anthropic\", \"openai\", \"openrouter\" or \"ollama\")");
+    const name = options.provider ?? process.env.SPECBOOK_AI_PROVIDER ?? "anthropic";
+    const provider = providers[name];
+    if (provider === undefined)
+        throw new Error(`unknown AI provider "${name}" (expected ` +
+            Object.keys(providers).map((n) => `"${n}"`).join(", ") + ")");
+    const model = options.model ?? process.env.SPECBOOK_AI_MODEL ?? provider.model;
+    return provider.create(model);
 };
 /*  perform a single LLM completion  */
 export const complete = async (options, system, prompt) => {
+    const { generateText } = await import("ai");
     const model = await resolveModel(options);
     const result = await generateText({ model, system, prompt });
     return result.text;

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 } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, formats, 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);
@@ -20,7 +20,7 @@ const errorResult = (err) => {
 };
 /*  serve the SpecBook functionality as "specbook_<cmd>" MCP tools over stdio  */
 export const serveMcp = async (verbose) => {
-    const server = new McpServer({ name: "specbook", version: "0.9.0" });
+    const server = new McpServer({ name: "specbook", version });
     const specbook = new SpecBook({ verbose });
     server.registerTool("specbook_init", {
         title: "Initialize Specification",

package/dst/specbook-parse-semantic.js

@@ -50,22 +50,12 @@ const matchAlternatives = (ctx, alternatives, item) => {
     }
     return false;
 };
-/*  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 props = schema.props ?? [];
-    /*  check the name convention (the configured name of non-artifact
-        objects is a regular expression pattern)  */
-    if (level > 1 && schema.name !== undefined && !anchored(schema.name).test(plainText(object.name)))
-        ctx.diagnose(meta.file, meta.line, `${object.kind} name "${object.name}" does not match pattern "${schema.name}"`);
-    /*  a configured id has to be explicitly specified 1:1 in the
-        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}"`);
-    /*  find a property by its key (case-sensitive)  */
-    const findProp = (name) => object.properties.find((p) => plainKey(p.key) === name);
-    /*  the tokens split off multi-token property values below, assigned
-        to the still unset configured properties by matching their patterns  */
+/*  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
@@ -77,7 +67,7 @@ const validateObject = (ctx, object, schema, level) => {
         const expr = compileValueExpr(prop.value);
         if (expr.kind !== "regex" && expr.kind !== "enum")
             continue;
-        const match = findProp(prop.name);
+        const match = findProp(object, prop.name);
         if (match === undefined || directMatches(expr, plainText(match.value)))
             continue;
         const parts = plainText(match.value).split(/\s+/);
@@ -91,8 +81,10 @@ const validateObject = (ctx, object, schema, level) => {
         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(prop.name) !== undefined)
+        if (prop.value === undefined || findProp(object, prop.name) !== undefined)
             continue;
         const expr = compileValueExpr(prop.value);
         if (expr.kind !== "regex" && expr.kind !== "enum")
@@ -104,13 +96,69 @@ const validateObject = (ctx, object, schema, level) => {
             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;
+};
+/*  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()))
+            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 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}"`);
+        }
+    }
+    else if (expr.kind === "tags") {
+        /*  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))) {
+            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))
+                ctx.diagnose(meta.file, meta.line, `duplicate tag "${item}" on property "${prop.name}"`);
+            seen.add(item);
+        }
+    }
+    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))
+            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}"`);
+    }
+    else if (!directMatches(expr, plainText(property.value)))
+        ctx.diagnose(meta.file, meta.line, expr.kind === "enum" ?
+            `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}"`);
+};
+/*  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 props = schema.props ?? [];
+    /*  check the name convention (the configured name of non-artifact
+        objects is a regular expression pattern)  */
+    if (level > 1 && schema.name !== undefined && !anchored(schema.name).test(plainText(object.name)))
+        ctx.diagnose(meta.file, meta.line, `${object.kind} name "${object.name}" does not match pattern "${schema.name}"`);
+    /*  a configured id has to be explicitly specified 1:1 in the
+        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;
     for (const prop of props) {
         const expr = prop.value !== undefined ? compileValueExpr(prop.value) : undefined;
-        const match = findProp(prop.name);
+        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  */
@@ -122,45 +170,10 @@ const validateObject = (ctx, object, schema, level) => {
             if (prop.optional !== true)
                 ctx.diagnose(meta.file, meta.line, `required property "${prop.name}" missing on ${object.kind} "${object.name}"`);
         }
-        else if (expr !== undefined) {
-            const line = ctx.propMeta.get(match)?.line ?? meta.line;
-            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(match.value.trim()))
-                    ctx.diagnose(meta.file, line, `property "${prop.name}" value "${match.value}" is not a single link reference`);
-                else {
-                    const ref = match.value.trim().slice(2, -2).trim();
-                    const target = resolveUnique(ctx.linkIndex, ref).target;
-                    if (target !== undefined && !resolveSet(ctx.linkIndex, expr.pattern).includes(target))
-                        ctx.diagnose(meta.file, line, `link reference "[[${ref}]]" does not match constraint "${prop.value}"`);
-                }
-            }
-            else if (expr.kind === "tags") {
-                /*  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(match.value))) {
-                    if (!expr.members.includes(item))
-                        ctx.diagnose(meta.file, line, `tag "${item}" of property "${prop.name}" not allowed by constraint "${prop.value}"`);
-                    else if (seen.has(item))
-                        ctx.diagnose(meta.file, line, `duplicate tag "${item}" on property "${prop.name}"`);
-                    seen.add(item);
-                }
-            }
-            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(match.value))
-                    if (!matchAlternatives(ctx, expr.alternatives, item))
-                        ctx.diagnose(meta.file, line, `list item "${item}" of property "${prop.name}" does not match constraint "${prop.value}"`);
-            }
-            else if (!tokenAssigned.has(prop.name) && !directMatches(expr, plainText(match.value)))
-                ctx.diagnose(meta.file, line, expr.kind === "enum" ?
-                    `property "${prop.name}" value "${match.value}" is not a member of "${prop.value}"` :
-                    `property "${prop.name}" value "${match.value}" does not match pattern "${prop.value}"`);
-        }
+        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)))
             ctx.diagnose(meta.file, ctx.propMeta.get(property)?.line ?? meta.line, `unknown property "${property.key}" on ${object.kind} "${object.name}"`);
@@ -179,6 +192,7 @@ const validateObject = (ctx, object, schema, level) => {
         }
         validateObject(ctx, child, childSchema, level + 1);
     }
+    /*  report the configured child object kinds which are missing  */
     for (const child of childs)
         if (child.optional !== true
             && !object.childs.some((c) => c.kind === child.kind))
@@ -204,7 +218,8 @@ export const validate = (ctx, specification, config) => {
         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 ?? "").toUpperCase() === plainText(object.name).toUpperCase());
+                config.find((s) => s.name !== undefined
+                    && s.name.toUpperCase() === plainText(object.name).toUpperCase());
             if (schema === undefined) {
                 ctx.diagnose(meta.file, meta.line, `unknown artifact "${object.kind}: ${object.name}" (id "${object.id}")`);
                 continue;