@rse/specbook 1.2.9 → 1.2.10

package/dst/specbook-api.d.ts

@@ -34,6 +34,7 @@ export declare class SpecBook {
     lint(options: {
         config?: string[];
         basedir?: string;
+        gitignore?: boolean;
     }): Promise<LintResult>;
     private renderFormats;
     export(options: {
@@ -41,6 +42,7 @@ export declare class SpecBook {
         basedir?: string;
         formats?: ExportFormat[];
         realtime?: boolean;
+        gitignore?: boolean;
     }): Promise<Buffer[]>;
     private observe;
     watch(options: {
@@ -48,6 +50,7 @@ export declare class SpecBook {
         basedir?: string;
         formats?: ExportFormat[];
         realtime?: boolean;
+        gitignore?: boolean;
         outputs?: string[];
         onExport: (buffers: Buffer[]) => void | Promise<void>;
     }): Promise<void>;
@@ -56,6 +59,7 @@ export declare class SpecBook {
         basedir?: string;
         addr?: string;
         port?: number;
+        gitignore?: boolean;
     }): Promise<void>;
     describe(options: {
         config?: string[];

package/dst/specbook-api.js

@@ -81,10 +81,13 @@ export class SpecBook {
         return initSpecification({ config: this.requireConfig(await this.configFiles(options.config), verbose),
             basedir: options.basedir ?? ".", verbose });
     }
-    /*  lint the specification Markdown files below the base directory  */
+    /*  lint the specification Markdown files below the base directory,
+        where "gitignore" treats an artifact file Git excludes from its
+        project exactly like an absent one  */
     async lint(options) {
         return lint({ config: await this.configFiles(options.config),
-            basedir: options.basedir ?? ".", verbose: this.verboseOf("lint") });
+            basedir: options.basedir ?? ".", gitignore: options.gitignore === true,
+            verbose: this.verboseOf("lint") });
     }
     /*  render an already parsed specification into the requested formats
         (strict: any error diagnostic prevents the export, as a partial or
@@ -116,7 +119,7 @@ export class SpecBook {
         if (requested.includes("pdf"))
             await requireBrowser(verbose);
         const result = lint({ config: await this.configFiles(options.config),
-            basedir: options.basedir ?? ".", verbose });
+            basedir: options.basedir ?? ".", gitignore: options.gitignore === true, verbose });
         return this.renderFormats(result, requested, verbose, options.realtime === true);
     }
     /*  keep an export in sync with its sources (the shared core of
@@ -135,7 +138,8 @@ export class SpecBook {
                 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: options.basedir ?? ".", verbose });
+            const result = lint({ config, basedir: options.basedir ?? ".",
+                gitignore: options.gitignore === true, verbose });
             const files = [...config.map((file) => path.resolve(file)), ...result.files];
             /*  an output which is itself an observed source would re-trigger
                 the observation with its own write and hence feed an endless
@@ -176,7 +180,7 @@ export class SpecBook {
         const server = await servePreview({ addr: options.addr ?? previewAddr,
             port: options.port ?? previewPort, verbose });
         return this.observe({ config: options.config, basedir: options.basedir,
-            formats: ["html"], realtime: true,
+            formats: ["html"], realtime: true, gitignore: options.gitignore,
             onExport: ([html]) => server.update(html) }, verbose);
     }
     /*  describe the generic SpecBook models and formats as Markdown (or

package/dst/specbook-cli.js

@@ -80,6 +80,13 @@ const configOf = (opts) => opts.config.length > 0 ? opts.config : envDefault("co
     for which the YAML schema configuration falls back onto the standard one  */
 const withCommonOptions = (command) => withConfigOption(withVerboseOption(command), "the bundled standard schema configuration")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."));
+/*  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
+    project exactly like an absent one  */
+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));
 /*  the help, version, and usage-error output Commander produces, which
     is collected instead of written directly, as Commander writes it
     synchronously and then terminates the process, truncating a piped
@@ -118,11 +125,12 @@ withCommonOptions(program.command("init"))
         "no artifact files were created\n");
 });
 /*  the lint command reports all diagnostics and fails on any error  */
-withCommonOptions(program.command("lint"))
+withGitignoreOption(withCommonOptions(program.command("lint")))
     .description("lint the specification Markdown files below the base directory")
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const result = await specbook.lint({ config: configOf(opts), basedir: opts.basedir });
+    const result = await specbook.lint({ config: configOf(opts), basedir: opts.basedir,
+        gitignore: opts.gitignore });
     for (const diagnostic of result.diagnostics)
         await writeStdout(parseVerbosity(opts.verbose) > 0 ?
             renderDiagnosticVerbose(diagnostic, process.stdout.isTTY === true) :
@@ -133,7 +141,7 @@ withCommonOptions(program.command("lint"))
         verboseOf(opts)("lint", "specification valid", "notice");
 });
 /*  the export command parses the input once and writes every output  */
-withCommonOptions(program.command("export"))
+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")
     .option("-w, --watch", "keep the outputs in sync by re-exporting on every source change", envDefaultFlag("watch", false))
@@ -156,13 +164,14 @@ withCommonOptions(program.command("export"))
     };
     if (opts.watch)
         await specbook.watch({ config: configOf(opts), basedir: opts.basedir,
-            formats: distinct, outputs: outputs.map(({ output }) => output), onExport: write });
+            formats: distinct, gitignore: opts.gitignore,
+            outputs: outputs.map(({ output }) => output), onExport: write });
     else
         await write(await specbook.export({ config: configOf(opts), basedir: opts.basedir,
-            formats: distinct }));
+            formats: distinct, gitignore: opts.gitignore }));
 });
 /*  the preview command serves the HTML export live in the browser  */
-withCommonOptions(program.command("preview"))
+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")
     .option("-a, --addr <ip-addr>", "IP address to listen on", envDefault("addr", previewAddr))
@@ -172,7 +181,8 @@ 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 });
+    await specbook.preview({ config: configOf(opts), basedir: opts.basedir, addr: opts.addr, port,
+        gitignore: opts.gitignore });
 });
 /*  the describe command also describes the generic SpecBook models and
     formats alone, so its YAML schema configuration stays optional  */

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

@@ -5,6 +5,7 @@ import { type Schema } from "./specbook-format-schema.js";
 export interface LintOptions {
     config: string[];
     basedir: string;
+    gitignore: boolean;
     verbose: Verbose;
 }
 export interface LintResult {

package/dst/specbook-cmd-lint.js

@@ -10,6 +10,7 @@ import { literal } from "./specbook-verbose.js";
 import { parseSpecification, specStatistics, resolveArtifact, 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  */
@@ -44,12 +45,24 @@ export const lint = (options) => {
     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  */
+    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);
         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",

package/dst/specbook-ignore.d.ts

@@ -0,0 +1,2 @@
+export type Excluder = (file: string) => boolean;
+export declare const excluder: (dir: string) => Excluder;

package/dst/specbook-ignore.js

@@ -0,0 +1,173 @@
+/*
+**  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 * as os from "node:os";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import picomatch from "picomatch";
+/*  translate a single Git exclude line into a picomatch-backed rule,
+    honoring the anchored-vs-floating, directory-only, and negation
+    semantics of the pattern; an anchored pattern resolves relative to
+    the "base" directory its rule file governs, given as a POSIX path
+    relative to the working tree root  */
+const compileRule = (line, base) => {
+    let pattern = line.trim();
+    if (pattern === "" || pattern.startsWith("#"))
+        return null;
+    let negated = false;
+    if (pattern.startsWith("!")) {
+        negated = true;
+        pattern = pattern.slice(1);
+    }
+    let dirOnly = false;
+    if (pattern.endsWith("/")) {
+        dirOnly = true;
+        pattern = pattern.slice(0, -1);
+    }
+    /*  a pattern carrying a slash anywhere but at its end is anchored at
+        the directory of its rule file, while every other one floats and
+        hence matches at any depth below it  */
+    const anchored = pattern.includes("/");
+    if (pattern.startsWith("/"))
+        pattern = pattern.slice(1);
+    const glob = anchored ? (base === "" ? pattern : `${base}/${pattern}`) : `**/${pattern}`;
+    const isMatch = picomatch(glob, { dot: true });
+    return { matcher: (p) => isMatch(p), negated, dirOnly };
+};
+/*  load the rules of a single exclude file, given as an absolute "file"
+    and the working-tree-relative "base" its anchored patterns resolve
+    against; an absent or unreadable file contributes no rules  */
+const loadRules = (file, base) => {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const rules = new Array();
+    for (const line of text.split(/\r?\n/)) {
+        const rule = compileRule(line, base);
+        if (rule !== null)
+            rules.push(rule);
+    }
+    return rules;
+};
+/*  locate the Git working tree containing a directory, i.e. the nearest
+    ancestor-or-self carrying a ".git" directory (a regular working
+    tree) or a ".git" file (a linked worktree or a submodule)  */
+const workingTree = (dir) => {
+    let current = path.resolve(dir);
+    for (;;) {
+        if (fs.existsSync(path.join(current, ".git")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+};
+/*  resolve the global Git excludes file: the configured
+    "core.excludesFile", or else the XDG location Git falls back onto
+    when that configuration value is unset  */
+const globalFile = () => {
+    let file = "";
+    try {
+        file = execFileSync("git", ["config", "--get", "core.excludesFile"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        /*  no such configuration value, or no Git at all  */
+    }
+    if (file === "") {
+        const xdg = process.env.XDG_CONFIG_HOME;
+        return xdg !== undefined && xdg !== "" ?
+            path.join(xdg, "git", "ignore") :
+            path.join(os.homedir(), ".config", "git", "ignore");
+    }
+    if (file.startsWith("~/"))
+        return path.join(os.homedir(), file.slice(2));
+    return file;
+};
+/*  resolve the repository-local exclude file of a working tree, held by
+    the Git *common* directory: a regular working tree carries ".git" as
+    that very directory, while a linked worktree carries it as a file
+    pointing at its own administrative directory, whose "commondir" in
+    turn points at the shared one  */
+const infoFile = (root) => {
+    const dot = path.join(root, ".git");
+    let dir = dot;
+    if (fs.statSync(dot, { throwIfNoEntry: false })?.isFile() === true) {
+        const pointer = (/^gitdir:\s*(.+?)\s*$/m).exec(fs.readFileSync(dot, "utf8"));
+        if (pointer === null)
+            return "";
+        dir = path.resolve(root, pointer[1]);
+        const common = path.join(dir, "commondir");
+        if (fs.existsSync(common))
+            dir = path.resolve(dir, fs.readFileSync(common, "utf8").trim());
+    }
+    return path.join(dir, "info", "exclude");
+};
+/*  create the predicate deciding whether an absolute file path is
+    excluded from the Git working tree containing "dir", honoring the
+    same three rule sources and the same precedence order as Git itself
+    -- the global excludes file, the repository-local "info/exclude",
+    and the ".gitignore" files from the working tree root down to the
+    file. A path outside any Git working tree is never excluded, as
+    there is no project to be excluded from  */
+export const excluder = (dir) => {
+    const root = workingTree(dir);
+    if (root === null)
+        return () => false;
+    /*  the rules which no directory of the working tree owns and which
+        hence govern it as a whole, in ascending Git precedence  */
+    const base = [...loadRules(globalFile(), ""), ...loadRules(infoFile(root), "")];
+    /*  the per-directory ".gitignore" rules, loaded on first use, as one
+        run queries many files sharing the very same directories  */
+    const cache = new Map();
+    const rulesOf = (relDir) => {
+        let rules = cache.get(relDir);
+        if (rules === undefined) {
+            rules = loadRules(path.join(root, relDir, ".gitignore"), relDir);
+            cache.set(relDir, rules);
+        }
+        return rules;
+    };
+    return (file) => {
+        const rel = path.relative(root, path.resolve(file)).replace(/\\/g, "/");
+        if (rel === "" || rel.startsWith("../"))
+            return false;
+        const segments = rel.split("/");
+        /*  walk the directory chain from the working tree root down to
+            the file, picking up the ".gitignore" rules on the way and
+            deciding every segment against the rules known at its level,
+            where the last matching rule wins; an excluded ancestor
+            directory excludes the file itself, as Git never descends
+            into it -- and, for the same reason, a rule below such an
+            ancestor can never re-include the file  */
+        let rules = base;
+        let relDir = "";
+        for (let i = 0; i < segments.length; i++) {
+            rules = rules.concat(rulesOf(relDir));
+            const current = relDir === "" ? segments[i] : `${relDir}/${segments[i]}`;
+            /*  every segment but the last one is a directory by
+                construction, while the last one is whatever the file
+                system says it is  */
+            const isDir = i < segments.length - 1
+                || fs.statSync(path.join(root, current), { throwIfNoEntry: false })?.isDirectory() === true;
+            let excluded = false;
+            for (const rule of rules) {
+                if (rule.dirOnly && !isDir)
+                    continue;
+                if (rule.matcher(current))
+                    excluded = !rule.negated;
+            }
+            if (excluded)
+                return true;
+            relDir = current;
+        }
+        return false;
+    };
+};

package/dst/specbook-mcp.js

@@ -51,7 +51,10 @@ export const serveMcp = async (verbose) => {
             config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
                 "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
                 "default: the bundled standard schema configuration)"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
+            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
+            gitignore: z.boolean().optional().describe("skip the artifact files excluded by the Git " +
+                "exclude rules (the \".gitignore\" files, \"info/exclude\", and the global excludes " +
+                "file), treating such a file exactly like an absent one (default: false)")
         }
     }, async (args) => {
         try {
@@ -78,7 +81,10 @@ export const serveMcp = async (verbose) => {
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
             format: z.enum(formats).optional().describe("output format (default: inferred from the " +
                 "output file extension, else json)"),
-            output: z.string().optional().describe("output file path (\"-\" or omitted returns the result directly)")
+            output: z.string().optional().describe("output file path (\"-\" or omitted returns the result directly)"),
+            gitignore: z.boolean().optional().describe("skip the artifact files excluded by the Git " +
+                "exclude rules (the \".gitignore\" files, \"info/exclude\", and the global excludes " +
+                "file), treating such a file exactly like an absent one (default: false)")
         }
     }, async (args) => {
         try {
@@ -89,7 +95,7 @@ export const serveMcp = async (verbose) => {
                 { format: args.format ?? "json", output: args.output } :
                 parseOutputSpec(args.output);
             const [data] = await specbook.export({ config: args.config, basedir: args.basedir,
-                formats: [spec.format] });
+                formats: [spec.format], gitignore: args.gitignore });
             if (spec.output !== undefined && spec.output !== "-") {
                 await fs.promises.writeFile(spec.output, data);
                 return { content: [{ type: "text", text: `exported specification into "${spec.output}" (${data.length} bytes)` }] };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.9",
+    "version":                             "1.2.10",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -38,6 +38,7 @@
         "chalk":                           "6.0.0",
         "chokidar5":                       "npm:chokidar@5.0.0",
         "glob":                            "13.0.6",
+        "picomatch":                       "4.0.7",
         "es-toolkit":                      "1.52.0",
         "fastify":                         "5.12.3",
         "@fastify/websocket":              "11.3.0",
@@ -55,6 +56,7 @@
         "markdownlint":                    "0.41.1",
         "markdownlint-cli2":               "0.23.2",
         "@types/node":                     "26.5.0",
+        "@types/picomatch":                "4.0.3",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",
         "@types/ws":                       "8.18.1",
@@ -67,7 +69,7 @@
         "postcss-cli":                     "12.0.0",
         "postcss-url":                     "10.1.4",
         "stylus":                          "0.64.0",
-        "@rse/stx":                        "1.1.6",
+        "@rse/stx":                        "1.1.7",
         "shx":                             "0.4.0",
         "nodemon":                         "3.1.14"
     },