@rse/specbook 0.9.6 → 0.9.8

package/README.md

@@ -22,15 +22,62 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 
 **SpecBook** provides the following distinct features:
 
-- Hierarchical Object Model
-- Versatile Object to Markdown Mapping
-- Wiki-Style Object Linking
-- Strict Validation with Custom Schema
-- Object Model Diagram Visualisation
-- CLI, MCP, and API Interface
-- AST Exports for AI/LLMs
-- HTML Export for Developers
-- PDF Export for Customers
+- **Hierarchical Object Model**:
+  A specification is a tree of typed objects, each with a kind and
+  name, an optional id, optional properties, optional description, and
+  optional child objects. The allowed object hierarchy is defined per
+  context by the YAML schema configuration.
+
+- **Versatile Object to Markdown Mapping**:
+  Objects are authored as plain Markdown headings, property lists,
+  and description prose. The objects can be mapped to nested sections
+  ("complex" format) or a compact bullet point lists ("concise" and
+  "group" format).
+
+- **Wiki-Style Object Linking**:
+  Objects can hierarchically reference each other through Wiki-style
+  `[[xxx]]` references, which are resolved against the locally-unique
+  ids and names of all objects. In the HTML and PDF exports they become
+  navigable links onto precise anchors.
+
+- **Strict Validation with Custom Schema**:
+  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.
+
+- **Object Model Diagram Visualisation**:
+  Object kinds can declare "graph", "hub", or "grid" diagrams in the
+  schema, whose nodes and edges are automatically derived from the
+  object model and its references. The diagrams are rendered with the
+  sibling project [Gradia](https://github.com/rse/gradia), which is
+  specialized on rendering object models.
+
+- **CLI, MCP, and API Interface**:
+  All commands are implemented once in the API class `SpecBook`, on
+  which both the CLI and the MCP service are just thin wrappers.
+  This way, humans, scripts, and AI agents use exactly the same
+  functionality.
+
+- **AST Exports for AI/LLMs**:
+  The parsed specification Abstract Syntax Tree (AST) can be exported in
+  JSON, JSON5, YAML, or TOON format for machine consumption. Together
+  with the `describe` command, which explains the models and formats,
+  this enables LLMs to both read and write specifications.
+
+- **HTML Export for Developers**:
+  The HTML export is a self-contained single document with a
+  table-of-contents, full-text search, embedded images, and a light/dark
+  theme toggle. It is intended for the day-to-day online reading during
+  development. The HTML export can map all object kinds to nested
+  sections or compact tables, or an automatic mixture which collapses
+  only the deepest level into tables.
+
+- **PDF Export for Customers**:
+  The PDF export prints the HTML rendering via Chromium and post-processes
+  it with page numbers, headers/footers, and a hierarchical PDF outline.
+  It is intended as a polished, paginated offline document for handing
+  over to customers.
 
 Overview Poster
 ---------------
@@ -70,7 +117,10 @@ The YAML schema configuration `-c`/`--config` is mandatory for `init`,
 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`.
+`optional`, and so is an artifact absent from its present file, unless
+it is `optional` itself. Both `lint` and `export` report all
+diagnostics and fail on any of them, so a partial or invalid
+specification is never exported.
 
 The base directory `-b`/`--basedir` (default: `.`) is the directory the
 referenced artifact files are resolved against, and generated
@@ -82,6 +132,11 @@ occur multiple times. The format (`json`, `json5`, `yaml`, `toon`,
 it is explicitly given as a `<format>:` prefix, and plain `-` (stdout)
 defaults to JSON.
 
+The `md` format normalizes the entire corpus into a *single* Markdown
+document, whose single frontmatter block carries the earliest `Created:`
+and the latest `Modified:` timestamp of all artifacts, so the
+per-artifact timestamps do not survive this round-trip.
+
 The `describe` command outputs the description of the SpecBook models
 and formats. If the configuration file `-c`/`--config` or the base
 directory `-b`/`--basedir` is given, it additionally appends a *SpecBook

package/dst/specbook-api.js

@@ -4,8 +4,6 @@
 **  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";
@@ -17,12 +15,9 @@ import { literal, renderVerbose } from "./specbook-verbose.js";
 export { literal, renderVerbose };
 export { formats, parseOutputSpec };
 export { renderDiagnostic, renderDiagnosticVerbose };
-/*  the own version, taken from the package manifest, which resides one
+/*  our 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;
-})();
+export const version = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 /*  the SpecBook API  */
 export class SpecBook {
     verbose;
@@ -44,7 +39,7 @@ export class SpecBook {
         file = this.requireConfigFile(file);
         verbose(`loading configuration "${literal(file)}"`);
         const { config, diagnostics } = loadConfig(file);
-        if (config === null)
+        if (config === undefined)
             throw new Error("invalid configuration:\n" +
                 diagnostics.map(renderDiagnostic).join("\n"));
         return config;
@@ -53,8 +48,8 @@ export class SpecBook {
         below the base directory  */
     async init(options) {
         const verbose = this.verboseOf("init");
-        return initSpecification({ ...options,
-            config: this.requireConfig(options.config, verbose), verbose });
+        return initSpecification({ config: this.requireConfig(options.config, verbose),
+            basedir: options.basedir ?? ".", verbose });
     }
     /*  lint the specification Markdown files below the base directory  */
     async lint(options) {
@@ -64,26 +59,32 @@ export class SpecBook {
     /*  export the specification Markdown files below the base directory
         as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown,
         parsing the input just once and returning one buffer per
-        requested format (best-effort: diagnostics do not prevent the
-        export, as validation is the concern of lint)  */
+        requested format (strict: any diagnostic prevents the export,
+        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),
             basedir: options.basedir ?? ".", verbose });
-        for (const diagnostic of result.diagnostics)
-            verbose(`diagnostic: ${renderDiagnostic(diagnostic)}`);
-        if (result.specification.artifacts.length === 0)
-            throw new Error("unexportable specification:\n" +
+        if (result.diagnostics.length > 0)
+            throw new Error("invalid specification:\n" +
                 result.diagnostics.map(renderDiagnostic).join("\n"));
+        if (result.specification.artifacts.length === 0)
+            throw new Error("unexportable specification: no artifacts found");
         const buffers = new Array();
         for (const format of options.formats ?? ["json"])
             buffers.push(await exportSpecification(result.specification, format, verbose, result.config));
         return buffers;
     }
     /*  describe the generic SpecBook models and formats as Markdown,
-        optionally pointing to the artifacts of the particular project  */
+        optionally pointing to the artifacts of the particular project,
+        whose YAML schema configuration is validated if given  */
     async describe(options) {
-        this.verboseOf("describe")("describing the SpecBook models and formats");
+        const verbose = this.verboseOf("describe");
+        if (options.config !== undefined)
+            this.requireConfig(options.config, verbose);
+        else if (options.embed === true)
+            throw new Error("YAML schema configuration required for embedding");
+        verbose("describing the SpecBook models and formats");
         return describeFormat(options);
     }
 }

package/dst/specbook-cli.js

@@ -56,7 +56,8 @@ const withVerboseOption = (command) => command
 /*  provide the common options of the specification processing sub-commands,
     for which the YAML schema configuration is mandatory  */
 const withCommonOptions = (command) => withVerboseOption(command)
-    .requiredOption("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"));
+    .requiredOption("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"))
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."));
 /*  parse the command line  */
 const program = new Command();
 program.name("specbook")
@@ -65,15 +66,16 @@ program.name("specbook")
     .action(() => {
     program.help();
 });
+/*  the mcp command runs all other commands as MCP tools over stdio  */
 withVerboseOption(program.command("mcp"))
     .description("run as MCP stdio server")
     .action(async (opts) => {
     verboseOf(opts)("mcp", "starting MCP server on stdio");
     await serveMcp(verboseOf(opts, "mcp"));
 });
+/*  the init command creates the configured artifact files  */
 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 });
@@ -81,9 +83,9 @@ withCommonOptions(program.command("init"))
         `initialized artifact file(s): ${created.join(", ")}\n` :
         "no artifact files were created\n");
 });
+/*  the lint command reports all diagnostics and fails on any of them  */
 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 });
@@ -96,16 +98,16 @@ withCommonOptions(program.command("lint"))
     else
         verboseOf(opts)("lint", "specification valid");
 });
+/*  the export command parses the input once and writes every output  */
 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), [])
+    "from the filename extension unless explicitly prefixed", (value, previous) => previous.concat(value), new Array())
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const outputs = (opts.output.length > 0 ? opts.output : [envDefault("output") ?? "-"])
-        .map((spec) => parseOutputSpec(spec));
+        .map(parseOutputSpec);
     /*  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,
@@ -126,6 +128,7 @@ withVerboseOption(program.command("describe"))
     const text = await specbook.describe({ config: opts.config, basedir: opts.basedir, embed: opts.embed });
     await writeOutput(opts.output, text, "describe", verboseOf(opts));
 });
+/*  run the command line program  */
 try {
     await program.parseAsync();
 }

package/dst/specbook-cmd-describe.js

@@ -4,12 +4,10 @@
 **  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 textframe from "textframe";
 /*  provide the build-time bundled description of the generic
     SpecBook models and formats  */
-const description = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-format.md"), "utf8");
+const description = () => fs.readFileSync(new URL("specbook-format.md", import.meta.url), "utf8");
 /*  describe the generic SpecBook models and formats as Markdown,
     optionally extended by the references to (or the embeddings of) the
     artifacts of the particular project instantiation  */

package/dst/specbook-cmd-export.js

@@ -4,7 +4,7 @@
 **  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 { documentTitle, documentLogo, documentCharset, documentThemeTone, subsetStylesheet, documentPaperSize, paperStylesheet, charsetCodepoints } 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";
@@ -13,27 +13,34 @@ import { htmlToPdf } from "./specbook-export-pdf.js";
 import { literal } from "./specbook-verbose.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"
-};
+/*  the format names and filename extensions mapping onto the export formats  */
+const extensions = new Map([
+    ["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] };
+    /*  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)
+            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 };
     const ext = spec.match(/\.([a-zA-Z0-9]+)$/);
-    const format = ext !== null ? extensions[ext[1].toLowerCase()] : undefined;
+    const format = ext !== null ? extensions.get(ext[1].toLowerCase()) : undefined;
     if (format !== undefined)
         return { format, output: spec };
     throw new Error(`unable to infer export format from output "${spec}" ` +
@@ -47,11 +54,11 @@ export const exportSpecification = async (specification, format, verbose, config
     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");
+        return Buffer.from(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)
+    if (charset !== undefined && charsetCodepoints(charset) !== undefined)
         verbose(`subsetting embedded fonts to charset "${literal(charset)}"`);
     /*  the theme tone (THEME-TONE) drives the layer-1 color spread
         variables and the PDF decoration colors  */

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

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

package/dst/specbook-cmd-init.js

@@ -18,8 +18,7 @@ const timestamp = () => {
     all artifacts configured onto the same file reside in it side by
     side, following each other on level 1  */
 export const initSpecification = (options) => {
-    const basedir = options.basedir ?? ".";
-    fs.mkdirSync(basedir, { recursive: true });
+    fs.mkdirSync(options.basedir, { recursive: true });
     const now = timestamp();
     const created = new Array();
     /*  group the configured artifacts by their file, preserving the
@@ -34,8 +33,10 @@ export const initSpecification = (options) => {
         else
             group.push(artifact);
     }
+    /*  create each absent artifact file with its frontmatter and
+        the level 1 headings of its artifacts  */
     for (const [file, artifacts] of groups) {
-        const target = path.join(basedir, file);
+        const target = path.join(options.basedir, file);
         if (fs.existsSync(target)) {
             options.verbose(`skipping existing artifact file "${literal(file)}"`);
             continue;
@@ -43,7 +44,7 @@ export const initSpecification = (options) => {
         const headings = artifacts.map((artifact) => {
             const name = artifact.name ?? "";
             const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
-            return `#   ${artifact.kind}: ${name}${paren}\n` + "\n";
+            return `#   ${artifact.kind}: ${name}${paren}\n\n`;
         }).join("");
         const text = "---\n" +
             `Created:  ${now}\n` +

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

@@ -11,5 +11,4 @@ export interface LintResult {
     diagnostics: Diagnostic[];
     config?: Schema;
 }
-export declare const schemaFiles: (config: Schema) => Map<string, boolean>;
 export declare const lint: (options: LintOptions) => LintResult;

package/dst/specbook-cmd-lint.js

@@ -7,11 +7,11 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadConfig } from "./specbook-config.js";
 import { literal } from "./specbook-verbose.js";
-import { parseSpecification } from "./specbook-parse.js";
+import { parseSpecification, resolveArtifact } from "./specbook-parse.js";
 /*  collect the distinct artifact files the schema configuration
     references, in their declaration order, each mapped onto whether
     all of its artifacts are optional and hence the file may be absent  */
-export const schemaFiles = (config) => {
+const schemaFiles = (config) => {
     const files = new Map();
     for (const artifact of config) {
         if (artifact.file === undefined)
@@ -28,17 +28,16 @@ export const lint = (options) => {
     options.verbose(`loading configuration "${literal(options.config)}"`);
     const loaded = loadConfig(options.config);
     diagnostics.push(...loaded.diagnostics);
-    const config = loaded.config ?? undefined;
+    const config = loaded.config;
     /*  read the artifact files the configuration references, resolved
         against the base directory and tolerating an absent file if all
         its artifacts are optional  */
     const files = config !== undefined ? schemaFiles(config) : new Map();
-    options.verbose(`parsing ${literal(files.size)} specification file(s) ` +
-        `below "${literal(options.basedir)}"`);
     if (config !== undefined && files.size === 0)
         diagnostics.push({ file: options.config, line: 1, column: 1,
             message: "no artifact files configured" });
     const sources = new Array();
+    const present = new Set();
     for (const [name, optional] of files) {
         const file = path.join(options.basedir, name);
         if (!fs.existsSync(file)) {
@@ -49,13 +48,38 @@ export const lint = (options) => {
         }
         try {
             sources.push({ file, text: fs.readFileSync(file, "utf8") });
+            present.add(name);
         }
         catch (err) {
             diagnostics.push({ file, line: 1, column: 1,
                 message: `unreadable file: ${err instanceof Error ? err.message : String(err)}` });
         }
     }
+    /*  parse and validate the artifact files against the configuration  */
+    options.verbose(`parsing ${literal(sources.length)} specification file(s) ` +
+        `below "${literal(options.basedir)}"`);
     const result = parseSpecification(sources, config);
     diagnostics.push(...result.diagnostics);
+    /*  report the non-optional artifacts absent from the specification,
+        against their loaded artifact file (an absent or unreadable file
+        is already reported above) or else against the configuration  */
+    if (config !== undefined) {
+        const found = new Set();
+        for (const artifact of result.specification.artifacts)
+            for (const object of artifact.objects) {
+                const schema = resolveArtifact(config, object);
+                if (schema !== undefined)
+                    found.add(schema);
+            }
+        for (const schema of config) {
+            if (schema.optional === true || found.has(schema)
+                || (schema.file !== undefined && !present.has(schema.file)))
+                continue;
+            const file = schema.file !== undefined ? path.join(options.basedir, schema.file) : options.config;
+            const paren = schema.id !== undefined ? ` (${schema.id})` : "";
+            diagnostics.push({ file, line: 1, column: 1,
+                message: `missing artifact "${schema.kind}: ${schema.name ?? ""}${paren}"` });
+        }
+    }
     return { specification: result.specification, diagnostics, config };
 };

package/dst/specbook-config.d.ts

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