@rse/specbook 0.9.2 → 0.9.4

package/README.md

@@ -33,18 +33,46 @@ service with tools `specbook_<cmd>()`.
 Specification Format
 --------------------
 
-A specification consists of Markdown *artifact* files, each carrying a
-frontmatter with `Created:` and `Modified:` timestamps and a tree of
-*objects*. Every object has a mandatory *kind*, a mandatory *name*, an
-optional unique anchor *id*, optional *properties* (key/value pairs),
-an optional *description* statement with an optional rationale, and
-optional *child* objects.
+### Artifact Files
+
+A specification consists of Markdown *artifact* files, which are
+scanned recursively from a base directory. Every file has to start with
+a frontmatter block carrying the `Created:` and `Modified:` timestamps
+(format `yyyy-LL-dd HH:mm`):
+
+```
+---
+Created:  2026-06-18 10:18
+Modified: 2026-06-18 10:18
+---
+```
+
+Every level 1 heading opens a new *artifact*, so usually each file
+carries exactly one. Both ATX headings (`# <text/>`, `## <text/>`, ...)
+and Setext headings (`<text/>` underlined with `===` or `---`) are
+supported.
+
+### Object Model
+
+An artifact carries a tree of *objects*. Every object has a mandatory
+*kind* (e.g. `ENTITY`), a mandatory *name*, a unique anchor *id*
+(explicitly given or derived from the name), an optional *primary*
+marker, optional *properties* (key/value pairs), an optional
+*description* statement with an optional rationale, and optional *child*
+objects. Which kinds, properties, and nestings are allowed is defined by
+the schema configuration (see below); object kinds and property keys are
+case-sensitive and have to be written exactly as configured. Backquotes
+in names and property values are preserved as code markup for rendering,
+but are ignored when matching names, references, and constraints.
 
 Three concrete syntaxes exist:
 
 ### Complex Format
 
-Usually used on object hierarchy levels 1-3 (`#`, `##`, `###`).
+Usually used on object hierarchy levels 1-3 (`#`, `##`, `###`). A
+heading opens the object, an optional unordered list carries its
+properties, and the remaining content up to the next heading is its
+description:
 
 ```
 #   <kind/>: <name/> (<id/>)
@@ -55,16 +83,38 @@ Usually used on object hierarchy levels 1-3 (`#`, `##`, `###`).
 <statement/>, BECAUSE <rationale/>.
 ```
 
+The heading level directly reflects the nesting level: a `##` object
+becomes a child of the preceding `#` object, a `###` object a child of
+the preceding `##` object, etc. Skipping a level (a heading without a
+parent object on the level above) is an error.
+
 ### Concise Format
 
-Usually used on level 4 and deeper, with child objects nested as
-indented list items below their parent item:
+Usually used on level 4 and deeper. A single unordered list item carries
+the entire object as `;`-separated segments -- the `<kind/>: <name/>`
+head, the `<key/>: <value/>` properties, and the trailing description --
+and may wrap over multiple (indented) lines:
 
 ```
 -   <kind/>: <name/>; <key/>: <value/>; [...];
     <statement/>, BECAUSE <rationale/>.
 ```
 
+A list item is recognized as a Concise Format object (instead of a
+property of the enclosing object) by carrying at least one `;` on its
+first line. Every segment of the form `<key/>: <value/>` becomes a
+property (unless it contains a ` BECAUSE `), all remaining segments are
+joined into the description. Child objects nest as indented list items
+below their parent item, where key/value items become properties and
+concise items become child objects of that parent:
+
+```
+-   <kind/>: <name/>; <key/>: <value/>;
+    <statement/>, BECAUSE <rationale/>.
+    -   <kind/>: <name/>; <key/>: <value/>;
+        <statement/>, BECAUSE <rationale/>.
+```
+
 ### Grouped Format
 
 A heading carrying just a *kind* and no `<kind/>: <name/>` pair opens a
@@ -81,13 +131,126 @@ with the (optionally backquoted) name directly:
 
 The heading kind is singularized by stripping one trailing `S`, so both
 `### STATES` and `### STATE` group objects of kind `STATE`. The grouped
-objects become childs of the object the heading is nested under.
+objects become children of the object the heading is nested under. An
+unquoted name must not contain a `:` (else 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. When **SpecBook** edits existing files, it mirrors the format
 each existing object already uses.
 
+### Names, Anchors, and Ids
+
+In all formats, the `<name/>` may carry trailing decorations, in any
+order:
+
+-   `{{<id/>}}`: the explicit Wiki-style anchor, setting the object id
+    (e.g. `## ENTITY: Attendee Browser {{attendee}}`).
+
+-   `(*)`: the *primary* marker, flagging the object as primary (e.g.
+    the primary attributes of an entity).
+
+-   `(<token/>)`: a parenthesized token with three possible roles: on
+    level 1 it becomes the artifact id (e.g. `# SPEC: Data Model (DM)`);
+    on deeper levels it is either accepted as the value of a still
+    missing configured property whose constraint it matches (e.g.
+    `### SCENARIO: Successful Token Login (Main)` satisfying an
+    `enum(Main,Alternative,Exceptional)` property), or else acts as the
+    implicit anchor id.
+
+-   `<a id="<id/>"></a>`: an HTML anchor at the very end of a heading,
+    as an alternative to `{{<id/>}}` (emitted by **SpecBook** itself
+    when exporting normalized Markdown).
+
+When no explicit id is given, the id is derived by slugifying the name
+(lowercased, with non-alphanumeric character runs dashed). An explicit
+`{{<id/>}}` anchor always takes precedence over a `(<token/>)` id. When
+the schema configures a fixed `id` for an object, it has to be
+explicitly written in the input, via either `{{<id/>}}` or `(<id/>)`.
+
+### Properties
+
+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 property key may carry
+a trailing parenthesized annotation (e.g. `WHEN (Context)`), which is
+kept for rendering but ignored when matching the key against the schema.
+
+A multi-token convenience exists for pattern-constrained properties:
+when a property value fails its (regex or enum) constraint as a whole,
+but consists of multiple whitespace-separated tokens of which one
+matches the property's own constraint, that token is kept as the value
+and the remaining tokens are distributed (case-insensitively) across the
+other still unset pattern-constrained properties of the object. Tokens
+assignable to no property are reported as errors.
+
+### Descriptions and Rationales
+
+The description of a Complex Format object is all block content below
+its heading (up to the next heading) except the property list:
+paragraphs, blockquotes, ordered lists (e.g. scenario steps), and
+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.
+
+A description is split into its *statement* and *rationale* at the first
+`, BECAUSE ` (or `, **BECAUSE** `) occurrence:
+
+```
+The event is created and configured but not visible to attendees,
+BECAUSE an event needs a private setup phase.
+```
+
+### Wiki-Style References
+
+A `[[<reference/>]]` anywhere in a name, property value, description, or
+rationale is a Wiki-style reference to another object, which is checked
+for unique resolvability and rendered as a hyperlink in the HTML/PDF
+exports. A reference is a `.`-separated path of segments, where each
+segment matches a single object as:
+
+-   `<id/>`: the object id or explicit anchor (e.g. `[[attendee]]`)
+-   `<name/>`: the object name (e.g. `[[Attendee Browser]]`)
+-   `<kind/>:<name-or-id/>`: kind-qualified (e.g. `[[ENTITY:Event]]`)
+-   `<kind/>:*` or `*`: wildcards (for match sets, see below)
+
+Each part can be double-quoted to allow spaces, dots, and colons inside
+it (e.g. `[["Vue.js"]]`, whose dot would otherwise be taken as a path
+separator). A multi-segment path matches object chains connected by
+direct parent-to-child steps, where the leading segments up to the root
+may be omitted (e.g. `[[FV.relay]]` matches the object `relay` directly
+below the artifact with id `FV`).
+
+A reference has to resolve to exactly one object: a single-segment
+reference tries the variants (1) id/anchor, (2) name, and (3)
+`<kind/>:<name-or-id/>` in order, where the first variant yielding any
+matches decides; several matches are an ambiguity and zero matches an
+unresolvable reference, both reported by the linter. Wildcard references
+resolve into match *sets* and are used in the schema configuration to
+constrain reference-valued properties (e.g. `[[PERSONA:*]]` or
+`[[DM.ENTITY:*]]`).
+
+### Image Embeddings
+
+A Markdown image `![<alt/>](<file/>)` inside a description or property
+value embeds a local image file, resolved relative to the artifact file:
+SVG files are inlined as-is; PNG/JPEG files are embedded as base64
+`data:` URLs. URLs and other file types are left untouched.
+
+### Normalization
+
+The semantic phase validates the parsed objects against the schema
+configuration (unknown kinds and properties, missing required properties
+and child kinds, and violated value constraints are reported with
+file/line-precise diagnostics) and then normalizes the specification:
+artifacts, child objects, and properties are stably reordered along the
+schema definition, so the exports always present them in their
+configured canonical order.
+
 Schema Configuration
 --------------------
 
@@ -110,8 +273,11 @@ object itself plus all objects below it), `center` names the object a
 `hub` is projected onto (default: `self`), `onlyConnected` drops the
 edge-less nodes of a `graph`, `collapse` (default: `true`) omits a
 degenerated diagram consisting of a single node only, `qualified` labels
-every node with its object kind, and `config` passes arbitrary Gradia
-rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
+every node with its object kind, `properties` lists the property names
+whose values are attached to the nodes as key/value annotations (with
+every `[[xxx]]` reference stripped to its target object name), and
+`config` passes arbitrary Gradia rendering options (e.g.
+`grid-columns-max: 5`) through to the diagram.
 
 The edges are derived from the `[[xxx]]` references of the node objects
 -- from their property values only, or, with `links: all`, from their
@@ -119,7 +285,7 @@ descriptions as well. As the *nesting* of the objects carries no such
 reference, `hierarchy: true` additionally derives a containment edge
 from every node object to each of its child objects which is part of the
 node set. This is what turns a parent object into the hub of its own
-childs, as the `TIER` objects of the sample schema configuration
+children, as the `TIER` objects of the sample schema configuration
 demonstrate:
 
 ```yaml
@@ -133,6 +299,22 @@ demonstrate:
 A `grid` is edge-less by definition and hence accepts neither `edges`
 nor `hierarchy`.
 
+An object kind can furthermore carry a `format` field, which controls
+how the HTML/PDF export renders the child objects of every object of
+that kind. Its `type` selects the rendering: `complex` (nested
+sections), `concise` (compact per-kind tables), or the default `auto`,
+which collapses only the deepest level into tables. Below a `concise`
+object, unconfigured children implicitly stay `concise` and render as
+sub-tables inside the description cells, while an explicitly configured
+`type` is always honored, even a `complex` rendering pressed into a
+cell. `maxTableColumns` (default: `4`) bounds the columns of the compact
+tables below the object (wider groups chunk their properties into
+embedded per-object tables), and `withUnusedProps` (default: `false`)
+unconditionally renders the defined but unused properties of that kind,
+as empty property table lines or table columns. Objects collapsed into
+tables carry no headings and hence leave the table of contents and the
+PDF outline.
+
 Usage
 -----
 
@@ -142,7 +324,6 @@ Usage
 $ 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>] [...]
-                    [--max-table-columns <count>]
 $ specbook describe [-v] [-c <yaml-file>] [-o <markdown-file>]
 $ specbook import   [-v] [-c <yaml-file>] [-b <basedir>] <input-files...>
 $ specbook edit     [-v] [-c <yaml-file>] [-b <basedir>] <query>

package/dst/specbook-api.d.ts

@@ -6,6 +6,7 @@ export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic };
 export { type LintResult };
 export type { Specification, Artifact, Object, Description, Property } from "./specbook-struct-spec.js";
 export type { SchemaSpecification, SchemaObject, SchemaProperty } from "./specbook-struct-schema.js";
+export declare const version: string;
 export interface SpecBookOptions {
     verbose?: (msg: string) => void;
 }
@@ -25,7 +26,6 @@ export declare class SpecBook {
         config?: string;
         basedir?: string;
         formats?: ExportFormat[];
-        maxTableColumns?: number;
     }): Promise<Buffer[]>;
     describe(options: {
         config?: string;

package/dst/specbook-api.js

@@ -3,6 +3,9 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import * as fs from "node:fs";
+import * as path from "node:path";
+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";
@@ -14,6 +17,12 @@ import { editSpecification } from "./specbook-cmd-edit.js";
 /*  re-export the central types for API consumers  */
 export { formats, parseOutputSpec };
 export { renderDiagnostic, renderDiagnosticVerbose };
+/*  the own version, taken from the package manifest, which resides one
+    level above both the source and the compiled module directory  */
+export const version = (() => {
+    const manifest = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    return JSON.parse(fs.readFileSync(manifest, "utf8")).version;
+})();
 /*  the SpecBook API  */
 export class SpecBook {
     verbose;
@@ -53,9 +62,9 @@ export class SpecBook {
         if (result.specification.artifacts.length === 0)
             throw new Error("unexportable specification:\n" +
                 result.diagnostics.map(renderDiagnostic).join("\n"));
-        const buffers = [];
+        const buffers = new Array();
         for (const format of options.formats ?? ["json"])
-            buffers.push(await exportSpecification(result.specification, format, this.verbose, options.maxTableColumns, result.config));
+            buffers.push(await exportSpecification(result.specification, format, this.verbose, result.config));
         return buffers;
     }
     /*  describe the configured specification format as Markdown  */

package/dst/specbook-cli.js

@@ -6,7 +6,7 @@
 */
 import * as fs from "node:fs";
 import { Command } from "commander";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, parseOutputSpec } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, parseOutputSpec, version } from "./specbook-api.js";
 import { serveMcp } from "./specbook-mcp.js";
 /*  route verbose messages to stderr, keeping stdout reserved
     for the command outputs and the MCP protocol  */
@@ -33,7 +33,7 @@ const writeOutput = async (output, data, verbose) => {
         await writeStdout(data);
     else {
         await fs.promises.writeFile(output, data);
-        verbose(`wrote "${output}" (${data.length} bytes)`);
+        verbose(`wrote "${output}" (${Buffer.byteLength(data)} bytes)`);
     }
 };
 /*  determine an option default value, overridable via a
@@ -46,14 +46,14 @@ const envDefaultFlag = (name, fallback) => {
     return value !== undefined ? !(/^(?:|0|false|no|off)$/i).test(value) : fallback;
 };
 /*  provide the common options of all sub-commands  */
-const common = (command) => command
+const withCommonOptions = (command) => command
     .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false))
     .option("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"));
 /*  parse the command line  */
 const program = new Command();
 program.name("specbook")
     .description("Markdown-based Specification Format")
-    .version("0.9.0")
+    .version(version)
     .action(() => {
     program.help();
 });
@@ -64,24 +64,24 @@ program.command("mcp")
     verboseOf(opts)("starting MCP server on stdio");
     await serveMcp(verboseOf(opts));
 });
-common(program.command("init"))
+withCommonOptions(program.command("init"))
     .description("initialize the configured specification artifact files below the base directory")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const created = await specbook.init({ config: opts.config, basedir: opts.basedir });
-    process.stdout.write(created.length > 0 ?
+    await writeStdout(created.length > 0 ?
         `initialized artifact file(s): ${created.join(", ")}\n` :
         "no artifact files were created\n");
 });
-common(program.command("lint"))
+withCommonOptions(program.command("lint"))
     .description("lint the specification Markdown files below the base directory")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const result = await specbook.lint({ config: opts.config, basedir: opts.basedir });
     for (const diagnostic of result.diagnostics)
-        process.stdout.write(opts.verbose ?
+        await writeStdout(opts.verbose ?
             renderDiagnosticVerbose(diagnostic, process.stdout.isTTY === true) :
             `${renderDiagnostic(diagnostic)}\n`);
     if (result.diagnostics.length > 0)
@@ -89,13 +89,12 @@ common(program.command("lint"))
     else
         verboseOf(opts)("specification valid");
 });
-common(program.command("export"))
+withCommonOptions(program.command("export"))
     .description("export the specification Markdown files below the base directory " +
     "as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .option("-o, --output [<format>:]<output-file>", "output file (\"-\" for stdout, repeatable), with the format inferred " +
     "from the filename extension unless explicitly prefixed", (value, previous) => previous.concat(value), [])
-    .option("--max-table-columns <count>", "maximum name/property/description columns for the compact table rendering", (value) => parseInt(value, 10), parseInt(envDefault("max-table-columns", "4") ?? "4", 10))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const outputs = (opts.output.length > 0 ? opts.output : [envDefault("output") ?? "-"])
@@ -103,11 +102,11 @@ common(program.command("export"))
     /*  parse the input once and export each distinct format once  */
     const distinct = Array.from(new Set(outputs.map(({ format }) => format)));
     const buffers = await specbook.export({ config: opts.config, basedir: opts.basedir,
-        formats: distinct, maxTableColumns: opts.maxTableColumns });
+        formats: distinct });
     for (const { format, output } of outputs)
         await writeOutput(output, buffers[distinct.indexOf(format)], verboseOf(opts));
 });
-common(program.command("describe"))
+withCommonOptions(program.command("describe"))
     .description("describe the configured specification format as Markdown")
     .option("-o, --output <markdown-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
     .action(async (opts) => {
@@ -115,7 +114,7 @@ common(program.command("describe"))
     const text = await specbook.describe({ config: opts.config });
     await writeOutput(opts.output, text, verboseOf(opts));
 });
-common(program.command("import"))
+withCommonOptions(program.command("import"))
     .description("import foreign sources into the specification artifact files below the base directory")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
@@ -125,11 +124,11 @@ common(program.command("import"))
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const written = await specbook.import({ config: opts.config, basedir: opts.basedir,
         inputs, provider: opts.provider, model: opts.model });
-    process.stdout.write(written.length > 0 ?
+    await writeStdout(written.length > 0 ?
         `imported into artifact file(s): ${written.join(", ")}\n` :
         "no artifact files were changed\n");
 });
-common(program.command("edit"))
+withCommonOptions(program.command("edit"))
     .description("apply a free-text edit request to the specification artifact files below the base directory")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
@@ -139,7 +138,7 @@ common(program.command("edit"))
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const written = await specbook.edit({ config: opts.config, basedir: opts.basedir,
         query, provider: opts.provider, model: opts.model });
-    process.stdout.write(written.length > 0 ?
+    await writeStdout(written.length > 0 ?
         `edited artifact file(s): ${written.join(", ")}\n` :
         "no artifact files were changed\n");
 });

package/dst/specbook-cmd-describe.js

@@ -84,11 +84,13 @@ export const describeConfiguration = (config) => {
     const sections = new Array();
     for (const artifact of config) {
         const lines = new Array();
-        lines.push(`### ${artifact.kind}: ${artifact.name} (${artifact.kind}-${artifact.id})`);
+        lines.push(`### ${artifact.kind}: ${artifact.name ?? ""} (${artifact.kind}-${artifact.id ?? ""})`);
         lines.push("");
         if (artifact.file !== undefined)
             lines.push(`-   file: \`${artifact.file}\``);
         lines.push(`-   description: ${collapse(artifact.desc)}`);
+        for (const prop of artifact.props ?? [])
+            lines.push(describeProperty(prop, ""));
         for (const child of artifact.childs ?? [])
             lines.push(describeObject(child, 2, ""));
         sections.push(lines.join("\n"));

package/dst/specbook-cmd-edit.js

@@ -42,6 +42,9 @@ const instruction = (description, now) => textframe `
 export const editSpecification = async (options) => {
     const basedir = options.basedir ?? ".";
     const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
+    /*  ensure a non-empty edit request was given  */
+    if (options.query.trim() === "")
+        throw new Error("no edit request given");
     /*  gather the existing artifact files  */
     const existing = files
         .filter((file) => fs.existsSync(path.join(basedir, file)))
@@ -61,7 +64,9 @@ export const editSpecification = async (options) => {
             options.verbose(`ignoring unconfigured file "${block.name}"`);
             continue;
         }
-        fs.writeFileSync(path.join(basedir, block.name), block.content, "utf8");
+        const file = path.join(basedir, block.name);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, block.content, "utf8");
         options.verbose(`wrote artifact file "${block.name}"`);
         written.push(block.name);
     }

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

@@ -6,4 +6,4 @@ export declare const parseOutputSpec: (spec: string) => {
     format: ExportFormat;
     output: string;
 };
-export declare const exportSpecification: (specification: Specification, format: ExportFormat, verbose: (msg: string) => void, maxTableColumns?: number, config?: SchemaSpecification) => Promise<Buffer>;
+export declare const exportSpecification: (specification: Specification, format: ExportFormat, verbose: (msg: string) => void, config?: SchemaSpecification) => Promise<Buffer>;

package/dst/specbook-cmd-export.js

@@ -32,13 +32,14 @@ export const parseOutputSpec = (spec) => {
     if (spec === "-")
         return { format: "json", output: spec };
     const ext = spec.match(/\.([a-zA-Z0-9]+)$/);
-    if (ext !== null && extensions[ext[1].toLowerCase()] !== undefined)
-        return { format: extensions[ext[1].toLowerCase()], output: spec };
+    const format = ext !== null ? extensions[ext[1].toLowerCase()] : undefined;
+    if (format !== undefined)
+        return { format, output: spec };
     throw new Error(`unable to infer export format from output "${spec}" ` +
         "(use an explicit \"<format>:<filename>\" specification)");
 };
 /*  export a specification into the requested format  */
-export const exportSpecification = async (specification, format, verbose, maxTableColumns = 4, config) => {
+export const exportSpecification = async (specification, format, verbose, config) => {
     if (!formats.includes(format))
         throw new Error(`unknown export format "${format}"`);
     verbose(`exporting specification as "${format}"`);
@@ -62,7 +63,7 @@ export const exportSpecification = async (specification, format, verbose, maxTab
     const css = themeStylesheet(colors) + await subsetStylesheet(charset) + paperStylesheet(paper);
     if (format === "html") {
         /*  compress the rendered HTML (whitespace, comments, and inline CSS/JS)  */
-        const html = await renderHtml(specification, maxTableColumns, config, undefined, css);
+        const html = await renderHtml(specification, config, undefined, css);
         const minified = await minify(Buffer.from(html, "utf8"), {
             collapseWhitespaces: "smart",
             removeComments: true,
@@ -74,5 +75,5 @@ export const exportSpecification = async (specification, format, verbose, maxTab
     else
         /*  the PDF export (like print in general) always uses the light
             theme, so its decoration colors are the light mapping, too  */
-        return htmlToPdf((tocPages) => renderHtml(specification, maxTableColumns, config, tocPages, css), { ...documentTitle(specification), logo: documentLogo(specification) }, htmlOutline(specification, maxTableColumns), verbose, css, themeMapping(colors, "light"), paper);
+        return htmlToPdf((tocPages) => renderHtml(specification, config, tocPages, css), { ...documentTitle(specification), logo: documentLogo(specification) }, htmlOutline(specification, config), verbose, css, themeMapping(colors, "light"), paper);
 };

package/dst/specbook-cmd-import.js

@@ -46,6 +46,9 @@ const instruction = (description, now) => textframe `
 export const importSpecification = async (options) => {
     const basedir = options.basedir ?? ".";
     const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
+    /*  ensure at least one foreign source was given  */
+    if (options.inputs.length === 0)
+        throw new Error("no foreign sources given to import");
     /*  gather the existing artifact files and the foreign sources  */
     const existing = files
         .filter((file) => fs.existsSync(path.join(basedir, file)))
@@ -65,7 +68,9 @@ export const importSpecification = async (options) => {
             options.verbose(`ignoring unconfigured file "${block.name}"`);
             continue;
         }
-        fs.writeFileSync(path.join(basedir, block.name), block.content, "utf8");
+        const file = path.join(basedir, block.name);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, block.content, "utf8");
         options.verbose(`wrote artifact file "${block.name}"`);
         written.push(block.name);
     }

package/dst/specbook-cmd-init.js

@@ -21,14 +21,16 @@ export const initSpecification = (options) => {
             options.verbose(`skipping existing artifact file "${artifact.file}"`);
             continue;
         }
-        const name = (artifact.name ?? "").toUpperCase();
+        const name = artifact.name ?? "";
+        const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
         const text = "---\n" +
             `Created:  ${now}\n` +
             `Modified: ${now}\n` +
             "---\n" +
             "\n" +
-            `#   ${artifact.kind}: ${name} (${artifact.kind}-${artifact.id})\n` +
+            `#   ${artifact.kind}: ${name}${paren}\n` +
             "\n";
+        fs.mkdirSync(path.dirname(file), { recursive: true });
         fs.writeFileSync(file, text, "utf8");
         options.verbose(`created artifact file "${artifact.file}"`);
         created.push(artifact.file);

package/dst/specbook-cmd-lint.js

@@ -25,11 +25,13 @@ export const lint = (options) => {
         config = loaded.config ?? undefined;
     }
     /*  parse and validate the specification Markdown files  */
-    const files = scanMarkdown(options.basedir);
+    const exists = fs.existsSync(options.basedir) && fs.statSync(options.basedir).isDirectory();
+    const files = exists ? scanMarkdown(options.basedir) : [];
     options.verbose(`parsing ${files.length} specification file(s) below "${options.basedir}"`);
     if (files.length === 0)
         diagnostics.push({ file: options.basedir, line: 1, column: 1,
-            message: "no Markdown files found below base directory" });
+            message: exists ? "no Markdown files found below base directory" :
+                "base directory does not exist" });
     const sources = new Array();
     for (const file of files) {
         try {

package/dst/specbook-config.js

@@ -24,7 +24,17 @@ const lineColOfPath = (yaml, cst, path) => {
 /*  load and validate a YAML schema configuration file  */
 export const loadConfig = (file) => {
     const diagnostics = [];
-    const yaml = fs.readFileSync(file, "utf8");
+    /*  read the configuration file  */
+    let yaml;
+    try {
+        yaml = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        diagnostics.push({ file, line: 1, column: 1,
+            message: "cannot read configuration file: " +
+                (err instanceof Error ? err.message : String(err)) });
+        return { config: null, diagnostics };
+    }
     /*  syntactically parse the YAML content  */
     let obj;
     try {
@@ -37,17 +47,22 @@ export const loadConfig = (file) => {
             line: e?.linePos?.[0]?.line ?? 1,
             column: e?.linePos?.[0]?.col ?? 1,
             message: "invalid YAML syntax: " +
-                (err instanceof Error ? err.message.replace(/:(?:.|\r?\n)*$/, "") : String(err))
+                (err instanceof Error ? err.message.replace(/:[\s\S]*$/, "") : String(err))
         });
         return { config: null, diagnostics };
     }
-    /*  semantically validate against the schema of the configuration  */
-    const cst = parseDocument(yaml);
+    /*  semantically validate against the schema of the configuration
+        (the CST is parsed lazily, as it is needed for positions only)  */
+    let cst;
+    const posOfPath = (path) => {
+        cst ??= parseDocument(yaml);
+        return lineColOfPath(yaml, cst, path);
+    };
     const result = v.safeParse(SchemaSpecification, obj);
     if (!result.success) {
         for (const issue of result.issues) {
             const path = (issue.path ?? []).map((item) => item.key);
-            const pos = lineColOfPath(yaml, cst, path);
+            const pos = posOfPath(path);
             diagnostics.push({ file, line: pos.line, column: pos.column,
                 message: `invalid configuration: ${path.join(".")}: ${issue.message}` });
         }
@@ -57,7 +72,7 @@ export const loadConfig = (file) => {
     const checkFileField = (objects, path, depth) => {
         objects.forEach((object, i) => {
             if (depth > 1 && object.file !== undefined) {
-                const pos = lineColOfPath(yaml, cst, [...path, i, "file"]);
+                const pos = posOfPath([...path, i, "file"]);
                 diagnostics.push({ file, line: pos.line, column: pos.column,
                     message: `"file" field is only allowed on the first (artifact) level (found on level ${depth})` });
             }
@@ -76,7 +91,7 @@ export const loadConfig = (file) => {
                     compileValueExpr(prop.value);
                 }
                 catch (err) {
-                    const pos = lineColOfPath(yaml, cst, [...path, i, "props", j, "value"]);
+                    const pos = posOfPath([...path, i, "props", j, "value"]);
                     diagnostics.push({ file, line: pos.line, column: pos.column,
                         message: `invalid value expression "${prop.value}": ` +
                             (err instanceof Error ? err.message : String(err)) });