@rse/specbook 1.3.0 → 1.3.2

package/dst/specbook-export-md.js

@@ -142,11 +142,11 @@ export const renderMarkdown = async (specification, config, rebase, verbose) =>
     };
     /*  embed and re-base on clones of the objects (as the AST is shared
         with the other exports), moving the diagrams along  */
-    const localized = (object, from, to) => {
+    const embedObjectMd = (object, from, to) => {
         const clone = {
             ...object,
             properties: object.properties.map((property) => ({ ...property, value: embedMd(property.value, property.embedding ?? [], from, to) })),
-            children: object.children.map((child) => localized(child, from, to))
+            children: object.children.map((child) => embedObjectMd(child, from, to))
         };
         if (object.description !== undefined)
             clone.description = { ...object.description,
@@ -160,7 +160,7 @@ export const renderMarkdown = async (specification, config, rebase, verbose) =>
         const origin = rebase?.origins.get(artifact);
         const from = origin !== undefined ? path.resolve(path.dirname(origin)) : undefined;
         const to = rebase !== undefined ? path.resolve(rebase.dir) : undefined;
-        return artifact.objects.map((object) => localized(object, from, to));
+        return artifact.objects.map((object) => embedObjectMd(object, from, to));
     });
     const definitions = Array.from(labels, ([url, label]) => `[${label}]: ${url}\n`).join("");
     /*  the single frontmatter block (only recognized at the start of a

package/dst/specbook-export-pdf.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 fs from "node:fs";
+import * as fs from "node:fs";
 import { escapeHtml, paperSetup, paperLength, paperSizeDefault } from "./specbook-export-common.js";
 import { literal } from "./specbook-verbose.js";
 /*  extract the per-anchor page numbers from a Chromium-generated PDF,
@@ -130,9 +130,10 @@ const drawBrandBar = async (doc, accent) => {
             height: page.getHeight(), color: rgb(r, g, b) });
 };
 /*  the launch options of the Chromium-class browser printing the PDF,
-    resolved just once per process, as probing a system-installed Google
-    Chrome has to actually launch it and as the export preflight and the
-    renderer both ask for the very same browser  */
+    resolved just once per process (a failed resolution excepted, so a
+    long-running process retries after the remedy), as probing a
+    system-installed Google Chrome has to actually launch it and as the
+    export preflight and the renderer both ask for the very same browser  */
 let browserOptions;
 /*  the remedy of an unavailable Playwright Chromium, shared by the
     fallback notice and the missing-browser error, as both have to point
@@ -191,10 +192,15 @@ const resolveBrowser = async (verbose) => {
     inside the rendering and with a Playwright-internal message  */
 export const requireBrowser = async (verbose) => {
     browserOptions ??= resolveBrowser(verbose);
-    const options = await browserOptions;
-    if (options === undefined)
+    const options = await browserOptions.catch((err) => {
+        browserOptions = undefined;
+        throw err;
+    });
+    if (options === undefined) {
+        browserOptions = undefined;
         throw new Error("the PDF export requires a Chromium-class browser, but neither the " +
             `Playwright Chromium nor a system-installed Google Chrome was found -- ${chromiumRemedy}`);
+    }
     return options;
 };
 /*  the bound of the ToC page number fixpoint iteration, as the page

package/dst/specbook-ignore.js

@@ -12,9 +12,12 @@ import picomatch from "picomatch";
     honoring the anchored-vs-floating, directory-only, and negation
     semantics of the pattern; an anchored pattern resolves relative to
     the "base" directory its rule file governs, given as a POSIX path
-    relative to the working tree root  */
-const compileRule = (line, base) => {
-    let pattern = line.trim();
+    relative to the working tree root, and "nocase" folds the case of
+    the pattern like Git does under "core.ignoreCase"  */
+const compileRule = (line, base, nocase) => {
+    /*  Git drops the trailing whitespace only (unless a backslash
+        escapes it), while a leading one is part of the pattern  */
+    let pattern = line.replace(/(?<!\\)\s+$/, "");
     if (pattern === "" || pattern.startsWith("#"))
         return null;
     let negated = false;
@@ -27,20 +30,28 @@ const compileRule = (line, base) => {
         dirOnly = true;
         pattern = pattern.slice(0, -1);
     }
+    /*  a trailing "/**" matches everything inside the directory but not
+        the directory itself (so a later negation can still re-include a
+        file below it), whereas picomatch would match the directory, too  */
+    if (pattern.endsWith("/**"))
+        pattern += "/*";
     /*  a pattern carrying a slash anywhere but at its end is anchored at
         the directory of its rule file, while every other one floats and
         hence matches at any depth below it  */
     const anchored = pattern.includes("/");
     if (pattern.startsWith("/"))
         pattern = pattern.slice(1);
+    /*  a negated character class is "[!...]" in the wildmatch of Git,
+        while picomatch knows the "[^...]" spelling only  */
+    pattern = pattern.replace(/\[!/g, "[^");
     const glob = anchored ? (base === "" ? pattern : `${base}/${pattern}`) : `**/${pattern}`;
-    const isMatch = picomatch(glob, { dot: true, nobrace: true, noextglob: true, nonegate: true });
+    const isMatch = picomatch(glob, { dot: true, nobrace: true, noextglob: true, nonegate: true, nocase });
     return { matcher: isMatch, negated, dirOnly };
 };
 /*  load the rules of a single exclude file, given as an absolute "file"
     and the working-tree-relative "base" its anchored patterns resolve
     against; an absent or unreadable file contributes no rules  */
-const loadRules = (file, base) => {
+const loadRules = (file, base, nocase) => {
     let text;
     try {
         text = fs.readFileSync(file, "utf8");
@@ -50,7 +61,7 @@ const loadRules = (file, base) => {
     }
     const rules = new Array();
     for (const line of text.split(/\r?\n/)) {
-        const rule = compileRule(line, base);
+        const rule = compileRule(line, base, nocase);
         if (rule !== null)
             rules.push(rule);
     }
@@ -70,25 +81,28 @@ const workingTree = (dir) => {
         current = parent;
     }
 };
-/*  resolve the global Git excludes file: the configured
-    "core.excludesFile", or else the XDG location Git falls back onto
-    when that configuration value is unset  */
-const globalFile = (root) => {
-    let file = "";
+/*  query a single Git configuration value of a working tree (its "~"
+    expanded and its booleans normalized by Git itself through the
+    "--type"), where an unset value or no Git at all yields ""  */
+const gitConfig = (root, type, key) => {
     try {
-        file = execFileSync("git", ["config", "--get", "core.excludesFile"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return execFileSync("git", ["config", "--get", `--type=${type}`, key], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
     }
     catch {
-        /*  no such configuration value, or no Git at all  */
+        return "";
     }
+};
+/*  resolve the global Git excludes file: the configured
+    "core.excludesFile", or else the XDG location Git falls back onto
+    when that configuration value is unset  */
+const globalFile = (root) => {
+    const file = gitConfig(root, "path", "core.excludesFile");
     if (file === "") {
         const xdg = process.env.XDG_CONFIG_HOME;
         return xdg !== undefined && xdg !== "" ?
             path.join(xdg, "git", "ignore") :
             path.join(os.homedir(), ".config", "git", "ignore");
     }
-    if (file.startsWith("~/"))
-        return path.join(os.homedir(), file.slice(2));
     return file;
 };
 /*  resolve the repository-local exclude file of a working tree, held by
@@ -121,16 +135,19 @@ export const excluder = (dir) => {
     const root = workingTree(dir);
     if (root === null)
         return () => false;
+    /*  Git folds the case of its exclude patterns on a case-insensitive
+        file system ("core.ignoreCase", set by Git itself on init/clone)  */
+    const nocase = gitConfig(root, "bool", "core.ignoreCase") === "true";
     /*  the rules which no directory of the working tree owns and which
         hence govern it as a whole, in ascending Git precedence  */
-    const base = [...loadRules(globalFile(root), ""), ...loadRules(infoFile(root), "")];
+    const baseRules = [...loadRules(globalFile(root), "", nocase), ...loadRules(infoFile(root), "", nocase)];
     /*  the per-directory ".gitignore" rules, loaded on first use, as one
         run queries many files sharing the very same directories  */
     const cache = new Map();
     const rulesOf = (relDir) => {
         let rules = cache.get(relDir);
         if (rules === undefined) {
-            rules = loadRules(path.join(root, relDir, ".gitignore"), relDir);
+            rules = loadRules(path.join(root, relDir, ".gitignore"), relDir, nocase);
             cache.set(relDir, rules);
         }
         return rules;
@@ -147,7 +164,7 @@ export const excluder = (dir) => {
             directory excludes the file itself, as Git never descends
             into it -- and, for the same reason, a rule below such an
             ancestor can never re-include the file  */
-        let rules = base;
+        let rules = baseRules;
         let relDir = "";
         for (let i = 0; i < segments.length; i++) {
             rules = rules.concat(rulesOf(relDir));

package/dst/specbook-link.js

@@ -141,8 +141,8 @@ const nearest = (index, matches, from) => {
             i++;
         return i;
     };
-    const proximities = matches.map((object) => proximity(object));
-    const best = proximities.reduce((max, p) => Math.max(max, p), 0);
+    const proximities = matches.map(proximity);
+    const best = Math.max(0, ...proximities);
     return matches.filter((_, i) => proximities[i] === best);
 };
 /*  resolve a reference into a unique target: a single segment tries the

package/dst/specbook-mcp.js

@@ -157,10 +157,11 @@ export const serveMcp = async (verbose) => {
         }
     }, async (args) => {
         try {
-            const text = await specbook.describe({ ...args, compress: args.compress ?? 2 });
-            if (args.output !== undefined && args.output !== "-") {
-                await fs.promises.writeFile(outputOf(args, args.output), text);
-                return { content: [{ type: "text", text: `described specification format into "${args.output}"` }] };
+            const { output, ...options } = args;
+            const text = await specbook.describe({ ...options, compress: options.compress ?? 2 });
+            if (output !== undefined && output !== "-") {
+                await fs.promises.writeFile(outputOf(args, output), text);
+                return { content: [{ type: "text", text: `described specification format into "${output}"` }] };
             }
             return { content: [{ type: "text", text }] };
         }

package/dst/specbook-parse-common.js

@@ -59,9 +59,12 @@ export const embeddingMimeType = (reference) => {
 /*  the number of embedding entries an image embedding markup occupies,
     given its inline reference: one per variant of an embeddable one, none
     for any other one, and one for a reference-style markup (no reference)  */
-export const embeddingCount = (reference) => reference === undefined ? 1 :
-    (embeddingMimeType(reference.trim()) !== undefined ?
-        embeddingVariants(reference.trim()).length : 0);
+export const embeddingCount = (reference) => {
+    if (reference === undefined)
+        return 1;
+    const trimmed = reference.trim();
+    return embeddingMimeType(trimmed) !== undefined ? embeddingVariants(trimmed).length : 0;
+};
 /*  the image definition ("[label]: data:...") a reference-style image
     embedding refers to: a base64 data: URL of an embeddable image type  */
 export const embeddingDataRegex = /^data:(image\/(?:svg\+xml|png|jpeg|webp));base64,([A-Za-z0-9+/=]+)$/;

package/dst/specbook-parse-semantic.js

@@ -108,7 +108,7 @@ const checkPropValue = (ctx, object, prop, expr, property, meta) => {
                 checkLocal(ctx, object, prop, singleTarget(ctx, object, item), meta);
         }
     }
-    else if (!directMatches(expr, plainText(property.value)))
+    else if (!directMatches(expr, plainText(property.value).trim()))
         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}"`);
@@ -330,14 +330,13 @@ const checkAutomata = (ctx, schemas) => {
             the node set is skipped, as the property checks report it)  */
         const succs = new Map(nodes.map((node) => [node, new Set()]));
         const preds = new Map(nodes.map((node) => [node, new Set()]));
-        for (const edge of object.children.filter((child) => child.kind === automaton.edges)) {
-            const source = referencedObjects(ctx, edge, automaton.source)[0];
-            const target = referencedObjects(ctx, edge, automaton.target)[0];
-            if (source !== undefined && target !== undefined && nodeSet.has(source) && nodeSet.has(target)) {
-                succs.get(source)?.add(target);
-                preds.get(target)?.add(source);
-            }
-        }
+        for (const edge of object.children.filter((child) => child.kind === automaton.edges))
+            for (const source of referencedObjects(ctx, edge, automaton.source))
+                for (const target of referencedObjects(ctx, edge, automaton.target))
+                    if (nodeSet.has(source) && nodeSet.has(target)) {
+                        succs.get(source)?.add(target);
+                        preds.get(target)?.add(source);
+                    }
         /*  the transitive closure of a node set along a neighbor map  */
         const closure = (starts, next) => {
             const seen = new Set(starts);

package/dst/specbook-parse-syntax.js

@@ -183,8 +183,9 @@ const parseList = (ctx, list, object, file, line) => {
                 const property = { key: km[1].trim(), value };
                 ctx.propMeta.set(property, { line });
                 object.properties.push(property);
-                if (item.tokens.some((sub) => sub.type === "list"))
-                    ctx.diagnose(file, line, `nested list below property "${property.key}" ignored`);
+                const ignored = item.tokens.find((sub) => sub.type !== "text" && sub.type !== "paragraph" && sub.type !== "space");
+                if (ignored !== undefined)
+                    ctx.diagnose(file, line, `nested ${ignored.type} below property "${property.key}" ignored`);
             }
             else
                 ctx.diagnose(file, line, `unrecognized list item "${first}"`);
@@ -269,13 +270,16 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
         object.description = splitDescription(statements.join("; ").replace(/\.\s*$/, ""));
     /*  recurse into nested concise-format child objects, tracking the
         source line of the nested list within the item (an ordered
-        nested list is not supported, so it is reported, not lost)  */
+        nested list or any other block content is not supported, so
+        it is reported, not lost)  */
     let subLine = line;
     for (const sub of item.tokens) {
         if (sub.type === "list" && !sub.ordered)
             parseList(ctx, sub, object, file, subLine);
         else if (sub.type === "list")
             ctx.diagnose(file, subLine, `nested ordered list below ${kind} "${name}" ignored`);
+        else if (sub.type !== "text" && sub.type !== "paragraph" && sub.type !== "space")
+            ctx.diagnose(file, subLine, `nested ${sub.type} below ${kind} "${name}" ignored`);
         subLine += (sub.raw.match(/\n/g) ?? []).length;
     }
     parent.children.push(object);
@@ -304,6 +308,10 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
         state.stack.length = depth - 1;
         return;
     }
+    /*  a level 1 object takes its parenthesized token as the id right
+        away, as the artifact resolution of the semantic phase matches
+        it against the configured id before any property could consume
+        the token (a nested object receives it there, see "validate")  */
     const object = {
         kind: heading.kind,
         id: heading.id ?? (depth === 1 ? heading.paren : undefined) ?? slugify(heading.name),
@@ -337,7 +345,8 @@ const unsupportedTokens = {
 };
 /*  parse a single source file into its artifacts  */
 export const parseFile = (ctx, source) => {
-    const { present, created, modified, body, offset } = parseFrontmatter(source.text);
+    /*  strip a leading byte order mark, as it would hide the frontmatter  */
+    const { present, created, modified, body, offset } = parseFrontmatter(source.text.replace(/^\uFEFF/, ""));
     if (!present)
         ctx.diagnose(source.file, 1, "missing frontmatter (\"Created:\"/\"Modified:\" block)");
     else

package/dst/specbook-project.js

@@ -14,12 +14,22 @@ export const projectFile = ".specbook.yaml";
 /*  the schema of the YAML project configuration: the files or glob
     patterns of the YAML schema configuration and the base directory
     of the specification Markdown files  */
-const Project = v.strictObject({
+const ProjectEntries = v.strictObject({
     config: v.optional(v.union([v.pipe(v.string(), v.minLength(1)),
         v.pipe(v.array(v.pipe(v.string(), v.minLength(1))), v.minLength(1))])),
     basedir: v.optional(v.pipe(v.string(), v.minLength(1)))
 }, (issue) => issue.expected === "never" ? "unknown project configuration entry" :
     "expected a map of project configuration entries");
+/*  whether a path names an existing regular file, where an
+    inaccessible one (not just an absent one) counts as absent  */
+const isFile = (file) => {
+    try {
+        return fs.statSync(file, { throwIfNoEntry: false })?.isFile() === true;
+    }
+    catch {
+        return false;
+    }
+};
 /*  find the project configuration file in the closest ancestor-or-self
     of the directory (up to the filesystem root, as the file can reside
     even above a nested Git working tree)  */
@@ -27,7 +37,7 @@ const findProject = (dir) => {
     let current = path.resolve(dir);
     for (;;) {
         const file = path.join(current, projectFile);
-        if (fs.statSync(file, { throwIfNoEntry: false })?.isFile() === true)
+        if (isFile(file))
             return file;
         const parent = path.dirname(current);
         if (parent === current)
@@ -58,6 +68,7 @@ export const loadProject = (dir) => {
     const file = findProject(dir);
     if (file === undefined)
         return undefined;
+    /*  parse the YAML, reporting its syntax errors as positioned diagnostics  */
     const diagnostics = new Array();
     const lines = new LineCounter();
     const yaml = readProject(file);
@@ -71,7 +82,7 @@ export const loadProject = (dir) => {
             message: "invalid YAML syntax: " + err.message.replace(/ at line \d+, column \d+(?::\n[\s\S]*)?$/, "")
         });
     /*  an empty or comment-only file carries no entries at all  */
-    const result = v.safeParse(Project, doc.errors.length === 0 ? (doc.toJS() ?? {}) : {});
+    const result = v.safeParse(ProjectEntries, doc.errors.length === 0 ? (doc.toJS() ?? {}) : {});
     if (!result.success)
         for (const issue of result.issues) {
             const keys = (issue.path ?? []).map((item) => item.key);
@@ -79,9 +90,11 @@ export const loadProject = (dir) => {
             diagnostics.push({ file, ...lineColOfPath(doc, lines, keys), severity: "error",
                 message: `invalid project configuration: ${where}${issue.message}` });
         }
+    /*  (the second condition just narrows the result type below)  */
     if (diagnostics.length > 0 || !result.success)
         throw new Error("invalid project configuration:\n" +
             diagnostics.map(renderDiagnostic).join("\n"));
+    /*  resolve the relative paths against the directory of the file  */
     const base = path.dirname(file);
     const { config, basedir } = result.output;
     const patterns = typeof config === "string" ? [config] : config;

package/dst/specbook-theme.js

@@ -9,7 +9,11 @@ import { parse, generate } from "@rse/mrcs";
     and a signal spread derived from the second tone (if given) or
     else from the complement-transposed first tone  */
 export const themeColors = (tone) => {
-    const [accent, signal = `${accent}^`] = tone.trim().split(/\s+/);
+    const tones = tone.trim().split(/\s+/);
+    if (tones.length > 2 || !tones.every((t) => (/^#[0-9a-fA-F]{6}$/).test(t)))
+        throw new Error(`invalid theme color tone "${tone}" (expected "#RRGGBB", ` +
+            "optionally followed by a second one)");
+    const [accent, signal = `${accent}^`] = tones;
     return {
         base: generate(parse("#000000/32")),
         accent: generate(parse(`${accent}+40-5/32`)),
@@ -27,7 +31,7 @@ export const themeStylesheet = (colors) => ":root {\n" +
     aligned with the layer-2 CSS mapping of the HTML rendering  */
 export const themeMapping = (colors, style) => {
     const idx = style === "dark" ?
-        { muted: 22, symbol: 20, border: 16, accent: 24 } :
+        { muted: 22, symbol: 20, border: 16, accent: 22 } :
         { muted: 22, symbol: 24, border: 28, accent: 12 };
     return {
         muted: colors.base[idx.muted - 1],

package/dst/specbook-verbose.js

@@ -15,10 +15,11 @@ export const parseVerbosity = (value) => {
     const level = (/^(?:true|yes|on)$/i).test(text) ? 1 :
         (/^(?:false|no|off)$/i).test(text) ? 0 :
             (/^\d+$/).test(text) ? Number(text) : NaN;
-    if (!verbosities.includes(level))
+    const verbosity = verbosities.find((n) => n === level);
+    if (verbosity === undefined)
         throw new Error(`unknown verbosity "${value}" ` +
             `(supported: ${verbosities.join(", ")})`);
-    return level;
+    return verbosity;
 };
 /*  the sentinel characters delimiting a marked literal value, taken
     from the Unicode private use area, so they never clash with the

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.3.0",
+    "version":                             "1.3.2",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -17,13 +17,13 @@
     },
     "files":                               [ "dst" ],
     "dependencies": {
-        "marked":                          "18.0.13",
+        "marked":                          "18.0.14",
         "marked-smartypants":              "1.1.12",
         "yaml":                            "2.9.1",
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
-        "subset-font":                     "2.7.0",
-        "sharp":                           "0.35.4",
+        "subset-font":                     "2.9.0",
+        "sharp":                           "0.35.5",
         "svgo":                            "4.1.0",
         "@rse/mrcs":                       "0.9.2",
         "@rse/gradia":                     "1.4.2",
@@ -32,36 +32,36 @@
         "nunjucks":                        "3.2.4",
         "@rse/nunjucks-addons":            "2.2.0",
         "textframe":                       "1.2.1",
-        "@swc/html":                       "1.16.2",
+        "@swc/html":                       "1.16.12",
         "tokenizr":                        "2.2.1",
         "playwright":                      "1.63.0",
         "source-code-error":               "1.2.0",
         "commander":                       "15.0.0",
-        "chalk":                           "6.0.0",
+        "chalk":                           "6.0.1",
         "chokidar5":                       "npm:chokidar@5.0.0",
         "glob":                            "13.0.6",
         "picomatch":                       "4.0.7",
         "es-toolkit":                      "1.52.0",
         "fastify":                         "5.12.5",
         "@fastify/websocket":              "11.3.1",
-        "@modelcontextprotocol/sdk":       "1.30.0",
+        "@modelcontextprotocol/sdk":       "1.31.0",
         "zod":                             "4.6.5"
     },
     "devDependencies": {
         "chokidar-cli":                    "3.0.0",
         "eslint":                          "10.9.0",
         "@eslint/js":                      "10.0.1",
-        "typescript-eslint":               "8.70.0",
+        "typescript-eslint":               "8.71.0",
         "eslint-plugin-promise":           "7.3.0",
         "neostandard":                     "0.14.0-next.1",
         "globals":                         "17.12.0",
         "markdownlint":                    "0.41.1",
         "markdownlint-cli2":               "0.23.3",
-        "@types/node":                     "26.6.2",
+        "@types/node":                     "26.6.3",
         "@types/picomatch":                "4.0.3",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",
-        "@types/ws":                       "8.18.1",
+        "@types/ws":                       "8.18.2",
         "typescript":                      "6.0.3",
         "tsx":                             "4.23.15",
         "source-sans":                     "3.52.0",