@rse/specbook 0.9.5 → 0.9.7

package/dst/specbook-parse-syntax.js

@@ -6,10 +6,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { marked } from "marked";
-import { embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
+import { embeddingRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
+/*  the marker separating a statement from its rationale  */
+const becauseRegex = /,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/;
 /*  split a description text into statement and optional rationale  */
 const splitDescription = (text) => {
-    const m = text.match(/,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/);
+    const m = text.match(becauseRegex);
     if (m === null || m.index === undefined)
         return { description: text };
     return {
@@ -17,33 +19,19 @@ const splitDescription = (text) => {
         rationale: text.slice(m.index + m[0].length)
     };
 };
-/*  parse a heading text of the form "<KIND>: <name> [(<token>)] [<a id="..."></a>]"  */
-const parseHeadingText = (raw) => {
-    let text = raw.trim();
-    let id;
-    const am = text.match(/<a\s+id="([^"]+)"\s*>\s*<\/a>\s*$/);
-    if (am !== null && am.index !== undefined) {
-        id = am[1];
-        text = text.slice(0, am.index).trim();
-    }
-    /*  detect a malformed trailing anchor fragment, still salvaging its id  */
-    let malformed;
-    const fm = text.match(/<a\b[^>]*>?\s*(?:<\/a>)?\s*$/);
-    if (fm !== null && fm.index !== undefined) {
-        malformed = fm[0].trim();
-        id ??= malformed.match(/id="([^"]+)"/)?.[1];
-        text = text.slice(0, fm.index).trim();
-    }
-    /*  detect the trailing explicit Wiki-style anchor ("{{xxx}}"), the
-        primary marker ("(*)"), and/or the implicit parenthesized anchor
-        token ("(xxx)"), in any order  */
+/*  strip the trailing explicit Wiki-style anchor ("{{xxx}}"), the
+    primary marker ("(*)"), and/or the implicit parenthesized anchor
+    token ("(xxx)") off a name, in any order  */
+const parseMarkers = (raw) => {
+    let text = raw;
+    let anchor;
     let paren;
     let primary = false;
     for (;;) {
-        const wm = text.match(/\{\{([^{}]+)\}\}\s*$/);
-        if (wm !== null && wm.index !== undefined) {
-            id ??= wm[1].trim();
-            text = text.slice(0, wm.index).trim();
+        const am = text.match(/\{\{([^{}]+)\}\}\s*$/);
+        if (am !== null && am.index !== undefined) {
+            anchor ??= am[1].trim();
+            text = text.slice(0, am.index).trim();
             continue;
         }
         const sm = text.match(/\(\*\)\s*$/);
@@ -60,20 +48,49 @@ const parseHeadingText = (raw) => {
         }
         break;
     }
-    const km = text.match(/^([^:]+):\s*(.*)$/);
+    return { text, anchor, paren, primary };
+};
+/*  parse a heading text of the form "<KIND>: <name> [(<token>)] [<a id="..."></a>]"  */
+const parseHeadingText = (raw) => {
+    let text = raw.trim();
+    let id;
+    const am = text.match(/<a\s+id="([^"]+)"\s*>\s*<\/a>\s*$/);
+    if (am !== null && am.index !== undefined) {
+        id = am[1];
+        text = text.slice(0, am.index).trim();
+    }
+    /*  detect a malformed trailing anchor fragment, still salvaging its id  */
+    let malformed;
+    const fm = text.match(/<a\b[^>]*>?\s*(?:<\/a>)?\s*$/);
+    if (fm !== null && fm.index !== undefined) {
+        malformed = fm[0].trim();
+        id ??= malformed.match(/id="([^"]+)"/)?.[1];
+        text = text.slice(0, fm.index).trim();
+    }
+    /*  detect the trailing markers (an HTML anchor id takes
+        precedence over the explicit Wiki-style anchor)  */
+    const markers = parseMarkers(text);
+    const km = markers.text.match(/^([^:]+):\s*(.*)$/);
     return {
-        kind: km !== null ? km[1].trim() : text,
+        kind: km !== null ? km[1].trim() : markers.text,
         name: km !== null ? km[2].trim() : "",
-        id, paren, primary, malformed
+        id: id ?? markers.anchor,
+        paren: markers.paren,
+        primary: markers.primary,
+        malformed
     };
 };
 /*  derive a stable slug identifier from an object name  */
 const slugify = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-/*  extract the plain text lines of a Markdown list item
-    (excluding any nested lists)  */
+/*  extract the plain text lines of a Markdown list item (excluding any
+    nested lists), whose body is a "text" token in a tight list, but a
+    "paragraph" token in a loose list (and never "item.text", as this
+    still contains the source of the nested lists)  */
 const itemLines = (item) => {
-    const body = item.tokens.find((token) => token.type === "text");
-    const text = body !== undefined ? body.text : item.text;
+    const text = item.tokens
+        .filter((token) => token.type === "text" || token.type === "paragraph")
+        .map((token) => token.text)
+        .join("\n");
     return text.split("\n").map((line) => line.trim());
 };
 /*  parse the optional Markdown frontmatter with Created/Modified timestamps  */
@@ -96,12 +113,15 @@ const parseFrontmatter = (text) => {
         created: grab("Created"),
         modified: grab("Modified"),
         body: text.slice(m[0].length),
-        offset: m[0].split("\n").length - 1
+        offset: (m[0].match(/\n/g) ?? []).length
     };
 };
 /*  recursively load the image files embedded via "![alt](file)" into the
     description and the property values of an object (SVG as-is, PNG/JPEG
-    as base64 data: URLs), resolving the references relative to the source file  */
+    as base64 data: URLs), resolving the references relative to the source
+    file and expanding a "{theme}" reference into its theme variants,
+    which are loaded into consecutive embedding entries (an unreadable
+    file leaves an empty entry, keeping the positions aligned)  */
 const embed = (ctx, object, file) => {
     const load = (target, text, line) => {
         for (const m of text.matchAll(embeddingRegex)) {
@@ -109,15 +129,18 @@ const embed = (ctx, object, file) => {
             const type = embeddingMimeType(reference);
             if (type === undefined)
                 continue;
-            try {
-                const data = fs.readFileSync(path.resolve(path.dirname(file), reference));
+            for (const variant of embeddingVariants(reference)) {
                 target.embedding ??= [];
-                target.embedding.push(type === "image/svg+xml" ?
-                    data.toString("utf8") : `data:${type};base64,${data.toString("base64")}`);
-            }
-            catch (err) {
-                ctx.diagnose(file, line, `unreadable embedding file "${reference}": ` +
-                    (err instanceof Error ? err.message : String(err)));
+                try {
+                    const data = fs.readFileSync(path.resolve(path.dirname(file), variant));
+                    target.embedding.push(type === "image/svg+xml" ?
+                        data.toString("utf8") : `data:${type};base64,${data.toString("base64")}`);
+                }
+                catch (err) {
+                    target.embedding.push("");
+                    ctx.diagnose(file, line, `unreadable embedding file "${variant}": ` +
+                        (err instanceof Error ? err.message : String(err)));
+                }
             }
         }
     };
@@ -148,6 +171,8 @@ 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`);
             }
             else
                 ctx.diagnose(file, line, `unrecognized list item "${first}"`);
@@ -170,7 +195,7 @@ const parseGrouped = (ctx, list, group, file, line) => {
     omits the leading "<kind>: " and receives its kind from the group  */
 const parseConcise = (ctx, item, parent, file, line, group) => {
     const text = itemLines(item).join(" ").trim();
-    const segments = text.split(/;\s*/).filter((segment) => segment !== "");
+    const segments = text.split(/\s*;\s*/).filter((segment) => segment !== "");
     const head = segments.shift() ?? "";
     let kind;
     let name;
@@ -192,30 +217,10 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
         kind = km[1].trim();
         name = km[2].trim();
     }
-    let anchor;
-    let paren;
-    let primary = false;
-    for (;;) {
-        const am = name.match(/\{\{([^{}]+)\}\}\s*$/);
-        if (am !== null && am.index !== undefined) {
-            anchor ??= am[1].trim();
-            name = name.slice(0, am.index).trim();
-            continue;
-        }
-        const sm = name.match(/\(\*\)\s*$/);
-        if (sm !== null && sm.index !== undefined) {
-            primary = true;
-            name = name.slice(0, sm.index).trim();
-            continue;
-        }
-        const pm = name.match(/\(([^()]+)\)\s*$/);
-        if (pm !== null && pm.index !== undefined && paren === undefined) {
-            paren = pm[1].trim();
-            name = name.slice(0, pm.index).trim();
-            continue;
-        }
-        break;
-    }
+    /*  detect the trailing markers of the name  */
+    const { text: plain, anchor, paren, primary } = parseMarkers(name);
+    name = plain;
+    /*  create the object with its markers, registering its source location  */
     const object = {
         kind,
         id: anchor ?? slugify(name),
@@ -230,11 +235,16 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
     if (primary)
         object.primary = true;
     ctx.objectMeta.set(object, { file, line });
+    /*  split the remaining segments into properties (with a possibly
+        empty value) and statements, where the last segment of a "."-
+        terminated item is always a statement, as only this lets a
+        "<key>: <value>"-shaped description round-trip on export  */
     const statements = new Array();
-    for (const segment of segments) {
-        const km = segment.match(/^([^:;]+):\s+(.+)$/);
-        if (km !== null && !(/\s(?:\*\*BECAUSE\*\*|BECAUSE)\s/.test(segment))) {
-            const property = { key: km[1].trim(), value: km[2].trim() };
+    const last = text.endsWith(".") ? segments.length - 1 : -1;
+    for (const [i, segment] of segments.entries()) {
+        const km = segment.match(/^([^:;]+):(?:\s+(.+))?$/);
+        if (km !== null && !becauseRegex.test(segment) && i !== last) {
+            const property = { key: km[1].trim(), value: (km[2] ?? "").trim() };
             ctx.propMeta.set(property, { line });
             object.properties.push(property);
         }
@@ -243,12 +253,67 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
     }
     if (statements.length > 0)
         object.description = splitDescription(statements.join("; ").replace(/\.\s*$/, ""));
-    /*  recurse into nested concise-format child objects  */
-    for (const sub of item.tokens)
+    /*  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)  */
+    let subLine = line;
+    for (const sub of item.tokens) {
         if (sub.type === "list" && !sub.ordered)
-            parseList(ctx, sub, object, file, line);
+            parseList(ctx, sub, object, file, subLine);
+        else if (sub.type === "list")
+            ctx.diagnose(file, subLine, `nested ordered list below ${kind} "${name}" ignored`);
+        subLine += (sub.raw.match(/\n/g) ?? []).length;
+    }
     parent.childs.push(object);
 };
+/*  parse a heading token into either a grouping container (e.g. "### STATE",
+    collecting objects of its kind below the parent object) or a new object
+    (an artifact on level 1, a child of the enclosing object below)  */
+const parseHeading = (ctx, token, state, stamps, file, line) => {
+    const { depth, text } = token;
+    const heading = parseHeadingText(text);
+    state.group = null;
+    if (heading.malformed !== undefined)
+        ctx.diagnose(file, line, `malformed anchor "${heading.malformed}" in heading`);
+    if (heading.name === "" && depth > 1) {
+        const parent = state.stack[depth - 2];
+        if (parent === undefined)
+            ctx.diagnose(file, line, `heading level ${depth} without parent object`);
+        else {
+            state.group = { parent, kind: heading.kind };
+            state.current = parent;
+            state.stack.length = depth - 1;
+        }
+        return;
+    }
+    const object = {
+        kind: heading.kind,
+        id: heading.id ?? (depth === 1 ? heading.paren : undefined) ?? slugify(heading.name),
+        name: heading.name,
+        properties: [],
+        childs: []
+    };
+    if (heading.id !== undefined)
+        object.anchor = heading.id;
+    if (heading.paren !== undefined)
+        object.paren = heading.paren;
+    if (heading.primary)
+        object.primary = true;
+    ctx.objectMeta.set(object, { file, line });
+    if (depth === 1)
+        state.artifacts.push({ ...stamps, objects: [object] });
+    else {
+        const parent = state.stack[depth - 2];
+        if (parent === undefined) {
+            ctx.diagnose(file, line, `heading level ${depth} without parent object`);
+            return;
+        }
+        parent.childs.push(object);
+    }
+    state.stack.length = depth - 1;
+    state.stack[depth - 1] = object;
+    state.current = object;
+};
 /*  parse a single source file into its artifacts  */
 export const parseFile = (ctx, source) => {
     const { present, created, modified, body, offset } = parseFrontmatter(source.text);
@@ -261,15 +326,30 @@ export const parseFile = (ctx, source) => {
                     `missing "${key}:" frontmatter key` :
                     `invalid "${key}:" frontmatter timestamp "${info.value}"`);
     /*  the state tracked while walking the Markdown tokens  */
-    const artifacts = new Array();
-    const stack = new Array();
-    let current = null;
-    let group = null;
+    const state = { artifacts: [], stack: [], current: null, group: null };
+    const stamps = {
+        created: created.date ?? new Date(),
+        modified: modified.date ?? new Date()
+    };
     let parts = new Array();
-    /*  flush the accumulated description parts into the current object  */
+    let partsLine = 1;
+    /*  collect a description part, remembering the line of the first one  */
+    const collect = (raw, line) => {
+        if (parts.length === 0)
+            partsLine = line;
+        parts.push(raw.trim());
+    };
+    /*  flush the accumulated description parts into the current object
+        (a grouping container re-targets the parent, whose description
+        is already flushed, so further content is reported, not lost)  */
     const flush = () => {
-        if (current !== null && parts.length > 0 && current.description === undefined)
-            current.description = splitDescription(parts.join("\n\n").trim());
+        const current = state.current;
+        if (current !== null && parts.length > 0) {
+            if (current.description === undefined)
+                current.description = splitDescription(parts.join("\n\n").trim());
+            else
+                ctx.diagnose(source.file, partsLine, `content ignored, as ${current.kind} "${current.name}" already carries a description`);
+        }
         parts = [];
     };
     /*  walk the top-level Markdown tokens, tracking source lines  */
@@ -277,88 +357,39 @@ export const parseFile = (ctx, source) => {
     for (const token of marked.lexer(body)) {
         if (token.type === "heading") {
             flush();
-            group = null;
-            const { depth, text } = token;
-            const heading = parseHeadingText(text);
-            if (heading.malformed !== undefined)
-                ctx.diagnose(source.file, line, `malformed anchor "${heading.malformed}" in heading`);
-            if (heading.name === "" && depth > 1) {
-                /*  a grouping container heading (e.g. "### STATES") collects
-                    objects of its singular kind below the parent object  */
-                const parent = stack[depth - 2];
-                if (parent === undefined)
-                    ctx.diagnose(source.file, line, `heading level ${depth} without parent object`);
-                else {
-                    group = { parent, kind: heading.kind.replace(/S$/, "") };
-                    current = parent;
-                }
-            }
-            else {
-                const object = {
-                    kind: heading.kind,
-                    id: heading.id ?? (depth === 1 ? heading.paren : undefined) ?? slugify(heading.name),
-                    name: heading.name,
-                    properties: [],
-                    childs: []
-                };
-                if (heading.id !== undefined)
-                    object.anchor = heading.id;
-                if (heading.paren !== undefined)
-                    object.paren = heading.paren;
-                if (heading.primary)
-                    object.primary = true;
-                ctx.objectMeta.set(object, { file: source.file, line });
-                if (depth === 1) {
-                    artifacts.push({
-                        created: created.date ?? new Date(),
-                        modified: modified.date ?? new Date(),
-                        objects: [object]
-                    });
-                    stack.length = 0;
-                }
-                else {
-                    const parent = stack[depth - 2];
-                    if (parent === undefined) {
-                        ctx.diagnose(source.file, line, `heading level ${depth} without parent object`);
-                        line += (token.raw.match(/\n/g) ?? []).length;
-                        continue;
-                    }
-                    parent.childs.push(object);
-                }
-                stack.length = depth - 1;
-                stack[depth - 1] = object;
-                current = object;
-            }
+            parseHeading(ctx, token, state, stamps, source.file, line);
         }
         else if (token.type === "list") {
             const list = token;
-            if (current === null)
+            if (state.current === null)
                 ctx.diagnose(source.file, line, "content outside of any object");
-            else if (!list.ordered && group !== null)
-                parseGrouped(ctx, list, group, source.file, line);
+            else if (!list.ordered && state.group !== null)
+                parseGrouped(ctx, list, state.group, source.file, line);
             else if (!list.ordered)
-                parseList(ctx, list, current, source.file, line);
+                parseList(ctx, list, state.current, source.file, line);
             else
-                parts.push(token.raw.trim());
+                collect(token.raw, line);
         }
         else if (token.type === "paragraph" || token.type === "blockquote"
             || (token.type === "code" && token.lang !== "gradia")) {
             /*  notice: a "gradia" code block is skipped entirely, as it is
                 the derived diagram of the Markdown renderer and hence must
                 not become authored content on a re-parse of exported files  */
-            if (current === null)
+            if (state.current === null)
                 ctx.diagnose(source.file, line, "content outside of any object");
             else
-                parts.push(token.raw.trim());
+                collect(token.raw, line);
         }
+        else if (token.type === "table")
+            ctx.diagnose(source.file, line, "unsupported table content ignored");
         line += (token.raw.match(/\n/g) ?? []).length;
     }
     flush();
     /*  load the embedded image files of all fully parsed objects  */
-    for (const artifact of artifacts)
+    for (const artifact of state.artifacts)
         for (const object of artifact.objects)
             embed(ctx, object, source.file);
-    if (artifacts.length === 0)
+    if (state.artifacts.length === 0)
         ctx.diagnose(source.file, 1, "no artifact (level 1 heading) found");
-    return artifacts;
+    return state.artifacts;
 };

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

@@ -1,7 +1,6 @@
 export type ValueExpr = {
     kind: "regex";
     regex: RegExp;
-    source: string;
 } | {
     kind: "reference";
     pattern: string;
@@ -15,5 +14,6 @@ export type ValueExpr = {
     kind: "list";
     alternatives: ValueExpr[];
 };
+export declare const anchored: (pattern: string) => RegExp;
 export declare const compileValueExpr: (source: string) => ValueExpr;
 export declare const splitItems: (text: string) => string[];

package/dst/specbook-parse-value.js

@@ -33,13 +33,16 @@ lexer.rule(/\s+/, (ctx) => {
 });
 /*  describe a token for error messages  */
 const tokenName = (token) => token.type === "EOF" ? "end of expression" : `"${token.text}"`;
+/*  compile a configured pattern (object name or value regex) into an
+    anchored regular expression, so it has to match a text as a whole  */
+export const anchored = (pattern) => new RegExp(`^(?:${pattern})$`);
 /*  parse a single expression from the token stream  */
 const parseValueExpr = (tokens, pos, nested) => {
     const token = tokens[pos.i++];
     if (token.type === "regex") {
         const source = String(token.value);
         try {
-            return { kind: "regex", regex: new RegExp(source), source };
+            return { kind: "regex", regex: anchored(source) };
         }
         catch (err) {
             throw new Error(`invalid regular expression "/${source}/": ` +
@@ -85,7 +88,7 @@ const cache = new Map();
 export const compileValueExpr = (source) => {
     let expr = cache.get(source);
     if (expr === undefined) {
-        const tokens = lexer.reset().input(source).tokens();
+        const tokens = lexer.input(source).tokens();
         const pos = { i: 0 };
         expr = parseValueExpr(tokens, pos, false);
         if (tokens[pos.i].type !== "EOF")
@@ -102,7 +105,7 @@ export const splitItems = (text) => {
     let bracketed = false;
     for (let i = 0; i < text.length; i++) {
         const char = text[i];
-        if (char === "\"")
+        if (char === "\"" && text[i - 1] !== "\\")
             quoted = !quoted;
         if (!quoted && !bracketed && char === "[" && text[i + 1] === "[") {
             parts[parts.length - 1] += "[[";

package/dst/specbook-parse.d.ts

@@ -1,8 +1,5 @@
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type Schema } from "./specbook-format-schema.js";
 import { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
-export { type SourceFile, type ParseResult, embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
-export declare class Parser {
-    private ctx;
-    parse(sources: SourceFile[], config?: SchemaSpecification): ParseResult;
-}
-export declare const parseSpecification: (sources: SourceFile[], config?: SchemaSpecification) => ParseResult;
+export { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
+export { resolveArtifact } from "./specbook-parse-semantic.js";
+export declare const parseSpecification: (sources: SourceFile[], config?: Schema) => ParseResult;

package/dst/specbook-parse.js

@@ -4,44 +4,37 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import * as v from "valibot";
-import { Specification } from "./specbook-struct-spec.js";
+import { Spec } from "./specbook-format-spec.js";
 import { buildLinkIndex } from "./specbook-link.js";
 import { ParseContext } from "./specbook-parse-common.js";
 import { parseFile } from "./specbook-parse-syntax.js";
 import { validate, validateReferences } from "./specbook-parse-semantic.js";
 import { validateDiagrams } from "./specbook-diagram.js";
-/*  re-export the public parsing types and embedding helpers  */
-export { embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
-/*  parser for a set of specification Markdown files  */
-export class Parser {
-    ctx = new ParseContext();
-    /*  parse all source files into the specification AST and
-        optionally validate the result against a configuration  */
-    parse(sources, config) {
-        /*  reset the parsing context to allow a reuse of the parser  */
-        this.ctx = new ParseContext();
-        /*  parse all source files into their artifacts  */
-        const artifacts = new Array();
-        for (const source of sources)
-            artifacts.push(...parseFile(this.ctx, source));
-        const specification = { artifacts };
-        /*  validate the resulting specification AST  */
-        if (artifacts.length > 0) {
-            this.ctx.linkIndex = buildLinkIndex(specification);
-            if (config !== undefined)
-                validate(this.ctx, specification, config);
-            validateReferences(this.ctx, specification);
-            if (config !== undefined)
-                validateDiagrams(this.ctx, specification, config);
-            const result = v.safeParse(Specification, specification);
-            if (!result.success)
-                for (const issue of result.issues) {
-                    const path = (issue.path ?? []).map((item) => String(item.key)).join(".");
-                    this.ctx.diagnose(sources[0]?.file ?? "", 1, `internal AST invalid at "${path}": ${issue.message}`);
-                }
-        }
-        return { specification, diagnostics: this.ctx.diagnostics };
+export { resolveArtifact } from "./specbook-parse-semantic.js";
+/*  parse a set of specification Markdown files into the specification
+    AST and optionally validate the result against a configuration  */
+export const parseSpecification = (sources, config) => {
+    /*  create a fresh parsing context for this parsing run  */
+    const ctx = new ParseContext();
+    /*  parse all source files into their artifacts  */
+    const artifacts = new Array();
+    for (const source of sources)
+        artifacts.push(...parseFile(ctx, source));
+    const specification = { artifacts };
+    /*  validate the resulting specification AST  */
+    if (artifacts.length > 0) {
+        ctx.linkIndex = buildLinkIndex(specification);
+        if (config !== undefined)
+            validate(ctx, specification, config);
+        validateReferences(ctx, specification);
+        if (config !== undefined)
+            validateDiagrams(ctx, specification, config);
+        const result = v.safeParse(Spec, specification);
+        if (!result.success)
+            for (const issue of result.issues) {
+                const path = v.getDotPath(issue) ?? "";
+                ctx.diagnose(sources[0]?.file ?? "", 1, `internal AST invalid at "${path}": ${issue.message}`);
+            }
     }
-}
-/*  convenience wrapper for one-shot parsing  */
-export const parseSpecification = (sources, config) => new Parser().parse(sources, config);
+    return { specification, diagnostics: ctx.diagnostics };
+};

package/dst/specbook-verbose.d.ts

@@ -0,0 +1,2 @@
+export declare const literal: (value: string | number) => string;
+export declare const renderVerbose: (msg: string, style?: (value: string) => string) => string;

package/dst/specbook-verbose.js

@@ -0,0 +1,17 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+/*  the sentinel characters delimiting a marked literal value, taken
+    from the Unicode private use area, so they never clash with the
+    regular content of a verbose message  */
+const begin = "\uE000";
+const end = "\uE001";
+const marker = new RegExp(`${begin}([^${end}]*)${end}`, "g");
+/*  mark a literal value (path, number, format, ...) inside a verbose
+    message, so the output sink can style it without having to guess  */
+export const literal = (value) => `${begin}${value}${end}`;
+/*  render a verbose message by either styling its marked literal values
+    with the given styler or just stripping their markers away  */
+export const renderVerbose = (msg, style) => msg.replace(marker, (_, value) => style !== undefined ? style(value) : value);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "0.9.5",
+    "version":                             "0.9.7",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -24,7 +24,7 @@
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.5.0",
         "@rse/mrcs":                       "0.9.2",
-        "@rse/gradia":                     "1.0.0",
+        "@rse/gradia":                     "1.1.4",
         "@toon-format/toon":               "4.1.1",
         "valibot":                         "1.4.2",
         "nunjucks":                        "3.2.4",
@@ -33,13 +33,9 @@
         "@swc/html":                       "1.16.1",
         "tokenizr":                        "2.2.1",
         "playwright":                      "1.62.1",
-        "ai":                              "7.0.69",
-        "@ai-sdk/anthropic":               "4.0.39",
-        "@ai-sdk/openai":                  "4.0.43",
-        "@openrouter/ai-sdk-provider":     "3.0.0",
-        "ollama-ai-provider-v2":           "4.0.1",
         "source-code-error":               "1.2.0",
         "commander":                       "15.0.0",
+        "chalk":                           "6.0.0",
         "@modelcontextprotocol/sdk":       "1.30.0",
         "zod":                             "4.4.3"
     },

package/dst/specbook-cmd-edit.d.ts

@@ -1,9 +0,0 @@
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
-import { type AiOptions } from "./specbook-llm.js";
-export interface EditOptions extends AiOptions {
-    config: SchemaSpecification;
-    basedir?: string;
-    query: string;
-    verbose: (msg: string) => void;
-}
-export declare const editSpecification: (options: EditOptions) => Promise<string[]>;