@rse/specbook 0.9.2

package/dst/specbook-parse-semantic.js

@@ -0,0 +1,254 @@
+/*
+**  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>
+*/
+import { referenceRegex, resolveUnique, resolveSet } from "./specbook-link.js";
+import { compileValueExpr, splitItems } from "./specbook-parse-value.js";
+/*  strip a trailing parenthesized annotation from a
+    property key (e.g. "WHEN (Context)")  */
+const plainKey = (key) => key.replace(/\s*\([^)]*\)\s*$/, "").trim();
+/*  strip the inline code markup of a name or property value
+    (preserved in the AST for rendering) for matching purposes  */
+const plainText = (text) => text.replace(/`/g, "");
+/*  compile a configured pattern into an anchored regular expression  */
+const anchored = (pattern, flags = "") => new RegExp(`^(?:${pattern})$`, flags);
+/*  match a single inline token against a value expression
+    (case-insensitively, as inline tokens are decorations)  */
+const tokenMatches = (expr, token) => expr.kind === "regex" ?
+    anchored(expr.source, "i").test(token) :
+    expr.kind === "enum" ?
+        expr.members.some((member) => member.toLowerCase() === token.toLowerCase()) :
+        false;
+/*  match a full property value directly against a value expression
+    (defined for the regex and enum kinds only)  */
+const directMatches = (expr, text) => expr.kind === "regex" ?
+    expr.regex.test(text) :
+    expr.kind === "enum" ?
+        expr.members.includes(text) :
+        false;
+/*  match a single list item against the alternatives of a list
+    constraint (a reference item resolves leniently, as unresolvable
+    and ambiguous ones are already reported by the reference pass)  */
+const matchAlternatives = (ctx, alternatives, item) => {
+    const rm = item.match(/^\[\[([^[\]]+)\]\]$/);
+    for (const alternative of alternatives) {
+        if (alternative.kind === "reference") {
+            if (rm === null)
+                continue;
+            const target = resolveUnique(ctx.linkIndex, rm[1].trim()).target;
+            if (target === undefined
+                || resolveSet(ctx.linkIndex, alternative.pattern).includes(target))
+                return true;
+        }
+        else if (alternative.kind === "tags") {
+            if (alternative.members.includes(plainText(item)))
+                return true;
+        }
+        else if (directMatches(alternative, plainText(item)))
+            return true;
+    }
+    return false;
+};
+/*  validate a single object (and recursively its childs) against its schema  */
+const validateObject = (ctx, object, schema, level) => {
+    const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+    const props = schema.props ?? [];
+    /*  check the name convention (the configured name of non-artifact
+        objects is a regular expression pattern)  */
+    if (level > 1 && schema.name !== undefined && !anchored(schema.name).test(plainText(object.name)))
+        ctx.diagnose(meta.file, meta.line, `${object.kind} name "${object.name}" does not match pattern "${schema.name}"`);
+    /*  a configured id has to be explicitly specified 1:1 in the
+        input, via either "{{<id>}}" or "(<id>)"  */
+    if (schema.id !== undefined && (object.anchor ?? object.paren) !== schema.id)
+        ctx.diagnose(meta.file, meta.line, `configured id "${schema.id}" not explicitly specified on ${object.kind} "${object.name}"`);
+    /*  find a property by its key (case-sensitive)  */
+    const findProp = (name) => object.properties.find((p) => plainKey(p.key) === name);
+    /*  the tokens split off multi-token property values below, assigned
+        to the still unset configured properties by matching their patterns  */
+    const tokens = new Array();
+    const tokenAssigned = new Set();
+    /*  explode a multi-token property value whose direct pattern check
+        fails: keep the token matching the own pattern and distribute
+        the remaining tokens across the sibling properties  */
+    for (const prop of props) {
+        if (prop.value === undefined)
+            continue;
+        const expr = compileValueExpr(prop.value);
+        if (expr.kind !== "regex" && expr.kind !== "enum")
+            continue;
+        const match = findProp(prop.name);
+        if (match === undefined || directMatches(expr, plainText(match.value)))
+            continue;
+        const parts = plainText(match.value).split(/\s+/);
+        if (parts.length < 2)
+            continue;
+        const idx = parts.findIndex((part) => tokenMatches(expr, part));
+        if (idx < 0)
+            continue;
+        match.value = parts[idx];
+        tokenAssigned.add(prop.name);
+        parts.splice(idx, 1);
+        tokens.push(...parts);
+    }
+    for (const prop of props) {
+        if (prop.value === undefined || findProp(prop.name) !== undefined)
+            continue;
+        const expr = compileValueExpr(prop.value);
+        if (expr.kind !== "regex" && expr.kind !== "enum")
+            continue;
+        const idx = tokens.findIndex((token) => tokenMatches(expr, token));
+        if (idx >= 0) {
+            object.properties.push({ key: prop.name, value: tokens[idx] });
+            tokenAssigned.add(prop.name);
+            tokens.splice(idx, 1);
+        }
+    }
+    for (const token of tokens)
+        ctx.diagnose(meta.file, meta.line, `unassignable inline token "${token}" on ${object.kind} "${object.name}"`);
+    /*  check the configured properties  */
+    let parenConsumed = false;
+    for (const prop of props) {
+        const expr = prop.value !== undefined ? compileValueExpr(prop.value) : undefined;
+        const match = findProp(prop.name);
+        if (match === undefined) {
+            /*  accept a trailing parenthesized name token as the value of a
+                still missing property when it matches the property pattern  */
+            if (object.paren !== undefined && expr !== undefined
+                && directMatches(expr, object.paren)) {
+                parenConsumed = true;
+                continue;
+            }
+            if (prop.optional !== true)
+                ctx.diagnose(meta.file, meta.line, `required property "${prop.name}" missing on ${object.kind} "${object.name}"`);
+        }
+        else if (expr !== undefined) {
+            const line = ctx.propMeta.get(match)?.line ?? meta.line;
+            if (expr.kind === "reference") {
+                /*  a reference constraint: the value has to be exactly one
+                    reference resolving into the constraint's wildcard match set  */
+                if (!/^\[\[[^[\]]+\]\]$/.test(match.value.trim()))
+                    ctx.diagnose(meta.file, line, `property "${prop.name}" value "${match.value}" is not a single link reference`);
+                else {
+                    const ref = match.value.trim().slice(2, -2).trim();
+                    const target = resolveUnique(ctx.linkIndex, ref).target;
+                    if (target !== undefined && !resolveSet(ctx.linkIndex, expr.pattern).includes(target))
+                        ctx.diagnose(meta.file, line, `link reference "[[${ref}]]" does not match constraint "${prop.value}"`);
+                }
+            }
+            else if (expr.kind === "tags") {
+                /*  a tags constraint: the value is a comma-separated set of
+                    configured tags, each occurring at most once  */
+                const seen = new Set();
+                for (const item of splitItems(plainText(match.value))) {
+                    if (!expr.members.includes(item))
+                        ctx.diagnose(meta.file, line, `tag "${item}" of property "${prop.name}" not allowed by constraint "${prop.value}"`);
+                    else if (seen.has(item))
+                        ctx.diagnose(meta.file, line, `duplicate tag "${item}" on property "${prop.name}"`);
+                    seen.add(item);
+                }
+            }
+            else if (expr.kind === "list") {
+                /*  a list constraint: the value is a comma-separated list
+                    of items, each matching at least one alternative  */
+                for (const item of splitItems(match.value))
+                    if (!matchAlternatives(ctx, expr.alternatives, item))
+                        ctx.diagnose(meta.file, line, `list item "${item}" of property "${prop.name}" does not match constraint "${prop.value}"`);
+            }
+            else if (!tokenAssigned.has(prop.name) && !directMatches(expr, plainText(match.value)))
+                ctx.diagnose(meta.file, line, expr.kind === "enum" ?
+                    `property "${prop.name}" value "${match.value}" is not a member of "${prop.value}"` :
+                    `property "${prop.name}" value "${match.value}" does not match pattern "${prop.value}"`);
+        }
+    }
+    for (const property of object.properties)
+        if (!props.some((p) => p.name === plainKey(property.key)))
+            ctx.diagnose(meta.file, ctx.propMeta.get(property)?.line ?? meta.line, `unknown property "${property.key}" on ${object.kind} "${object.name}"`);
+    /*  a parenthesized token not consumed as a property value acts as
+        the implicit anchor (an explicit "{{...}}" anchor takes precedence)  */
+    if (object.paren !== undefined && !parenConsumed && object.anchor === undefined)
+        object.id = object.paren;
+    /*  check the configured child objects  */
+    const childs = schema.childs ?? [];
+    for (const child of object.childs) {
+        const childMeta = ctx.objectMeta.get(child) ?? { file: "", line: 1 };
+        const childSchema = childs.find((c) => c.kind === child.kind);
+        if (childSchema === undefined) {
+            ctx.diagnose(childMeta.file, childMeta.line, `unknown object kind "${child.kind}" below ${object.kind} "${object.name}"`);
+            continue;
+        }
+        validateObject(ctx, child, childSchema, level + 1);
+    }
+    for (const child of childs)
+        if (child.optional !== true
+            && !object.childs.some((c) => c.kind === child.kind))
+            ctx.diagnose(meta.file, meta.line, `required object kind "${child.kind}" missing below ${object.kind} "${object.name}"`);
+    /*  order the childs and properties exactly along the schema
+        definition (the sort is stable, so objects of the same kind
+        and unknown items keep their document order)  */
+    const kindPos = (kind) => {
+        const i = childs.findIndex((c) => c.kind === kind);
+        return i >= 0 ? i : childs.length;
+    };
+    object.childs.sort((a, b) => kindPos(a.kind) - kindPos(b.kind));
+    const propPos = (key) => {
+        const i = props.findIndex((p) => p.name === plainKey(key));
+        return i >= 0 ? i : props.length;
+    };
+    object.properties.sort((a, b) => propPos(a.key) - propPos(b.key));
+};
+/*  validate the parsed specification against the configuration  */
+export const validate = (ctx, specification, config) => {
+    const position = new Map();
+    for (const artifact of specification.artifacts) {
+        for (const object of artifact.objects) {
+            const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+            const schema = config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
+                config.find((s) => (s.name ?? "").toUpperCase() === plainText(object.name).toUpperCase());
+            if (schema === undefined) {
+                ctx.diagnose(meta.file, meta.line, `unknown artifact "${object.kind}: ${object.name}" (id "${object.id}")`);
+                continue;
+            }
+            /*  the artifact heading must carry the configured kind and
+                name verbatim (the resolution above is deliberately
+                lenient, so deviations are still precisely reported)  */
+            if (object.kind !== schema.kind)
+                ctx.diagnose(meta.file, meta.line, `artifact kind "${object.kind}" does not match configured kind "${schema.kind}"`);
+            if (schema.name !== undefined && plainText(object.name) !== schema.name)
+                ctx.diagnose(meta.file, meta.line, `artifact name "${object.name}" does not match configured name "${schema.name}"`);
+            if (!position.has(artifact))
+                position.set(artifact, config.indexOf(schema));
+            validateObject(ctx, object, schema, 1);
+        }
+    }
+    /*  order the artifacts exactly along the schema definition  */
+    specification.artifacts.sort((a, b) => (position.get(a) ?? config.length) - (position.get(b) ?? config.length));
+};
+/*  validate every Wiki-style reference for unique resolvability,
+    independent of any configuration  */
+export const validateReferences = (ctx, specification) => {
+    const check = (text, file, line) => {
+        for (const m of text.matchAll(referenceRegex)) {
+            const ref = m[1].trim();
+            const resolution = resolveUnique(ctx.linkIndex, ref);
+            if (resolution.ambiguous)
+                ctx.diagnose(file, line, `ambiguous link reference "[[${ref}]]"`);
+            else if (resolution.target === undefined)
+                ctx.diagnose(file, line, `unresolvable link reference "[[${ref}]]"`);
+        }
+    };
+    const walk = (object) => {
+        const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+        check(object.name, meta.file, meta.line);
+        for (const property of object.properties)
+            check(property.value, meta.file, ctx.propMeta.get(property)?.line ?? meta.line);
+        if (object.description !== undefined) {
+            check(object.description.description, meta.file, meta.line);
+            if (object.description.rationale !== undefined)
+                check(object.description.rationale, meta.file, meta.line);
+        }
+        object.childs.forEach(walk);
+    };
+    for (const artifact of specification.artifacts)
+        artifact.objects.forEach(walk);
+};

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

@@ -0,0 +1,3 @@
+import { type Artifact } from "./specbook-struct-spec.js";
+import { ParseContext, type SourceFile } from "./specbook-parse-common.js";
+export declare const parseFile: (ctx: ParseContext, source: SourceFile) => Artifact[];

package/dst/specbook-parse-syntax.js

@@ -0,0 +1,363 @@
+/*
+**  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>
+*/
+import fs from "node:fs";
+import path from "node:path";
+import { marked } from "marked";
+import { embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
+/*  split a description text into statement and optional rationale  */
+const splitDescription = (text) => {
+    const m = text.match(/,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/);
+    if (m === null || m.index === undefined)
+        return { description: text };
+    return {
+        description: text.slice(0, m.index),
+        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  */
+    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();
+            continue;
+        }
+        const sm = text.match(/\(\*\)\s*$/);
+        if (sm !== null && sm.index !== undefined) {
+            primary = true;
+            text = text.slice(0, sm.index).trim();
+            continue;
+        }
+        const pm = text.match(/\(([^()]+)\)\s*$/);
+        if (pm !== null && pm.index !== undefined && paren === undefined) {
+            paren = pm[1].trim();
+            text = text.slice(0, pm.index).trim();
+            continue;
+        }
+        break;
+    }
+    const km = text.match(/^([^:]+):\s*(.*)$/);
+    return {
+        kind: km !== null ? km[1].trim() : text,
+        name: km !== null ? km[2].trim() : "",
+        id, paren, 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)  */
+const itemLines = (item) => {
+    const body = item.tokens.find((token) => token.type === "text");
+    const text = body !== undefined ? body.text : item.text;
+    return text.split("\n").map((line) => line.trim());
+};
+/*  parse the optional Markdown frontmatter with Created/Modified timestamps  */
+const parseFrontmatter = (text) => {
+    const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+    const missing = { date: null, line: 1, value: null };
+    if (m === null)
+        return { present: false, created: missing, modified: missing, body: text, offset: 0 };
+    const grab = (key) => {
+        const km = m[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+        if (km === null || km.index === undefined)
+            return missing;
+        const line = 2 + (m[1].slice(0, km.index).match(/\n/g) ?? []).length;
+        const value = km[1].trim();
+        const date = new Date(value);
+        return { date: isNaN(date.getTime()) ? null : date, line, value };
+    };
+    return {
+        present: true,
+        created: grab("Created"),
+        modified: grab("Modified"),
+        body: text.slice(m[0].length),
+        offset: m[0].split("\n").length - 1
+    };
+};
+/*  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  */
+const embed = (ctx, object, file) => {
+    const load = (target, text, line) => {
+        for (const m of text.matchAll(embeddingRegex)) {
+            const reference = m[2].trim();
+            const type = embeddingMimeType(reference);
+            if (type === undefined)
+                continue;
+            try {
+                const data = fs.readFileSync(path.resolve(path.dirname(file), 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)));
+            }
+        }
+    };
+    const line = ctx.objectMeta.get(object)?.line ?? 1;
+    if (object.description !== undefined)
+        load(object.description, object.description.description, line);
+    for (const property of object.properties)
+        load(property, property.value, ctx.propMeta.get(property)?.line ?? line);
+    for (const child of object.childs)
+        embed(ctx, child, file);
+};
+/*  parse an unordered list of key-values and/or concise-format objects  */
+const parseList = (ctx, list, object, file, line) => {
+    for (const item of list.items) {
+        const lines = itemLines(item);
+        const first = lines[0];
+        /*  a concise-format item carries a further segment on its first
+            line, or ends it with the segment terminator (the case of an
+            object without properties, whose description follows below)  */
+        const cm = first.match(/^([^:;]+):\s+(.+;.*)$/);
+        if (cm !== null)
+            parseConcise(ctx, item, object, file, line);
+        else {
+            const km = first.match(/^([^:;]+):\s*(.*)$/);
+            if (km !== null) {
+                /*  a key/value property, whose value may continue
+                    on the following lines of the item  */
+                const value = [km[2], ...lines.slice(1)].join(" ").trim();
+                const property = { key: km[1].trim(), value };
+                ctx.propMeta.set(property, { line });
+                object.properties.push(property);
+            }
+            else
+                ctx.diagnose(file, line, `unrecognized list item "${first}"`);
+        }
+        line += (item.raw.match(/\n/g) ?? []).length;
+    }
+};
+/*  parse a grouped list of concise-format object items of the form
+    "`<name>`; <key>: <value>; ...; <statement>, BECAUSE <rationale>.",
+    whose kind is given by the enclosing grouping container heading  */
+const parseGrouped = (ctx, list, group, file, line) => {
+    for (const item of list.items) {
+        parseConcise(ctx, item, group.parent, file, line, group.kind);
+        line += (item.raw.match(/\n/g) ?? []).length;
+    }
+};
+/*  parse a concise-format object item of the form
+    "<kind>: <name>; <key>: <value>; ...; <statement>, BECAUSE <rationale>.",
+    which may continue on the following lines of the item; a grouped item
+    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 head = segments.shift() ?? "";
+    let kind;
+    let name;
+    if (group !== undefined) {
+        const nm = head.match(/^`([^`]+)`$|^([^`:]+)$/);
+        if (nm === null) {
+            ctx.diagnose(file, line, `unrecognized ${group} item "${text}"`);
+            return;
+        }
+        kind = group;
+        name = (nm[1] ?? nm[2]).trim();
+    }
+    else {
+        const km = head.match(/^([^:]+):\s*(.*)$/);
+        if (km === null) {
+            ctx.diagnose(file, line, `invalid concise object item "${text}"`);
+            return;
+        }
+        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;
+    }
+    const object = {
+        kind,
+        id: anchor ?? slugify(name),
+        name,
+        properties: [],
+        childs: []
+    };
+    if (anchor !== undefined)
+        object.anchor = anchor;
+    if (paren !== undefined)
+        object.paren = paren;
+    if (primary)
+        object.primary = true;
+    ctx.objectMeta.set(object, { file, line });
+    const statements = new Array();
+    for (const segment of segments) {
+        const km = segment.match(/^([^:;]+):\s+(.+)$/);
+        if (km !== null && !(/\sBECAUSE\s/.test(segment))) {
+            const property = { key: km[1].trim(), value: km[2].trim() };
+            ctx.propMeta.set(property, { line });
+            object.properties.push(property);
+        }
+        else
+            statements.push(segment);
+    }
+    if (statements.length > 0)
+        object.description = splitDescription(statements.join("; ").replace(/\.\s*$/, ""));
+    /*  recurse into nested concise-format child objects  */
+    for (const sub of item.tokens)
+        if (sub.type === "list" && !sub.ordered)
+            parseList(ctx, sub, object, file, line);
+    parent.childs.push(object);
+};
+/*  parse a single source file into its artifacts  */
+export const parseFile = (ctx, source) => {
+    const { present, created, modified, body, offset } = parseFrontmatter(source.text);
+    if (!present)
+        ctx.diagnose(source.file, 1, "missing frontmatter (\"Created:\"/\"Modified:\" block)");
+    else
+        for (const [key, info] of [["Created", created], ["Modified", modified]])
+            if (info.date === null)
+                ctx.diagnose(source.file, info.line, info.value === null ?
+                    `missing "${key}:" frontmatter key` :
+                    `invalid "${key}:" frontmatter timestamp "${info.value}"`);
+    const artifacts = new Array();
+    const stack = new Array();
+    let current = null;
+    let group = null;
+    let parts = new Array();
+    /*  flush the accumulated description parts into the current object  */
+    const flush = () => {
+        if (current !== null && parts.length > 0 && current.description === undefined)
+            current.description = splitDescription(parts.join("\n\n").trim());
+        parts = [];
+    };
+    /*  walk the top-level Markdown tokens, tracking source lines  */
+    let line = offset + 1;
+    for (const token of marked.lexer(body)) {
+        if (token.type === "heading") {
+            flush();
+            group = null;
+            const heading = parseHeadingText(token.text);
+            if (heading.malformed !== undefined)
+                ctx.diagnose(source.file, line, `malformed anchor "${heading.malformed}" in heading`);
+            if (heading.name === "" && token.depth > 1) {
+                /*  a grouping container heading (e.g. "### STATES") collects
+                    objects of its singular kind below the parent object  */
+                const parent = stack[token.depth - 2];
+                if (parent === undefined)
+                    ctx.diagnose(source.file, line, `heading level ${token.depth} without parent object`);
+                else {
+                    group = { parent, kind: heading.kind.replace(/S$/, "") };
+                    current = parent;
+                }
+            }
+            else {
+                const object = {
+                    kind: heading.kind,
+                    id: heading.id ?? (token.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 (token.depth === 1) {
+                    artifacts.push({
+                        created: created.date ?? new Date(),
+                        modified: modified.date ?? new Date(),
+                        objects: [object]
+                    });
+                    stack.length = 0;
+                }
+                else {
+                    const parent = stack[token.depth - 2];
+                    if (parent === undefined) {
+                        ctx.diagnose(source.file, line, `heading level ${token.depth} without parent object`);
+                        line += (token.raw.match(/\n/g) ?? []).length;
+                        continue;
+                    }
+                    parent.childs.push(object);
+                }
+                stack.length = token.depth - 1;
+                stack[token.depth - 1] = object;
+                current = object;
+            }
+        }
+        else if (token.type === "list") {
+            const list = token;
+            if (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)
+                parseList(ctx, list, current, source.file, line);
+            else
+                parts.push(token.raw.trim());
+        }
+        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)
+                ctx.diagnose(source.file, line, "content outside of any object");
+            else
+                parts.push(token.raw.trim());
+        }
+        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 object of artifact.objects)
+            embed(ctx, object, source.file);
+    if (artifacts.length === 0)
+        ctx.diagnose(source.file, 1, "no artifact (level 1 heading) found");
+    return artifacts;
+};

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

@@ -0,0 +1,19 @@
+export type ValueExpr = {
+    kind: "regex";
+    regex: RegExp;
+    source: string;
+} | {
+    kind: "reference";
+    pattern: string;
+} | {
+    kind: "enum";
+    members: string[];
+} | {
+    kind: "tags";
+    members: string[];
+} | {
+    kind: "list";
+    alternatives: ValueExpr[];
+};
+export declare const compileValueExpr: (source: string) => ValueExpr;
+export declare const splitItems: (text: string) => string[];