@rse/specbook 1.2.6 → 1.2.8

package/README.md

@@ -6,6 +6,8 @@ SpecBook
 
 **Markdown-based Specification Format**
 
+[specbook.tools](https://specbook.tools)
+
 [![github (author stars)](https://img.shields.io/github/stars/rse?logo=github&label=author%20stars&color=%233377aa)](https://github.com/rse)
 [![github (author followers)](https://img.shields.io/github/followers/rse?label=author%20followers&logo=github&color=%234477aa)](https://github.com/rse)
 
@@ -131,17 +133,17 @@ Commands:
 
 ```bash
 $ specbook init \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>]
 
 $ specbook lint \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>]
 
 $ specbook export \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
   [-o|--output [<format>:]<output-file>] \
@@ -149,14 +151,14 @@ $ specbook export \
   [...]
 
 $ specbook preview \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
   [-a|--addr <ip-addr>] \
   [-p|--port <tcp-port>]
 
 $ specbook describe \
-  [-v|--verbose] \
+  [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
   [-b|--basedir <spec-md-file-basedir>] \
   [-e|--embed] \
@@ -166,13 +168,17 @@ $ specbook describe \
   [-o|--output <output-file>]
 
 $ specbook mcp \
-  [-v|--verbose]
+  [-v|--verbose [<level>]]
 ```
 
 Options:
 
--   `-v|--verbose`:
-    Enable verbose logging of processing information to `stderr`.
+-   `-v|--verbose [<level>]`:
+    Enable verbose logging of processing information to `stderr` at the
+    given verbosity level: `0` (the default) logs the notices only, `1`
+    (the bare flag) also the regular processing information, `2` also
+    the reference coverage ratios, and `3` also the unreferenced objects
+    of a reference coverage.
 
 -   `-c|--config <schema-yaml-file>`:
     The YAML schema configuration (default: the bundled standard schema
@@ -185,10 +191,10 @@ Options:
     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 verbose output additionally states the reference
-    coverage ratios: the ones the `referenced` object kinds receive and
-    the ones the `coverage` object kinds report, the latter naming the
-    unreferenced objects.
+    exported. The verbose output additionally states at verbosity level
+    `2` the reference coverage ratios: the ones the `referenced` object
+    kinds receive and the ones the `coverage` object kinds report, the
+    latter naming the unreferenced objects at level `3`.
     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

package/dst/specbook-api.d.ts

@@ -3,8 +3,9 @@ import { type LintResult } from "./specbook-cmd-lint.js";
 import { parseOutputSpec, formats, type ExportFormat } from "./specbook-cmd-export.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 };
+import { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity, type Verbose, type VerboseLevel, type Verbosity } from "./specbook-verbose.js";
+export { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity };
+export { type Verbose, type VerboseLevel, type Verbosity };
 export { formats, parseOutputSpec, type ExportFormat };
 export { previewAddr, previewPort };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };

package/dst/specbook-api.js

@@ -14,9 +14,9 @@ import { lint } from "./specbook-cmd-lint.js";
 import { exportSpecification, watchSpecification, parseOutputSpec, formats, requireBrowser } 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 { literal, renderVerbose } from "./specbook-verbose.js";
+import { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
-export { literal, renderVerbose };
+export { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity };
 export { formats, parseOutputSpec };
 export { previewAddr, previewPort };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
@@ -37,7 +37,7 @@ export class SpecBook {
     }
     /*  bind the verbose sink to a particular command  */
     verboseOf(cmd) {
-        return (msg, level = "debug") => this.verbose(cmd, msg, level);
+        return (msg, level = "notice") => this.verbose(cmd, msg, level);
     }
     /*  determine the files of the YAML schema configuration out of the
         glob patterns, in the order of the patterns and alphabetically
@@ -96,7 +96,7 @@ export class SpecBook {
             throw new Error("invalid specification:\n" +
                 result.diagnostics.map(renderDiagnostic).join("\n"));
         for (const diagnostic of result.diagnostics)
-            verbose(renderDiagnostic(diagnostic), "notice");
+            verbose(renderDiagnostic(diagnostic), "none");
         if (result.specification.artifacts.length === 0)
             throw new Error("unexportable specification: no artifacts found");
         const buffers = new Array();
@@ -149,7 +149,7 @@ export class SpecBook {
             }
             catch (err) {
                 verbose("export failed: " +
-                    (err instanceof Error ? err.message : String(err)), "notice");
+                    (err instanceof Error ? err.message : String(err)), "none");
             }
             return files;
         }, verbose);

package/dst/specbook-cli.js

@@ -8,19 +8,23 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Command, CommanderError } from "commander";
 import chalk from "chalk";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, parseVerbosity, verbosityOf, 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
     the tool name plus the scope path of the emitting command, where
     Chalk styles the output only if the terminal supports colors; the
-    "notice" messages pass regardless of the verbose option, as they
+    verbosity of the verbose option gates the messages by their level,
+    so the "none" messages pass regardless of the option, as they
     report environment problems the user has to see  */
-const verboseOf = (opts, ...scope) => (cmd, msg, level) => {
-    if (opts.verbose || level === "notice") {
-        const scopePath = [...scope, cmd].map((segment) => chalk.bold(segment)).join(": ");
-        process.stderr.write(`specbook: ${scopePath}: ${renderVerbose(msg, chalk.blue)}\n`);
-    }
+const verboseOf = (opts, ...scope) => {
+    const verbosity = parseVerbosity(opts.verbose);
+    return (cmd, msg, level) => {
+        if (verbosityOf[level] <= verbosity) {
+            const scopePath = [...scope, cmd].map((segment) => chalk.bold(segment)).join(": ");
+            process.stderr.write(`specbook: ${scopePath}: ${renderVerbose(msg, chalk.blue)}\n`);
+        }
+    };
 };
 /*  write a buffer to a standard stream, awaiting the write callback
     which only fires once the data has been flushed to the underlying
@@ -41,7 +45,7 @@ const writeOutput = async (output, data, cmd, verbose) => {
         await writeStdout(data);
     else {
         await fs.promises.writeFile(output, data);
-        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`, "debug");
+        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`, "notice");
     }
 };
 /*  determine an option default value, overridable via a
@@ -56,9 +60,13 @@ const envDefaultFlag = (name, fallback) => {
     const value = process.env[`SPECBOOK_${name.toUpperCase().replace(/-/g, "_")}`];
     return value !== undefined ? !(/^(?:|0|false|no|off)$/i).test(value) : fallback;
 };
-/*  provide the verbose option of all sub-commands  */
+/*  provide the verbose option of all sub-commands, whose optional level
+    selects the verbosity (where the environment default carries a level
+    or a boolean word)  */
 const withVerboseOption = (command) => command
-    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false));
+    .option("-v, --verbose [level]", "print verbose processing information to stderr " +
+    "(0: none, 1: notices, 2: also the details like the coverage ratios, " +
+    "3: also the traces like the unreferenced objects; default: 0, bare flag: 1)", envDefault("verbose", "0"));
 /*  provide the repeatable schema configuration option, whose files or
     glob patterns are merged in order (with "std" naming the bundled
     standard one), and determine its value, where the environment default
@@ -96,7 +104,7 @@ program.name("specbook")
 withVerboseOption(program.command("mcp"))
     .description("run as MCP stdio server")
     .action(async (opts) => {
-    verboseOf(opts)("mcp", "starting MCP server on stdio", "debug");
+    verboseOf(opts)("mcp", "starting MCP server on stdio", "notice");
     await serveMcp(verboseOf(opts, "mcp"));
 });
 /*  the init command creates the configured artifact files  */
@@ -116,13 +124,13 @@ withCommonOptions(program.command("lint"))
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const result = await specbook.lint({ config: configOf(opts), basedir: opts.basedir });
     for (const diagnostic of result.diagnostics)
-        await writeStdout(opts.verbose ?
+        await writeStdout(parseVerbosity(opts.verbose) > 0 ?
             renderDiagnosticVerbose(diagnostic, process.stdout.isTTY === true) :
             `${renderDiagnostic(diagnostic)}\n`);
     if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
         process.exitCode = 1;
     else
-        verboseOf(opts)("lint", "specification valid", "debug");
+        verboseOf(opts)("lint", "specification valid", "notice");
 });
 /*  the export command parses the input once and writes every output  */
 withCommonOptions(program.command("export"))

package/dst/specbook-cmd-export.js

@@ -3,6 +3,7 @@
 **  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";
 /*  Chokidar is aliased in "package.json", as Nunjucks declares the
     (unused) Chokidar 3 as an optional peer dependency and the current
     Chokidar under its plain name would raise a peer warning on install  */
@@ -56,23 +57,45 @@ export const parseOutputSpec = (spec) => {
 /*  the quiet period the observed files have to stay silent for before a
     burst of changes is coalesced into a single re-export  */
 const watchDelay = 1000;
+/*  the interval of the safety-net scan, which catches the changes the
+    file-system watcher missed: a watcher can die unnoticed -- macOS
+    tears down its FSEvents streams across a sleep/wake cycle -- and
+    would then leave the export stale for the rest of the process life  */
+const scanDelay = 30 * 1000;
+/*  take the modification time snapshot of the observed files, where an
+    absent file (a still missing artifact) is remembered as absent, too,
+    so its creation and removal are noticed like a modification  */
+const snapshot = (files) => {
+    const times = new Map();
+    for (const file of files) {
+        try {
+            times.set(file, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            times.set(file, 0);
+        }
+    }
+    return times;
+};
 /*  keep a specification export in sync with its sources, where "run"
     performs one export and returns the files to observe: the initial
     export is performed up-front and every observed change triggers a
     re-export once the sources fell silent again. The observed set is
     re-synchronized after every run, as an edit can add or drop an
     embedded asset. The returned promise settles once the initial export
-    is done, while the active watcher keeps the process alive afterwards  */
+    is done, while the active watcher and the safety-net scan keep the
+    process alive afterwards  */
 export const watchSpecification = async (run, verbose) => {
     /*  perform the regular export before entering the observe loop  */
     let observed = await run();
+    let times = snapshot(observed);
     const watcher = watch(observed, { ignoreInitial: true });
     verbose(`observing ${literal(observed.length)} specification file(s) for changes`);
     /*  report the failures of the observation itself, as an unhandled
         "error" event would otherwise terminate the process  */
     watcher.on("error", (err) => {
         verbose("observing failed: " +
-            (err instanceof Error ? err.message : String(err)), "notice");
+            (err instanceof Error ? err.message : String(err)), "none");
     });
     /*  perform a re-export and re-synchronize the observed files  */
     const cycle = async () => {
@@ -80,6 +103,7 @@ export const watchSpecification = async (run, verbose) => {
         watcher.unwatch(observed.filter((file) => !files.includes(file)));
         watcher.add(files.filter((file) => !observed.includes(file)));
         observed = files;
+        times = snapshot(files);
     };
     /*  restart the quiet period on every change, so a burst collapses
         into a single re-export, and chain the runs onto each other, so a
@@ -88,17 +112,34 @@ export const watchSpecification = async (run, verbose) => {
         and hence silently ending the observe loop)  */
     let chain = Promise.resolve();
     let timer;
-    watcher.on("all", () => {
+    const schedule = () => {
         if (timer !== undefined)
             clearTimeout(timer);
         timer = setTimeout(() => {
             timer = undefined;
             chain = chain.then(cycle).catch((err) => {
                 verbose("re-export failed: " +
-                    (err instanceof Error ? err.message : String(err)), "notice");
+                    (err instanceof Error ? err.message : String(err)), "none");
             });
         }, watchDelay);
-    });
+    };
+    watcher.on("all", schedule);
+    /*  compare the modification times regularly, so a change the
+        watcher never reported still reaches the export, and re-establish
+        the watchers on such a miss, as a watcher which lost a file never
+        regains it on its own and the following changes would be caught
+        by the scan only  */
+    setInterval(() => {
+        for (const [file, time] of snapshot(observed))
+            if (times.get(file) !== time) {
+                verbose(`observing missed the change of "${literal(file)}" ` +
+                    "-- re-establishing the file observation", "none");
+                watcher.unwatch(observed);
+                watcher.add(observed);
+                schedule();
+                break;
+            }
+    }, scanDelay);
 };
 /*  render a specification into the requested format, where "realtime"
     injects the client-side script of the live preview into the HTML  */

package/dst/specbook-cmd-lint.js

@@ -75,9 +75,10 @@ export const lint = (options) => {
     options.verbose(`parsed specification defining ${literal(stats.objects)} object(s) ` +
         `and ${literal(stats.links)} link relationship(s)`);
     /*  report the reference coverage the "referenced"-flagged object
-        kinds receive and the "coverage"-configured objects report, the
-        unreferenced objects of the latter by name (the ones of the
-        former are already reported as warnings)  */
+        kinds receive and the "coverage"-configured objects report as
+        additional figures, the unreferenced objects of the latter by
+        name as a lengthy detail (the ones of the former are already
+        reported as warnings)  */
     if (config !== undefined && result.specification.artifacts.length > 0) {
         const index = buildLinkIndex(result.specification);
         const schemas = collectSchemas(result.specification, config);
@@ -88,13 +89,17 @@ export const lint = (options) => {
             const chain = chainOf(index, covered[0] ?? uncovered[0]);
             options.verbose((schema.referenced ?? []).map((entry) => `"${literal(entry)}"`).join(" or ") +
                 ` references ${ratio(covered, uncovered)} ${schema.kind} object(s)` +
-                (chain.length > 1 ? ` below ${label(chain[0])}` : ""));
+                (chain.length > 1 ? ` below ${label(chain[0])}` : ""), "detail");
         }
         for (const [object, entries] of specCoverage(index, schemas))
-            for (const { pattern, covered, uncovered } of entries)
+            for (const { pattern, covered, uncovered } of entries) {
                 options.verbose(`${label(object)} references ${ratio(covered, uncovered)} ` +
-                    `"${literal(pattern)}" object(s)` + (uncovered.length > 0 ?
-                    `, unreferenced: ${uncovered.map(label).join(", ")}` : ""));
+                    `"${literal(pattern)}" object(s)`, "detail");
+                if (uncovered.length > 0)
+                    options.verbose(`${label(object)} leaves ${literal(uncovered.length)} ` +
+                        `"${literal(pattern)}" object(s) unreferenced: ` +
+                        uncovered.map(label).join(", "), "trace");
+            }
     }
     /*  report the non-optional artifacts absent from the specification,
         against their loaded artifact file (an absent or unreadable file

package/dst/specbook-cmd-preview.js

@@ -36,16 +36,16 @@ export const servePreview = async (options) => {
             /*  identify the client by its remote address and port  */
             const addr = request.socket.remoteAddress ?? "unknown";
             const client = `${addr.includes(":") ? `[${addr}]` : addr}:${request.socket.remotePort ?? 0}`;
-            options.verbose(`client ${literal(client)} connected`, "notice");
+            options.verbose(`client ${literal(client)} connected`, "none");
             clients.add(socket);
             socket.on("close", () => {
                 clients.delete(socket);
-                options.verbose(`client ${literal(client)} disconnected`, "notice");
+                options.verbose(`client ${literal(client)} disconnected`, "none");
             });
             /*  report a failing client, as an unhandled "error" event
                 would otherwise terminate the process  */
             socket.on("error", (err) => {
-                options.verbose(`client ${literal(client)} failed: ${err.message}`, "notice");
+                options.verbose(`client ${literal(client)} failed: ${err.message}`, "none");
             });
         }
     });
@@ -53,12 +53,12 @@ export const servePreview = async (options) => {
     await fastify.listen({ host: options.addr, port: options.port });
     const host = options.addr.includes(":") ? `[${options.addr}]` : options.addr;
     const url = `http://${host}:${options.port}/`;
-    options.verbose(`listening on ${literal(url)}`, "notice");
+    options.verbose(`listening on ${literal(url)}`, "none");
     return {
         update: (buffer) => {
             /*  the first export turns the 503 placeholder into the document  */
             if (html === undefined)
-                options.verbose(`serving ${literal(url)}`, "notice");
+                options.verbose(`serving ${literal(url)}`, "none");
             html = buffer;
             options.verbose(`notifying ${literal(clients.size)} preview client(s)`);
             for (const client of clients)

package/dst/specbook-export-pdf.js

@@ -176,7 +176,7 @@ const resolveBrowser = async (verbose) => {
         const chrome = await chromium.launch({ channel: "chrome" });
         await chrome.close();
         verbose("Playwright Chromium unavailable -- falling back to the " +
-            `system-installed Google Chrome (${chromiumRemedy})`, "notice");
+            `system-installed Google Chrome (${chromiumRemedy})`, "none");
         return { channel: "chrome" };
     }
     catch {
@@ -248,7 +248,7 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, titlePage, ver
             would otherwise ship silently wrong page numbers  */
         if (!stable)
             verbose(`the ToC page numbers did not stabilize within ${literal(tocPasses)} ` +
-                "passes -- they can be off by a page", "notice");
+                "passes -- they can be off by a page", "none");
         /*  render the final document, decorated with header/footer  */
         const decorated = await renderPdf(html, {
             displayHeaderFooter: true,

package/dst/specbook-format.md

@@ -622,7 +622,8 @@ the description of the reporting object (one row per pattern, labeled
 by the kinds of the matching objects, with the covered and total counts
 and the ratio as a bar), the AST exports attach the counts as the
 `coverage` field of the object, and the verbose output of `lint` and
-`export` names the unreferenced objects.
+`export` states the ratio at its higher levels and names the
+unreferenced objects at its highest one.
 
 ### Format
 

package/dst/specbook-verbose.d.ts

@@ -1,4 +1,8 @@
-export type VerboseLevel = "debug" | "notice";
+export type VerboseLevel = "none" | "notice" | "detail" | "trace";
 export type Verbose = (msg: string, level?: VerboseLevel) => void;
+export declare const verbosities: readonly [0, 1, 2, 3];
+export type Verbosity = typeof verbosities[number];
+export declare const verbosityOf: Record<VerboseLevel, Verbosity>;
+export declare const parseVerbosity: (value: string | number | boolean) => Verbosity;
 export declare const literal: (value: string | number) => string;
 export declare const renderVerbose: (msg: string, style?: (value: string) => string) => string;

package/dst/specbook-verbose.js

@@ -3,6 +3,28 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+/*  the verbosity a consumer runs at, as the least one surfacing the
+    messages of each level: a message passes a consumer whose verbosity
+    is at least the one of its level  */
+export const verbosities = [0, 1, 2, 3];
+export const verbosityOf = { none: 0, notice: 1, detail: 2, trace: 3 };
+/*  parse and validate a verbosity specification, where a bare flag (or
+    a boolean word) selects the regular processing information  */
+export const parseVerbosity = (value) => {
+    let level;
+    if (typeof value === "boolean")
+        level = value ? 1 : 0;
+    else if (typeof value === "string" && (/^(?:true|yes|on)$/i).test(value))
+        level = 1;
+    else if (typeof value === "string" && (/^(?:false|no|off)$/i).test(value))
+        level = 0;
+    else
+        level = typeof value === "string" && !(/^\d+$/).test(value) ? NaN : Number(value);
+    if (!verbosities.includes(level))
+        throw new Error(`unknown verbosity "${value}" ` +
+            `(supported: ${verbosities.join(", ")})`);
+    return level;
+};
 /*  the sentinel characters delimiting a marked literal value, taken
     from the Unicode private use area, so they never clash with the
     regular content of a verbose message  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.6",
+    "version":                             "1.2.8",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -54,7 +54,7 @@
         "globals":                         "17.12.0",
         "markdownlint":                    "0.41.1",
         "markdownlint-cli2":               "0.23.2",
-        "@types/node":                     "26.4.1",
+        "@types/node":                     "26.5.0",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",
         "@types/ws":                       "8.18.1",