@rse/specbook 1.5.2 → 1.6.1

package/dst/specbook-cmd-init-sample.js

@@ -0,0 +1,322 @@
+/*
+**  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 RandExpModule from "randexp";
+import wrapAnsi from "wrap-ansi";
+import { compileValueExpr, anchored } from "./specbook-parse-value.js";
+import { slugify } from "./specbook-parse-syntax.js";
+import { buildLinkIndex, resolveSet, referenceTo, chainOf } from "./specbook-link.js";
+import { titleProperties, isTitleObject } from "./specbook-export-common.js";
+import { referencedCoverage } from "./specbook-coverage.js";
+const RandExp = RandExpModule;
+/*  the fixed rationale of every sample description, which explains the
+    statement/rationale split of a description by example  */
+const rationale = "the sample shows that a description states what holds and, behind the keyword, why it holds.";
+/*  the capitalized words of a kind or property name
+    ("USE-CASE" yields "Use" and "Case")  */
+const wordsOf = (name) => name.split(/[^A-Za-z0-9]+/).filter((word) => word !== "")
+    .map((word) => word[0].toUpperCase() + word.slice(1).toLowerCase());
+/*  the leading word of a sample object or value: the first object of a
+    kind is the "Sample ..." one, its partner the "Other ..." one  */
+const ordinalWord = (ordinal) => ordinal === 0 ? "Sample" : "Other";
+/*  the casing variants of a word list, the title case first  */
+const casings = (words) => {
+    const lower = words.map((word) => word.toLowerCase());
+    const upper = words.map((word) => word.toUpperCase());
+    return [words.join(" "), words.join(""), lower[0] + words.slice(1).join(""),
+        lower.join("-"), lower.join("_"), upper.join("-"), upper.join("_"),
+        lower.join(" "), upper.join(" "), lower.join(""), upper.join("")];
+};
+/*  generate a text matching a regular expression deterministically (the
+    random choices of RandExp replaced by the lowest option, shifted by
+    the ordinal, so a partner object receives a distinct text, and its
+    free characters restricted to letters and digits, as the Markdown
+    parsing would strip a leading or trailing whitespace), or none if
+    the expression is beyond RandExp  */
+const generate = (regex, ordinal) => {
+    try {
+        const randexp = new RandExp(regex);
+        randexp.randInt = (a, b) => Math.min(a + ordinal, b);
+        for (const [a, b] of [[0, 47], [58, 64], [91, 96], [123, 126]])
+            randexp.defaultRange.subtract(a, b);
+        const text = randexp.gen();
+        return regex.test(text) && text.trim() === text ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/*  derive the name of a sample object: the first casing variant of
+    "Sample <Kind>", else of the single word "Sample", matching the
+    configured name pattern, else a generated match, else the plain
+    title case (which the check reports)  */
+const sampleName = (schema, ordinal) => {
+    const words = [ordinalWord(ordinal), ...wordsOf(schema.kind)];
+    if (schema.name === undefined)
+        return words.join(" ");
+    const regex = anchored(schema.name);
+    const name = [...casings(words), ...casings([ordinalWord(ordinal)])].find((text) => regex.test(text));
+    return name ?? generate(regex, ordinal) ?? words.join(" ");
+};
+/*  the first sentence of a text (its first paragraph up to the first
+    sentence-ending punctuation not closing an abbreviation), without
+    its trailing punctuation  */
+const firstSentence = (text) => {
+    const paragraph = text.trim().split(/\n\s*\n/)[0].replace(/\s+/g, " ");
+    const sentence = paragraph.match(/^.*?(?<!\b(?:e\.g|i\.e|etc|vs|cf|resp))[.!?](?=\s|$)/)?.[0] ?? paragraph;
+    return sentence.replace(/[.!?]$/, "");
+};
+/*  the number of sample objects of a child kind: two where a relation
+    needs a partner -- the node kind of the automaton of the parent and
+    a kind carrying a symmetric or acyclic property -- and one otherwise  */
+const countOf = (parent, child) => (parent.automaton?.nodes === child.kind
+    || (child.props ?? []).some((prop) => prop.symmetric === true || prop.acyclic === true)) ? 2 : 1;
+/*  instantiate the sample objects of a schema node (recursively) with
+    their names and ids only, as the property values need the whole
+    corpus, where a recurring artifact (configured without a name) is
+    named like a nested object  */
+const instantiate = (schema, ordinal, count, samples, parent) => {
+    const name = parent === undefined && schema.name !== undefined ? schema.name : sampleName(schema, ordinal);
+    const object = { kind: schema.kind, id: schema.id ?? slugify(name), name, properties: [], children: [] };
+    if (schema.id !== undefined)
+        object.paren = schema.id;
+    const sample = { object, schema, ordinal, count, parent };
+    samples.push(sample);
+    for (const child of schema.children ?? []) {
+        const n = countOf(schema, child);
+        for (let i = 0; i < n; i++)
+            object.children.push(instantiate(child, i, n, samples, sample));
+    }
+    return object;
+};
+/*  match a text directly against a regex or enum expression  */
+const matches = (expr, text) => (expr.kind === "regex" && expr.regex.test(text))
+    || (expr.kind === "enum" && expr.members.includes(text));
+/*  the objects a reference pattern matches, the ones nearest to the
+    referencing object (sharing the longest ancestor chain with it)
+    first and the referencing object itself last, as a self-reference
+    is the last resort only  */
+const targetsOf = (index, pattern, from) => {
+    const chain = chainOf(index, from);
+    const proximity = (object) => {
+        if (object === from)
+            return -1;
+        const other = chainOf(index, object);
+        let i = 0;
+        while (i < chain.length && i < other.length && chain[i] === other[i])
+            i++;
+        return i;
+    };
+    return resolveSet(index, pattern)
+        .map((object, pos) => ({ object, pos, proximity: proximity(object) }))
+        .sort((a, b) => b.proximity - a.proximity || a.pos - b.pos)
+        .map((entry) => entry.object);
+};
+/*  the candidate values of a property, in order of preference: the
+    members of an enum/tags, the references onto the nearest objects of
+    a reference pattern, the alternatives of a list in order, and the
+    placeholders matching a regex -- "Sample <Name>" first, then the
+    common literals, then a generated match -- or, without a value
+    constraint, the placeholder alone  */
+const candidates = (prop, expr, index, from, ordinal) => {
+    const placeholder = `${ordinalWord(ordinal)} ${wordsOf(prop.name).join(" ")}`;
+    if (expr === undefined)
+        return [placeholder];
+    else if (expr.kind === "enum" || expr.kind === "tags")
+        return [...expr.members];
+    else if (expr.kind === "reference")
+        return targetsOf(index, expr.pattern, from).map((target) => `[[${referenceTo(index, target, from)}]]`);
+    else if (expr.kind === "list")
+        return expr.alternatives.flatMap((alternative) => candidates(prop, alternative, index, from, ordinal));
+    const literals = [placeholder, "true", "false", "1", "2", "0"].filter((text) => expr.regex.test(text));
+    if (literals.length > 0)
+        return literals;
+    const generated = generate(expr.regex, ordinal);
+    return generated !== undefined ? [generated] : [];
+};
+/*  the value of a property on a sample object: the first candidate,
+    where a "present" expression prefers a candidate matching it on the
+    first object of the kind and a "unique" flag skips the candidates
+    the sibling objects of the kind already carry (all of them, or the
+    ones matching its expression), or none if no candidate exists  */
+const valueOf = (sample, prop, index) => {
+    const expr = prop.value !== undefined ? compileValueExpr(prop.value) : undefined;
+    const compile = (flag) => typeof flag === "string" ? compileValueExpr(flag) : undefined;
+    const present = compile(prop.present);
+    const unique = compile(prop.unique);
+    const list = candidates(prop, expr, index, sample.object, sample.ordinal);
+    if (sample.ordinal === 0 && present !== undefined)
+        list.sort((a, b) => Number(matches(present, b)) - Number(matches(present, a)));
+    const taken = (sample.parent?.object.children ?? [])
+        .filter((child) => child.kind === sample.object.kind && child !== sample.object)
+        .flatMap((child) => child.properties.filter((p) => p.key === prop.name).map((p) => p.value));
+    const applies = (value) => prop.unique === true || (unique !== undefined && matches(unique, value));
+    return list.find((value) => !applies(value) || !taken.includes(value)) ?? list[0];
+};
+/*  fill in the property values of a sample object: the title object
+    keeps the properties the exports interpret at their rendering
+    defaults, the automaton of the parent dictates the flags of a node
+    (the first node is the initial one, the last node the final one) and
+    the ends of an edge (from the first node to the last one), an
+    acyclic property is carried by the first object of its kind only,
+    and an optional property no candidate satisfies is left out, while
+    a required one stays empty (which the check reports)  */
+const fill = (sample, index) => {
+    const automaton = sample.parent?.schema.automaton;
+    const title = isTitleObject(sample.object);
+    const siblings = (kind) => sample.parent?.object.children.filter((child) => child.kind === kind) ?? [];
+    for (const prop of sample.schema.props ?? []) {
+        let value;
+        const seeded = title ? titleProperties.find((p) => p.name === prop.name) : undefined;
+        if (seeded !== undefined)
+            value = seeded.init;
+        else if (automaton !== undefined && sample.object.kind === automaton.nodes
+            && (prop.name === automaton.initial || prop.name === automaton.final)) {
+            const flagged = prop.name === automaton.initial ?
+                sample.ordinal === 0 : sample.ordinal === sample.count - 1;
+            const expr = prop.value !== undefined ? compileValueExpr(prop.value) : undefined;
+            value = flagged ? "true" : candidates(prop, expr, index, sample.object, sample.ordinal)
+                .find((candidate) => candidate !== "true");
+        }
+        else if (automaton !== undefined && sample.object.kind === automaton.edges
+            && (prop.name === automaton.source || prop.name === automaton.target)) {
+            const nodes = siblings(automaton.nodes);
+            const node = nodes[prop.name === automaton.source ? 0 : nodes.length - 1];
+            value = node !== undefined ? `[[${referenceTo(index, node, sample.object)}]]` : undefined;
+        }
+        else if (prop.acyclic === true && sample.ordinal > 0 && prop.optional === true)
+            continue;
+        else
+            value = valueOf(sample, prop, index);
+        if (value === undefined && prop.optional === true)
+            continue;
+        sample.object.properties.push({ key: prop.name, value: value ?? "" });
+    }
+};
+/*  add the references the "referenced"-flagged kinds demand: an object
+    lacking its coverage gets referenced from an object matching one of
+    the patterns of its kind (or from below one, but never from within
+    its own subtree), preferably by extending a list-valued property
+    admitting it -- one without a uniqueness or relation flag, whose
+    shape the extension could break, and keeping a "local" one local --
+    and else through the elaboration of the description of the first
+    such object, as every reference of a description counts, too  */
+const cover = (samples, index) => {
+    const schemas = new Map(samples.map((sample) => [sample.object, sample.schema]));
+    const fallbacks = new Map();
+    for (const { schema, uncovered } of referencedCoverage(index, schemas)) {
+        const sources = new Set((schema.referenced ?? []).flatMap((pattern) => {
+            const expr = compileValueExpr(pattern);
+            return expr.kind === "reference" ? resolveSet(index, expr.pattern) : [];
+        }));
+        for (const object of uncovered) {
+            const referrers = samples.filter((sample) => {
+                const chain = chainOf(index, sample.object);
+                return chain.some((o) => sources.has(o)) && !chain.includes(object);
+            });
+            const admits = (sample, prop) => {
+                if (prop.value === undefined || (prop.unique ?? false) !== false
+                    || prop.symmetric === true || prop.acyclic === true)
+                    return false;
+                const expr = compileValueExpr(prop.value);
+                if (expr.kind !== "list" || !expr.alternatives.some((alternative) => alternative.kind === "reference" && resolveSet(index, alternative.pattern).includes(object)))
+                    return false;
+                const chain = chainOf(index, sample.object);
+                return prop.local !== true || chain.length < 2
+                    || chainOf(index, object).includes(chain[chain.length - 2]);
+            };
+            const target = referrers.map((sample) => ({ referrer: sample, prop: (sample.schema.props ?? []).find((p) => admits(sample, p)) }))
+                .find((entry) => entry.prop !== undefined);
+            if (target?.prop !== undefined) {
+                /*  extend (or add) the first admitting property, keeping
+                    the properties in the order of the schema  */
+                const { referrer, prop } = target;
+                const props = referrer.schema.props ?? [];
+                const reference = `[[${referenceTo(index, object, referrer.object)}]]`;
+                const property = referrer.object.properties.find((p) => p.key === prop.name);
+                if (property === undefined) {
+                    referrer.object.properties.push({ key: prop.name, value: reference });
+                    referrer.object.properties.sort((a, b) => props.findIndex((p) => p.name === a.key) - props.findIndex((p) => p.name === b.key));
+                }
+                else
+                    property.value = property.value !== "" ? `${property.value}, ${reference}` : reference;
+            }
+            else if (referrers.length > 0) {
+                const from = referrers[0].object;
+                fallbacks.set(from, [...(fallbacks.get(from) ?? []), `[[${referenceTo(index, object, from)}]]`]);
+            }
+        }
+    }
+    for (const [object, references] of fallbacks)
+        if (object.description !== undefined)
+            object.description.elaboration = `The sample references ${references.join(", ")}, ` +
+                `as the schema configuration demands ${references.length === 1 ? "it" : "them"} ` +
+                "to be referenced from here.";
+};
+/*  the maximum line width of the rendered sample, and the placeholder
+    protecting a space from becoming a line break (the ones inside the
+    references and code spans, and the ones of the kept line prefix)  */
+const lineWidth = 100;
+const space = "\u{E000}";
+/*  wrap the text parts of the rendered sample -- the descriptions and the
+    property values -- onto lines of at most 100 characters through
+    wrap-ansi, which breaks just the text part of an overlong line and
+    never the Markdown structure in front of it: the line prefix
+    (indentation, list marker, property key, or the leading segments of a
+    Concise Format item) stays on the first line as an unbreakable word,
+    and the continuation lines are indented onto the text column of the
+    line, while a line whose wrapping would start a continuation line with
+    a block marker stays unwrapped  */
+export const wrapSample = (text) => text.split("\n").flatMap((line) => {
+    if (line.length <= lineWidth || line.startsWith("#"))
+        return [line];
+    /*  the kept prefix: the indentation of a plain line, else the part
+        of a list item up to its description (behind the last segment
+        separator of a Concise Format item) or up to its property value  */
+    const item = line.match(/^(\s*)- {3}/);
+    const indent = item !== null ? item[1].length + 4 : (line.match(/^\s*/)?.[0].length ?? 0);
+    const prefix = item === null ? line.slice(0, indent) :
+        line.includes("; ") ? line.slice(0, line.lastIndexOf("; ") + 2) :
+            (line.match(/^\s*- {3}[^:]*:\s*/)?.[0] ?? item[0]);
+    /*  wrap the line behind its continuation indentation, with the
+        spaces of the prefix (but its last one) and of the atoms protected  */
+    const head = prefix.slice(indent);
+    const input = head.replace(/ (?=.)/g, space) + line.slice(prefix.length)
+        .replace(/\[\[[^\]]*\]\]|`[^`]*`/g, (atom) => atom.replaceAll(" ", space));
+    const output = wrapAnsi(input, lineWidth - indent, { hard: false, trim: true })
+        .replaceAll(space, " ").split("\n");
+    if (output.slice(1).some((cont) => /^(?:[-+*>#]|\d+[.)])(?:\s|$)/.test(cont)))
+        return [line];
+    return [`${line.slice(0, indent)}${output[0]}`,
+        ...output.slice(1).map((cont) => `${" ".repeat(indent)}${cont}`)];
+}).join("\n");
+/*  generate the sample objects of the given artifacts (all at once, as
+    the references of the sample reach across the artifacts): one object
+    per allowed kind (two where a relation needs a partner), carrying
+    every configured property with a placeholder value satisfying its
+    constraint and the first sentence of the schema description of its
+    kind as its statement, mapped per artifact onto its level 1 object  */
+export const sampleArtifacts = (artifacts) => {
+    const samples = new Array();
+    const roots = new Map();
+    for (const artifact of artifacts)
+        roots.set(artifact, instantiate(artifact, 0, 1, samples));
+    /*  the property values are filled in once all objects exist, as the
+        reference-valued ones target the nearest sample object of their
+        pattern through the link index of the whole sample  */
+    const now = new Date();
+    const spec = { artifacts: Array.from(roots.values()).map((object) => ({ created: now, modified: now, objects: [object] })) };
+    const index = buildLinkIndex(spec);
+    for (const sample of samples) {
+        fill(sample, index);
+        sample.object.description = {
+            description: sample.schema.desc !== undefined ?
+                firstSentence(sample.schema.desc) : `The sample ${sample.schema.kind} object`,
+            rationale
+        };
+    }
+    cover(samples, index);
+    return roots;
+};

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

@@ -3,6 +3,7 @@ import { type Schema } from "./specbook-format-schema.js";
 export interface InitOptions {
     config: Schema;
     basedir: string;
+    sample: boolean;
     verbose: Verbose;
 }
 export declare const initSpecification: (options: InitOptions) => string[];

package/dst/specbook-cmd-init.js

@@ -6,8 +6,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { literal } from "./specbook-verbose.js";
-import { formatTimestamp } from "./specbook-export-md.js";
+import { renderDiagnostic } from "./specbook-diagnostic.js";
+import { parseSpecification, specStatistics, isRecurring } from "./specbook-parse.js";
+import { formatTimestamp, renderObjectMd } from "./specbook-export-md.js";
 import { titleProperties } from "./specbook-export-common.js";
+import { sampleArtifacts, wrapSample } from "./specbook-cmd-init-sample.js";
 /*  render the property list of the title artifact, seeding the properties
     the exports interpret themselves with their rendering defaults (as far
     as the schema configures them, as any other is reported as unknown)  */
@@ -22,15 +25,16 @@ const titleList = (artifact) => {
 };
 /*  initialize the configured specification artifact files below the
     base directory with their frontmatter and artifact headings (plus
-    the title properties), where
-    all artifacts configured onto the same file reside in it side by
-    side, following each other on level 1  */
+    the title properties), or, under "sample", with a sample object per
+    allowed object kind, where all artifacts configured onto the same
+    file reside in it side by side, following each other on level 1  */
 export const initSpecification = (options) => {
     fs.mkdirSync(options.basedir, { recursive: true });
     const now = formatTimestamp(new Date());
     const created = new Array();
     /*  group the configured artifacts by their file, preserving the
-        schema order both of the files and of the artifacts within  */
+        schema order both of the files and of the artifacts within,
+        and skipping the already existing files  */
     const groups = new Map();
     for (const artifact of options.config) {
         if (artifact.file === undefined)
@@ -41,15 +45,29 @@ export const initSpecification = (options) => {
         else
             group.push(artifact);
     }
+    for (const file of groups.keys())
+        if (fs.existsSync(path.join(options.basedir, file))) {
+            options.verbose(`skipping existing artifact file "${literal(file)}"`);
+            groups.delete(file);
+        }
+    /*  generate the sample objects over the artifacts of all files to
+        be created at once, as the references of the sample reach
+        across the files  */
+    const samples = options.sample ?
+        sampleArtifacts(Array.from(groups.values()).flat()) : undefined;
     /*  create each absent artifact file with its frontmatter and
-        the level 1 headings of its artifacts  */
+        the level 1 headings of its artifacts (or their sample objects),
+        where a recurring artifact receives no heading, as its objects
+        are named by the authors  */
+    const sources = new Array();
     for (const [file, artifacts] of groups) {
         const target = path.join(options.basedir, file);
-        if (fs.existsSync(target)) {
-            options.verbose(`skipping existing artifact file "${literal(file)}"`);
-            continue;
-        }
         const headings = artifacts.map((artifact) => {
+            const sample = samples?.get(artifact);
+            if (sample !== undefined)
+                return `${wrapSample(renderObjectMd(sample, 1))}\n\n`;
+            if (isRecurring(artifact))
+                return "";
             const name = artifact.name ?? "";
             const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
             return `#   ${artifact.kind}: ${name}${paren}\n\n` + titleList(artifact);
@@ -64,7 +82,21 @@ export const initSpecification = (options) => {
         fs.writeFileSync(target, text, "utf8");
         options.verbose(`created artifact file "${literal(file)}" ` +
             `with ${literal(artifacts.length)} artifact(s)`);
+        sources.push({ file: target, text });
         created.push(file);
     }
+    /*  check the generated sample, as the generation satisfies the
+        constraints of the schema configuration on a best-effort basis
+        only, reporting the errors unconditionally (the files stay, as
+        they are the starting point to fix) and the warnings (like the
+        coverage lapses) as regular notices  */
+    if (samples !== undefined && sources.length > 0) {
+        const result = parseSpecification(sources, options.config);
+        const stats = specStatistics(result.specification);
+        options.verbose(`generated sample defining ${literal(stats.objects)} object(s) ` +
+            `and ${literal(stats.links)} link relationship(s)`);
+        for (const diagnostic of result.diagnostics)
+            options.verbose(renderDiagnostic(diagnostic), diagnostic.severity === "error" ? "none" : "notice");
+    }
     return created;
 };

package/dst/specbook-cmd-lint.js

@@ -6,23 +6,16 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadConfig, configStatistics } from "./specbook-config.js";
+import { reportOverlaps } from "./specbook-remote.js";
 import { literal } from "./specbook-verbose.js";
-import { parseSpecification, specStatistics, resolveArtifact, collectSchemas } from "./specbook-parse.js";
+import { parseSpecification, specStatistics, resolveArtifact, isRecurring, collectSchemas } from "./specbook-parse.js";
 import { buildLinkIndex, chainOf, plainText } from "./specbook-link.js";
 import { referencedCoverage, specCoverage, coverageRatio } from "./specbook-coverage.js";
 import { excluder } from "./specbook-ignore.js";
-/*  collect the distinct artifact files the schema configuration
-    references, in their declaration order, each mapped onto whether
-    all of its artifacts are optional and hence the file may be absent  */
-const schemaFiles = (config) => {
-    const files = new Map();
-    for (const artifact of config) {
-        if (artifact.file === undefined)
-            continue;
-        files.set(artifact.file, (files.get(artifact.file) ?? true) && artifact.optional === true);
-    }
-    return files;
-};
+import { specFiles } from "./specbook-files.js";
+/*  whether a configured artifact is demanded: neither optional nor
+    recurring (the latter being optional by definition)  */
+const isDemanded = (schema) => schema !== undefined && schema.optional !== true && !isRecurring(schema);
 /*  report the reference coverage the "referenced"-flagged object kinds
     receive and the "coverage"-configured objects report as additional
     figures, the unreferenced objects of the latter by name as a lengthy
@@ -58,52 +51,57 @@ export const lint = (options) => {
         options.config.map((file) => `"${literal(file)}"`).join(", "));
     const loaded = loadConfig(options.config);
     diagnostics.push(...loaded.diagnostics);
+    reportOverlaps(loaded.overlaps, options.verbose);
     const config = loaded.config;
     if (config !== undefined) {
         const stats = configStatistics(config);
         options.verbose(`loaded schema configuration specifying ${literal(stats.objects)} object kind(s) ` +
             `and ${literal(stats.links)} link relationship(s)`);
     }
-    /*  read the artifact files the configuration references, resolved
-        against the base directory and tolerating an absent file if all
-        its artifacts are optional  */
-    const files = config !== undefined ? schemaFiles(config) : new Map();
-    if (config !== undefined && files.size === 0)
-        diagnostics.push({ file: options.config[0], line: 1, column: 1, severity: "error",
-            message: "no artifact files configured" });
-    /*  an artifact file Git excludes from its project is treated exactly
-        like an absent one -- it is no part of the project and hence no
-        part of its specification  */
+    /*  read the specification Markdown files below the base directory
+        (every one of them is taken for a SpecBook one, the "file"
+        fields of the configuration drive "init" only), where the base
+        directory itself heads the observed paths, so a watching
+        consumer notices added and removed files, too  */
+    const files = specFiles(options.basedir);
+    if (files.length === 0)
+        diagnostics.push({ file: options.basedir, line: 1, column: 1, severity: "error",
+            message: "no specification files found" });
+    /*  a file Git excludes from its project is no part of the project
+        and hence no part of its specification, so it is set aside  */
     const excluded = options.gitignore ? excluder(options.basedir) : () => false;
     const sources = new Array();
-    const present = new Set();
-    const watched = new Array();
-    for (const [name, optional] of files) {
-        const file = path.join(options.basedir, name);
+    const pruned = new Array();
+    const watched = [path.resolve(options.basedir)];
+    for (const file of files) {
         watched.push(path.resolve(file));
-        if (excluded(file)) {
-            if (optional)
-                options.verbose(`skipping artifact file "${literal(file)}" excluded by Git`);
-            else
-                diagnostics.push({ file, line: 1, column: 1, severity: "error",
-                    message: "artifact file excluded by Git" });
-            continue;
-        }
-        if (!fs.existsSync(file)) {
-            if (!optional)
-                diagnostics.push({ file, line: 1, column: 1, severity: "error",
-                    message: "missing artifact file" });
-            continue;
-        }
         try {
-            sources.push({ file, text: fs.readFileSync(file, "utf8") });
-            present.add(name);
+            (excluded(file) ? pruned : sources).push({ file, text: fs.readFileSync(file, "utf8") });
         }
         catch (err) {
             diagnostics.push({ file, line: 1, column: 1, severity: "error",
                 message: `unreadable file: ${err instanceof Error ? err.message : String(err)}` });
         }
     }
+    /*  an excluded file is an error unless all of its artifacts are
+        optional, which only its own (separate, as it is dropped) parsing
+        tells, whose diagnostics are irrelevant for the very same reason  */
+    if (pruned.length > 0) {
+        const demanded = new Set();
+        if (config !== undefined) {
+            const dropped = parseSpecification(pruned, config);
+            for (const artifact of dropped.specification.artifacts)
+                if (artifact.objects.some((object) => isDemanded(resolveArtifact(config, object))))
+                    demanded.add(dropped.origins.get(artifact) ?? "");
+        }
+        for (const { file } of pruned) {
+            if (demanded.has(file))
+                diagnostics.push({ file, line: 1, column: 1, severity: "error",
+                    message: "artifact file excluded by Git" });
+            else
+                options.verbose(`skipping specification file "${literal(file)}" excluded by Git`);
+        }
+    }
     /*  parse and validate the artifact files against the configuration  */
     options.verbose(`parsing ${literal(sources.length)} specification file(s) ` +
         `below "${literal(options.basedir)}"`);
@@ -116,9 +114,10 @@ export const lint = (options) => {
     /*  report the reference coverage as additional figures  */
     if (config !== undefined && result.specification.artifacts.length > 0)
         reportCoverage(result.specification, config, options.verbose);
-    /*  report the non-optional artifacts absent from the specification,
-        against their loaded artifact file (an absent or unreadable file
-        is already reported above) or else against the configuration  */
+    /*  report the demanded artifacts absent from the specification,
+        against the artifact file configured for them below the base
+        directory (where "init" would create them, present or not) or
+        else against the configuration  */
     if (config !== undefined) {
         const found = new Set();
         for (const artifact of result.specification.artifacts)
@@ -128,8 +127,7 @@ export const lint = (options) => {
                     found.add(schema);
             }
         for (const schema of config) {
-            if (schema.optional === true || found.has(schema)
-                || (schema.file !== undefined && !present.has(schema.file)))
+            if (!isDemanded(schema) || found.has(schema))
                 continue;
             const file = schema.file !== undefined ? path.join(options.basedir, schema.file) : options.config[0];
             const paren = schema.id !== undefined ? ` (${schema.id})` : "";

package/dst/specbook-cmd-query.d.ts

@@ -0,0 +1,30 @@
+import ASTQ from "astq";
+import type { Spec, SpecArtifact, SpecObject } from "./specbook-format-spec.js";
+import type { Schema } from "./specbook-format-schema.js";
+import type { Diagnostic } from "./specbook-diagnostic.js";
+export type SpecNode = Spec | SpecArtifact | SpecObject;
+export type SpecQueryAdapter = ASTQ.Adapter<SpecNode>;
+export type SpecQueryFunc = (adapter: SpecQueryAdapter, node: SpecNode, ...args: unknown[]) => unknown;
+export declare const queryFormats: readonly ["json", "json5", "yaml", "toon"];
+export type QueryFormat = typeof queryFormats[number];
+export declare const parseQueryOutput: (output: string, format?: string) => {
+    format: QueryFormat;
+    output: string;
+};
+export declare const renderNodes: (nodes: SpecNode[], format?: QueryFormat) => string;
+export declare class SpecBookDocument {
+    readonly specification: Spec;
+    readonly config: Schema;
+    readonly diagnostics: Diagnostic[];
+    private astq;
+    private parents;
+    private attrs;
+    private index;
+    constructor(specification: Spec, config: Schema, diagnostics: Diagnostic[], origins: Map<SpecArtifact, string>);
+    query(selector: string, params?: Record<string, unknown>): SpecNode[];
+    parent(node: SpecNode): SpecNode | undefined;
+    func(name: string, fn: SpecQueryFunc): this;
+    private expand;
+    plain(text: string, from?: SpecObject): string;
+    html(text: string, from?: SpecObject): string;
+}