@rse/specbook 1.1.0 → 1.2.1

package/dst/specbook-link.d.ts

@@ -4,6 +4,8 @@ export declare const plainText: (text: string) => string;
 interface LinkNode {
     object: SpecObject;
     parent?: LinkNode;
+    pos: number;
+    name: string;
 }
 export type LinkIndex = LinkNode[];
 export declare const chainOf: (index: LinkIndex, object: SpecObject) => SpecObject[];

package/dst/specbook-link.js

@@ -8,22 +8,37 @@ export const referenceRegex = /\[\[([^[\]]+)\]\]/g;
 /*  strip the inline code markup of a name or property value
     (preserved in the AST for rendering) for matching and labeling  */
 export const plainText = (text) => text.replace(/`/g, "");
-/*  the per-index lookup of the nodes by their objects, built lazily on
-    the first scoped resolution (as the index itself stays a plain list)  */
+/*  provide the lookup structures of an index, built once on first use  */
 const lookups = new WeakMap();
-const lookup = (index, object) => {
-    let nodes = lookups.get(index);
-    if (nodes === undefined) {
-        nodes = new Map(index.map((node) => [node.object, node]));
-        lookups.set(index, nodes);
+const lookup = (index) => {
+    let result = lookups.get(index);
+    if (result === undefined) {
+        result = { nodes: new Map(), byKey: new Map(), byName: new Map(), byKind: new Map(),
+            sets: new Map(), uniques: new Map() };
+        const add = (map, key, node) => {
+            const nodes = map.get(key);
+            if (nodes === undefined)
+                map.set(key, [node]);
+            else
+                nodes.push(node);
+        };
+        for (const node of index) {
+            result.nodes.set(node.object, node);
+            add(result.byKey, node.object.id, node);
+            if (node.object.anchor !== undefined && node.object.anchor !== node.object.id)
+                add(result.byKey, node.object.anchor, node);
+            add(result.byName, node.name, node);
+            add(result.byKind, node.object.kind, node);
+        }
+        lookups.set(index, result);
     }
-    return nodes.get(object);
+    return result;
 };
 /*  the ancestor-or-self chain of an object, root first
     (empty for an object unknown to the index)  */
 export const chainOf = (index, object) => {
     const chain = new Array();
-    for (let node = lookup(index, object); node !== undefined; node = node.parent)
+    for (let node = lookup(index).nodes.get(object); node !== undefined; node = node.parent)
         chain.unshift(node.object);
     return chain;
 };
@@ -31,7 +46,7 @@ export const chainOf = (index, object) => {
 export const buildLinkIndex = (specification) => {
     const index = [];
     const walk = (object, parent) => {
-        const node = { object, parent };
+        const node = { object, parent, pos: index.length, name: plainText(object.name) };
         index.push(node);
         for (const child of object.childs)
             walk(child, node);
@@ -58,40 +73,53 @@ const splitQuoted = (text, separator) => {
 };
 /*  strip the optional surrounding double quotes of a part  */
 const unquote = (part) => part.replace(/^"(.*)"$/s, "$1");
-/*  match a name-or-id part against an object (with "*" wildcard)  */
-const matchesPart = (object, part) => part === "*"
-    || object.id === part
-    || object.anchor === part
-    || plainText(object.name) === part;
-/*  match a single reference segment ("id", "name", "KIND:name-or-id",
-    "KIND:*", or "*", each part optionally double-quoted to allow
-    spaces, dots, and colons) against a single object  */
-const matchesSegment = (object, segment) => {
+const parseSegment = (segment) => {
     const parts = splitQuoted(segment, ":");
     if (parts.length >= 2)
-        return object.kind === unquote(parts[0].trim())
-            && matchesPart(object, unquote(parts.slice(1).join(":").trim()));
-    return matchesPart(object, unquote(segment.trim()));
+        return { kind: unquote(parts[0].trim()), part: unquote(parts.slice(1).join(":").trim()) };
+    return { part: unquote(segment.trim()) };
+};
+/*  match a parsed segment against a single node (with "*" wildcard)  */
+const matchesSegment = (node, segment) => (segment.kind === undefined || node.object.kind === segment.kind)
+    && (segment.part === "*"
+        || node.object.id === segment.part
+        || node.object.anchor === segment.part
+        || node.name === segment.part);
+/*  the candidate nodes matching a parsed segment, in index order,
+    found through the lookup structures instead of an index scan  */
+const candidates = (index, segment) => {
+    const { byKey, byName, byKind } = lookup(index);
+    if (segment.part === "*")
+        return segment.kind !== undefined ? (byKind.get(segment.kind) ?? []) : index;
+    const nodes = Array.from(new Set([...(byKey.get(segment.part) ?? []), ...(byName.get(segment.part) ?? [])]))
+        .sort((a, b) => a.pos - b.pos);
+    return segment.kind !== undefined ? nodes.filter((node) => node.object.kind === segment.kind) : nodes;
 };
 /*  split a reference into its hierarchical path segments,
     honoring double-quoted parts  */
 const segmentsOf = (reference) => splitQuoted(reference, ".").map((segment) => segment.trim()).filter((segment) => segment !== "");
 /*  resolve a reference into the set of all matching objects: a path
     matches object chains connected by direct parent-to-child steps,
-    with the leading segments up to the root freely omittable  */
+    with the leading segments up to the root freely omittable (the
+    candidates of the last segment are walked up along the parents)  */
 export const resolveSet = (index, reference) => {
-    const segments = segmentsOf(reference);
-    if (segments.length === 0)
-        return [];
-    return index.filter((node) => {
-        let current = node;
-        for (let i = segments.length - 1; i >= 0; i--) {
-            if (current === undefined || !matchesSegment(current.object, segments[i]))
-                return false;
-            current = current.parent;
-        }
-        return true;
-    }).map((node) => node.object);
+    const { sets } = lookup(index);
+    let matches = sets.get(reference);
+    if (matches === undefined) {
+        const segments = segmentsOf(reference).map(parseSegment);
+        matches = segments.length === 0 ? [] :
+            candidates(index, segments[segments.length - 1]).filter((node) => {
+                let current = node.parent;
+                for (let i = segments.length - 2; i >= 0; i--) {
+                    if (current === undefined || !matchesSegment(current, segments[i]))
+                        return false;
+                    current = current.parent;
+                }
+                return true;
+            }).map((node) => node.object);
+        sets.set(reference, matches);
+    }
+    return matches;
 };
 /*  narrow several matches down to the ones nearest to the referencing
     object, i.e. sharing the longest ancestor chain with it (the lexical
@@ -115,26 +143,23 @@ const nearest = (index, matches, from) => {
     the first variant yielding matches decides, while a hierarchical path
     resolves via its full match set; several matches are narrowed down to
     the ones nearest to the referencing object (if known) and remain an
-    ambiguity only if still more than one remains  */
+    ambiguity only if still more than one remains (the scope-independent
+    match set is memoized per reference)  */
 export const resolveUnique = (index, reference, from) => {
-    const segments = segmentsOf(reference);
-    let matches = [];
-    if (segments.length === 1) {
-        const segment = segments[0];
-        const unquoted = unquote(segment);
-        const variants = [
-            (object) => object.id === unquoted || object.anchor === unquoted,
-            (object) => plainText(object.name) === unquoted,
-            (object) => matchesSegment(object, segment)
-        ];
-        for (const variant of variants) {
-            matches = index.filter((node) => variant(node.object)).map((node) => node.object);
-            if (matches.length > 0)
-                break;
+    const { byKey, byName, uniques } = lookup(index);
+    let matches = uniques.get(reference);
+    if (matches === undefined) {
+        const segments = segmentsOf(reference);
+        if (segments.length === 1) {
+            const segment = segments[0];
+            const unquoted = unquote(segment);
+            matches = (byKey.get(unquoted) ?? byName.get(unquoted) ?? candidates(index, parseSegment(segment)))
+                .map((node) => node.object);
         }
+        else
+            matches = resolveSet(index, reference);
+        uniques.set(reference, matches);
     }
-    else
-        matches = resolveSet(index, reference);
     if (matches.length > 1 && from !== undefined)
         matches = nearest(index, matches, from);
     return { target: matches.length === 1 ? matches[0] : undefined, ambiguous: matches.length > 1 };

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, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, parseCompressLevel, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, compressLevels, 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);
@@ -78,7 +78,7 @@ export const serveMcp = async (verbose) => {
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
             format: z.enum(formats).optional().describe("output format (default: inferred from the " +
                 "output file extension, else json)"),
-            output: z.string().optional().describe("output file path (\"-\" returns the result directly)")
+            output: z.string().optional().describe("output file path (\"-\" or omitted returns the result directly)")
         }
     }, async (args) => {
         try {
@@ -120,7 +120,7 @@ export const serveMcp = async (verbose) => {
             basedir: z.string().optional().describe("base directory of the specification Markdown files"),
             embed: z.boolean().optional().describe("embed the given YAML schema configuration instead " +
                 "of just referencing it (default: false; the bundled standard one is always embedded)"),
-            compress: z.number().int().min(0).max(3).optional().describe("compression level of the emitted " +
+            compress: z.literal(compressLevels).optional().describe("compression level of the emitted " +
                 "YAML schema configuration (embedded or raw): 0 for verbatim, 1 for re-emitted with 2-space " +
                 "indentation and without comments, 2 for additionally without its \"refs\" fields, or 3 for " +
                 "additionally without its \"desc\" fields (default: 1)"),
@@ -134,10 +134,9 @@ export const serveMcp = async (verbose) => {
         }
     }, async (args) => {
         try {
-            const text = await specbook.describe({ ...args,
-                compress: args.compress !== undefined ? parseCompressLevel(args.compress) : undefined });
+            const text = await specbook.describe(args);
             if (args.output !== undefined && args.output !== "-") {
-                await fs.promises.writeFile(args.output, text, "utf8");
+                await fs.promises.writeFile(args.output, text);
                 return { content: [{ type: "text", text: `described specification format into "${args.output}"` }] };
             }
             return { content: [{ type: "text", text }] };

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

@@ -21,6 +21,7 @@ export declare class ParseContext {
         line: number;
     }>;
     linkIndex: LinkIndex;
+    parenProps: WeakMap<SpecObject, SpecProperty>;
     assets: Set<string>;
     diagnose(file: string, line: number, message: string, severity?: DiagnosticSeverity): void;
 }

package/dst/specbook-parse-common.js

@@ -9,6 +9,10 @@ export class ParseContext {
     objectMeta = new WeakMap();
     propMeta = new WeakMap();
     linkIndex = [];
+    /*  the synthetic properties supplied by the parenthesized name
+        tokens consumed as property values (kept outside the AST, so
+        the tokens stay plain heading markers on export)  */
+    parenProps = new WeakMap();
     /*  the resolved paths of the embedded asset files, recorded even for
         an unreadable one, as a watching consumer has to observe it, too  */
     assets = new Set();

package/dst/specbook-parse-semantic.js

@@ -41,8 +41,13 @@ const matchAlternatives = (ctx, object, alternatives, item) => {
     }
     return false;
 };
-/*  find a property of an object by its key (case-sensitive)  */
-const findProp = (object, name) => object.properties.find((p) => p.key === name);
+/*  find a property of an object by its key (case-sensitive), including
+    the synthetic one supplied by a consumed parenthesized name token  */
+const findProp = (ctx, object, name) => {
+    const synthetic = ctx.parenProps.get(object);
+    return object.properties.find((p) => p.key === name) ??
+        (synthetic?.key === name ? synthetic : undefined);
+};
 /*  split a multi-valued property value into its items, reporting an
     empty one -- stemming from an empty value or a stray comma -- once,
     as such an item can never satisfy any constraint  */
@@ -114,9 +119,50 @@ const parenProp = (object, props) => {
     const paren = object.paren;
     if (paren === undefined)
         return undefined;
-    return props.find((prop) => prop.value !== undefined && findProp(object, prop.name) === undefined
+    return props.find((prop) => prop.value !== undefined && !object.properties.some((p) => p.key === prop.name)
         && directMatches(compileValueExpr(prop.value), paren));
 };
+/*  check the property values flagged unique for distinctness among
+    the sibling objects of the same kind and the ones flagged present
+    for occurring on at least one of the (existing) siblings (all
+    values, or only the values matching the regexp or enum expression
+    of the flag)  */
+const checkSiblingFlags = (ctx, object, childs, meta) => {
+    const marker = (flag) => flag === undefined || flag === false ? undefined :
+        { filter: typeof flag === "string" ? compileValueExpr(flag) : undefined };
+    for (const child of childs) {
+        const siblings = object.childs.filter((c) => c.kind === child.kind);
+        for (const prop of child.props ?? []) {
+            const unique = marker(prop.unique);
+            const present = marker(prop.present);
+            if (unique === undefined && present === undefined)
+                continue;
+            const seen = new Map();
+            let found = false;
+            for (const sibling of siblings) {
+                const property = findProp(ctx, sibling, prop.name);
+                if (property === undefined)
+                    continue;
+                const value = plainText(property.value).trim();
+                if (present !== undefined && (present.filter === undefined || directMatches(present.filter, value)))
+                    found = true;
+                if (unique === undefined || (unique.filter !== undefined && !directMatches(unique.filter, value)))
+                    continue;
+                const first = seen.get(value);
+                if (first === undefined)
+                    seen.set(value, sibling);
+                else {
+                    const siblingMeta = ctx.objectMeta.get(sibling) ?? { file: "", line: 1 };
+                    ctx.diagnose(siblingMeta.file, ctx.propMeta.get(property)?.line ?? siblingMeta.line, `value "${value}" of unique property "${prop.name}" on ${sibling.kind} "${sibling.name}" ` +
+                        `already used by preceding ${sibling.kind} "${first.name}"`);
+                }
+            }
+            if (present !== undefined && siblings.length > 0 && !found)
+                ctx.diagnose(meta.file, meta.line, `no ${child.kind} below ${object.kind} "${object.name}" carries property "${prop.name}"` +
+                    (typeof prop.present === "string" ? ` with a value matching "${prop.present}"` : ""));
+        }
+    }
+};
 /*  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 };
@@ -132,11 +178,11 @@ const validateObject = (ctx, object, schema, level) => {
     /*  check every occurrence of the configured properties (a trailing
         parenthesized name token is accepted as the value of a still
         missing property, and a repeated key is reported as duplicate)  */
-    const consumed = parenProp(object, props);
+    const consumed = ctx.parenProps.get(object);
     for (const prop of props) {
         const expr = prop.value !== undefined ? compileValueExpr(prop.value) : undefined;
         const matches = object.properties.filter((p) => p.key === prop.name);
-        if (matches.length === 0 && prop !== consumed && prop.optional !== true)
+        if (matches.length === 0 && prop.name !== consumed?.key && prop.optional !== true)
             ctx.diagnose(meta.file, meta.line, `required property "${prop.name}" missing on ${object.kind} "${object.name}"`);
         for (const [i, match] of matches.entries()) {
             const line = ctx.propMeta.get(match)?.line ?? meta.line;
@@ -161,45 +207,8 @@ const validateObject = (ctx, object, schema, level) => {
         }
         validateObject(ctx, child, childSchema, level + 1);
     }
-    /*  check the property values flagged unique for distinctness among
-        the sibling objects of the same kind and the ones flagged present
-        for occurring on at least one of the (existing) siblings (all
-        values, or only the values matching the regexp or enum expression
-        of the flag)  */
-    for (const child of childs) {
-        const siblings = object.childs.filter((c) => c.kind === child.kind);
-        for (const prop of child.props ?? []) {
-            const marker = (flag) => flag === undefined || flag === false ? undefined :
-                { filter: typeof flag === "string" ? compileValueExpr(flag) : undefined };
-            const unique = marker(prop.unique);
-            const present = marker(prop.present);
-            if (unique === undefined && present === undefined)
-                continue;
-            const seen = new Map();
-            let found = false;
-            for (const sibling of siblings) {
-                const property = findProp(sibling, prop.name);
-                if (property === undefined)
-                    continue;
-                const value = plainText(property.value).trim();
-                if (present !== undefined && (present.filter === undefined || directMatches(present.filter, value)))
-                    found = true;
-                if (unique === undefined || (unique.filter !== undefined && !directMatches(unique.filter, value)))
-                    continue;
-                const first = seen.get(value);
-                if (first === undefined)
-                    seen.set(value, sibling);
-                else {
-                    const siblingMeta = ctx.objectMeta.get(sibling) ?? { file: "", line: 1 };
-                    ctx.diagnose(siblingMeta.file, ctx.propMeta.get(property)?.line ?? siblingMeta.line, `value "${value}" of unique property "${prop.name}" on ${sibling.kind} "${sibling.name}" ` +
-                        `already used by preceding ${sibling.kind} "${first.name}"`);
-                }
-            }
-            if (present !== undefined && siblings.length > 0 && !found)
-                ctx.diagnose(meta.file, meta.line, `no ${child.kind} below ${object.kind} "${object.name}" carries property "${prop.name}"` +
-                    (typeof prop.present === "string" ? ` with a value matching "${prop.present}"` : ""));
-        }
-    }
+    /*  check the sibling-scoped property flags of the child kinds  */
+    checkSiblingFlags(ctx, object, childs, meta);
     /*  report the configured child object kinds which are missing  */
     for (const child of childs)
         if (child.optional !== true
@@ -222,7 +231,7 @@ const validateObject = (ctx, object, schema, level) => {
 /*  resolve a level 1 object onto its configured artifact, deliberately
     leniently by kind and id first and by case-insensitive name second,
     so deviations of the heading can still be precisely reported  */
-export const resolveArtifact = (config, object) => config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
+export const resolveArtifact = (config, object) => config.find((s) => (s.kind === object.kind && s.id === object.id) || (s.id !== undefined && `${s.kind}-${s.id}` === object.id)) ??
     config.find((s) => s.name !== undefined
         && s.name.toUpperCase() === plainText(object.name).toUpperCase());
 /*  map the specification objects onto their schema configuration
@@ -267,7 +276,7 @@ const checkIds = (ctx, objects) => {
     distinct, in document order), leniently skipping the unresolvable
     ones, as those are already reported by the reference pass  */
 const referencedObjects = (ctx, object, name) => {
-    const property = findProp(object, name);
+    const property = findProp(ctx, object, name);
     if (property === undefined)
         return [];
     const targets = new Array();
@@ -296,7 +305,7 @@ const checkAutomata = (ctx, schemas) => {
         const nodes = object.childs.filter((child) => child.kind === automaton.nodes);
         const nodeSet = new Set(nodes);
         const flagged = (node, name) => {
-            const property = findProp(node, name);
+            const property = findProp(ctx, node, name);
             return property !== undefined && plainText(property.value).trim() === "true";
         };
         const initials = nodes.filter((node) => flagged(node, automaton.initial));
@@ -317,7 +326,7 @@ const checkAutomata = (ctx, schemas) => {
         const closure = (starts, next) => {
             const seen = new Set(starts);
             const queue = [...starts];
-            for (let node = queue.shift(); node !== undefined; node = queue.shift())
+            for (const node of queue)
                 for (const other of next.get(node) ?? [])
                     if (!seen.has(other)) {
                         seen.add(other);
@@ -349,13 +358,18 @@ const checkRelations = (ctx, schemas) => {
     const groups = new Map();
     for (const [object, schema] of schemas)
         for (const prop of schema.props ?? [])
-            if (prop.symmetric === true || prop.acyclic === true)
-                groups.set(prop, [...(groups.get(prop) ?? []), object]);
+            if (prop.symmetric === true || prop.acyclic === true) {
+                const group = groups.get(prop);
+                if (group === undefined)
+                    groups.set(prop, [object]);
+                else
+                    group.push(object);
+            }
     for (const [prop, objects] of groups) {
         const members = new Set(objects);
         const locate = (object) => {
             const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
-            const property = findProp(object, prop.name);
+            const property = findProp(ctx, object, prop.name);
             const line = property !== undefined ? ctx.propMeta.get(property)?.line : undefined;
             return { file: meta.file, line: line ?? meta.line };
         };
@@ -403,11 +417,11 @@ const checkRelations = (ctx, schemas) => {
     the references from within the subtree of the object itself do not
     count (a lapse is a warning only, as the specification stays valid)  */
 const checkReferenced = (ctx, specification, schemas) => {
-    /*  collect the referencing objects of every referenced object,
-        together with the parent of every object for the ancestor walk  */
+    /*  collect the referencing objects of every referenced object
+        (the references from within its own subtree excluded)  */
     const referrers = new Map();
-    const parents = new Map();
-    const walk = (object, chain) => {
+    const walk = (object) => {
+        const chain = chainOf(ctx.linkIndex, object);
         const texts = [object.name, ...object.properties.map((p) => p.value)];
         if (object.description !== undefined)
             texts.push(object.description.description, object.description.rationale ?? "");
@@ -417,14 +431,10 @@ const checkReferenced = (ctx, specification, schemas) => {
                 if (target !== undefined && !chain.includes(target))
                     referrers.set(target, (referrers.get(target) ?? new Set()).add(object));
             }
-        for (const child of object.childs) {
-            parents.set(child, object);
-            walk(child, [...chain, child]);
-        }
+        object.childs.forEach(walk);
     };
     for (const artifact of specification.artifacts)
-        for (const object of artifact.objects)
-            walk(object, [object]);
+        artifact.objects.forEach(walk);
     /*  resolve the reference patterns of every flagged kind into the
         admissible referencing objects (once per shared schema node)  */
     const sources = new Map();
@@ -442,12 +452,8 @@ const checkReferenced = (ctx, specification, schemas) => {
             }
             sources.set(schema, admissible);
         }
-        const covered = Array.from(referrers.get(object) ?? []).some((referrer) => {
-            for (let o = referrer; o !== undefined; o = parents.get(o))
-                if (admissible.has(o))
-                    return true;
-            return false;
-        });
+        const covered = Array.from(referrers.get(object) ?? [])
+            .some((referrer) => chainOf(ctx.linkIndex, referrer).some((o) => admissible.has(o)));
         if (!covered) {
             const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
             ctx.diagnose(meta.file, meta.line, `${object.kind} "${object.name}" is not referenced from any object matching ` +
@@ -469,9 +475,13 @@ export const validate = (ctx, specification, config) => {
             token, so the token still acts as the id and a single
             unresolved heading no longer cascades into unresolvable
             references all over the corpus  */
-        if (object.paren !== undefined && object.anchor === undefined
-            && parenProp(object, schemas.get(object)?.props ?? []) === undefined)
-            object.id = object.paren;
+        if (object.paren !== undefined) {
+            const prop = parenProp(object, schemas.get(object)?.props ?? []);
+            if (prop !== undefined)
+                ctx.parenProps.set(object, { key: prop.name, value: object.paren });
+            else if (object.anchor === undefined)
+                object.id = object.paren;
+        }
         object.childs.forEach(promote);
     };
     for (const artifact of specification.artifacts)
@@ -513,7 +523,7 @@ export const validate = (ctx, specification, config) => {
     its carrying object), independent of any configuration  */
 export const validateReferences = (ctx, specification) => {
     const check = (object, text, file, line) => {
-        for (const m of text.matchAll(referenceRegex)) {
+        for (const m of plainText(text).matchAll(referenceRegex)) {
             const ref = m[1].trim();
             const resolution = resolveUnique(ctx.linkIndex, ref, object);
             if (resolution.ambiguous)

package/dst/specbook-parse-syntax.js

@@ -27,8 +27,8 @@ const parseMarkers = (raw) => {
     let primary = false;
     for (;;) {
         const am = text.match(/\{\{([^{}]+)\}\}\s*$/);
-        if (am !== null && am.index !== undefined) {
-            anchor ??= am[1].trim();
+        if (am !== null && am.index !== undefined && anchor === undefined) {
+            anchor = am[1].trim();
             text = text.slice(0, am.index).trim();
             continue;
         }
@@ -48,7 +48,8 @@ const parseMarkers = (raw) => {
     }
     return { text, anchor, paren, primary };
 };
-/*  parse a heading text of the form "<KIND>: <name> [(<token>)] [<a id="..."></a>]"  */
+/*  parse a heading text of the form
+    "<KIND>: <name> [(<token>)] [(*)] [{{<anchor>}}] [<a id="..."></a>]"  */
 const parseHeadingText = (raw) => {
     let text = raw.trim();
     let id;

package/dst/specbook-parse.js

@@ -33,7 +33,7 @@ export const parseSpecification = (sources, config) => {
         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}`);
+                ctx.diagnose(sources[0].file, 1, `internal AST invalid at "${path}": ${issue.message}`);
             }
     }
     return { specification, diagnostics: ctx.diagnostics, assets: Array.from(ctx.assets) };

package/dst/specbook-theme.d.ts

@@ -7,7 +7,6 @@ export type ThemeColors = {
 export declare const themeColors: (tone: string) => ThemeColors;
 export declare const themeStylesheet: (colors: ThemeColors) => string;
 export type ThemeMapping = {
-    text: string;
     muted: string;
     symbol: string;
     border: string;

package/dst/specbook-theme.js

@@ -26,10 +26,9 @@ 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" ?
-        { text: 29, muted: 22, symbol: 20, border: 16, accent: 24 } :
-        { text: 5, muted: 22, symbol: 24, border: 28, accent: 12 };
+        { muted: 22, symbol: 20, border: 16, accent: 24 } :
+        { muted: 22, symbol: 24, border: 28, accent: 12 };
     return {
-        text: colors.base[idx.text - 1],
         muted: colors.base[idx.muted - 1],
         symbol: colors.base[idx.symbol - 1],
         border: colors.base[idx.border - 1],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.1.0",
+    "version":                             "1.2.1",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -22,9 +22,9 @@
         "yaml":                            "2.9.0",
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
-        "subset-font":                     "2.6.0",
+        "subset-font":                     "2.7.0",
         "@rse/mrcs":                       "0.9.2",
-        "@rse/gradia":                     "1.1.4",
+        "@rse/gradia":                     "1.1.7",
         "@toon-format/toon":               "4.1.1",
         "valibot":                         "1.4.2",
         "nunjucks":                        "3.2.4",
@@ -42,26 +42,28 @@
         "fastify":                         "5.12.1",
         "@fastify/websocket":              "11.3.0",
         "@modelcontextprotocol/sdk":       "1.30.0",
-        "zod":                             "4.5.1"
+        "zod":                             "4.5.4"
     },
     "devDependencies": {
         "chokidar-cli":                    "3.0.0",
         "eslint":                          "10.9.0",
         "@eslint/js":                      "10.0.1",
-        "typescript-eslint":               "8.68.0",
+        "typescript-eslint":               "8.69.0",
         "eslint-plugin-promise":           "7.3.0",
         "neostandard":                     "0.14.0-next.1",
-        "globals":                         "17.11.0",
-        "@types/node":                     "26.4.0",
+        "globals":                         "17.12.0",
+        "markdownlint":                    "0.41.1",
+        "markdownlint-cli2":               "0.23.2",
+        "@types/node":                     "26.4.1",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",
         "@types/ws":                       "8.18.1",
         "typescript":                      "6.0.3",
-        "tsx":                             "4.23.12",
+        "tsx":                             "4.23.13",
         "source-sans":                     "3.52.0",
         "source-code-pro":                 "2.42.0",
         "@fontsource/noto-sans-symbols":   "5.3.0",
-        "postcss":                         "8.5.26",
+        "postcss":                         "8.5.28",
         "postcss-cli":                     "11.0.1",
         "postcss-url":                     "10.1.4",
         "stylus":                          "0.64.0",