@rse/specbook 1.2.6 → 1.2.7

package/README.md

@@ -131,17 +131,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 +149,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 +166,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 +189,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

@@ -72,7 +72,7 @@ export const watchSpecification = async (run, verbose) => {
         "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 () => {
@@ -95,7 +95,7 @@ export const watchSpecification = async (run, verbose) => {
             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);
     });

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.7",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",