@rse/specbook 1.0.3 → 1.1.0

package/README.md

@@ -13,8 +13,8 @@ About
 format* which can be configured for the specifications of particular
 contexts through a YAML-based *schema configuration*. SpecBook allows
 specifications to be *initialized*, *linted*, *exported* (JSON, JSON5,
-YAML, TOON, HTML, PDF, and normalized Markdown), and *described* to
-LLMs.
+YAML, TOON, HTML, PDF, and normalized Markdown), *previewed* (HTML, live
+in the browser), and *described* to LLMs.
 
 **SpecBook** ships with an API class with methods `<xxx>()`, a
 CLI with commands `specbook <xxx>`, and an MCP service with tools
@@ -44,8 +44,9 @@ 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. A bundled standard
-    schema configuration applies if no particular one is given.
+    are reported as file- and line-precise diagnostics, while the reference
+    coverage an object kind demands is reported as a warning only. 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
@@ -68,7 +69,8 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 
 -   **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
+    table-of-contents (also as a slide-in side panel for quick navigation),
+    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
@@ -107,31 +109,55 @@ export class SpecBook {
     /*  initialize the configured specification artifact files below the
         base directory and return the list of the generated files  */
     init (options: {
-        config?:  string,          /*  YAML schema configuration (default: bundled standard one)  */
+        config?:  string[],        /*  YAML schema configuration files or glob patterns, merged
+                                       in order (default: bundled standard one, named "std")  */
         basedir?: string           /*  base directory (default: ".")  */
     }): Promise<string[]>
 
     /*  parse and validate the specification Markdown files below the base directory  */
     lint (options: {
-        config?:  string,
+        config?:  string[],
         basedir?: string
     }): Promise<LintResult>
 
     /*  export the specification, parsing the input just once and
-        returning one buffer per requested format (strict: any diagnostic
-        rejects the export with an "Error")  */
+        returning one buffer per requested format (strict: any error
+        diagnostic rejects the export with an "Error", while the warnings
+        are surfaced as "notice" verbose messages)  */
     export (options: {
-        config?:  string,
+        config?:  string[],
         basedir?: string,
-        formats?: ExportFormat[]   /*  requested output formats (default: [ "json" ])  */
+        formats?: ExportFormat[],  /*  requested output formats (default: [ "json" ])  */
+        realtime?: boolean         /*  inject the live preview script into the HTML  */
     }): Promise<Buffer[]>
 
+    /*  export the specification like "export" and then keep it in sync by
+        re-exporting it on every change of a specification file (a failed
+        re-export is reported and leaves the observe loop intact)  */
+    watch (options: {
+        config?:  string[],
+        basedir?: string,
+        formats?: ExportFormat[],
+        realtime?: boolean,
+        onExport: (buffers: Buffer[]) => void | Promise<void>
+    }): Promise<void>
+
+    /*  serve the HTML export as a live preview on "http://<addr>:<port>/",
+        kept in sync like "watch" and updated in the browser on every change  */
+    preview (options: {
+        config?:  string[],
+        basedir?: string,
+        addr?:    string,          /*  listening IP address (default: "127.0.0.1")  */
+        port?:    number           /*  listening TCP port (default: 12345)  */
+    }): Promise<void>
+
     /*  describe the SpecBook models and formats, optionally pointing to
         the artifacts of the particular project  */
     describe (options: {
-        config?:  string,
+        config?:  string[],
         basedir?: string,
         embed?:   boolean,         /*  embed the schema configuration instead of referencing it  */
+        compress?: CompressLevel,  /*  compression level of the schema configuration (default: 1)  */
         format?:  DescribeFormat,  /*  output format (default: "md")  */
         part?:    DescribePart     /*  document part (default: "all")  */
     }): Promise<string>
@@ -149,21 +175,25 @@ export interface LintResult {
     specification: Spec
     diagnostics:   Diagnostic[]
     config?:       Schema
+    files:         string[]    /*  the artifact files plus their embedded assets  */
 }
 export interface Diagnostic {
     file:          string
     line:          number
     column:        number
+    severity:      "error" | "warning"
     message:       string
 }
 
-/*  the supported export formats and describe formats/parts  */
+/*  the supported export formats and describe formats/parts/compression levels  */
 export const formats:         readonly [ "json", "json5", "yaml", "toon", "html", "pdf", "md" ]
 export const describeFormats: readonly [ "md", "raw" ]
 export const describeParts:   readonly [ "all", "meta", "schema", "spec" ]
+export const compressLevels:  readonly [ 0, 1, 2, 3 ]
 export type  ExportFormat   = typeof formats[number]
 export type  DescribeFormat = typeof describeFormats[number]
 export type  DescribePart   = typeof describeParts[number]
+export type  CompressLevel  = typeof compressLevels[number]
 
 /*  the Abstract Syntax Tree (AST) of a parsed specification  */
 export type Spec = {
@@ -251,13 +281,23 @@ $ specbook export \
   [-v|--verbose] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
-  [-o|--output [<format>:]<output-file>] [...]
+  [-o|--output [<format>:]<output-file>] \
+  [-w|--watch] \
+  [...]
+
+$ specbook preview \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-a|--addr <ip-addr>] \
+  [-p|--port <tcp-port>]
 
 $ specbook describe \
   [-v|--verbose] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
   [-e|--embed] \
+  [-z|--compress [<level>]] \
   [-f|--format <format>] \
   [-p|--part <part>] \
   [-o|--output <output-file>]
@@ -279,8 +319,22 @@ Options:
     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 diagnostics and fail on any of them, so a partial or invalid
-    specification is never exported.
+    all diagnostics and fail on any error among them (a warning, like a
+    lapse of the reference coverage a `referenced` object kind demands,
+    is reported only), so a partial or invalid specification is never
+    exported.
+    The option accepts glob patterns and can be given multiple times: the
+    matching files (in the order of the patterns and alphabetically within
+    a pattern, where the literal `std` names the bundled standard schema
+    configuration, and where a pattern matching no file is an error) are
+    merged in order into one effective schema configuration, the later
+    files into the earlier ones. The objects merge deeply, while the
+    elements of the lists are matched by identity (artifacts by `kind`
+    plus `id`/`name`, nested objects by `kind`, properties by `name`, and
+    scalar entries by value): a matching element is merged into its
+    counterpart, an unmatched one is appended. Every file has to be valid
+    YAML on its own, while the merged result alone is validated against
+    the schema of the configuration.
 
 -   `-b|--basedir <spec-md-file-basedir>`:
     The base directory (default: `.`) is the directory the referenced
@@ -295,18 +349,48 @@ Options:
     The `md` export format normalizes the entire corpus into a *single*
     Markdown document.
 
+-   `-w|--watch` (`export` only):
+    Keep the outputs in sync with their sources: after the regular export,
+    the referenced artifact files and all assets they embed are observed,
+    and every change re-exports the specification once the sources stayed
+    silent for one second. A failed re-export is reported and leaves the
+    observe loop intact, so a transiently invalid specification does not
+    end the watch. The outputs have to be regular files, as `-` (stdout)
+    cannot receive a repeated export.
+
+-   `-a|--addr <ip-addr>`, `-p|--port <tcp-port>` (`preview` only):
+    The IP address (default: `127.0.0.1`) and TCP port (default: `12345`)
+    the live preview listens on. The HTML export is served on
+    `http://<ip-addr>:<tcp-port>/`, kept in sync with its sources exactly
+    like `export --watch`, and updated in the browser after every change
+    through a WebSocket connection the served page keeps open, where the
+    document is replaced in place, so the scroll position survives (a
+    failed re-export keeps the previous HTML in place). A status icon
+    left of the theme switcher shows the connection state: grey while
+    connected, in the search highlight color while disconnected, and
+    blinking for 2s after every update.
+
 -   `-o|--output <output-file>` (`describe` only):
     The output file (default: `-` for stdout) receives the described
     Markdown document.
 
 -   `-e|--embed` (`describe` only):
-    Embed the given YAML schema configuration verbatim instead of just
+    Embed the given YAML schema configuration itself instead of just
     referencing it, so the resulting document describes the specification
     format entirely on its own.
 
+-   `-z|--compress [<level>]` (`describe` only):
+    The compression level (default and bare flag: `1`) of the YAML
+    schema configuration (embedded into the Markdown or emitted as the
+    raw file content), so the configuration costs fewer tokens: `0`
+    emits it verbatim, `1` re-emits it with 2-space indentation, unwrapped
+    lines, and without comments, `2` additionally leaves out its `refs` fields, and
+    `3` additionally leaves out its `desc` fields of objects and properties.
+
 -   `-f|--format <format>` (`describe` only):
     The output format (default: `md`) switches from the rendered Markdown
-    onto the raw original file content with `raw`, which is available for
+    onto the raw original file content (the `schema` one compressed by the
+    `-z|--compress` level) with `raw`, which is available for
     the file-backed parts `meta` and `schema` only.
 
 -   `-p|--part <part>` (`describe` only):
@@ -319,7 +403,10 @@ Options:
 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.
+`SPECBOOK_VERBOSE`, `SPECBOOK_ADDR`, `SPECBOOK_PORT`), while an
+explicitly supplied option always wins. As `-c|--config` is repeatable,
+`SPECBOOK_CONFIG` carries a list of patterns separated by the path
+delimiter of the platform (`:` on Unix, `;` on Windows).
 
 Example:
 

package/dst/specbook-api.d.ts

@@ -1,13 +1,16 @@
-import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic } from "./specbook-diagnostic.js";
+import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic, type DiagnosticSeverity } 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 { previewAddr, previewPort } from "./specbook-cmd-preview.js";
+import { describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel, type DescribeFormat, type DescribePart, type CompressLevel } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose, type Verbose, type VerboseLevel } from "./specbook-verbose.js";
 export { literal, renderVerbose, type Verbose, type VerboseLevel };
 export { formats, parseOutputSpec, type ExportFormat };
+export { previewAddr, previewPort };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
-export { type DescribeFormat, type DescribePart };
-export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic };
+export { compressLevels, parseCompressLevel };
+export { type DescribeFormat, type DescribePart, type CompressLevel };
+export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic, type DiagnosticSeverity };
 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";
@@ -21,25 +24,42 @@ export declare class SpecBook {
     private verbose;
     constructor(options?: SpecBookOptions);
     private verboseOf;
-    private configFile;
+    private configFiles;
     private requireConfig;
     init(options: {
-        config?: string;
+        config?: string[];
         basedir?: string;
     }): Promise<string[]>;
     lint(options: {
-        config?: string;
+        config?: string[];
         basedir?: string;
     }): Promise<LintResult>;
+    private renderFormats;
     export(options: {
-        config?: string;
+        config?: string[];
         basedir?: string;
         formats?: ExportFormat[];
+        realtime?: boolean;
     }): Promise<Buffer[]>;
+    private observe;
+    watch(options: {
+        config?: string[];
+        basedir?: string;
+        formats?: ExportFormat[];
+        realtime?: boolean;
+        onExport: (buffers: Buffer[]) => void | Promise<void>;
+    }): Promise<void>;
+    preview(options: {
+        config?: string[];
+        basedir?: string;
+        addr?: string;
+        port?: number;
+    }): Promise<void>;
     describe(options: {
-        config?: string;
+        config?: string[];
         basedir?: string;
         embed?: boolean;
+        compress?: CompressLevel;
         format?: DescribeFormat;
         part?: DescribePart;
     }): Promise<string>;

package/dst/specbook-api.js

@@ -5,18 +5,22 @@
 */
 import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
+import { glob } from "glob";
 import { loadConfig } from "./specbook-config.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 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, describeFormats, describeParts, parseDescribeFormat, parseDescribePart } from "./specbook-cmd-describe.js";
+import { exportSpecification, watchSpecification, parseOutputSpec, formats } from "./specbook-cmd-export.js";
+import { servePreview, previewAddr, previewPort } from "./specbook-cmd-preview.js";
+import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel } from "./specbook-cmd-describe.js";
 import { requireBrowser } from "./specbook-export-pdf.js";
 import { literal, renderVerbose } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
 export { literal, renderVerbose };
 export { formats, parseOutputSpec };
+export { previewAddr, previewPort };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
+export { compressLevels, parseCompressLevel };
 export { renderDiagnostic, renderDiagnosticVerbose };
 /*  our own version, taken from the package manifest, which resides one
     level above both the source and the compiled module directory  */
@@ -35,16 +39,32 @@ export class SpecBook {
     verboseOf(cmd) {
         return (msg, level = "debug") => this.verbose(cmd, msg, level);
     }
-    /*  determine the file of the YAML schema configuration, falling
-        back onto the bundled standard schema configuration  */
-    configFile(file) {
-        return file ?? standardConfig;
+    /*  determine the files of the YAML schema configuration out of the
+        glob patterns, in the order of the patterns and alphabetically
+        within a pattern, where the literal "std" names the bundled
+        standard schema configuration, which is also the fallback if no
+        pattern is given at all  */
+    async configFiles(patterns) {
+        if (patterns === undefined || patterns.length === 0)
+            return [standardConfig];
+        const files = new Array();
+        for (const pattern of patterns) {
+            if (pattern === "std") {
+                files.push(standardConfig);
+                continue;
+            }
+            const matches = await glob(pattern, { nodir: true });
+            if (matches.length === 0)
+                throw new Error(`no configuration file matches "${pattern}"`);
+            files.push(...matches.sort());
+        }
+        return files;
     }
-    /*  load a YAML schema configuration, failing on any problem  */
-    requireConfig(file, verbose) {
-        file = this.configFile(file);
-        verbose(`loading schema configuration "${literal(file)}"`);
-        const { config, diagnostics } = loadConfig(file);
+    /*  load the YAML schema configuration out of its files, failing on any problem  */
+    requireConfig(files, verbose) {
+        verbose("loading schema configuration " +
+            files.map((file) => `"${literal(file)}"`).join(", "));
+        const { config, diagnostics } = loadConfig(files);
         if (config === undefined)
             throw new Error("invalid configuration:\n" +
                 diagnostics.map(renderDiagnostic).join("\n"));
@@ -54,19 +74,36 @@ export class SpecBook {
         below the base directory  */
     async init(options) {
         const verbose = this.verboseOf("init");
-        return initSpecification({ config: this.requireConfig(options.config, verbose),
+        return initSpecification({ config: this.requireConfig(await this.configFiles(options.config), verbose),
             basedir: options.basedir ?? ".", verbose });
     }
     /*  lint the specification Markdown files below the base directory  */
     async lint(options) {
-        return lint({ config: this.configFile(options.config),
+        return lint({ config: await this.configFiles(options.config),
             basedir: options.basedir ?? ".", verbose: this.verboseOf("lint") });
     }
+    /*  render an already parsed specification into the requested formats
+        (strict: any error diagnostic prevents the export, as a partial or
+        invalid specification must never be emitted, while the warnings
+        are just surfaced as notices), where "realtime" injects the
+        client-side script of the live preview into the HTML  */
+    async renderFormats(result, formats, verbose, realtime) {
+        if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
+            throw new Error("invalid specification:\n" +
+                result.diagnostics.map(renderDiagnostic).join("\n"));
+        for (const diagnostic of result.diagnostics)
+            verbose(renderDiagnostic(diagnostic), "notice");
+        if (result.specification.artifacts.length === 0)
+            throw new Error("unexportable specification: no artifacts found");
+        const buffers = new Array();
+        for (const format of formats)
+            buffers.push(await exportSpecification(result.specification, format, verbose, result.config, realtime));
+        return buffers;
+    }
     /*  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 (strict: any diagnostic prevents the export,
-        as a partial or invalid specification must never be emitted)  */
+        requested format  */
     async export(options) {
         const verbose = this.verboseOf("export");
         const requested = options.formats ?? ["json"];
@@ -74,23 +111,62 @@ export class SpecBook {
             export fail before the specification is even parsed  */
         if (requested.includes("pdf"))
             await requireBrowser(verbose);
-        const result = lint({ config: this.configFile(options.config),
-            basedir: options.basedir ?? ".", verbose });
-        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 requested)
-            buffers.push(await exportSpecification(result.specification, format, verbose, result.config));
-        return buffers;
+        return this.renderFormats(lint({ config: await this.configFiles(options.config),
+            basedir: options.basedir ?? ".", verbose }), requested, verbose, options.realtime === true);
+    }
+    /*  keep an export in sync with its sources (the shared core of
+        "watch" and "preview"): every change of an artifact file or of one
+        of its embedded assets re-exports the specification and hands the
+        buffers to "onExport" once the sources fell silent again. A failed
+        re-export is reported and leaves the observe loop intact, so a
+        transiently invalid specification does not end the watch. The
+        returned promise settles once the initial export is done, while
+        the active watcher keeps the process alive afterwards  */
+    async observe(options, verbose) {
+        const config = await this.configFiles(options.config);
+        return watchSpecification(async () => {
+            /*  the lint result carries the files to observe even for an
+                invalid specification, so a failing export still keeps the
+                observe loop fed with an up-to-date file set  */
+            const result = lint({ config, basedir: options.basedir ?? ".", verbose });
+            try {
+                await options.onExport(await this.renderFormats(result, options.formats, verbose, options.realtime));
+            }
+            catch (err) {
+                verbose("export failed: " +
+                    (err instanceof Error ? err.message : String(err)), "notice");
+            }
+            return result.files;
+        }, verbose);
+    }
+    /*  export the specification like "export" and then keep the export
+        in sync with its sources (see "observe")  */
+    async watch(options) {
+        const verbose = this.verboseOf("export");
+        const requested = options.formats ?? ["json"];
+        if (requested.includes("pdf"))
+            await requireBrowser(verbose);
+        return this.observe({ ...options, formats: requested,
+            realtime: options.realtime === true }, verbose);
+    }
+    /*  serve the HTML export of the specification as a live preview on
+        "http://<addr>:<port>/": the export is kept in sync with its
+        sources (see "observe") and every fresh export is pushed to the
+        connected browsers as an in-place document update, through the
+        client-side script the "realtime" export injects into the HTML  */
+    async preview(options) {
+        const verbose = this.verboseOf("preview");
+        const server = await servePreview({ addr: options.addr ?? previewAddr,
+            port: options.port ?? previewPort, verbose });
+        return this.observe({ config: options.config, basedir: options.basedir,
+            formats: ["html"], realtime: true,
+            onExport: ([html]) => server.update(html) }, verbose);
     }
     /*  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  */
+        before use and optionally emitted compressed by level  */
     async describe(options) {
         const verbose = this.verboseOf("describe");
         const format = options.format ?? "md";
@@ -98,15 +174,14 @@ export class SpecBook {
         /*  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 given = options.config !== undefined && options.config.length > 0;
+        const standard = !given && (part === "all" || part === "schema" || options.embed === true);
+        const config = given || standard ? await this.configFiles(options.config) : undefined;
         const embed = options.embed === true || standard;
         const basedir = options.basedir ?? (part === "spec" ? "." : undefined);
-        if (config !== undefined)
-            this.requireConfig(config, verbose);
+        const schema = config !== undefined ? this.requireConfig(config, verbose) : undefined;
         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 });
+        return describeFormat({ ...options, config, schema, basedir, embed, standard, format, part });
     }
 }