@rse/specbook 0.9.8 → 1.0.0

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

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

package/dst/specbook-api.js

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

package/dst/specbook-cli.js

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

package/dst/specbook-cmd-describe.js

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

package/dst/specbook-cmd-lint.js

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

package/dst/specbook-format.md

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