@rse/specbook 0.9.9 → 1.0.1

package/README.md

@@ -31,7 +31,7 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 - **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
+  ("complex" format) or compact bullet point lists ("concise" and
   "group" format).
 
 - **Wiki-Style Object Linking**:
@@ -52,7 +52,7 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
   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.
+  specialized in rendering object models.
 
 - **CLI, MCP, and API Interface**:
   All commands are implemented once in the API class `SpecBook`, on
@@ -80,45 +80,37 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
   It is intended as a polished, paginated offline document for handing
   over to customers.
 
-Overview Poster
----------------
+Overview
+--------
 
 [![poster-1](etc/poster-1.png)](etc/poster-1.pdf)
 
 [![poster-2](etc/poster-2.png)](etc/poster-2.pdf)
 
-Rendering Example
------------------
+Installation
+------------
 
-### HTML Rendering (Light Theme)
-
-![screenshot-light](etc/screenshot-light.png)
-
-### HTML Rendering (Dark Theme)
-
-![screenshot-dark](etc/screenshot-dark.png)
-
-### PDF Rendering
-
-![screenshot-print](etc/screenshot-print.png)
+```bash
+$ npm install -g @rse/specbook
+```
 
 Usage
 -----
 
 ### CLI
 
-```
+```bash
 $ 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 describe [-v] [-c <yaml-file>] [-b <basedir>] [-e] [-f <format>] [-p <part>] [-o <markdown-file>]
 $ specbook mcp      [-v]
 ```
 
 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
+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
@@ -142,13 +134,24 @@ 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
-Project Instantiation* section which points to these artifacts of the
-particular project. With `-e`/`--embed` the YAML schema configuration is
-embedded verbatim instead of just being referenced, so the resulting
-document describes the specification format of the project entirely on
-its own.
+and formats, extended by a *SpecBook Project Instantiation* section which
+points to the YAML schema configuration `-c`/`--config` and the base
+directory `-b`/`--basedir`. The schema configuration falls back onto the
+bundled standard one, embedded verbatim, as long as no particular
+configuration file `-c`/`--config` is given. With `-e`/`--embed` the
+given YAML schema configuration is embedded verbatim instead of just
+being referenced, so the resulting document describes the specification
+format entirely on its own.
+
+The `describe` document part `-p`/`--part` (default: `all`) reduces the
+output to a single part: `meta` for the description of the generic
+SpecBook models and formats, `schema` for the YAML schema configuration
+(the given one, referenced or embedded with `-e`/`--embed`, else the
+bundled standard one, embedded), or `spec` for the reference to
+the base directory. The output format `-f`/`--format` (default: `md`)
+switches from this rendered Markdown onto the raw original file content
+with `raw`, which is available for the file-backed parts `meta` and
+`schema` only.
 
 The default value of every CLI option `--xxx` can be overridden by a
 corresponding `SPECBOOK_XXX` environment variable (e.g.
@@ -173,6 +176,21 @@ const result = await specbook.lint({
 Run `specbook mcp` to serve the tools `specbook_init`, `specbook_lint`,
 `specbook_export`, and `specbook_describe` over stdio.
 
+Rendering Examples
+------------------
+
+### HTML Rendering (Light Theme)
+
+![screenshot-light](etc/screenshot-light.png)
+
+### HTML Rendering (Dark Theme)
+
+![screenshot-dark](etc/screenshot-dark.png)
+
+### PDF Rendering
+
+![screenshot-print](etc/screenshot-print.png)
+
 License
 -------
 

package/dst/specbook-api.d.ts

@@ -1,9 +1,12 @@
 import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic } from "./specbook-diagnostic.js";
 import { type LintResult } from "./specbook-cmd-lint.js";
 import { parseOutputSpec, formats, type ExportFormat } from "./specbook-cmd-export.js";
+import { describeFormats, describeParts, parseDescribeFormat, parseDescribePart, type DescribeFormat, type DescribePart } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose } from "./specbook-verbose.js";
 export { literal, renderVerbose };
 export { formats, parseOutputSpec, type ExportFormat };
+export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
+export { type DescribeFormat, type DescribePart };
 export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic };
 export { type LintResult };
 export type { Spec, SpecArtifact, SpecObject, SpecDescription, SpecProperty } from "./specbook-format-spec.js";
@@ -37,5 +40,7 @@ export declare class SpecBook {
         config?: string;
         basedir?: string;
         embed?: boolean;
+        format?: DescribeFormat;
+        part?: DescribePart;
     }): Promise<string>;
 }

package/dst/specbook-api.js

@@ -10,11 +10,12 @@ import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
 import { exportSpecification, parseOutputSpec, formats } from "./specbook-cmd-export.js";
-import { describeFormat } from "./specbook-cmd-describe.js";
+import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
 export { literal, renderVerbose };
 export { formats, parseOutputSpec };
+export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
 export { renderDiagnostic, renderDiagnosticVerbose };
 /*  our own version, taken from the package manifest, which resides one
     level above both the source and the compiled module directory  */
@@ -79,16 +80,27 @@ export class SpecBook {
             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,
-        whose YAML schema configuration is validated if given  */
+    /*  describe the generic SpecBook models and formats as Markdown (or
+        as the raw original file content), either entirely or reduced to
+        a single part, optionally pointing to the artifacts of the
+        particular project, whose YAML schema configuration is validated
+        before use  */
     async describe(options) {
         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);
+        const format = options.format ?? "md";
+        const part = options.part ?? "all";
+        /*  the schema-bearing parts require a schema configuration, so
+            they fall back onto the bundled standard one, which is always
+            embedded, as its bundled file is no meaningful reference  */
+        const standard = options.config === undefined
+            && (part === "all" || part === "schema" || options.embed === true);
+        const config = options.config ?? (standard ? standardConfig : undefined);
+        const embed = options.embed === true || standard;
+        const basedir = options.basedir ?? (part === "spec" ? "." : undefined);
+        if (config !== undefined)
+            this.requireConfig(config, verbose);
+        verbose(`describing the "${literal(part)}" part of the SpecBook models and formats ` +
+            `in the "${literal(format)}" format`);
+        return describeFormat({ ...options, config, basedir, embed, standard, format, part });
     }
 }

package/dst/specbook-cli.js

@@ -7,7 +7,7 @@
 import * as fs from "node:fs";
 import { Command } from "commander";
 import chalk from "chalk";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, 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, and qualify every message with
@@ -120,13 +120,17 @@ withCommonOptions(program.command("export"))
     formats alone, so its YAML schema configuration stays optional  */
 withVerboseOption(program.command("describe"))
     .description("describe the SpecBook models and formats as Markdown")
-    .option("-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, embedded verbatim)", envDefault("config"))
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir"))
-    .option("-e, --embed", "embed the YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
+    .option("-e, --embed", "embed the given YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
+    .option("-f, --format <format>", `output format (${describeFormats.join(", ")})`, envDefault("format", "md"))
+    .option("-p, --part <part>", `document part (${describeParts.join(", ")})`, envDefault("part", "all"))
     .option("-o, --output <markdown-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const text = await specbook.describe({ config: opts.config, basedir: opts.basedir, embed: opts.embed });
+    const text = await specbook.describe({ config: opts.config, basedir: opts.basedir,
+        embed: opts.embed, format: parseDescribeFormat(opts.format), part: parseDescribePart(opts.part) });
     await writeOutput(opts.output, text, "describe", verboseOf(opts));
 });
 /*  run the command line program  */

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

@@ -1,5 +1,14 @@
+export declare const describeFormats: readonly ["md", "raw"];
+export declare const describeParts: readonly ["all", "meta", "schema", "spec"];
+export type DescribeFormat = typeof describeFormats[number];
+export type DescribePart = typeof describeParts[number];
+export declare const parseDescribeFormat: (value: string) => DescribeFormat;
+export declare const parseDescribePart: (value: string) => DescribePart;
 export declare const describeFormat: (options: {
     config?: string;
     basedir?: string;
     embed?: boolean;
+    standard?: boolean;
+    format?: DescribeFormat;
+    part?: DescribePart;
 }) => string;

package/dst/specbook-cmd-describe.js

@@ -5,31 +5,94 @@
 */
 import * as fs from "node:fs";
 import textframe from "textframe";
+/*  the supported description output formats and document parts  */
+export const describeFormats = ["md", "raw"];
+export const describeParts = ["all", "meta", "schema", "spec"];
+/*  parse and validate an output format or document part specification  */
+const parseChoice = (choices, kind, value) => {
+    if (!choices.includes(value))
+        throw new Error(`unknown describe ${kind} "${value}" ` +
+            `(supported: ${choices.join(", ")})`);
+    return value;
+};
+export const parseDescribeFormat = (value) => parseChoice(describeFormats, "format", value);
+export const parseDescribePart = (value) => parseChoice(describeParts, "part", value);
 /*  provide the build-time bundled description of the generic
     SpecBook models and formats  */
 const description = () => fs.readFileSync(new URL("specbook-format.md", import.meta.url), "utf8");
+/*  render the reference to (or the embedding of) the YAML schema configuration,
+    where the bundled standard one is embedded without its leading comment block  */
+const schemaSection = (config, embed, standard) => {
+    if (!embed)
+        return textframe(`
+            The **SpecBook SCHEMA Model** is the YAML schema configuration in file:
+            @${config}
+        `);
+    let yaml = fs.readFileSync(config, "utf8");
+    if (standard)
+        yaml = yaml.replace(/^(?:[ \t]*##.*\n)+\s*/, "");
+    return textframe(`
+        The **SpecBook SCHEMA Model** is the following YAML schema configuration:
+    `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n\n";
+};
+/*  render the reference to the specification Markdown files  */
+const specSection = (basedir) => textframe(`
+        The **SpecBook SPEC Model** is the set of Markdown specification files in directory:
+        @${basedir}
+    `) + "\n";
 /*  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  */
+    artifacts of the particular project instantiation, and optionally
+    reduced to a single part or to the raw original file content, where
+    "standard" marks the configuration as the bundled standard one,
+    which still belongs to the generic description  */
 export const describeFormat = (options) => {
+    const format = options.format ?? "md";
+    const part = options.part ?? "all";
+    if (!describeFormats.includes(format))
+        throw new Error(`unknown describe format "${format}"`);
+    if (!describeParts.includes(part))
+        throw new Error(`unknown describe part "${part}"`);
+    /*  the raw format emits the original file content of a single part,
+        so it is available for the file-backed parts only  */
+    if (format === "raw") {
+        if (part === "all" || part === "spec")
+            throw new Error(`format "raw" is not available for part "${part}", ` +
+                "as this part is not backed by a single original file");
+        else if (part === "meta")
+            return description();
+        else if (options.config === undefined)
+            throw new Error("format \"raw\" for part \"schema\" requires a YAML schema configuration");
+        else
+            return fs.readFileSync(options.config, "utf8");
+    }
+    /*  the md format renders a single part standalone  */
+    if (part === "meta")
+        return description();
+    else if (part === "schema") {
+        if (options.config === undefined)
+            throw new Error("part \"schema\" requires a YAML schema configuration");
+        return schemaSection(options.config, options.embed === true, options.standard === true);
+    }
+    else if (part === "spec") {
+        if (options.basedir === undefined)
+            throw new Error("part \"spec\" requires a base directory");
+        return specSection(options.basedir);
+    }
+    /*  the md format renders all parts as a single coherent document,
+        where the schema configuration and the base directory are the
+        artifacts of the project instantiation and hence are always
+        placed under their own section  */
     const sections = [description()];
-    if (options.config !== undefined || options.basedir !== undefined) {
+    const schema = options.config !== undefined ?
+        schemaSection(options.config, options.embed === true, options.standard === true) : undefined;
+    if (schema !== undefined || options.basedir !== undefined) {
         sections.push("SpecBook Project Instantiation\n" +
             "==============================\n");
-        if (options.config !== undefined && options.embed === true)
-            sections.push(textframe(`
-                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** is the YAML schema configuration in file \`${options.config}\`.
-            `));
+        if (schema !== undefined)
+            sections.push(schema);
         if (options.basedir !== undefined)
-            sections.push(textframe(`
-                The **SpecBook SPEC Model** is the set of Markdown specification files in directory \`${options.basedir}\`.
-            `));
+            sections.push(specSection(options.basedir));
     }
     return sections.join("\n");
 };

package/dst/specbook-export-html.js

@@ -249,7 +249,7 @@ const inline = (text) => safe(marked.parseInline(linker !== null ? linker(text)
     constructs (lists, quotes, code blocks, tables) intact  */
 const block = (text) => safe(marked.parse(linker !== null ? linker(text) : text, { async: false }));
 /*  check whether a text carries any block-level Markdown, i.e. is
-    anything else than the single paragraph a description usually is  */
+    anything other than the single paragraph a description usually is  */
 const isBlock = (text) => {
     const tokens = marked.lexer(text).filter((token) => token.type !== "space");
     return tokens.length > 0 && !(tokens.length === 1 && tokens[0].type === "paragraph");

package/dst/specbook-export-md.js

@@ -66,7 +66,7 @@ const renderConciseMd = (object, depth = 0) => {
     level 4 upwards in the Concise Format -- unless a descendant carries
     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
+    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))}` +

package/dst/specbook-format.md

@@ -19,7 +19,7 @@ SpecBook Models and Formats
 ```
 
 **SpecBook** deals with four distinct object models and their particular
-format, each represented in a formal language and serving a particular
+formats, each represented in a formal language and serving a particular
 task:
 
 -   **SpecBook SCHEMA Meta Model**:

package/dst/specbook-mcp.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, formats, parseOutputSpec, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, formats, parseOutputSpec, describeFormats, describeParts, version } from "./specbook-api.js";
 /*  render an error with its cause chain into a tool error result  */
 const errorResult = (err) => {
     let msg = err instanceof Error ? err.message : String(err);
@@ -105,14 +105,23 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_describe", {
         title: "Describe Specification Format",
-        description: "Describe the SpecBook models and formats as a Markdown document. If the YAML " +
-            "schema configuration or the base directory is given, the description additionally points " +
-            "to the artifacts of that particular project.",
+        description: "Describe the SpecBook models and formats as a Markdown document, which embeds the " +
+            "bundled standard YAML schema configuration as long as no particular one is given. If the " +
+            "YAML schema configuration or the base directory is given, the description additionally " +
+            "points to the artifacts of that particular project. The description can be reduced to a " +
+            "single part and emitted as the raw original file content instead of Markdown.",
         inputSchema: {
-            config: z.string().optional().describe("YAML schema configuration file"),
+            config: z.string().optional().describe("YAML schema configuration file " +
+                "(default: the bundled standard schema configuration, embedded verbatim)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files"),
-            embed: z.boolean().optional().describe("embed the YAML schema configuration instead of " +
-                "just referencing it (default: false)"),
+            embed: z.boolean().optional().describe("embed the given YAML schema configuration instead " +
+                "of just referencing it (default: false; the bundled standard one is always embedded)"),
+            format: z.enum(describeFormats).optional().describe("output format: \"md\" for Markdown or " +
+                "\"raw\" for the raw original file content of the part (default: \"md\")"),
+            part: z.enum(describeParts).optional().describe("document part: \"all\" for the entire " +
+                "description, \"meta\" for the generic models and formats, \"schema\" for the YAML schema " +
+                "configuration, or \"spec\" for the specification files (default: \"all\"; \"raw\" is " +
+                "available for \"meta\" and \"schema\" only)"),
             output: z.string().optional().describe("output file path (\"-\" or omitted returns the description directly)")
         }
     }, async (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "0.9.9",
+    "version":                             "1.0.1",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",