@rse/specbook 0.9.2

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

@@ -0,0 +1,9 @@
+import type { Specification } from "./specbook-struct-spec.js";
+import type { SchemaSpecification } from "./specbook-struct-schema.js";
+export declare const formats: readonly ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
+export type ExportFormat = typeof formats[number];
+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>;

package/dst/specbook-cmd-export.js

@@ -0,0 +1,78 @@
+/*
+**  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 { minify } from "@swc/html";
+import { documentTitle, documentLogo, documentCharset, documentThemeTone, subsetStylesheet, documentPaperSize, paperStylesheet } from "./specbook-export-common.js";
+import { themeColors, themeStylesheet, themeMapping } from "./specbook-theme.js";
+import { renderAst } from "./specbook-export-ast.js";
+import { renderMarkdown } from "./specbook-export-md.js";
+import { renderHtml, htmlOutline } from "./specbook-export-html.js";
+import { htmlToPdf } from "./specbook-export-pdf.js";
+/*  the supported export formats  */
+export const formats = ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
+/*  the filename extensions mapping onto the export formats  */
+const extensions = {
+    json: "json",
+    json5: "json5",
+    yaml: "yaml", yml: "yaml",
+    toon: "toon",
+    html: "html", htm: "html",
+    pdf: "pdf",
+    md: "md", markdown: "md"
+};
+/*  parse an output specification "[<format>:]<filename>", inferring the
+    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]+):(.+)$/);
+    if (prefixed !== null && formats.includes(prefixed[1]))
+        return { format: prefixed[1], output: prefixed[2] };
+    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 };
+    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) => {
+    if (!formats.includes(format))
+        throw new Error(`unknown export format "${format}"`);
+    verbose(`exporting specification as "${format}"`);
+    if (format === "json" || format === "json5" || format === "yaml" || format === "toon")
+        return renderAst(specification, format, config);
+    else if (format === "md")
+        return Buffer.from(await renderMarkdown(specification, config), "utf8");
+    /*  the HTML-based formats share the stylesheet, with the embedded
+        fonts subsetted to the CHARSET of the specification (if any)  */
+    const charset = documentCharset(specification);
+    if (charset !== undefined)
+        verbose(`subsetting embedded fonts to charset "${charset}"`);
+    /*  the theme tone (THEME-TONE) drives the layer-1 color spread
+        variables and the PDF decoration colors  */
+    const tone = documentThemeTone(specification) ?? "#336699";
+    verbose(`generating theme color spreads (tone "${tone}")`);
+    const colors = themeColors(tone);
+    /*  the paper size (PAPER-SIZE) drives the PDF page setup and the
+        print-time height constraint of the diagrams  */
+    const paper = documentPaperSize(specification);
+    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 minified = await minify(Buffer.from(html, "utf8"), {
+            collapseWhitespaces: "smart",
+            removeComments: true,
+            minifyCss: true,
+            minifyJs: true
+        });
+        return Buffer.from(minified.code, "utf8");
+    }
+    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);
+};

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

@@ -0,0 +1,9 @@
+import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { type AiOptions } from "./specbook-llm.js";
+export interface ImportOptions extends AiOptions {
+    config: SchemaSpecification;
+    basedir?: string;
+    inputs: string[];
+    verbose: (msg: string) => void;
+}
+export declare const importSpecification: (options: ImportOptions) => Promise<string[]>;

package/dst/specbook-cmd-import.js

@@ -0,0 +1,73 @@
+/*
+**  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 * as fs from "node:fs";
+import * as path from "node:path";
+import textframe from "textframe";
+import { describeConfiguration } from "./specbook-cmd-describe.js";
+import { complete, timestamp, renderFileBlock, parseFileBlocks } from "./specbook-llm.js";
+/*  the LLM instruction for the import command  */
+const instruction = (description, now) => textframe `
+    You are the import engine of SpecBook, a Markdown-based specification
+    format. Import the information of the given foreign sources into the
+    Markdown specification artifact files of the project, generating or
+    updating the artifact files so they faithfully reflect the imported
+    information. Strictly honor the following rules:
+
+    -   Faithful reflection: the artifacts must reflect the imported
+        sources exactly -- no more, no less.
+    -   No fabrication: never invent content the sources do not support;
+        leave gaps open instead of guessing.
+    -   Surgical updates: when updating an existing artifact, change only
+        what the imported information actually requires.
+    -   Level-appropriate translation: re-express the imported facts at the
+        artifact's level of abstraction; do not copy verbatim.
+    -   Format conformance: strictly follow the specification format
+        described below.
+    -   Markdown generation: emit the Complex Format on levels 1-3
+        ("#"/"##"/"###") and the Concise Format on level 4 and deeper.
+    -   Timestamps: use "${now}" for the "Created:" and "Modified:"
+        frontmatter of generated files, and refresh "Modified:" to
+        "${now}" on updated files.
+    -   Files: generate or update ONLY the configured artifact files listed
+        in the format description below -- never any other file.
+    -   Output: return ONLY the generated or updated files, each as a block
+        of the exact form below, and no other text at all:
+
+        <<<FILE: <name>>>>
+        <content>
+        <<<END-FILE>>>
+
+    ${description}
+`;
+/*  import foreign sources into the specification artifact files  */
+export const importSpecification = async (options) => {
+    const basedir = options.basedir ?? ".";
+    const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
+    /*  gather the existing artifact files and the foreign sources  */
+    const existing = files
+        .filter((file) => fs.existsSync(path.join(basedir, file)))
+        .map((file) => renderFileBlock(file, fs.readFileSync(path.join(basedir, file), "utf8")));
+    const sources = options.inputs
+        .map((input) => renderFileBlock(input, fs.readFileSync(input, "utf8")));
+    /*  let the LLM generate or update the artifact files  */
+    options.verbose(`importing ${options.inputs.length} foreign source(s) into "${basedir}"`);
+    const system = instruction(describeConfiguration(options.config), timestamp());
+    const prompt = "EXISTING ARTIFACT FILES:\n\n" + (existing.length > 0 ? existing.join("\n\n") : "(none)") +
+        "\n\nFOREIGN SOURCES TO IMPORT:\n\n" + sources.join("\n\n");
+    const response = await complete(options, system, prompt);
+    /*  write back all returned artifact files  */
+    const written = new Array();
+    for (const block of parseFileBlocks(response)) {
+        if (!files.includes(block.name)) {
+            options.verbose(`ignoring unconfigured file "${block.name}"`);
+            continue;
+        }
+        fs.writeFileSync(path.join(basedir, block.name), block.content, "utf8");
+        options.verbose(`wrote artifact file "${block.name}"`);
+        written.push(block.name);
+    }
+    return written;
+};

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

@@ -0,0 +1,7 @@
+import { type SchemaSpecification } from "./specbook-struct-schema.js";
+export interface InitOptions {
+    config: SchemaSpecification;
+    basedir?: string;
+    verbose: (msg: string) => void;
+}
+export declare const initSpecification: (options: InitOptions) => string[];

package/dst/specbook-cmd-init.js

@@ -0,0 +1,37 @@
+/*
+**  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 * as fs from "node:fs";
+import * as path from "node:path";
+import { timestamp } from "./specbook-llm.js";
+/*  initialize the configured specification artifact files below the
+    base directory with their frontmatter and artifact heading  */
+export const initSpecification = (options) => {
+    const basedir = options.basedir ?? ".";
+    fs.mkdirSync(basedir, { recursive: true });
+    const now = timestamp();
+    const created = new Array();
+    for (const artifact of options.config) {
+        if (artifact.file === undefined)
+            continue;
+        const file = path.join(basedir, artifact.file);
+        if (fs.existsSync(file)) {
+            options.verbose(`skipping existing artifact file "${artifact.file}"`);
+            continue;
+        }
+        const name = (artifact.name ?? "").toUpperCase();
+        const text = "---\n" +
+            `Created:  ${now}\n` +
+            `Modified: ${now}\n` +
+            "---\n" +
+            "\n" +
+            `#   ${artifact.kind}: ${name} (${artifact.kind}-${artifact.id})\n` +
+            "\n";
+        fs.writeFileSync(file, text, "utf8");
+        options.verbose(`created artifact file "${artifact.file}"`);
+        created.push(artifact.file);
+    }
+    return created;
+};

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

@@ -0,0 +1,15 @@
+import { type Diagnostic } from "./specbook-diagnostic.js";
+import { type Specification } from "./specbook-struct-spec.js";
+import { type SchemaSpecification } from "./specbook-struct-schema.js";
+export interface LintOptions {
+    config?: string;
+    basedir: string;
+    verbose: (msg: string) => void;
+}
+export interface LintResult {
+    specification: Specification;
+    diagnostics: Diagnostic[];
+    config?: SchemaSpecification;
+}
+export declare const scanMarkdown: (basedir: string) => string[];
+export declare const lint: (options: LintOptions) => LintResult;

package/dst/specbook-cmd-lint.js

@@ -0,0 +1,46 @@
+/*
+**  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 * as fs from "node:fs";
+import * as path from "node:path";
+import { loadConfig } from "./specbook-config.js";
+import { parseSpecification } from "./specbook-parse.js";
+/*  recursively scan a base directory for Markdown files  */
+export const scanMarkdown = (basedir) => fs.readdirSync(basedir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => path.join(entry.parentPath, entry.name))
+    .sort();
+/*  lint the specification Markdown files below the base directory
+    against the optional configuration  */
+export const lint = (options) => {
+    const diagnostics = new Array();
+    /*  load the optional YAML schema configuration  */
+    let config;
+    if (options.config !== undefined) {
+        options.verbose(`loading configuration "${options.config}"`);
+        const loaded = loadConfig(options.config);
+        diagnostics.push(...loaded.diagnostics);
+        config = loaded.config ?? undefined;
+    }
+    /*  parse and validate the specification Markdown files  */
+    const files = 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" });
+    const sources = new Array();
+    for (const file of files) {
+        try {
+            sources.push({ file, text: fs.readFileSync(file, "utf8") });
+        }
+        catch (err) {
+            diagnostics.push({ file, line: 1, column: 1,
+                message: `unreadable file: ${err instanceof Error ? err.message : String(err)}` });
+        }
+    }
+    const result = parseSpecification(sources, config);
+    diagnostics.push(...result.diagnostics);
+    return { specification: result.specification, diagnostics, config };
+};

package/dst/specbook-config.d.ts

@@ -0,0 +1,6 @@
+import { SchemaSpecification } from "./specbook-struct-schema.js";
+import { type Diagnostic } from "./specbook-diagnostic.js";
+export declare const loadConfig: (file: string) => {
+    config: SchemaSpecification | null;
+    diagnostics: Diagnostic[];
+};

package/dst/specbook-config.js

@@ -0,0 +1,91 @@
+/*
+**  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 * as fs from "node:fs";
+import { parse as parseYaml, parseDocument, YAMLParseError } from "yaml";
+import * as v from "valibot";
+import { SchemaSpecification } from "./specbook-struct-schema.js";
+import { compileValueExpr } from "./specbook-parse-value.js";
+/*  determine line/column of a YAML document path via the CST  */
+const lineColOfPath = (yaml, cst, path) => {
+    for (let i = path.length; i >= 0; i--) {
+        const node = cst.getIn(path.slice(0, i), true);
+        if (typeof node === "object" && node !== null
+            && "range" in node && Array.isArray(node.range)) {
+            const start = node.range[0];
+            const lines = yaml.slice(0, start).split("\n");
+            return { line: lines.length, column: lines[lines.length - 1].length + 1 };
+        }
+    }
+    return { line: 1, column: 1 };
+};
+/*  load and validate a YAML schema configuration file  */
+export const loadConfig = (file) => {
+    const diagnostics = [];
+    const yaml = fs.readFileSync(file, "utf8");
+    /*  syntactically parse the YAML content  */
+    let obj;
+    try {
+        obj = parseYaml(yaml);
+    }
+    catch (err) {
+        const e = err instanceof YAMLParseError ? err : null;
+        diagnostics.push({
+            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))
+        });
+        return { config: null, diagnostics };
+    }
+    /*  semantically validate against the schema of the configuration  */
+    const cst = parseDocument(yaml);
+    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);
+            diagnostics.push({ file, line: pos.line, column: pos.column,
+                message: `invalid configuration: ${path.join(".")}: ${issue.message}` });
+        }
+        return { config: null, diagnostics };
+    }
+    /*  reject "file" fields below the first (artifact) level  */
+    const checkFileField = (objects, path, depth) => {
+        objects.forEach((object, i) => {
+            if (depth > 1 && object.file !== undefined) {
+                const pos = lineColOfPath(yaml, cst, [...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})` });
+            }
+            if (object.childs !== undefined)
+                checkFileField(object.childs, [...path, i, "childs"], depth + 1);
+        });
+    };
+    checkFileField(result.output, [], 1);
+    /*  reject syntactically invalid property value expressions  */
+    const checkValueExpr = (objects, path) => {
+        objects.forEach((object, i) => {
+            (object.props ?? []).forEach((prop, j) => {
+                if (prop.value === undefined)
+                    return;
+                try {
+                    compileValueExpr(prop.value);
+                }
+                catch (err) {
+                    const pos = lineColOfPath(yaml, cst, [...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)) });
+                }
+            });
+            if (object.childs !== undefined)
+                checkValueExpr(object.childs, [...path, i, "childs"]);
+        });
+    };
+    checkValueExpr(result.output, []);
+    return { config: diagnostics.length === 0 ? result.output : null, diagnostics };
+};

package/dst/specbook-diagnostic.d.ts

@@ -0,0 +1,8 @@
+export interface Diagnostic {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+}
+export declare const renderDiagnostic: (diagnostic: Diagnostic) => string;
+export declare const renderDiagnosticVerbose: (diagnostic: Diagnostic, colors?: boolean) => string;

package/dst/specbook-diagnostic.js

@@ -0,0 +1,23 @@
+/*
+**  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 * as fs from "node:fs";
+import sourceCodeError from "source-code-error";
+/*  render a diagnostic as a standard single-line message  */
+export const renderDiagnostic = (diagnostic) => `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}: ${diagnostic.message}`;
+/*  render a diagnostic as a multi-line message with the affected
+    source snippet, falling back to the single-line message when the
+    source file is unreadable (e.g. the file is a directory)  */
+export const renderDiagnosticVerbose = (diagnostic, colors = false) => {
+    let code;
+    try {
+        code = fs.readFileSync(diagnostic.file, "utf8");
+    }
+    catch {
+        return `${renderDiagnostic(diagnostic)}\n`;
+    }
+    return sourceCodeError({ message: diagnostic.message, filename: diagnostic.file,
+        code, line: diagnostic.line, column: diagnostic.column, colors });
+};

package/dst/specbook-diagram.d.ts

@@ -0,0 +1,9 @@
+import type { Specification, Object as SpecObject } from "./specbook-struct-spec.js";
+import type { SchemaSpecification } from "./specbook-struct-schema.js";
+import { type ParseContext } from "./specbook-parse-common.js";
+export interface DiagramResult {
+    spec?: string;
+    errors: string[];
+}
+export declare const specDiagrams: (specification: Specification, config: SchemaSpecification) => Map<SpecObject, DiagramResult>;
+export declare const validateDiagrams: (ctx: ParseContext, specification: Specification, config: SchemaSpecification) => void;