@rse/specbook 1.5.2 → 1.6.1

package/dst/specbook-api.js

@@ -3,16 +3,17 @@
 **  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";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { glob } from "glob";
 import { loadConfig, configStatistics } from "./specbook-config.js";
-import { loadProject, writeProject, projectFile } from "./specbook-project.js";
+import { loadProject, writeProject, projectFile, isRemote } from "./specbook-project.js";
+import { version, standardConfig, metaConfig, pmConfig, isBundled, cacheDir, isCached, expandPattern, resolveConfig, reportOverlaps, search, fetchModes, parseFetchMode } from "./specbook-remote.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
+import { isBelow } from "./specbook-files.js";
 import { exportSpecification, watchSpecification, parseOutputSpec, formats, requireBrowser, parseOmit, omitAspects } from "./specbook-cmd-export.js";
+import { lintSchema } from "./specbook-cmd-export-schema.js";
+import { SpecBookDocument, renderNodes, queryFormats, parseQueryOutput } from "./specbook-cmd-query.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, verbosities, verbosityOf, parseVerbosity } from "./specbook-verbose.js";
@@ -24,13 +25,8 @@ export { projectFile };
 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  */
-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));
+export { SpecBookDocument, renderNodes, queryFormats, parseQueryOutput };
+export { version, standardConfig, metaConfig, pmConfig, cacheDir, fetchModes, parseFetchMode };
 /*  the SpecBook API  */
 export class SpecBook {
     verbose;
@@ -64,32 +60,39 @@ export class SpecBook {
         return {
             file: project?.file,
             config: config !== undefined && config.length > 0 ?
-                config.map((pattern) => pattern === "std" ? pattern : given(pattern)) :
-                project?.config?.map((pattern) => pattern === "std" ? pattern : derived(pattern)),
+                config.map((pattern) => isRemote(pattern) ? pattern : given(pattern)) :
+                project?.config?.map((pattern) => isRemote(pattern) ? pattern : derived(pattern)),
             basedir: basedir !== undefined ? given(basedir) :
                 project?.basedir !== undefined ? derived(project.basedir) :
                     options.cwd !== undefined ? cwd : undefined
         };
     }
+    /*  the options of the remote resolution of a command  */
+    remoteOptions(options, verbose) {
+        return { fetch: parseFetchMode(options.fetch ?? "auto"),
+            cwd: path.resolve(options.cwd ?? "."), verbose };
+    }
     /*  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)
+        patterns, in the order of the patterns and alphabetically within
+        a pattern, where a remote reference (the literals "std", "meta",
+        and "pm" included, naming the bundled schema configurations, the
+        standard one being also the fallback if no pattern is given at all) is
+        resolved into the files of the download cache, and optionally
+        collect the display label of every file: the remote reference it
+        stems from (plus its base name, if the reference yields several
+        files), or its local path  */
+    async configFiles(patterns, access, labels) {
+        if (patterns === undefined || patterns.length === 0) {
+            labels?.set(standardConfig, "std");
             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,
-                windowsPathsNoEscape: process.platform === "win32" });
-            if (matches.length === 0)
-                throw new Error(`no configuration file matches "${pattern}"`);
-            files.push(...matches.sort());
+            const matches = isRemote(pattern) ? await resolveConfig(pattern, access) : await expandPattern(pattern);
+            for (const file of matches)
+                labels?.set(file, !isRemote(pattern) ? file :
+                    matches.length === 1 ? pattern : `${pattern} (${path.basename(file)})`);
+            files.push(...matches);
         }
         return files;
     }
@@ -97,31 +100,34 @@ export class SpecBook {
     requireConfig(files, verbose) {
         verbose("loading schema configuration " +
             files.map((file) => `"${literal(file)}"`).join(", "));
-        const { config, diagnostics } = loadConfig(files);
+        const { config, diagnostics, overlaps } = loadConfig(files);
         if (config === undefined)
             throw new Error("invalid configuration:\n" +
                 diagnostics.map(renderDiagnostic).join("\n"));
+        reportOverlaps(overlaps, verbose);
         const stats = configStatistics(config);
         verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
             `and ${literal(stats.links)} link relationship(s)`);
         return config;
     }
     /*  initialize the configured specification artifact files below the
-        base directory and persist the effective project options into a
-        new project configuration file in the working directory, unless
-        one already applies (as a new one would shadow it)  */
+        base directory (where "sample" scaffolds a sample object per
+        allowed object kind into them) and persist the effective project
+        options into a new project configuration file in the working
+        directory, unless one already applies (as a new one would shadow it)  */
     async init(options) {
         const verbose = this.verboseOf("init");
         const project = this.project(options, verbose);
-        const files = initSpecification({ config: this.requireConfig(await this.configFiles(project.config), verbose),
-            basedir: project.basedir ?? ".", verbose });
+        const config = await this.configFiles(project.config, this.remoteOptions(options, verbose));
+        const files = initSpecification({ config: this.requireConfig(config, verbose),
+            basedir: project.basedir ?? ".", sample: options.sample === true, verbose });
         if (project.file !== undefined) {
             verbose(`skipping existing project configuration "${literal(project.file)}"`);
             return { files };
         }
         const cwd = path.resolve(options.cwd ?? ".");
         const relative = (value) => path.relative(cwd, path.resolve(cwd, value)) || ".";
-        const file = writeProject(cwd, project.config?.map((pattern) => pattern === "std" ? pattern : relative(pattern)) ?? ["std"], relative(project.basedir ?? "."));
+        const file = writeProject(cwd, project.config?.map((pattern) => isRemote(pattern) ? pattern : relative(pattern)) ?? ["std"], relative(project.basedir ?? "."));
         verbose(`created project configuration "${literal(file)}"`);
         return { files, project: options.cwd !== undefined ? file : path.relative(process.cwd(), file) };
     }
@@ -131,9 +137,39 @@ export class SpecBook {
     async lint(options) {
         const verbose = this.verboseOf("lint");
         const project = this.project(options, verbose);
-        return lint({ config: await this.configFiles(project.config),
+        return lint({ config: await this.configFiles(project.config, this.remoteOptions(options, verbose)),
             basedir: project.basedir ?? ".", gitignore: options.gitignore === true, verbose });
     }
+    /*  load the specification Markdown files below the base directory (or,
+        under "schema", the effective schema configuration itself, described
+        as a specification of the bundled meta schema configuration) as a
+        document queryable through ASTq selectors, strictly like "export":
+        any error diagnostic prevents the loading, as a partial or invalid
+        specification must never be consumed, while the warnings are just
+        surfaced as unconditional verbose messages  */
+    async load(options) {
+        const verbose = this.verboseOf("load");
+        if (options.schema === true && options.basedir !== undefined)
+            throw new Error("the base directory is not applicable to the export of the schema configuration");
+        const project = this.project(options, verbose);
+        const labels = new Map();
+        const config = await this.configFiles(project.config, this.remoteOptions(options, verbose), labels);
+        const result = this.parseSource(options, config, labels, project.basedir ?? ".", verbose);
+        if (result.config === undefined || 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), "none");
+        return new SpecBookDocument(result.specification, result.config, result.diagnostics, result.origins);
+    }
+    /*  search the bundled schema configurations, the npm
+        registry, and GitHub for the shareable schema configurations
+        matching a term  */
+    async search(options) {
+        const verbose = this.verboseOf("search");
+        verbose(`searching for schema configurations matching "${literal(options.term ?? "")}"`);
+        return search(options.term ?? "", this.remoteOptions(options, verbose));
+    }
     /*  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
@@ -163,26 +199,54 @@ export class SpecBook {
         const cwd = options.cwd;
         return cwd === undefined ? options.rebase : options.rebase?.map((dir) => dir !== undefined ? path.resolve(cwd, dir) : dir);
     }
+    /*  refuse a normalized Markdown output below the base directory (told
+        by its re-basing directory), as every ".md" file below the base
+        directory is a specification file and hence the output would be
+        parsed as one on the next run  */
+    guardRebase(formats, rebase, basedir) {
+        for (const [i, format] of formats.entries()) {
+            const dir = rebase?.[i];
+            if (format === "md" && dir !== undefined && isBelow(dir, basedir))
+                throw new Error(`the Markdown output directory "${dir}" is at or below the base directory ` +
+                    `"${basedir}", so the output would be parsed as a specification file`);
+        }
+    }
+    /*  parse the source of an export: the specification Markdown files
+        below the base directory, or, under "schema", the specification
+        generated out of the effective schema configuration itself (to
+        which no base directory applies)  */
+    parseSource(options, config, labels, basedir, verbose) {
+        if (options.schema === true)
+            return lintSchema({ config, labels, verbose });
+        return lint({ config, basedir, gitignore: options.gitignore === true, verbose });
+    }
     /*  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, where "rebase" names, per requested format, the
-        directory of the output file, onto which the image references of
-        the normalized Markdown are re-based (an absent one keeps them),
-        and "omit" names the (comma-separated) aspects the HTML, the PDF,
-        and (the diagrams) the AST leave out (see "omitAspects")  */
+        (or, under "schema", the effective schema configuration itself,
+        described as a specification of the bundled meta schema
+        configuration) as JSON, JSON5, YAML, TOON, HTML, PDF, or
+        normalized Markdown, parsing the input just once and returning
+        one buffer per requested format, where "rebase" names, per
+        requested format, the directory of the output file, onto which
+        the image references of the normalized Markdown are re-based (an
+        absent one keeps them), and "omit" names the (comma-separated)
+        aspects the HTML, the PDF, and (the diagrams) the AST leave out
+        (see "omitAspects")  */
     async export(options) {
         const verbose = this.verboseOf("export");
         const requested = options.formats ?? ["json"];
         const omit = parseOmit(options.omit);
+        if (options.schema === true && options.basedir !== undefined)
+            throw new Error("the base directory is not applicable to the export of the schema configuration");
         const project = this.project(options, verbose);
-        const config = await this.configFiles(project.config);
+        if (options.schema !== true)
+            this.guardRebase(requested, this.rebaseOf(options), project.basedir ?? ".");
+        const labels = new Map();
+        const config = await this.configFiles(project.config, this.remoteOptions(options, verbose), labels);
         /*  a missing browser is an environment problem, so let the PDF
             export fail before the specification is even parsed  */
         if (requested.includes("pdf"))
             await requireBrowser(verbose);
-        const result = lint({ config,
-            basedir: project.basedir ?? ".", gitignore: options.gitignore === true, verbose });
+        const result = this.parseSource(options, config, labels, project.basedir ?? ".", verbose);
         return this.renderFormats(result, requested, verbose, { realtime: options.realtime === true, omit }, this.rebaseOf(options));
     }
     /*  keep an export in sync with its sources (the shared core of
@@ -196,8 +260,13 @@ export class SpecBook {
         process alive afterwards  */
     async observe(options, verbose) {
         const omit = parseOmit(options.omit);
+        if (options.schema === true && options.basedir !== undefined)
+            throw new Error("the base directory is not applicable to the export of the schema configuration");
         const project = this.project(options, verbose);
-        const config = await this.configFiles(project.config);
+        if (options.schema !== true)
+            this.guardRebase(options.formats, this.rebaseOf(options), project.basedir ?? ".");
+        const labels = new Map();
+        const config = await this.configFiles(project.config, this.remoteOptions(options, verbose), labels);
         /*  a missing browser is an environment problem, so let the PDF
             export fail before the specification is even parsed, but
             after the usage problems (exactly like "export")  */
@@ -206,11 +275,13 @@ export class SpecBook {
         return watchSpecification(async () => {
             /*  the lint result carries the files to observe even for an
                 invalid specification, and the configuration files are
-                observed, too, so a failing export (even one due to an
-                invalid configuration) still keeps the observe loop fed  */
-            const result = lint({ config, basedir: project.basedir ?? ".",
-                gitignore: options.gitignore === true, verbose });
-            const files = [...config.map((file) => path.resolve(file)), ...result.files];
+                observed, too (the only sources of the schema export), so
+                a failing export (even one due to an invalid configuration)
+                still keeps the observe loop fed, while the files of the
+                download cache never change  */
+            const result = this.parseSource(options, config, labels, project.basedir ?? ".", verbose);
+            const files = [...config.map((file) => path.resolve(file)), ...result.files]
+                .filter((file) => !isCached(file));
             /*  an output which is itself an observed source would re-trigger
                 the observation with its own write and hence feed an endless
                 re-export loop, so refuse it before it is ever written  */
@@ -241,7 +312,7 @@ export class SpecBook {
         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,
-        where "omit" is the one of "export"  */
+        where "omit" and "schema" are the ones of "export"  */
     async preview(options) {
         const verbose = this.verboseOf("preview");
         /*  an invalid omit aspect is a usage problem, so let the preview
@@ -255,7 +326,7 @@ export class SpecBook {
         try {
             return await this.observe({ config: options.config, basedir: options.basedir, cwd: options.cwd,
                 formats: ["html"], realtime: true, omit: options.omit, gitignore: options.gitignore,
-                onExport: ([html]) => server.update(html) }, verbose);
+                schema: options.schema, onExport: ([html]) => server.update(html) }, verbose);
         }
         catch (err) {
             /*  a failing release must not mask the primary error  */
@@ -275,13 +346,16 @@ export class SpecBook {
         const project = this.project(options, verbose);
         /*  the schema-bearing parts require a schema configuration, so
             they fall back onto the bundled standard one, which is always
-            embedded (also when named explicitly through "std"), as its
-            bundled file is no meaningful reference  */
+            embedded (also when named explicitly through "std", and so are
+            the bundled meta and project management ones named through
+            "meta" and "pm"), as its bundled file is no meaningful
+            reference, and so is a remote one, as its download cache file
+            is none either  */
         const given = project.config !== undefined;
         const config = given || part === "all" || part === "schema" ?
-            await this.configFiles(project.config) : undefined;
-        const standard = config !== undefined && config.every((file) => file === standardConfig);
-        const embed = options.embed === true || standard;
+            await this.configFiles(project.config, this.remoteOptions(options, verbose)) : undefined;
+        const standard = config !== undefined && config.every(isBundled);
+        const embed = options.embed === true || standard || (config?.some(isCached) ?? false);
         const basedir = project.basedir ?? (part === "spec" ? "." : undefined);
         const schema = config !== undefined ? this.requireConfig(config, verbose) : undefined;
         verbose(`describing the "${literal(part)}" part of the SpecBook models and formats ` +

package/dst/specbook-cli.js

@@ -8,7 +8,7 @@ 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, parseVerbosity, verbosityOf, projectFile, omitAspects, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, parseVerbosity, verbosityOf, projectFile, omitAspects, parseFetchMode, version, renderNodes, queryFormats, parseQueryOutput } 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
@@ -67,14 +67,17 @@ const withVerboseOption = (command) => command
     .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 an absent one is left
-    to the API, which resolves it through the environment variable
-    SPECBOOK_CONFIG and the project configuration file  */
+/*  provide the repeatable schema configuration option, whose files,
+    glob patterns, or remote references are merged in order (with "std",
+    "meta", and "pm" naming the bundled ones), and determine its value, where
+    an absent one is left to the API, which resolves it through the
+    environment variable SPECBOOK_CONFIG and the project configuration file  */
 const withConfigOption = (command, fallback) => command
-    .option("-c, --config <yaml-file>", "YAML schema configuration file or glob pattern " +
-    "(repeatable, merged in order, \"std\" for the bundled standard schema configuration; " +
+    .option("-c, --config <yaml-file>", "YAML schema configuration file, glob pattern, or remote reference " +
+    "(\"npm:<pkg>[@<range>][/<path>]\", \"github:<user>/<repo>[/<path>][#<ref>]\", " +
+    "or an \"http[s]://...\" URL) " +
+    "(repeatable, merged in order, \"std\" for the bundled standard schema configuration, " +
+    "\"meta\" for the bundled meta one, \"pm\" for the bundled project management one; " +
     `default: SPECBOOK_CONFIG, else the "config" entry of "${projectFile}", else ${fallback})`, (value, previous) => previous.concat(value), new Array());
 const configOf = (opts) => opts.config.length > 0 ? opts.config : undefined;
 /*  provide the base directory option, where an absent one is left to
@@ -83,9 +86,16 @@ const configOf = (opts) => opts.config.length > 0 ? opts.config : undefined;
 const withBasedirOption = (command, fallback) => command
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files " +
     `(default: SPECBOOK_BASEDIR, else the "basedir" entry of "${projectFile}", else ${fallback})`);
+/*  provide the fetch option, which selects when the remote references
+    are fetched through the network, and determine its value  */
+const withFetchOption = (command) => command
+    .option("-F, --fetch <mode>", "when to fetch the remote references through the network (\"never\": " +
+    "the download cache only, \"auto\": whenever the download cache lacks them or is no longer fresh, " +
+    "\"always\": ignoring the download cache; default: auto)", envDefault("fetch", "auto"));
+const fetchOf = (opts) => parseFetchMode(opts.fetch);
 /*  provide the common options of the specification processing sub-commands,
     for which the YAML schema configuration falls back onto the standard one  */
-const withCommonOptions = (command) => withBasedirOption(withConfigOption(withVerboseOption(command), "the bundled standard schema configuration"), "\".\"");
+const withCommonOptions = (command) => withFetchOption(withBasedirOption(withConfigOption(withVerboseOption(command), "the bundled standard schema configuration"), "\".\""));
 /*  provide the Git exclude option of the specification *reading*
     sub-commands (not of "init", which creates artifact files instead of
     reading them), which treats an artifact file Git excludes from its
@@ -93,6 +103,14 @@ const withCommonOptions = (command) => withBasedirOption(withConfigOption(withVe
 const withGitignoreOption = (command) => command
     .option("-g, --gitignore", "skip the artifact files excluded by the Git exclude rules " +
     "(the \".gitignore\" files, \"info/exclude\", and the global excludes file)", envDefaultFlag("gitignore", false));
+/*  provide the schema option of the HTML-rendering sub-commands, which
+    exports the effective schema configuration itself (described as a
+    specification of the bundled meta schema configuration) instead of
+    the specification below the base directory  */
+const withSchemaOption = (command) => command
+    .option("-S, --schema", "export the schema configuration itself as a SpecBook document " +
+    "(described through the bundled meta schema configuration) instead of the specification " +
+    "(the base directory is not applicable then)", envDefaultFlag("schema", false));
 /*  provide the repeatable omit option of the HTML-rendering sub-commands,
     whose aspects are left out of the output instead of being foldable,
     and determine its value (validated by the API)  */
@@ -130,13 +148,17 @@ withVerboseOption(program.command("mcp"))
     verboseOf(opts)("mcp", "starting MCP server on stdio", "notice");
     await serveMcp(verboseOf(opts, "mcp"));
 });
-/*  the init command creates the configured artifact files and,
-    unless one already applies, the project configuration file  */
+/*  the init command creates the configured artifact files (optionally
+    with a sample object per allowed object kind) and, unless one already
+    applies, the project configuration file  */
 withCommonOptions(program.command("init"))
     .description("initialize the configured specification artifact files below the base directory")
+    .option("-s, --sample", "scaffold a sample object per allowed object kind into the artifact files, " +
+    "with placeholder values satisfying the schema configuration", envDefaultFlag("sample", false))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const result = await specbook.init({ config: configOf(opts), basedir: opts.basedir });
+    const result = await specbook.init({ config: configOf(opts), basedir: opts.basedir,
+        fetch: fetchOf(opts), sample: opts.sample });
     await writeStdout((result.files.length > 0 ?
         `initialized artifact file(s): ${result.files.join(", ")}\n` :
         "no artifact files were created\n") +
@@ -150,7 +172,7 @@ withGitignoreOption(withCommonOptions(program.command("lint")))
     const verbose = verboseOf(opts);
     const specbook = new SpecBook({ verbose });
     const result = await specbook.lint({ config: configOf(opts), basedir: opts.basedir,
-        gitignore: opts.gitignore });
+        fetch: fetchOf(opts), gitignore: opts.gitignore });
     const detailed = parseVerbosity(opts.verbose) > 0;
     for (const diagnostic of result.diagnostics)
         await writeStdout(detailed ?
@@ -162,9 +184,9 @@ withGitignoreOption(withCommonOptions(program.command("lint")))
         verbose("lint", "specification valid", "notice");
 });
 /*  the export command parses the input once and writes every output  */
-withOmitOption(withGitignoreOption(withCommonOptions(program.command("export"))))
+withSchemaOption(withOmitOption(withGitignoreOption(withCommonOptions(program.command("export")))))
     .description("export the specification Markdown files below the base directory " +
-    "as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
+    "(or the schema configuration itself) as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
     .option("-w, --watch", "keep the outputs in sync by re-exporting on every source change", envDefaultFlag("watch", false))
     .option("-o, --output [<format>:]<output-file>", "output file (\"-\" for stdout, repeatable), with the format inferred " +
     "from the filename extension unless explicitly prefixed", (value, previous) => previous.concat(value), new Array())
@@ -195,17 +217,18 @@ withOmitOption(withGitignoreOption(withCommonOptions(program.command("export")))
     const formats = distinct.map(({ format }) => format);
     const rebase = distinct.map(rebaseOf);
     if (opts.watch)
-        await specbook.watch({ config: configOf(opts), basedir: opts.basedir,
-            formats, rebase, omit: omitOf(opts), gitignore: opts.gitignore,
+        await specbook.watch({ config: configOf(opts), basedir: opts.basedir, fetch: fetchOf(opts),
+            formats, rebase, omit: omitOf(opts), gitignore: opts.gitignore, schema: opts.schema,
             outputs: outputs.map(({ output }) => output), onExport: write });
     else
-        await write(await specbook.export({ config: configOf(opts), basedir: opts.basedir,
-            formats, rebase, omit: omitOf(opts), gitignore: opts.gitignore }));
+        await write(await specbook.export({ config: configOf(opts), basedir: opts.basedir, fetch: fetchOf(opts),
+            formats, rebase, omit: omitOf(opts), gitignore: opts.gitignore, schema: opts.schema }));
 });
 /*  the preview command serves the HTML export live in the browser  */
-withOmitOption(withGitignoreOption(withCommonOptions(program.command("preview"))))
+withSchemaOption(withOmitOption(withGitignoreOption(withCommonOptions(program.command("preview")))))
     .description("serve the HTML export of the specification Markdown files below the base " +
-    "directory as a live preview, re-exported and reloaded on every source change")
+    "directory (or of the schema configuration itself) as a live preview, re-exported and " +
+    "reloaded on every source change")
     .option("-a, --addr <ip-addr>", "IP address to listen on", envDefault("addr", previewAddr))
     .option("-p, --port <tcp-port>", "TCP port to listen on", envDefault("port", String(previewPort)))
     .action(async (opts) => {
@@ -213,17 +236,45 @@ withOmitOption(withGitignoreOption(withCommonOptions(program.command("preview"))
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new Error(`invalid TCP port "${opts.port}"`);
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    await specbook.preview({ config: configOf(opts), basedir: opts.basedir, addr: opts.addr, port,
-        omit: omitOf(opts), gitignore: opts.gitignore });
+    await specbook.preview({ config: configOf(opts), basedir: opts.basedir, fetch: fetchOf(opts),
+        addr: opts.addr, port, omit: omitOf(opts), gitignore: opts.gitignore, schema: opts.schema });
+});
+/*  the query command loads the specification and writes the
+    nodes an ASTq selector matches as JSON, JSON5, YAML, or TOON  */
+withSchemaOption(withGitignoreOption(withCommonOptions(program.command("query"))))
+    .description("query the specification Markdown files below the base directory " +
+    "(or the schema configuration itself) with an ASTq selector, writing the matched nodes " +
+    "as JSON, JSON5, YAML, or TOON")
+    .argument("<selector>", "the ASTq selector of the nodes to write")
+    .option("-P, --param <name>=<value>", "value of a \"{name}\" parameter of the selector (repeatable)", (value, previous) => previous.concat(value), new Array())
+    .option("-f, --format <format>", `output format (${queryFormats.join(", ")}; ` +
+    "default: inferred from the output file like for \"export\", else json)", envDefault("format"))
+    .option("-o, --output [<format>:]<output-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
+    .action(async (selector, opts) => {
+    const verbose = verboseOf(opts);
+    const output = parseQueryOutput(opts.output, opts.format);
+    const fallback = envDefault("param");
+    const given = opts.param.length > 0 ? opts.param : (fallback !== undefined ? [fallback] : []);
+    const params = {};
+    for (const param of given) {
+        const m = (/^([^=]+)=(.*)$/s).exec(param);
+        if (m === null)
+            throw new Error(`invalid query parameter "${param}" (expected "<name>=<value>")`);
+        params[m[1]] = m[2];
+    }
+    const specbook = new SpecBook({ verbose });
+    const document = await specbook.load({ config: configOf(opts), basedir: opts.basedir,
+        fetch: fetchOf(opts), gitignore: opts.gitignore, schema: opts.schema });
+    await writeOutput(output.output, renderNodes(document.query(selector, params), output.format), "query", verbose);
 });
 /*  the describe command also describes the generic SpecBook models and
     formats alone, so its YAML schema configuration stays optional  */
-withBasedirOption(withConfigOption(withVerboseOption(program.command("describe")), "the bundled standard schema configuration, embedded"), "none")
+withFetchOption(withBasedirOption(withConfigOption(withVerboseOption(program.command("describe")), "the bundled standard schema configuration, embedded"), "none"))
     .description("describe the SpecBook models and formats as Markdown")
     .option("-e, --embed", "embed the given YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
     .option("-z, --compress [level]", "compression level of the emitted YAML schema configuration " +
     "(0: verbatim, 1: re-emitted with 2-space indentation and without comments, " +
-    "2: also without \"refs\", \"diagram\", and \"format\" fields, " +
+    "2: also without \"refs\", \"badge\", \"multiple\", \"diagram\", and \"format\" fields, " +
     "3: also without \"desc\" fields; default and bare flag: 1)", envDefault("compress", "1"))
     .option("-f, --format <format>", `output format (${describeFormats.join(", ")})`, envDefault("format", "md"))
     .option("-p, --part <part>", `document part (${describeParts.join(", ")})`, envDefault("part", "all"))
@@ -232,10 +283,26 @@ withBasedirOption(withConfigOption(withVerboseOption(program.command("describe")
     const verbose = verboseOf(opts);
     const specbook = new SpecBook({ verbose });
     const text = await specbook.describe({ config: configOf(opts), basedir: opts.basedir,
-        embed: opts.embed, compress: parseCompressLevel(opts.compress),
+        fetch: fetchOf(opts), embed: opts.embed, compress: parseCompressLevel(opts.compress),
         format: parseDescribeFormat(opts.format), part: parseDescribePart(opts.part) });
     await writeOutput(opts.output, text, "describe", verbose);
 });
+/*  the search command finds the bundled schema configurations
+    and the shareable ones of the npm registry and GitHub  */
+withFetchOption(withVerboseOption(program.command("search")))
+    .description("search the bundled schema configurations, the npm registry, " +
+    "and GitHub for shareable schema configurations")
+    .argument("[term...]", "the words a matching schema configuration has to carry")
+    .action(async (term, opts) => {
+    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    const hits = await specbook.search({ term: term.join(" "), fetch: fetchOf(opts) });
+    if (hits.length === 0)
+        await writeStdout("no matching schema configurations found\n");
+    const width = Math.max(0, ...hits.map((hit) => hit.ref.length));
+    for (const hit of hits)
+        await writeStdout((`${hit.ref.padEnd(width)}  ` +
+            `${(hit.version ?? "").padEnd(8)}  ${hit.description ?? ""}`).trimEnd() + "\n");
+});
 /*  run the command line program  */
 try {
     await program.parseAsync();

package/dst/specbook-cmd-describe.js

@@ -21,9 +21,9 @@ export const parseDescribeFormat = (value) => parseChoice(describeFormats, "form
 export const parseDescribePart = (value) => parseChoice(describeParts, "part", value);
 /*  the supported compression levels of the emitted YAML schema
     configuration: verbatim (0), re-emitted with 2-space indentation and
-    without comments (1), additionally without its "refs", "diagram", and
-    "format" fields (2), and additionally without its "desc" fields of
-    objects and properties (3)  */
+    without comments (1), additionally without its "refs", "badge",
+    "multiple", "diagram", and "format" fields (2), and additionally
+    without its "desc" fields of objects and properties (3)  */
 export const compressLevels = [0, 1, 2, 3];
 /*  parse and validate a compression level specification,
     where a bare flag (or a boolean word) selects the plain re-emitting  */
@@ -48,7 +48,7 @@ const compressYaml = (yaml, level) => {
     if (level === 0)
         return yaml;
     const doc = parseDocument(yaml);
-    const drop = [["refs", "diagram", "format"], ["desc"]].slice(0, level - 1).flat();
+    const drop = [["refs", "badge", "multiple", "diagram", "format"], ["desc"]].slice(0, level - 1).flat();
     doc.commentBefore = null;
     doc.comment = null;
     visit(doc, {

package/dst/specbook-cmd-export-schema.d.ts

@@ -0,0 +1,8 @@
+import { type Verbose } from "./specbook-verbose.js";
+import { type LintResult } from "./specbook-cmd-lint.js";
+export interface SchemaLintOptions {
+    config: string[];
+    labels: Map<string, string>;
+    verbose: Verbose;
+}
+export declare const lintSchema: (options: SchemaLintOptions) => LintResult;