@rse/specbook 0.9.7 → 0.9.8

package/README.md

@@ -132,6 +132,11 @@ occur multiple times. The format (`json`, `json5`, `yaml`, `toon`,
 it is explicitly given as a `<format>:` prefix, and plain `-` (stdout)
 defaults to JSON.
 
+The `md` format normalizes the entire corpus into a *single* Markdown
+document, whose single frontmatter block carries the earliest `Created:`
+and the latest `Modified:` timestamp of all artifacts, so the
+per-artifact timestamps do not survive this round-trip.
+
 The `describe` command outputs the description of the SpecBook models
 and formats. If the configuration file `-c`/`--config` or the base
 directory `-b`/`--basedir` is given, it additionally appends a *SpecBook

package/dst/specbook-cmd-export.js

@@ -27,11 +27,15 @@ const extensions = new Map([
     format from the filename extension when not explicitly given
     (plain "-" for stdout defaults to JSON)  */
 export const parseOutputSpec = (spec) => {
-    const prefixed = spec.match(/^([a-zA-Z0-9]+):(.+)$/);
+    /*  a single-character prefix is never a format name, so a Windows
+        drive letter still falls through to the extension inference  */
+    const prefixed = spec.match(/^([a-zA-Z0-9]{2,}):(.+)$/);
     if (prefixed !== null) {
         const explicit = extensions.get(prefixed[1].toLowerCase());
-        if (explicit !== undefined)
-            return { format: explicit, output: prefixed[2] };
+        if (explicit === undefined)
+            throw new Error(`unknown export format "${prefixed[1]}" in output "${spec}" ` +
+                `(supported: ${Array.from(extensions.keys()).join(", ")})`);
+        return { format: explicit, output: prefixed[2] };
     }
     if (spec === "-")
         return { format: "json", output: spec };

package/dst/specbook-config.js

@@ -22,10 +22,11 @@ const lineColOfPath = (doc, lines, path) => {
     return { line: 1, column: 1 };
 };
 /*  check the constraints of a structurally valid configuration which
-    are beyond its schema: "file" fields are allowed on the first
-    (artifact) level only, property value expressions have to be
-    syntactically valid, and the names of non-artifact objects have to
-    be valid patterns (as they are compiled into regular expressions)  */
+    are beyond its schema: sibling objects have to stay distinctly
+    resolvable, "file" fields are allowed on the first (artifact) level
+    only, property value expressions have to be syntactically valid, and
+    the names of non-artifact objects have to be valid patterns (as they
+    are compiled into regular expressions)  */
 const checkConstraints = (config, file, posOfPath) => {
     const diagnostics = new Array();
     const diagnose = (path, message) => {
@@ -33,8 +34,17 @@ const checkConstraints = (config, file, posOfPath) => {
         diagnostics.push({ file, line: pos.line, column: pos.column, message });
     };
     const check = (objects, path, depth) => {
+        /*  the sibling objects are resolved by kind and id on the first
+            (artifact) level and by kind alone below it, so a sibling
+            colliding on this key stays unreachable dead configuration  */
+        const seen = new Set();
         for (const [i, object] of objects.entries()) {
             const at = [...path, i];
+            const ident = depth > 1 ? object.kind : `${object.kind}:${object.id ?? object.name ?? ""}`;
+            if (seen.has(ident))
+                diagnose([...at, "kind"], `object "${ident}" collides with a preceding sibling object (the later one is unreachable)`);
+            else
+                seen.add(ident);
             if (depth > 1 && object.file !== undefined)
                 diagnose([...at, "file"], `"file" field is only allowed on the first (artifact) level (found on level ${depth})`);
             for (const [j, prop] of (object.props ?? []).entries()) {

package/dst/specbook-diagram.d.ts

@@ -1,10 +1,14 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
 import type { Schema, SchemaDiagram } from "./specbook-format-schema.js";
 import type { ParseContext } from "./specbook-parse-common.js";
+export interface DiagramError {
+    reason: string;
+    object?: SpecObject;
+}
 export interface DiagramResult {
     spec?: string;
     config?: SchemaDiagram["config"];
-    errors: string[];
+    errors: DiagramError[];
 }
 export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;
 export declare const validateDiagrams: (ctx: ParseContext, specification: Spec, config: Schema) => void;

package/dst/specbook-diagram.js

@@ -110,13 +110,13 @@ const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors,
                 edgeNode(edgeObject, diagram.edgeSource) : parents.get(edgeObject);
             const target = edgeNode(edgeObject, diagram.edgeTarget);
             if (source === undefined) {
-                errors.push(diagram.edgeSource !== undefined ?
-                    `diagram edge object "${edgeObject.name}" carries no resolvable source reference` :
-                    `diagram edge object "${edgeObject.name}" has no parent object as source`);
+                errors.push({ object: edgeObject, reason: diagram.edgeSource !== undefined ?
+                        "carries no resolvable source reference" :
+                        "has no parent object as source" });
                 continue;
             }
             if (target === undefined) {
-                errors.push(`diagram edge object "${edgeObject.name}" carries no resolvable target reference`);
+                errors.push({ object: edgeObject, reason: "carries no resolvable target reference" });
                 continue;
             }
             if (!nodeSet.has(source) || !nodeSet.has(target))
@@ -136,11 +136,11 @@ const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors,
     }
     else {
         if (diagram.edges !== undefined)
-            errors.push("\"grid\" diagram cannot carry an \"edges\" configuration");
+            errors.push({ reason: "\"grid\" diagram cannot carry an \"edges\" configuration" });
         if (diagram.hierarchy === true)
-            errors.push("\"grid\" diagram cannot carry a \"hierarchy\" configuration");
+            errors.push({ reason: "\"grid\" diagram cannot carry a \"hierarchy\" configuration" });
         if (diagram.onlyConnected === true)
-            errors.push("\"grid\" diagram cannot carry an \"onlyConnected\" configuration");
+            errors.push({ reason: "\"grid\" diagram cannot carry an \"onlyConnected\" configuration" });
     }
     /*  deduplicate the edges (the same reference can occur in
         multiple texts of the same node object)  */
@@ -167,7 +167,7 @@ const resolvePatterns = (index, errors, value, field) => {
         const pattern = m[1].trim();
         const set = resolveSet(index, pattern);
         if (set.length === 0)
-            errors.push(`unresolvable diagram "${field}" pattern "[[${pattern}]]"`);
+            errors.push({ reason: `unresolvable diagram "${field}" pattern "[[${pattern}]]"` });
         for (const match of set) {
             if (!seen.has(match)) {
                 seen.add(match);
@@ -176,7 +176,7 @@ const resolvePatterns = (index, errors, value, field) => {
         }
     }
     if (!found)
-        errors.push(`diagram "${field}" carries no "[[...]]" reference pattern`);
+        errors.push({ reason: `diagram "${field}" carries no "[[...]]" reference pattern` });
     return matches;
 };
 /*  derive the Gradia spec of a single object from its "diagram:"
@@ -210,13 +210,13 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         resolved object of an explicit "[[...]]" reference otherwise  */
     let center = object;
     if (type !== "hub" && diagram.center !== undefined)
-        errors.push(`"${type}" diagram cannot carry a "center" configuration`);
+        errors.push({ reason: `"${type}" diagram cannot carry a "center" configuration` });
     if (type === "hub" && diagram.center !== undefined && diagram.center !== "self") {
         const reference = diagram.center.match(referenceOnce)?.[1].trim();
         const resolved = reference !== undefined ? resolveUnique(index, reference) : undefined;
         if (resolved?.target === undefined) {
-            errors.push((resolved?.ambiguous === true ? "ambiguous" : "unresolvable") +
-                ` diagram "center" reference "${diagram.center}"`);
+            errors.push({ reason: (resolved?.ambiguous === true ? "ambiguous" : "unresolvable") +
+                    ` diagram "center" reference "${diagram.center}"` });
             return { errors };
         }
         center = resolved.target;
@@ -227,7 +227,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         Gradia requires exactly this constrained topology  */
     if (type === "hub") {
         if (!nodeSet.has(center))
-            errors.push(`"hub" diagram center "${center.name}" is not part of the node set`);
+            errors.push({ reason: `"hub" diagram center "${center.name}" is not part of the node set` });
         else {
             edges = edges.filter((edge) => (edge.source === center || edge.target === center)
                 && edge.source !== edge.target);
@@ -250,7 +250,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         nodes = nodes.filter((node) => connected.has(node));
     }
     if (nodes.length === 0)
-        errors.push("diagram yields no nodes");
+        errors.push({ reason: "diagram yields no nodes" });
     if (errors.length > 0)
         return { errors };
     /*  the "collapse" handling (enabled by default) silently omits a
@@ -277,9 +277,21 @@ export const specDiagrams = (specification, config) => {
 /*  validate all configured diagrams of a specification, reporting
     every invalid diagram situation as a file/line-precise diagnostic  */
 export const validateDiagrams = (ctx, specification, config) => {
-    for (const [object, result] of specDiagrams(specification, config)) {
-        const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
-        for (const error of result.errors)
-            ctx.diagnose(meta.file, meta.line, `invalid diagram on ${object.kind} "${object.name}": ${error}`);
-    }
+    const seen = new Set();
+    for (const [object, result] of specDiagrams(specification, config))
+        for (const error of result.errors) {
+            /*  attribute an edge object situation to the offending edge
+                object itself and report it just once, as a wildcard
+                "edges" pattern lets every diagram walk the very same
+                edge objects again  */
+            const meta = ctx.objectMeta.get(error.object ?? object) ?? { file: "", line: 1 };
+            const message = error.object !== undefined ?
+                `invalid diagram edge on ${error.object.kind} "${error.object.name}": ${error.reason}` :
+                `invalid diagram on ${object.kind} "${object.name}": ${error.reason}`;
+            const key = `${meta.file}${meta.line}${message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            ctx.diagnose(meta.file, meta.line, message);
+        }
 };

package/dst/specbook-export-html.js

@@ -342,7 +342,8 @@ const inlineValue = (kind, { key, value, embedding }) => {
         .map((content) => `<div class="embedding">${content}</div>`).join("");
     if (member === undefined || text === "")
         return safe(`${inline(text)}${embeddings}`);
-    const items = member === "tags" ? splitItems(text) : [text];
+    const items = member === "tags" ?
+        splitItems(text).filter((item) => item !== "") : [text];
     return safe(items.map((item) => `<span class="value-member">${inline(item)}</span>`).join(" ") + embeddings);
 };
 /*  expand the inline Markdown of the property values  */

package/dst/specbook-export-md.js

@@ -4,6 +4,7 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { specDiagrams } from "./specbook-diagram.js";
+import { becauseRegex } from "./specbook-parse-common.js";
 /*  format a timestamp in the frontmatter format  */
 const formatTimestamp = (date) => {
     const pad = (n) => String(n).padStart(2, "0");
@@ -19,6 +20,10 @@ const renderKeyValuesMd = (properties, indent = "") => {
         `${indent}-   ${property.key}:\n${indent}    ${property.value}` :
         `${indent}-   ${`${property.key}:`.padEnd(width)} ${property.value}`.trimEnd()).join("\n");
 };
+/*  whether a property can be a Concise Format segment: a value carrying
+    a ";" would split the segment, and a value carrying the rationale
+    marker would not be taken for a property at all on re-parsing  */
+const segmentableMd = (property) => !property.value.includes(";") && !becauseRegex.test(property.value);
 /*  render a description statement with its optional rationale  */
 const renderDescriptionMd = (description) => description.description + (description.rationale !== undefined ?
     `, BECAUSE ${description.rationale}` : "");
@@ -27,20 +32,22 @@ const renderDescriptionMd = (description) => description.description + (descript
 const nameSuffixMd = (object) => (object.primary === true ? " (*)" : "") +
     (object.paren !== undefined ? ` (${object.paren})` : "") +
     (object.anchor !== undefined ? ` {{${object.anchor}}}` : "");
-/*  whether any descendant of an object carries a multi-line description
-    (a fenced code block, an ordered list, a blockquote, or multiple
-    paragraphs), which no Concise Format item can carry  */
-const multiLineBelowMd = (object) => object.childs.some((child) => (child.description !== undefined
-    && renderDescriptionMd(child.description).includes("\n")) || multiLineBelowMd(child));
+/*  whether any descendant of an object carries a description which no
+    Concise Format item can carry -- a multi-line one (a fenced code
+    block, an ordered list, a blockquote, or multiple paragraphs) or one
+    carrying a ";", as only a ";"-free description stays a single segment
+    on re-parsing instead of splitting off a spurious property  */
+const complexBelowMd = (object) => object.childs.some((child) => (child.description !== undefined
+    && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
 /*  render an object in the Concise Format as a list item of the
     given nesting depth, with its childs as nested list items  */
 const renderConciseMd = (object, depth = 0) => {
     const indent = " ".repeat(depth * 4);
     const segments = [`${object.kind}: ${object.name}${nameSuffixMd(object)}`];
-    /*  a value carrying ";" cannot be a segment, so its property has to
-        become a nested key/value item below the item instead  */
-    const wrapped = object.properties.filter((property) => property.value.includes(";"));
-    const inline = object.properties.filter((property) => !property.value.includes(";"));
+    /*  a property which cannot be a segment has to become a nested
+        key/value item below the item instead  */
+    const wrapped = object.properties.filter((property) => !segmentableMd(property));
+    const inline = object.properties.filter((property) => segmentableMd(property));
     segments.push(...inline.map((property) => `${property.key}: ${property.value}`));
     if (object.description !== undefined)
         segments.push(renderDescriptionMd(object.description));
@@ -57,10 +64,10 @@ const renderConciseMd = (object, depth = 0) => {
 };
 /*  render an object in the Complex Format (levels 1-3), with childs from
     level 4 upwards in the Concise Format -- unless a descendant carries
-    a multi-line description, so all childs (as siblings have to share
-    the format) stay in the Complex Format down to heading level 6 --,
-    and the optionally derived Gradia diagram spec embedded as a
-    "gradia" fenced code block below the heading  */
+    a description no concise item can carry, so all childs (as siblings
+    have to share the format) stay in the Complex Format down to heading
+    level 6 --, and the optionally derived Gradia diagram spec embedded
+    as a "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
     const heading = `${"#".repeat(level)}${" ".repeat(Math.max(1, 4 - level))}` +
         `${object.kind}: ${object.name}${nameSuffixMd(object)}`;
@@ -74,7 +81,7 @@ const renderObjectMd = (object, level, diagrams) => {
         parts.push(renderDescriptionMd(object.description));
     /*  the childs share one format, as a concise item following
         a heading would attach to the heading's object instead  */
-    if (level >= 3 && !multiLineBelowMd(object))
+    if (level >= 3 && !complexBelowMd(object))
         parts.push(object.childs.map((child) => renderConciseMd(child)).join("\n"));
     else
         parts.push(...object.childs.map((child) => renderObjectMd(child, level + 1, diagrams)));

package/dst/specbook-format.md

@@ -160,7 +160,8 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE artifacts and their content follow one recursive structure
 
 -   `SchemaObject.kind: string`:
-    kind name of the object (e.g. `SPEC`, `REQUIREMENT`),
+    kind name of the object (e.g. `SPEC`, `REQUIREMENT`), unique among
+    its siblings, on level 1 together with its `id`,
     BECAUSE it discriminates objects and anchors `[[xxx]]` references
 
 -   `SchemaObject.name?: string`:
@@ -557,6 +558,12 @@ follow each other on level 1, below the single frontmatter block of that
 file. Both ATX headings (`# <text/>`, `## <text/>`, ...) and Setext
 headings (`<text/>` underlined with `===` or `---`) are supported.
 
+As the timestamps are a property of the *file* and not of the individual
+artifact, the normalized Markdown export -- which merges the entire
+corpus into a single document -- carries the earliest `Created:` and the
+latest `Modified:` timestamp of all artifacts in its single frontmatter
+block, so the per-artifact timestamps do not survive this round-trip.
+
 ### Object Model
 
 An artifact carries a tree of *objects*. Every object has a mandatory
@@ -644,12 +651,13 @@ the item would look like a key/value pair) -- backquote it in this case.
 
 When **SpecBook** itself generates specification Markdown, it emits
 the Complex Format on levels 1-3 and the Concise Format from level 4
-upwards -- unless a descendant of an object carries a multi-line
-description (a fenced code block, an ordered list, a blockquote, or
-multiple paragraphs), which no single list item can carry: all child
-objects of such an object then stay in the Complex Format (as sibling
-objects have to share the format), with headings reaching down to level
-6. When **SpecBook** edits existing files, it mirrors the format each
+upwards -- unless a descendant of an object carries a description which
+no single list item can carry: a multi-line one (a fenced code block, an
+ordered list, a blockquote, or multiple paragraphs) or one carrying a
+`;` (which a re-parse would split into a spurious property plus a
+truncated description). All child objects of such an object then stay in
+the Complex Format (as sibling objects have to share the format), with
+headings reaching down to level 6. When **SpecBook** edits existing files, it mirrors the format each
 existing object already uses.
 
 ### Names, Anchors, and Ids
@@ -679,9 +687,10 @@ In the Complex Format, each property is an unordered list item of the
 form `<key/>: <value/>`, whose value may continue on the following
 indented lines of the item (joined with spaces). In the Concise Format,
 each property is a `<key/>: <value/>` segment. A value carrying a `;`
-cannot be a segment and has to start on a continuation line of a
-key/value item, as a `;` on the first line of a list item marks a
-Concise Format object. The key is matched
+or a ` BECAUSE ` cannot be a segment and has to become a key/value item
+nested below the item instead -- a `;` value additionally starting on a
+continuation line of that item, as a `;` on the first line of a list
+item marks a Concise Format object. The key is matched
 against the schema exactly as written and may occur only once per
 object, and the value has to satisfy the configured constraint as a
 whole.
@@ -695,7 +704,9 @@ fenced code blocks. A fenced code block
 of language `gradia` is skipped, as it is the derived diagram which
 **SpecBook** itself emits into exported Markdown and which must not
 become authored content on a re-parse. In the Concise Format, the
-description is formed by the non-property segments of the item.
+description is formed by the non-property segments of the item, so a
+description carrying a `;` cannot be a segment either and forces its
+object into the Complex Format.
 
 A description is split into its *statement* and *rationale* at the first
 `, BECAUSE ` (or `, **BECAUSE** `) occurrence:

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

@@ -22,6 +22,7 @@ export declare class ParseContext {
     linkIndex: LinkIndex;
     diagnose(file: string, line: number, message: string): void;
 }
+export declare const becauseRegex: RegExp;
 export declare const embeddingRegex: RegExp;
 export declare const embeddingThemes: readonly ["light", "dark"];
 export declare const embeddingVariants: (reference: string) => string[];

package/dst/specbook-parse-common.js

@@ -14,6 +14,8 @@ export class ParseContext {
         this.diagnostics.push({ file, line, column: 1, message });
     }
 }
+/*  the marker separating a statement from its rationale  */
+export const becauseRegex = /,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/;
 /*  the Markdown image embedding syntax ("![alt](file)")  */
 export const embeddingRegex = /!\[([^\]]*)\]\(([^()]+)\)/g;
 /*  the theme variants of a theme-aware image embedding  */

package/dst/specbook-parse-semantic.js

@@ -36,6 +36,15 @@ const matchAlternatives = (ctx, alternatives, item) => {
 };
 /*  find a property of an object by its key (case-sensitive)  */
 const findProp = (object, name) => object.properties.find((p) => p.key === name);
+/*  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  */
+const splitPropItems = (ctx, prop, property, meta) => {
+    const items = splitItems(plainText(property.value));
+    if (items.some((item) => item === ""))
+        ctx.diagnose(meta.file, meta.line, `property "${prop.name}" value "${property.value}" contains an empty item`);
+    return items.filter((item) => item !== "");
+};
 /*  check a property value against the compiled value expression of its
     configured schema property  */
 const checkPropValue = (ctx, prop, expr, property, meta) => {
@@ -56,7 +65,7 @@ const checkPropValue = (ctx, prop, expr, property, meta) => {
         /*  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))) {
+        for (const item of splitPropItems(ctx, prop, property, meta)) {
             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))
@@ -67,7 +76,7 @@ const checkPropValue = (ctx, prop, expr, property, meta) => {
     else if (expr.kind === "list") {
         /*  a list constraint: the value is a comma-separated list
             of items, each matching at least one alternative  */
-        for (const item of splitItems(plainText(property.value)))
+        for (const item of splitPropItems(ctx, prop, property, meta))
             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}"`);
     }
@@ -201,10 +210,19 @@ export const validate = (ctx, specification, config) => {
         precedence), which has to happen before any property check, as
         those resolve references by id across all artifacts  */
     const schemas = collectSchemas(specification, config);
-    for (const [object, schema] of schemas)
+    const promote = (object) => {
+        /*  an object below an unresolved artifact or an unknown kind
+            carries no schema and hence no property able to consume the
+            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, schema.props ?? []) === undefined)
+            && parenProp(object, schemas.get(object)?.props ?? []) === undefined)
             object.id = object.paren;
+        object.childs.forEach(promote);
+    };
+    for (const artifact of specification.artifacts)
+        artifact.objects.forEach(promote);
     /*  check the ids for local uniqueness, now that all of them are final  */
     checkIds(ctx, specification.artifacts.flatMap((artifact) => artifact.objects));
     /*  validate every level 1 object against its artifact schema  */

package/dst/specbook-parse-syntax.js

@@ -6,9 +6,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { marked } from "marked";
-import { embeddingRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
-/*  the marker separating a statement from its rationale  */
-const becauseRegex = /,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/;
+import { becauseRegex, embeddingRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
 /*  split a description text into statement and optional rationale  */
 const splitDescription = (text) => {
     const m = text.match(becauseRegex);
@@ -268,7 +266,9 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
 };
 /*  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)  */
+    (an artifact on level 1, a child of the enclosing object below); a heading
+    without a parent object detaches the current object, so the content below
+    it is reported, too, instead of being absorbed by the previous object  */
 const parseHeading = (ctx, token, state, stamps, file, line) => {
     const { depth, text } = token;
     const heading = parseHeadingText(text);
@@ -277,8 +277,10 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
         ctx.diagnose(file, line, `malformed anchor "${heading.malformed}" in heading`);
     if (heading.name === "" && depth > 1) {
         const parent = state.stack[depth - 2];
-        if (parent === undefined)
+        if (parent === undefined) {
             ctx.diagnose(file, line, `heading level ${depth} without parent object`);
+            state.current = null;
+        }
         else {
             state.group = { parent, kind: heading.kind };
             state.current = parent;
@@ -306,6 +308,7 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
         const parent = state.stack[depth - 2];
         if (parent === undefined) {
             ctx.diagnose(file, line, `heading level ${depth} without parent object`);
+            state.current = null;
             return;
         }
         parent.childs.push(object);
@@ -314,6 +317,15 @@ const parseHeading = (ctx, token, state, stamps, file, line) => {
     state.stack[depth - 1] = object;
     state.current = object;
 };
+/*  the block-level token types which carry content no description can
+    hold, mapped onto their diagnostic name (the only other unhandled
+    type is "space", which carries no content at all)  */
+const unsupportedTokens = {
+    table: "table",
+    html: "raw HTML",
+    hr: "horizontal rule",
+    def: "link definition"
+};
 /*  parse a single source file into its artifacts  */
 export const parseFile = (ctx, source) => {
     const { present, created, modified, body, offset } = parseFrontmatter(source.text);
@@ -380,8 +392,11 @@ export const parseFile = (ctx, source) => {
             else
                 collect(token.raw, line);
         }
-        else if (token.type === "table")
-            ctx.diagnose(source.file, line, "unsupported table content ignored");
+        else {
+            const unsupported = unsupportedTokens[token.type];
+            if (unsupported !== undefined)
+                ctx.diagnose(source.file, line, `unsupported ${unsupported} content ignored`);
+        }
         line += (token.raw.match(/\n/g) ?? []).length;
     }
     flush();

package/dst/specbook-parse-value.js

@@ -98,7 +98,8 @@ export const compileValueExpr = (source) => {
     return expr;
 };
 /*  split a property value at top-level commas, honoring double-quoted
-    sections and "[[...]]" reference bracketing  */
+    sections and "[[...]]" reference bracketing (empty items are kept,
+    as only the caller can decide whether to report or skip them)  */
 export const splitItems = (text) => {
     const parts = [""];
     let quoted = false;
@@ -128,5 +129,5 @@ export const splitItems = (text) => {
         const item = part.trim();
         const m = item.match(/^"((?:\\"|[^"])*)"$/);
         return m !== null ? m[1].replace(/\\"/g, "\"") : item;
-    }).filter((part) => part !== "");
+    });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "0.9.7",
+    "version":                             "0.9.8",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",