@rse/specbook 1.5.2 → 1.6.1

package/dst/specbook-cmd-export-schema.js

@@ -0,0 +1,441 @@
+/*
+**  Specification Book (SpecBook)
+**  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 { loadConfig, configStatistics, originKey } from "./specbook-config.js";
+import { metaConfig, version, reportOverlaps } from "./specbook-remote.js";
+import { literal } from "./specbook-verbose.js";
+import { renderDiagnostic } from "./specbook-diagnostic.js";
+import { parseSpecification, specStatistics } from "./specbook-parse.js";
+import { compileValueExpr } from "./specbook-parse-value.js";
+import { buildLinkIndex, resolveSet, referenceTo, outsideCode } from "./specbook-link.js";
+import { slugify } from "./specbook-parse-syntax.js";
+import { renderObjectMd, formatTimestamp } from "./specbook-export-md.js";
+/*  escape the Markdown-significant characters of a prose text (a
+    configuration file label), with its whitespace collapsed, so it
+    renders literally  */
+const escapeMd = (text) => text.replace(/\s+/g, " ").trim().replace(/[\\`*_[\]<>|]/g, "\\$&");
+/*  render a verbatim text (a value expression, a name pattern, a file
+    name, a configuration) as an inline code span, with its whitespace
+    collapsed, which renders it literally and in which its "[[...]]"
+    is plain code instead of a reference (the fence outgrows every
+    backtick run inside, padded where the text touches a backtick)  */
+const codeMd = (text) => {
+    const code = text.replace(/\s+/g, " ").trim();
+    const fence = "`".repeat(Math.max(0, ...Array.from(code.matchAll(/`+/g), (m) => m[0].length)) + 1);
+    const pad = code.startsWith("`") || code.endsWith("`") ? " " : "";
+    return `${fence}${pad}${code}${pad}${fence}`;
+};
+/*  escape a description text taken from the schema configuration for
+    the generated corpus, outside of its fenced code blocks and inline
+    code spans (in which a "[[" is plain code): every "[[" and "![" is
+    escaped, a line-leading "#" would open a heading, and the unordered
+    list items become ordered ones, as the former would be taken for
+    properties, while an inline code span carrying an "![" becomes
+    escaped plain text, as the parser loads an embedding even there  */
+const escapeDesc = (text) => outsideCode(text.trim().replace(/`([^`\n]*!\[[^`\n]*)`/g, (_, code) => escapeMd(code)), (part) => {
+    let counter = 0;
+    return part
+        .replace(/\[\[/g, "\\[\\[")
+        .replace(/!\[/g, "!\\[")
+        .split("\n").map((line) => {
+        const item = line.match(/^(\s*)[-*+]\s+(.*)$/);
+        if (item !== null)
+            return `${item[1]}${++counter}.  ${item[2]}`;
+        if ((/^\S/).test(line))
+            counter = 0;
+        return line.replace(/^(\s*)#/, "$1\\#");
+    }).join("\n");
+});
+/*  flatten a nested configuration value (an automaton, badge, multiple,
+    diagram, or format) into "key=value" pairs, with the nested keys dotted, the
+    lists of scalars bracketed, and the elements of the lists of objects
+    (the diagrams) indexed  */
+const flatten = (value, prefix = "") => {
+    if (Array.isArray(value) && value.some((item) => typeof item === "object" && item !== null))
+        return value.flatMap((item, i) => flatten(item, `${prefix}[${i}]`));
+    else if (Array.isArray(value))
+        return [`${prefix}=[${value.map((item) => String(item)).join(", ")}]`];
+    else if (typeof value === "object" && value !== null)
+        return Object.entries(value)
+            .filter(([, val]) => val !== undefined)
+            .flatMap(([key, val]) => flatten(val, prefix !== "" ? `${prefix}.${key}` : key));
+    else
+        return [`${prefix}=${String(value)}`];
+};
+/*  the "[[...]]" reference patterns a property value expression carries  */
+const patternsOf = (prop) => {
+    if (prop.value === undefined)
+        return [];
+    const expr = compileValueExpr(prop.value);
+    return (expr.kind === "list" ? expr.alternatives : [expr])
+        .flatMap((alternative) => alternative.kind === "reference" ? [alternative.pattern] : []);
+};
+/*  the cardinality of a reference-valued property: a single reference
+    or a "list" of them, required or optional  */
+const arityOf = (prop) => {
+    const many = prop.value !== undefined && compileValueExpr(prop.value).kind === "list";
+    return `${prop.optional === true ? "0.." : many ? "1.." : ""}${many ? "n" : "1"}`;
+};
+/*  the value of a sibling marker flag: "true", or its expression  */
+const markerOf = (flag) => flag === true ? "true" : typeof flag === "string" ? codeMd(flag) : undefined;
+/*  a count with its noun  */
+const plural = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
+/*  render a text as a Mermaid class diagram identifier (in the dotted
+    notation of the qualified references)  */
+const classId = (text) => text.replace(/[^A-Za-z0-9_.-]/g, "_");
+/*  render a non-reference property as a class attribute, typed by the
+    kind of its value constraint plus its multiplicity  */
+const classAttribute = (prop) => {
+    const kind = prop.value !== undefined ? compileValueExpr(prop.value).kind : "text";
+    return `${kind === "reference" ? "ref" : kind}[${prop.optional === true ? "0..1" : "1"}] ${classId(prop.name)}`;
+};
+/*  generate the Markdown sources of the specification describing a
+    schema configuration (against the meta schema configuration): the
+    title artifact and one (recurring) ARTIFACT-KIND artifact per
+    artifact kind, holding one ARTIFACT object per artifact, the
+    OBJECT-KIND objects flat below their artifact (in
+    pre-order, named after their kind, qualified by the parent kind on
+    a collision), and the PROPERTY/REFERENCE objects below the artifacts
+    and object kinds, where the reference patterns of the configuration
+    are resolved at the kind level against a skeleton corpus  */
+const generateSources = (config, meta, files, labels, origins) => {
+    const now = new Date();
+    /*  the skeleton corpus standing in for the configuration: one object
+        per schema node, the artifacts carrying their ids and names, so
+        the reference patterns resolve onto the kinds through the
+        regular resolution  */
+    const chains = new Map();
+    const skeletons = new Map();
+    const skeletonOf = (schema, chain) => {
+        const artifact = chain.length === 1;
+        const object = { kind: schema.kind,
+            id: artifact ? (schema.id ?? slugify(schema.name ?? schema.kind)) : "",
+            name: artifact ? (schema.name ?? "") : "", properties: [], children: [] };
+        if (artifact && schema.id !== undefined)
+            object.paren = schema.id;
+        chains.set(schema, chain);
+        skeletons.set(object, schema);
+        object.children = (schema.children ?? []).map((child) => skeletonOf(child, [...chain, child]));
+        return object;
+    };
+    const skeleton = { artifacts: config.map((schema) => ({ created: now, modified: now, objects: [skeletonOf(schema, [schema])] })) };
+    const skeletonIndex = buildLinkIndex(skeleton);
+    /*  the schema nodes a reference pattern matches at the kind level:
+        every name part is generalized to the wildcard, as the skeleton
+        knows the kinds only, and a pattern matching every node (like
+        "[[*]]") names no particular target  */
+    const targetsOf = (pattern) => {
+        const generalized = pattern.replace(/:("(?:[^"\\]|\\.)*"|[^.":]+)/g, ":*");
+        const matches = resolveSet(skeletonIndex, generalized).flatMap((object) => skeletons.get(object) ?? []);
+        return matches.length === skeletons.size ? [] : matches;
+    };
+    const targetsOfAll = (patterns) => Array.from(new Set(patterns.flatMap(targetsOf)));
+    /*  the meta objects: the title, the schema, the artifact kinds, the
+        artifacts, the object kinds, and the properties, where a property
+        whose value constraint references at least one kind is a REFERENCE  */
+    const metaObject = (kind, name, paren) => {
+        const o = { kind, id: paren ?? slugify(name), name, properties: [], children: [] };
+        if (paren !== undefined)
+            o.paren = paren;
+        return o;
+    };
+    const title = metaObject("META", "Title", "TI");
+    const kinds = new Map();
+    const metas = new Map();
+    const props = new Map();
+    const propertyObjects = (owner, chain) => {
+        for (const prop of chain[chain.length - 1].props ?? []) {
+            const targets = targetsOfAll(patternsOf(prop));
+            const o = metaObject(targets.length > 0 ? "REFERENCE" : "PROPERTY", prop.name);
+            props.set(o, { chain, prop, targets });
+            owner.children.push(o);
+        }
+    };
+    for (const schema of config) {
+        let kind = kinds.get(schema.kind);
+        if (kind === undefined) {
+            kind = metaObject("ARTIFACT-KIND", schema.kind);
+            kinds.set(schema.kind, kind);
+        }
+        const artifact = metaObject("ARTIFACT", schema.name ?? schema.id ?? schema.kind, schema.id);
+        metas.set(schema, artifact);
+        kind.children.push(artifact);
+        propertyObjects(artifact, [schema]);
+        /*  the object kinds, flat below their artifact in pre-order  */
+        const names = new Set();
+        const walk = (parent) => {
+            for (const child of parent.children ?? []) {
+                const name = names.has(child.kind) ? `${parent.kind}/${child.kind}` : child.kind;
+                names.add(name);
+                const o = metaObject("OBJECT-KIND", name);
+                metas.set(child, o);
+                artifact.children.push(o);
+                propertyObjects(o, chains.get(child) ?? [child]);
+                walk(child);
+            }
+        };
+        walk(schema);
+    }
+    /*  the references among the meta objects, shortest unique from
+        their referencing object (resolved through the final index)  */
+    const spec = { artifacts: [title, ...kinds.values()].map((o) => ({ created: now, modified: now, objects: [o] })) };
+    const index = buildLinkIndex(spec);
+    const ref = (target, from) => `[[${referenceTo(index, target, from)}]]`;
+    const refs = (targets, from) => targets.flatMap((target) => metas.get(target) ?? []).map((target) => ref(target, from)).join(", ");
+    /*  the display labels of the configuration files, and the origin of
+        a node (its contributing files, shown when several files are merged)  */
+    const labelOf = (file) => labels.get(file) ?? file;
+    const labelsMd = files.map((file) => escapeMd(labelOf(file))).join(", ");
+    const filesOf = (chain, prop) => origins.get(originKey(chain, prop)) ?? [];
+    const originOf = (origin) => files.length > 1 && origin.length > 0 ? origin.map((file) => codeMd(labelOf(file))).join(", ") : undefined;
+    /*  the property values of a meta object (the absent ones left out)  */
+    const push = (o, entries) => {
+        for (const [key, value] of entries)
+            if (value !== undefined)
+                o.properties.push({ key, value });
+    };
+    const patternsMd = (patterns) => patterns !== undefined ? codeMd(patterns.join(", ")) : undefined;
+    const configMd = (value) => value !== undefined ? codeMd(flatten(value).join(", ")) : undefined;
+    /*  the title: the document properties and the abstract  */
+    const stats = configStatistics(config);
+    push(title, [
+        ["TITLE", "Schema Configuration"],
+        ["SUBTITLE", labelsMd],
+        ["VERSION", `SpecBook ${version}`],
+        ["LANG", "en"]
+    ]);
+    title.description = {
+        description: `The schema configuration ${labelsMd} specifies ${plural(kinds.size, "artifact kind")} ` +
+            `with ${plural(config.length, "artifact")}, ${plural(stats.objects - config.length, "object kind")}, ` +
+            `and ${plural(stats.links, "reference relationship")}.`,
+        elaboration: "Every artifact and object kind lists its properties (`PROPERTY`) and its " +
+            "reference-valued properties (`REFERENCE`, the edges of the diagrams, leading to the " +
+            "artifacts and object kinds the value constraint references), and every object kind " +
+            "names the artifact or object kind it is nested directly below (`PARENT`). The value " +
+            "constraints, name patterns, and configurations are quoted verbatim from the schema " +
+            "configuration.\n\n" +
+            "The UML class diagram of an artifact shows the artifact (stereotyped `artifact`) and " +
+            "its object kinds as classes with their properties as attributes (typed by the kind of " +
+            "their value constraint and their multiplicity), their nesting as compositions, and " +
+            "their reference-valued properties as associations labeled with the property and its " +
+            "arity, where a referenced artifact or object kind of another artifact appears as a bare class."
+    };
+    /*  the UML class diagram of an artifact and its object kinds -- the
+        artifact stereotyped, the non-reference properties as typed
+        attributes, the nesting as compositions, and the reference-valued
+        properties as labeled associations with their arity (none for a
+        degenerate diagram without any relationship, exactly like the
+        collapsed Gradia diagrams)  */
+    const membersOf = (artifacts) => {
+        const members = new Array();
+        const collect = (schema) => {
+            members.push(schema);
+            for (const child of schema.children ?? [])
+                collect(child);
+        };
+        artifacts.forEach(collect);
+        return members;
+    };
+    const classDiagramOf = (artifacts) => {
+        const members = membersOf(artifacts);
+        /*  the class names in the notation of the references: an artifact
+            as "<kind>.<id>", an object kind by its kind, qualified by the
+            id of its artifact (and then by its parent kind) only where
+            the name collides among the classes of the diagram  */
+        const shown = new Set([...members,
+            ...members.flatMap((schema) => (schema.props ?? []).flatMap((prop) => targetsOfAll(patternsOf(prop))))]);
+        const names = new Map();
+        const unique = (candidate, nodes) => {
+            const counts = new Map();
+            for (const schema of nodes)
+                counts.set(candidate(schema), (counts.get(candidate(schema)) ?? 0) + 1);
+            return nodes.filter((schema) => {
+                if (counts.get(candidate(schema)) !== 1)
+                    return true;
+                names.set(schema, classId(candidate(schema)));
+                return false;
+            });
+        };
+        const artifactLabel = (schema) => schema.id ?? slugify(schema.name ?? schema.kind);
+        for (const schema of shown) {
+            const chain = chains.get(schema) ?? [schema];
+            if (chain.length === 1)
+                names.set(schema, classId(`${schema.kind}.${artifactLabel(schema)}`));
+        }
+        const qualified = (schema) => `${artifactLabel((chains.get(schema) ?? [schema])[0])}.${schema.kind}`;
+        const nested = (schema) => `${artifactLabel((chains.get(schema) ?? [schema])[0])}.` +
+            (metas.get(schema)?.name ?? schema.kind).replace(/\//g, ".");
+        let rest = Array.from(shown).filter((schema) => !names.has(schema));
+        rest = unique((schema) => schema.kind, rest);
+        rest = unique(qualified, rest);
+        for (const schema of rest)
+            names.set(schema, classId(nested(schema)));
+        const classOf = (schema) => names.get(schema) ?? classId(schema.kind);
+        const relations = new Array();
+        for (const schema of members) {
+            for (const child of schema.children ?? [])
+                relations.push(`    ${classOf(schema)} *-- "${child.optional === true ? "0..n" : "1..n"}" ` +
+                    classOf(child));
+            for (const prop of schema.props ?? [])
+                for (const target of targetsOfAll(patternsOf(prop)))
+                    relations.push(`    ${classOf(schema)} --> "${arityOf(prop)}" ${classOf(target)} : ${prop.name}`);
+        }
+        if (relations.length === 0)
+            return undefined;
+        const lines = ["classDiagram"];
+        for (const schema of members) {
+            lines.push(`    class ${classOf(schema)} {`);
+            if ((chains.get(schema) ?? [schema]).length === 1)
+                lines.push("        <<artifact>>");
+            for (const prop of schema.props ?? [])
+                if (targetsOfAll(patternsOf(prop)).length === 0)
+                    lines.push(`        ${classAttribute(prop)}`);
+            lines.push("    }");
+        }
+        return [...lines, ...relations].join("\n") + "\n";
+    };
+    /*  the artifact kinds: their artifacts  */
+    for (const [name, o] of kinds) {
+        const artifacts = config.filter((schema) => schema.kind === name);
+        push(o, [["ORIGIN", originOf(Array.from(new Set(artifacts.flatMap((schema) => filesOf([schema])))))]]);
+        o.description = {
+            description: `The artifact kind **${escapeMd(name)}** comprises ${plural(artifacts.length, "artifact")}: ` +
+                `${refs(artifacts, o)}.`
+        };
+    }
+    /*  the class diagram of an artifact, introduced by its figures: its
+        object kinds and associations, plus the other artifacts the
+        associations reach into  */
+    const classDiagramMd = (schema, o) => {
+        const uml = classDiagramOf([schema]);
+        if (uml === undefined)
+            return undefined;
+        const members = membersOf([schema]);
+        const targets = members.flatMap((member) => (member.props ?? []).flatMap((prop) => targetsOfAll(patternsOf(prop))));
+        const foreign = Array.from(new Set(targets.map((target) => (chains.get(target) ?? [target])[0])))
+            .filter((artifact) => artifact !== schema);
+        return `The class diagram shows ${plural(members.length - 1, "object kind")} of the artifact` +
+            (targets.length > 0 ? ` with ${plural(targets.length, "association")}` : "") +
+            (foreign.length > 0 ? `, reaching into ${refs(foreign, o)}` : "") +
+            ".\n\n```mermaid\n" + uml + "```";
+    };
+    /*  the artifacts and object kinds: their configuration, their
+        description, and the prose of their relationships  */
+    const kindsMd = (patterns, o) => {
+        const inner = patterns.map((pattern) => compileValueExpr(pattern))
+            .flatMap((expr) => expr.kind === "reference" ? [expr.pattern] : []);
+        const targets = targetsOfAll(inner);
+        return targets.length > 0 ? `the ${refs(targets, o)} objects` :
+            inner.includes("*") ? "any object" : `the objects matching ${codeMd(patterns.join(", "))}`;
+    };
+    for (const [schema, o] of metas) {
+        const chain = chains.get(schema) ?? [schema];
+        const parent = chain.length >= 2 ? metas.get(chain[chain.length - 2]) : undefined;
+        push(o, [
+            ["ORIGIN", originOf(filesOf(chain))],
+            ["PARENT", parent !== undefined ? ref(parent, o) : undefined],
+            ["FILE", chain.length === 1 && schema.file !== undefined ? codeMd(schema.file) : undefined],
+            ["NAME", chain.length > 1 && schema.name !== undefined ? codeMd(schema.name) : undefined],
+            ["OPTIONAL", schema.optional === true ? "true" : "false"],
+            ["REFERENCED", patternsMd(schema.referenced)],
+            ["COVERAGE", patternsMd(schema.coverage)],
+            ["AUTOMATON", configMd(schema.automaton)],
+            ["BADGE", typeof schema.badge === "string" ? codeMd(schema.badge) : configMd(schema.badge)],
+            ["MULTIPLE", configMd(schema.multiple)],
+            ["DIAGRAM", configMd(schema.diagram)],
+            ["FORMAT", configMd(schema.format)]
+        ]);
+        const parts = new Array();
+        const subject = `Every object of the kind **${escapeMd(schema.kind)}**`;
+        if (schema.referenced !== undefined)
+            parts.push(`${subject} has to be referenced from ${kindsMd(schema.referenced, o)}.`);
+        if (schema.coverage !== undefined)
+            parts.push(`${subject} reports the reference coverage of ${kindsMd(schema.coverage, o)}.`);
+        if (schema.automaton !== undefined) {
+            const automaton = schema.automaton;
+            const childMd = (kind) => {
+                const child = (schema.children ?? []).find((c) => c.kind === kind);
+                const target = child !== undefined ? metas.get(child) : undefined;
+                return target !== undefined ? ref(target, o) : `\`${kind}\``;
+            };
+            parts.push(`The ${childMd(automaton.nodes)} children form a finite state machine, whose ` +
+                `${childMd(automaton.edges)} children lead from the node their \`${automaton.source}\` names ` +
+                `to the node their \`${automaton.target}\` names, where \`${automaton.initial}\` flags the ` +
+                `initial and \`${automaton.final}\` the final nodes.`);
+        }
+        if (schema.refs !== undefined)
+            parts.push(`References:\n\n${escapeDesc(schema.refs)}`);
+        const uml = chain.length === 1 ? classDiagramMd(schema, o) : undefined;
+        if (uml !== undefined)
+            parts.push(uml);
+        o.description = { description: escapeDesc(schema.desc ?? `The objects of the kind \`${schema.kind}\`.`),
+            elaboration: parts.length > 0 ? parts.join("\n\n") : undefined };
+    }
+    /*  the properties: their constraint, flags, and targets  */
+    for (const [o, { chain, prop, targets }] of props) {
+        push(o, [
+            ["ORIGIN", originOf(filesOf(chain, prop))],
+            ["OPTIONAL", prop.optional === true ? "true" : "false"],
+            ["VALUE", prop.value !== undefined ? codeMd(prop.value) : undefined],
+            ["TARGET", targets.length > 0 ? refs(targets, o) : undefined],
+            ["ARITY", targets.length > 0 ? arityOf(prop) : undefined],
+            ["UNIQUE", markerOf(prop.unique)],
+            ["PRESENT", markerOf(prop.present)],
+            ["LOCAL", prop.local === true ? "true" : undefined],
+            ["SYMMETRIC", prop.symmetric === true ? "true" : undefined],
+            ["ACYCLIC", prop.acyclic === true ? "true" : undefined]
+        ]);
+        o.description = { description: escapeDesc(prop.desc ?? `The property \`${prop.name}\`.`) };
+    }
+    /*  render the title artifact and the (recurring) artifact kind
+        artifacts into the Markdown sources of their configured files,
+        timestamped with the oldest and the latest configuration file  */
+    const times = files.map((file) => fs.statSync(file).mtime.getTime());
+    const created = formatTimestamp(new Date(Math.min(...times)));
+    const modified = formatTimestamp(new Date(Math.max(...times)));
+    const source = (objects) => ({
+        file: meta.find((schema) => schema.kind === objects[0].kind)?.file ?? `${objects[0].kind}.md`,
+        text: `---\nCreated:  ${created}\nModified: ${modified}\n---\n\n` +
+            objects.map((o) => renderObjectMd(o, 1)).join("\n\n") + "\n"
+    });
+    return [source([title]), ...(kinds.size > 0 ? [source(Array.from(kinds.values()))] : [])];
+};
+/*  generate the specification describing the effective schema
+    configuration and parse it against the bundled meta schema
+    configuration, exactly like "lint" parses the specification files,
+    so the result feeds the very same exports (the generated sources
+    carry no files to observe beyond the configuration ones)  */
+export const lintSchema = (options) => {
+    const { verbose } = options;
+    const diagnostics = new Array();
+    /*  load the schema configuration to describe, merged out of its files  */
+    verbose("loading schema configuration " +
+        options.config.map((file) => `"${literal(file)}"`).join(", "));
+    const loaded = loadConfig(options.config);
+    diagnostics.push(...loaded.diagnostics);
+    reportOverlaps(loaded.overlaps, verbose);
+    const config = loaded.config;
+    if (config === undefined)
+        return { specification: { artifacts: [] }, diagnostics, files: [], origins: new Map() };
+    const stats = configStatistics(config);
+    verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
+        `and ${literal(stats.links)} link relationship(s)`);
+    /*  load the bundled meta schema configuration the generated specification follows  */
+    const meta = loadConfig([metaConfig]);
+    if (meta.config === undefined)
+        throw new Error("invalid meta schema configuration:\n" +
+            meta.diagnostics.map(renderDiagnostic).join("\n"));
+    /*  generate and parse the specification describing the schema configuration  */
+    const sources = generateSources(config, meta.config, options.config, options.labels, loaded.origins);
+    verbose(`parsing ${literal(sources.length)} generated specification file(s) describing the schema configuration`);
+    const result = parseSpecification(sources, meta.config);
+    diagnostics.push(...result.diagnostics);
+    const specStats = specStatistics(result.specification);
+    verbose(`parsed specification defining ${literal(specStats.objects)} object(s) ` +
+        `and ${literal(specStats.links)} link relationship(s)`);
+    return { specification: result.specification, diagnostics, config: meta.config,
+        files: [], origins: result.origins };
+};

package/dst/specbook-cmd-export.js

@@ -4,6 +4,7 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import * as fs from "node:fs";
+import * as path from "node:path";
 /*  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  */
@@ -16,6 +17,7 @@ import { renderMarkdown } from "./specbook-export-md.js";
 import { renderHtml, htmlOutline, titlePageObject } from "./specbook-export-html.js";
 import { htmlToPdf, requireBrowser } from "./specbook-export-pdf.js";
 import { literal } from "./specbook-verbose.js";
+import { specFiles } from "./specbook-files.js";
 /*  re-export the browser pre-check of the PDF renderer, so the API
     facade reaches the renderers through this command module only  */
 export { requireBrowser };
@@ -66,12 +68,16 @@ const watchDelay = 1000;
 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  */
+    so its creation and removal are noticed like a modification, while a
+    directory is represented by the number of its specification files,
+    as its own modification time also changes with every unrelated file
+    created in it (like an editor swap file)  */
 const snapshot = (files) => {
     const times = new Map();
     for (const file of files) {
         try {
-            times.set(file, fs.statSync(file).mtimeMs);
+            const stats = fs.statSync(file);
+            times.set(file, stats.isDirectory() ? specFiles(file).length : stats.mtimeMs);
         }
         catch {
             times.set(file, 0);
@@ -92,7 +98,15 @@ export const watchSpecification = async (run, verbose) => {
     const started = Date.now();
     let observed = await run();
     let times = snapshot(observed);
-    const watcher = watch(observed, { ignoreInitial: true });
+    /*  the observed set carries the base directory as a whole (so the
+        added and removed specification files are noticed, too), below
+        which only the Markdown files and the explicitly observed files
+        count, as any other file written into it (like an export output)
+        would re-trigger the export endlessly, and whose "."-prefixed
+        directories (like ".git") the specification never spans  */
+    const watcher = watch(observed, { ignoreInitial: true,
+        ignored: (file, stats) => stats !== undefined && !observed.includes(file)
+            && (stats.isDirectory() ? path.basename(file).startsWith(".") : !file.endsWith(".md")) });
     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  */
@@ -100,13 +114,16 @@ export const watchSpecification = async (run, verbose) => {
         verbose("observing failed: " +
             (err instanceof Error ? err.message : String(err)), "none");
     });
-    /*  perform a re-export and re-synchronize the observed files  */
+    /*  perform a re-export and re-synchronize the observed files (the
+        observed set is replaced before the watcher is fed, as its filter
+        above consults it)  */
     const cycle = async () => {
         const files = await run();
-        watcher.unwatch(observed.filter((file) => !files.includes(file)));
-        watcher.add(files.filter((file) => !observed.includes(file)));
+        const previous = observed;
         observed = files;
         times = snapshot(files);
+        watcher.unwatch(previous.filter((file) => !files.includes(file)));
+        watcher.add(files.filter((file) => !previous.includes(file)));
     };
     /*  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

package/dst/specbook-cmd-init-sample.d.ts

@@ -0,0 +1,4 @@
+import { type SchemaObject } from "./specbook-format-schema.js";
+import { type SpecObject } from "./specbook-format-spec.js";
+export declare const wrapSample: (text: string) => string;
+export declare const sampleArtifacts: (artifacts: SchemaObject[]) => Map<SchemaObject, SpecObject>;