@rse/specbook 1.2.8 → 1.2.10

package/README.md

@@ -86,6 +86,7 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
     reference coverage tables (e.g. the share of the use cases, scenarios,
     requirements, and rules the test cases verify), a
     scroll progress meter (which also scrolls back to the top on click),
+    diagram maximization (into the viewport or the fullscreen),
     description popups (which show the schema and corpus description of
     an object kind, property, or object instance on hover), and a
     light/dark theme toggle. It is intended for the day-to-day online

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-export-html-search.js

@@ -74,6 +74,23 @@
                     units.push({ el, text, words, keep: false })
                 })
         })
+
+        /*  let a hyperlink whose target the filtering hid leave the
+            search mode (like the Escape key) before it jumps: the click
+            is intercepted, the document revealed again, and the click
+            re-issued, so the browser performs the regular jump  */
+        document.querySelectorAll("a[href^='#']").forEach((link) => {
+            link.addEventListener("click", (event) => {
+                const target = document.getElementById(
+                    decodeURIComponent((link.getAttribute("href") ?? "").slice(1)))
+                if (target === null || target.closest(".search-hide") === null)
+                    return
+                event.preventDefault()
+                reset()
+                slide(false)
+                link.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }))
+            })
+        })
     }
 
     /*  the Levenshtein edit distance of two words  */

package/dst/specbook-export-html.css

@@ -574,6 +574,87 @@ span.fold-label svg {
     display: none;
   }
 }
+/*  the maximization of the diagrams (screen-only): every diagram
+    carries two controls at its top right corner (drawn like the fold
+    chevron of an over-long cell, in rounded boxes on the page
+    background), faded in while the diagram is hovered, which maximize
+    the diagram temporarily in the shared overlay covering the whole
+    viewport (or, taken into the browser fullscreen, the whole screen)
+    on the page background, where the cloned diagram scales to fit the
+    padded area (aspect ratio kept, centered) and a close mark sits at
+    the top right corner, while the document beneath stops scrolling  */
+span.maximize-controls {
+  position: absolute;
+  top: 0.35rem;
+  right: 0.35rem;
+  display: flex;
+  gap: 0.25rem;
+  line-height: 0;
+  opacity: 0;
+  transition: opacity 0.2s ease;
+}
+div.diagram:hover span.maximize-controls {
+  opacity: 1;
+}
+span.maximize-controls > span,
+span.maximize-close {
+  display: inline-block;
+  padding: 0.2rem;
+  line-height: 0;
+  color: var(--theme-color-specbook-symbol);
+  background-color: var(--theme-color-specbook-background);
+  border: 1px solid var(--theme-color-specbook-border);
+  border-radius: 0.25rem;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+}
+span.maximize-controls > span:hover,
+span.maximize-close:hover {
+  color: var(--theme-color-specbook-accent);
+  border-color: var(--theme-color-specbook-accent);
+}
+span.maximize-controls svg,
+span.maximize-close svg {
+  width: 1rem;
+  height: 1rem;
+}
+div.maximize {
+  display: none;
+  position: fixed;
+  inset: 0;
+  z-index: 40;
+  box-sizing: border-box;
+  padding: 2rem;
+  background-color: var(--theme-color-specbook-background);
+}
+div.maximize.open {
+  display: block;
+}
+div.maximize span.maximize-close {
+  position: absolute;
+  top: 0.6rem;
+  right: 0.6rem;
+}
+div.maximize div.maximize-content {
+  width: 100%;
+  height: 100%;
+}
+div.maximize div.maximize-content svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+  max-width: none;
+}
+html.maximized {
+  overflow: hidden;
+}
+@media print {
+  span.maximize-controls,
+  div.maximize {
+    display: none;
+  }
+}
 /*  the connection status tab of the live preview (screen-only): the
     bottommost tab riding right of the brand bar below the table of
     contents tab (sized like the search tab, fixed independent of the
@@ -1204,6 +1285,7 @@ span.theme-dark-only {
 }
 /*  the diagrams, rationales, keywords, and code spans  */
 div.diagram {
+  position: relative;
   margin: 1rem 0;
 }
 div.diagram svg {

package/dst/specbook-export-html.js

@@ -60,6 +60,7 @@ const templates = {
                 {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
                 <script>{{ Document.progress }}</script>
                 <script>{{ Document.fold }}</script>
+                <script>{{ Document.maximize }}</script>
                 {% if Document.tocpanel %}<script>{{ Document.tocscript }}</script>{% endif %}
                 {% if Document.info %}<script>{{ Document.info }}</script>{% endif %}
                 {% if Document.realtime %}<script class="realtime">{{ Document.realtime }}</script>{% endif %}
@@ -654,6 +655,110 @@ const foldScript = textframe `
 
     })()
 `;
+/*  the client-side script of the diagram maximization: it attaches two
+    controls to the top right corner of every diagram, revealed by the
+    stylesheet while the diagram is hovered, which maximize the diagram
+    temporarily in a single shared overlay covering the viewport (the
+    SVG cloned into it and fitted by the stylesheet), the second one
+    additionally taking the overlay into the browser fullscreen (a
+    refused request leaves the viewport overlay), where the close mark
+    at the top right corner, "Escape", a click beside the diagram, and
+    a jump through a node hyperlink close the overlay again (a browser
+    leaving the fullscreen on its own closes it, too). The script runs
+    at the end of the body, as the diagrams it decorates have to exist
+    already, and a live preview body swap replaces the overlay and the
+    body-bound listeners along with the body, while the document-bound
+    fullscreen listener retires itself  */
+const maximizeScript = textframe `
+    (function () {
+        /*  an icon control drawn like the tab icons  */
+        const svgNS = "http://www.w3.org/2000/svg"
+        const mark = (name, title, paths) => {
+            const span = document.createElement("span")
+            span.className = name
+            span.title = title
+            const svg = document.createElementNS(svgNS, "svg")
+            svg.setAttribute("viewBox", "0 0 24 24")
+            svg.setAttribute("fill", "none")
+            svg.setAttribute("stroke", "currentColor")
+            svg.setAttribute("stroke-width", "2.5")
+            svg.setAttribute("stroke-linecap", "round")
+            svg.setAttribute("stroke-linejoin", "round")
+            for (const d of paths) {
+                const path = document.createElementNS(svgNS, "path")
+                path.setAttribute("d", d)
+                svg.appendChild(path)
+            }
+            span.appendChild(svg)
+            return span
+        }
+
+        /*  the shared overlay: the close mark plus the content holding
+            the clone of the maximized diagram  */
+        const overlay = document.createElement("div")
+        overlay.className = "maximize"
+        const close   = mark("maximize-close", "close the maximized diagram",
+            [ "M18 6 6 18", "M6 6l12 12" ])
+        const content = document.createElement("div")
+        content.className = "maximize-content"
+        overlay.append(close, content)
+        document.body.appendChild(overlay)
+
+        /*  open the overlay onto a diagram, optionally in the browser
+            fullscreen, and close it again (leaving the fullscreen, too),
+            with the document scrolling locked while it is open  */
+        const open = (diagram, fullscreen) => {
+            const svg = diagram.querySelector("svg").cloneNode(true)
+            svg.removeAttribute("style")
+            content.replaceChildren(svg)
+            overlay.classList.add("open")
+            document.documentElement.classList.add("maximized")
+            if (fullscreen)
+                overlay.requestFullscreen().catch(() => {})
+        }
+        const shut = () => {
+            overlay.classList.remove("open")
+            document.documentElement.classList.remove("maximized")
+            content.replaceChildren()
+            if (document.fullscreenElement === overlay)
+                document.exitFullscreen().catch(() => {})
+        }
+        close.addEventListener("click", shut)
+        overlay.addEventListener("click", (event) => {
+            /*  a node hyperlink navigates on its own, the overlay just
+                gets out of its way, while a click beside the diagram
+                closes the overlay alone  */
+            if (event.target.closest("a") !== null || event.target.closest("svg") === null)
+                shut()
+        })
+        document.body.addEventListener("keydown", (event) => {
+            if (event.key === "Escape" && overlay.classList.contains("open"))
+                shut()
+        })
+        const left = () => {
+            if (!overlay.isConnected)
+                document.removeEventListener("fullscreenchange", left)
+            else if (document.fullscreenElement === null && overlay.classList.contains("open"))
+                shut()
+        }
+        document.addEventListener("fullscreenchange", left)
+
+        /*  attach the two controls to every diagram  */
+        document.querySelectorAll("article div.diagram, nav.doc div.diagram").forEach((diagram) => {
+            const controls = document.createElement("span")
+            controls.className = "maximize-controls"
+            const view = mark("maximize-view", "maximize this diagram in the viewport",
+                [ "M15 3h6v6", "M21 3l-7 7", "M9 21H3v-6", "M3 21l7-7" ])
+            const full = mark("maximize-full", "maximize this diagram in fullscreen",
+                [ "M3 7V5a2 2 0 0 1 2-2h2", "M17 3h2a2 2 0 0 1 2 2v2",
+                  "M21 17v2a2 2 0 0 1-2 2h-2", "M7 21H5a2 2 0 0 1-2-2v-2" ])
+            view.addEventListener("click", () => { open(diagram, false) })
+            full.addEventListener("click", () => { open(diagram, true) })
+            controls.append(view, full)
+            diagram.appendChild(controls)
+        })
+    })()
+`;
 /*  the client-side script of the table of contents side panel: it
     slides the panel out of and back into the viewport edge (closing it
     also on a jump, on "Escape", and on a click outside), remembers the
@@ -1661,6 +1766,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
                 search: safe(searchScript()),
                 progress: safe(scrollProgressScript),
                 fold: safe(foldScript),
+                maximize: safe(maximizeScript),
                 info: info !== null ? safe(infoScript(info, spec ?? {})) : "",
                 realtime: realtime ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",

package/dst/specbook-format.md

@@ -185,6 +185,7 @@ type SchemaGradiaConfig = Partial<{
     "grid-gap-horizontal":       number
     "grid-gap-vertical":         number
     "grid-node-width-equal":     boolean
+    "grid-node-height-equal":    boolean
 }>
 ```
 

package/dst/specbook-format.yaml

@@ -1239,7 +1239,27 @@
         type: graph
         nodes: "[[DM.ENTITY:*]]"
         edges: "[[RELATION:*]]"
+        nest:
+            properties:
+                -   GROUP
+        config:
+            graph-columns-max: 2
     children:
+        -   kind: GROUP
+            name: "[A-Z][a-zA-Z0-9]*"
+            desc: >
+                A named group of strongly related entities, carrying a Pascal-cased, 1-3 word long,
+                per-artifact unique name, distinct from the names of its entities (e.g. `Statistics`
+                for the snapshot entities, `Messages` for a message and its texts), and described by
+                a 1-sentence description ("what") plus a 1-sentence rationale ("why") of the
+                cohesion. A group is either an aggregate (a root entity with the part entities it
+                owns) or a subject area (entities sharing one concern), affects the overview diagram
+                only, where its entities are drawn next to each other inside a box, and carries no
+                semantics of its own: the relations between its entities stay explicit. The groups
+                are listed before the entities, and every entity belongs to at most one group.
+            optional: true
+            referenced:
+                -   "[[DM.ENTITY:*]]"
         -   kind: ENTITY
             name: "[A-Z][a-zA-Z0-9]*"
             desc: >
@@ -1281,6 +1301,13 @@
                         is anchored in the ubiquitous language and every term shows its data.
                     value: list([[TERM:*]])
                     optional: true
+                -   name: GROUP
+                    desc: >
+                        Reference to the DATA-MODEL group the entity belongs to, placing it next to
+                        the other entities of the group in the overview diagram; omitted for an
+                        entity standing on its own.
+                    value: "[[DM.GROUP:*]]"
+                    optional: true
             children:
                 -   kind: ATTRIBUTE
                     name: "[a-z][a-zA-Z0-9]*"
@@ -2872,7 +2899,7 @@
             -   PRODUCT
         config:
             size-node-width-max: 440
-            grid-columns-max: 3
+            grid-columns-max: 2
     children:
         -   kind: TIER
             desc: |

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.8",
+    "version":                             "1.2.10",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -17,16 +17,16 @@
     },
     "files":                               [ "dst" ],
     "dependencies": {
-        "marked":                          "18.0.11",
+        "marked":                          "18.0.12",
         "marked-smartypants":              "1.1.12",
         "yaml":                            "2.9.0",
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.7.0",
         "@rse/mrcs":                       "0.9.2",
-        "@rse/gradia":                     "1.2.1",
+        "@rse/gradia":                     "1.2.3",
         "@toon-format/toon":               "4.1.1",
-        "valibot":                         "1.4.2",
+        "valibot":                         "1.5.0",
         "nunjucks":                        "3.2.4",
         "@rse/nunjucks-addons":            "2.2.0",
         "textframe":                       "1.2.1",
@@ -38,23 +38,25 @@
         "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",
         "@modelcontextprotocol/sdk":       "1.30.0",
-        "zod":                             "4.5.4"
+        "zod":                             "4.6.1"
     },
     "devDependencies": {
         "chokidar-cli":                    "3.0.0",
         "eslint":                          "10.9.0",
         "@eslint/js":                      "10.0.1",
-        "typescript-eslint":               "8.69.0",
+        "typescript-eslint":               "8.70.0",
         "eslint-plugin-promise":           "7.3.0",
         "neostandard":                     "0.14.0-next.1",
         "globals":                         "17.12.0",
         "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"
     },