@rse/specbook 0.9.7 → 0.9.9

package/README.md

@@ -44,7 +44,8 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
   The YAML schema configuration strictly defines the allowed object
   kinds, hierarchies, and properties, whose values are constrained by an
   expression language (regex, enum, tags, list, and reference). Violations
-  are reported as file- and line-precise diagnostics.
+  are reported as file- and line-precise diagnostics. A bundled standard
+  schema configuration applies if no particular one is given.
 
 - **Object Model Diagram Visualisation**:
   Object kinds can declare "graph", "hub", or "grid" diagrams in the
@@ -82,7 +83,9 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 Overview Poster
 ---------------
 
-[![poster](etc/poster.png)](etc/poster.pdf)
+[![poster-1](etc/poster-1.png)](etc/poster-1.pdf)
+
+[![poster-2](etc/poster-2.png)](etc/poster-2.pdf)
 
 Rendering Example
 -----------------
@@ -105,17 +108,18 @@ Usage
 ### CLI
 
 ```
-$ specbook init     [-v] -c <yaml-file> [-b <basedir>]
-$ specbook lint     [-v] -c <yaml-file> [-b <basedir>]
-$ specbook export   [-v] -c <yaml-file> [-b <basedir>] [-o [<format>:]<output-file>] [...]
+$ specbook init     [-v] [-c <yaml-file>] [-b <basedir>]
+$ specbook lint     [-v] [-c <yaml-file>] [-b <basedir>]
+$ specbook export   [-v] [-c <yaml-file>] [-b <basedir>] [-o [<format>:]<output-file>] [...]
 $ specbook describe [-v] [-c <yaml-file>] [-b <basedir>] [-e] [-o <markdown-file>]
 $ specbook mcp      [-v]
 ```
 
-The YAML schema configuration `-c`/`--config` is mandatory for `init`,
-`lint`, and `export`, as it determines the specification: exactly the
-artifact files its `file` fields reference are loaded and parsed, all
-other Markdown files below the base directory are ignored. A referenced
+The YAML schema configuration `-c`/`--config` (default: the bundled
+standard schema configuration `specbook-format.yaml`) determines the
+specification: exactly the artifact files its `file` fields reference
+are loaded and parsed, all other Markdown files below the base
+directory are ignored. A referenced
 file which is absent is reported, unless all of its artifacts are
 `optional`, and so is an artifact absent from its present file, unless
 it is `optional` itself. Both `lint` and `export` report all
@@ -132,6 +136,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
@@ -144,9 +153,7 @@ its own.
 The default value of every CLI option `--xxx` can be overridden by a
 corresponding `SPECBOOK_XXX` environment variable (e.g.
 `SPECBOOK_BASEDIR`, `SPECBOOK_CONFIG`, `SPECBOOK_OUTPUT`,
-`SPECBOOK_VERBOSE`), while an explicitly supplied option always wins. A
-`SPECBOOK_CONFIG` value also satisfies the otherwise mandatory
-`-c`/`--config` option.
+`SPECBOOK_VERBOSE`), while an explicitly supplied option always wins.
 
 ### API
 
@@ -157,7 +164,6 @@ const specbook = new SpecBook({
     verbose: (cmd, msg) => console.error(`specbook: ${cmd}: ${renderVerbose(msg)}`)
 })
 const result = await specbook.lint({
-    config:  "smp/ase.specbook.yaml",
     basedir: "smp/broadcast"
 })
 ```

package/dst/specbook-api.d.ts

@@ -9,6 +9,7 @@ export { type LintResult };
 export type { Spec, SpecArtifact, SpecObject, SpecDescription, SpecProperty } from "./specbook-format-spec.js";
 export type { Schema, SchemaObject, SchemaProperty } from "./specbook-format-schema.js";
 export declare const version: string;
+export declare const standardConfig: string;
 export type VerboseSink = (cmd: string, msg: string) => void;
 export interface SpecBookOptions {
     verbose?: VerboseSink;
@@ -17,18 +18,18 @@ export declare class SpecBook {
     private verbose;
     constructor(options?: SpecBookOptions);
     private verboseOf;
-    private requireConfigFile;
+    private configFile;
     private requireConfig;
     init(options: {
-        config: string;
+        config?: string;
         basedir?: string;
     }): Promise<string[]>;
     lint(options: {
-        config: string;
+        config?: string;
         basedir?: string;
     }): Promise<LintResult>;
     export(options: {
-        config: string;
+        config?: string;
         basedir?: string;
         formats?: ExportFormat[];
     }): Promise<Buffer[]>;

package/dst/specbook-api.js

@@ -4,6 +4,7 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import { loadConfig } from "./specbook-config.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
@@ -18,6 +19,10 @@ export { renderDiagnostic, renderDiagnosticVerbose };
 /*  our own version, taken from the package manifest, which resides one
     level above both the source and the compiled module directory  */
 export const version = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+/*  the bundled standard YAML schema configuration, which resides
+    alongside the compiled module and is used whenever no particular
+    schema configuration is given  */
+export const standardConfig = fileURLToPath(new URL("specbook-format.yaml", import.meta.url));
 /*  the SpecBook API  */
 export class SpecBook {
     verbose;
@@ -28,16 +33,15 @@ export class SpecBook {
     verboseOf(cmd) {
         return (msg) => this.verbose(cmd, msg);
     }
-    /*  require the file of the mandatory YAML schema configuration  */
-    requireConfigFile(file) {
-        if (file === undefined)
-            throw new Error("YAML schema configuration required");
-        return file;
+    /*  determine the file of the YAML schema configuration, falling
+        back onto the bundled standard schema configuration  */
+    configFile(file) {
+        return file ?? standardConfig;
     }
-    /*  load a mandatory YAML schema configuration, failing on any problem  */
+    /*  load a YAML schema configuration, failing on any problem  */
     requireConfig(file, verbose) {
-        file = this.requireConfigFile(file);
-        verbose(`loading configuration "${literal(file)}"`);
+        file = this.configFile(file);
+        verbose(`loading schema configuration "${literal(file)}"`);
         const { config, diagnostics } = loadConfig(file);
         if (config === undefined)
             throw new Error("invalid configuration:\n" +
@@ -53,7 +57,7 @@ export class SpecBook {
     }
     /*  lint the specification Markdown files below the base directory  */
     async lint(options) {
-        return lint({ config: this.requireConfigFile(options.config),
+        return lint({ config: this.configFile(options.config),
             basedir: options.basedir ?? ".", verbose: this.verboseOf("lint") });
     }
     /*  export the specification Markdown files below the base directory
@@ -63,7 +67,7 @@ export class SpecBook {
         as a partial or invalid specification must never be emitted)  */
     async export(options) {
         const verbose = this.verboseOf("export");
-        const result = lint({ config: this.requireConfigFile(options.config),
+        const result = lint({ config: this.configFile(options.config),
             basedir: options.basedir ?? ".", verbose });
         if (result.diagnostics.length > 0)
             throw new Error("invalid specification:\n" +

package/dst/specbook-cli.js

@@ -54,9 +54,10 @@ const envDefaultFlag = (name, fallback) => {
 const withVerboseOption = (command) => command
     .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false));
 /*  provide the common options of the specification processing sub-commands,
-    for which the YAML schema configuration is mandatory  */
+    for which the YAML schema configuration falls back onto the standard one  */
 const withCommonOptions = (command) => withVerboseOption(command)
-    .requiredOption("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"))
+    .option("-c, --config <yaml-file>", "YAML schema configuration file " +
+    "(default: the bundled standard schema configuration)", envDefault("config"))
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."));
 /*  parse the command line  */
 const program = new Command();

package/dst/specbook-cmd-describe.js

@@ -18,20 +18,17 @@ export const describeFormat = (options) => {
             "==============================\n");
         if (options.config !== undefined && options.embed === true)
             sections.push(textframe(`
-                The **SpecBook SCHEMA Model** of this particular project is the following
-                YAML schema configuration of the file \`${options.config}\`:
+                The **SpecBook SCHEMA Model** is the following YAML schema configuration:
             `) + "\n```yaml\n" +
                 fs.readFileSync(options.config, "utf8").replace(/\n*$/, "\n") +
                 "```\n");
         else if (options.config !== undefined)
             sections.push(textframe(`
-                The **SpecBook SCHEMA Model** of this particular project is the YAML
-                schema configuration in the file \`${options.config}\`.
+                The **SpecBook SCHEMA Model** is the YAML schema configuration in file \`${options.config}\`.
             `));
         if (options.basedir !== undefined)
             sections.push(textframe(`
-                The **SpecBook SPEC Model** of this particular project is the set of
-                specification Markdown files in the directory \`${options.basedir}\`.
+                The **SpecBook SPEC Model** is the set of Markdown specification files in directory \`${options.basedir}\`.
             `));
     }
     return sections.join("\n");

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-cmd-lint.js

@@ -25,7 +25,7 @@ const schemaFiles = (config) => {
 export const lint = (options) => {
     const diagnostics = new Array();
     /*  load the mandatory YAML schema configuration  */
-    options.verbose(`loading configuration "${literal(options.config)}"`);
+    options.verbose(`loading schema configuration "${literal(options.config)}"`);
     const loaded = loadConfig(options.config);
     diagnostics.push(...loaded.diagnostics);
     const config = loaded.config;

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

@@ -37,9 +37,9 @@ task:
 -   **SpecBook SCHEMA Model**:
     This is an object model, described in *YAML*, outside of
     **SpecBook**, which defines a particular **SpecBook** *Schema*.
-    It is user-supplied and non-generic but reusable and applied onto
-    the **SpecBook SPEC Model** to validate that it is domain-wise
-    well-structured.
+    It is user-supplied (or the bundled standard one) and non-generic
+    but reusable and applied onto the **SpecBook SPEC Model** to
+    validate that it is domain-wise well-structured.
 
 -   **SpecBook SPEC Model**:
     This is an object model, described in *Markdown*, outside
@@ -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`:
@@ -530,7 +531,9 @@ SpecBook SCHEMA Model
 ### Artifacts
 
 A schema consists of a YAML file, which is exactly a serialization of
-the object model defined by the **SpecBook SCHEMA Meta Model**.
+the object model defined by the **SpecBook SCHEMA Meta Model**. If no
+particular schema is given, the standard schema configuration bundled
+with **SpecBook** applies.
 
 SpecBook SPEC Model
 -------------------
@@ -557,6 +560,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 +653,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 +689,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 +706,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: