@heroiclands/package-build 23.1.0 → 23.2.0

package/engine/pdf-render.mjs

@@ -327,7 +327,7 @@ function offsetPosition(source, offset, opts = {}) {
  * @param {object} opts - As {@link markdownToTypst} takes.
  * @param {string} original - `source` before its definitions were blanked —
  *   {@link unusedFootnoteDefinitions} locates a definition by searching for
- *   its own text, which `source` no longer carries.
+ *   its own text, which `source` does not carry.
  * @returns {void}
  */
 function reportUnrenderable(source, definitions, opts, original) {
@@ -475,6 +475,9 @@ function reportUnrenderable(source, definitions, opts, original) {
  *   at. Every link the book sets as a URL is resolved against it, because a
  *   reader holding a PDF has no page to resolve a path against — see
  *   {@link renderLink}.
+ * @param {{get: (key: string) => ({title: string, page: string|number}|undefined)}} [opts.elsewhere] -
+ *   The notes another book is home to, by the slug and addresses a link reaches
+ *   them through — see {@link crossBookReference}.
  * @param {boolean} [opts.generated] - Whether the Markdown is a note's
  *   generated sections rather than its author's text — see
  *   {@link module:engine/generated-sections}. Their links follow the rules
@@ -518,6 +521,7 @@ export function markdownToTypst(markdown, opts = {}) {
         headingOffset,
         anchorPrefix,
         url: opts.url,
+        elsewhere: opts.elsewhere,
         indexMentions: opts.indexMentions === true,
         generated: Boolean(opts.generated),
         seen: new Map(),
@@ -1361,6 +1365,10 @@ function pageOfLabel(label) {
  * usable; one whose target the book leaves out is its words alone, with no
  * link and no finding.
  *
+ * **A link to a note another book is home to** is not a link: a PDF link cannot
+ * leave its file. It is set as {@link crossBookReference}, in generated text
+ * and authored prose alike, and adds nothing to the index.
+ *
  * The address slug is read from the tail of the URL, which is where every
  * address this toolchain publishes puts it — `…/<type>-<shortcode>/`. A
  * cross-package URL resolved through the link manifest is on another package's
@@ -1395,10 +1403,33 @@ function renderLink(href, inner, ctx) {
         const marker = ctx.indexMentions && slug ? indexMarker(slug) : "";
         return `${link}${marker}`;
     }
+    const away = ctx.elsewhere?.get(slug);
+    if (away) {
+        // A mention in authored prose is what lists the note, under
+        // `pdf.indexSeeAlso`.
+        const marker = ctx.indexMentions && ctx.elsewhere.seeAlso ? indexMarker(away.slug) : "";
+        return `${crossBookReference(inner, away)}${marker}`;
+    }
     if (!url || ctx.generated) return inner;
     return `#link("${escapeTypstString(absolutePageUrl(url, ctx.url))}")[${inner}]`;
 }
 
+/**
+ * A reference to a note another book prints, as Typst: the words the link
+ * carried, then the book and the page, `Name (_Book title_, p. 12)`.
+ *
+ * The space before the page number does not break, so a number never starts a
+ * line of its own.
+ *
+ * @param {string} inner - The already-rendered link text.
+ * @param {{title: string, page: string|number}} away - The home book's title
+ *   and the page the entry starts on.
+ * @returns {string} Typst markup.
+ */
+export function crossBookReference(inner, away) {
+    return `${inner} (#emph[${escapeTypst(away.title)}], p.~${away.page})`;
+}
+
 /**
  * A width in inches, as a Typst length literal.
  *
@@ -1606,6 +1637,27 @@ export function bookTypstPreamble() {
         '#let book-accent = rgb("#7c3b1e")',
         '#let book-head = rgb("#5e2b14")',
         '#let book-faint = rgb("#6b6357")',
+        // The cover is a page of its own: the picture fills it, cropped to fit as
+        // a section banner is, and the title and subtitle sit in white over a
+        // translucent dark band across the upper third so they read over any
+        // art. It carries no running foot or number, and counts as page 1.
+        "#let book-cover(path, title, subtitle) = page(margin: 0pt, fill: book-ink, footer: none)[\n" +
+            '  #place(top + left, image(path, width: 100%, height: 100%, fit: "cover"))\n' +
+            "  #place(top + left, rect(width: 100%, height: 33.4%, fill: rgb(10, 8, 6, 170)))\n" +
+            "  #place(top + left, block(width: 100%, height: 33.4%)[\n" +
+            "    #align(center + horizon)[\n" +
+            "      #block(width: 80%)[\n" +
+            "        #set par(justify: false, first-line-indent: 0em)\n" +
+            "        #set text(fill: white, hyphenate: false)\n" +
+            '        #text(size: 34pt, weight: "bold")[#title]\n' +
+            '        #if subtitle != "" [\n' +
+            "          #v(0.6em)\n" +
+            "          #text(size: 16pt)[#subtitle]\n" +
+            "        ]\n" +
+            "      ]\n" +
+            "    ]\n" +
+            "  ])\n" +
+            "]",
         "#let book-ornament = box(baseline: 1pt, " +
             "rotate(45deg, rect(width: 3pt, height: 3pt, fill: book-accent)))",
         "#let book-footer(name) = context {\n" +
@@ -1755,6 +1807,18 @@ export function bookTypstPreamble() {
     ].join("\n");
 }
 
+/**
+ * One author as the title page prints it: `Name`, or `Name, Role` with the
+ * role in title case.
+ *
+ * @param {{name: string, role?: string}} person - An entry of `authors`.
+ * @returns {string} The line.
+ */
+function authorLine({ name, role }) {
+    if (!role) return name;
+    return `${name}, ${role.charAt(0).toUpperCase()}${role.slice(1)}`;
+}
+
 /**
  * The whole book, as one Typst document.
  *
@@ -1858,6 +1922,17 @@ export function bookTypstPreamble() {
  *   plate draws without a picture.
  * @param {Map<string, {path: string, title: string}>} [opts.maps] - An entry
  *   anchor to its SVG path and page heading. Each map takes a page after its entry.
+ * @param {string} [opts.coverImage] - The staged cover picture, relative to the
+ *   `.typ`. When given the book opens on a full-page cover, page 1, with the
+ *   title and subtitle over it; without one the book opens on the title page.
+ * @param {Array<{name: string, role?: string}>} [opts.authors] - Printed on the
+ *   title page one per line, as `Name` or `Name, Role`.
+ * @param {string} [opts.copyright] - The title page foot's first line.
+ * @param {string} [opts.license] - The title page foot's remaining lines; a
+ *   line break in it starts a new line.
+ * @param {object} [opts.index] - As {@link module:engine/pdf-index.indexTerms}:
+ *   `owns` limits the index to the notes this book is home to, and `foreign`
+ *   (present only under `pdf.indexSeeAlso`) lists notes another book prints.
  * @returns {string} A complete `.typ` document.
  */
 export function renderBook({
@@ -1871,6 +1946,11 @@ export function renderBook({
     preamble = "",
     banners = new Map(),
     maps = new Map(),
+    coverImage = "",
+    authors = [],
+    copyright = "",
+    license = "",
+    index = {},
 } = {}) {
     // The two halves of one superfamily, chosen together: matched metrics are
     // most of why the sans can carry every heading over a serif body without
@@ -1883,7 +1963,7 @@ export function renderBook({
     const out = [];
 
     out.push(bookTypstPreamble());
-    out.push(indexPreamble());
+    out.push(indexPreamble({ seeAlso: index.foreign !== undefined }));
     out.push("");
     out.push(`#set document(title: "${escapeTypstString(title)}")`);
     // Cream stock and dark ink rather than a dark screen theme: 2,000 pages of
@@ -1930,6 +2010,14 @@ export function renderBook({
         out.push("");
     }
 
+    // The cover, when the book has one, is page 1.
+    if (coverImage) {
+        out.push(
+            `#book-cover("${escapeTypstString(coverImage)}", ` +
+                `"${escapeTypstString(title)}", "${escapeTypstString(subtitle)}")`,
+        );
+    }
+
     // Title page.
     out.push("#align(center + horizon)[");
     out.push(`  #text(size: 30pt, weight: "bold")[${escapeTypst(title)}]`);
@@ -1941,7 +2029,29 @@ export function renderBook({
         out.push("  #v(2em)");
         out.push(`  #text(size: 10pt)[${escapeTypst(version)}]`);
     }
+    if (authors.length) {
+        out.push("  #v(2.5em)");
+        out.push("  #set par(first-line-indent: 0em, justify: false)");
+        out.push(
+            "  #text(size: 12pt)[" +
+                authors.map((person) => escapeTypst(authorLine(person))).join(" \\\n  ") +
+                "]",
+        );
+    }
     out.push("]");
+    const foot = [copyright, ...String(license).split(/\r?\n/)]
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (foot.length) {
+        out.push("#place(bottom + center)[");
+        out.push("  #set par(first-line-indent: 0em, justify: false)");
+        out.push(
+            "  #block(width: 80%)[#text(size: 8.5pt, fill: book-faint)[" +
+                foot.map((line) => escapeTypst(line)).join(" \\\n  ") +
+                "]]",
+        );
+        out.push("]");
+    }
     out.push("#pagebreak()");
     out.push("");
 
@@ -2031,8 +2141,8 @@ export function renderBook({
         }
     }
 
-    const index = indexChapter(plan?.entries, title);
-    if (index) out.push(index);
+    const chapter = indexChapter(plan?.entries, title, index);
+    if (chapter) out.push(chapter);
 
     return `${out.join("\n")}\n`;
 }

package/engine/pdf-toc.mjs

@@ -22,9 +22,10 @@
  *
  * Three consequences follow, and they are behaviour rather than oversights:
  *
- * - **A note no clause selects is not in the book.** A project decides what its
- *   own volume carries, so an omission is an editorial act and this pass has no
- *   standing to call it a defect.
+ * - **A note no clause selects is not in the book.** This pass has no standing
+ *   to call that a defect: whether a note belongs in some other book of the
+ *   package is a question about every book at once, which the coverage report
+ *   ({@link module:engine/pdf-coverage}) answers.
  * - **A note several clauses select appears several times.** A reference work
  *   may legitimately carry an entry under more than one heading, so each
  *   occurrence is its own page, its own outline node and its own anchor — and
@@ -169,20 +170,25 @@ const QUALIFIED_TABLE = /\bfrom\s+["'`]?[A-Za-z_][\w-]*["'`]?\s*\./i;
  * @param {object} [opts] - Options.
  * @param {string} [opts.text] - The file's source, for finding positions. Every
  *   finding without one is still reported, just without a locator.
+ * @param {Array<string|number>} [opts.at] - Where `raw` sits in `text`: `[]`
+ *   for a tree file, `["pdf", "books", i]` for a tree written inline in the
+ *   configuration. Every key path — and so every position, here and in
+ *   {@link runTreeFilters} — starts with it.
  * @returns {{nodes: object[], findings: object[]}} The flattened tree and what
  *   was wrong with it.
  */
-export function parseDocumentTree(raw, { text } = {}) {
+export function parseDocumentTree(raw, { text, at = [] } = {}) {
     const findings = [];
     const nodes = [];
     if (!raw || typeof raw !== "object" || !Array.isArray(raw.contents)) {
         findings.push({
             severity: "error",
             message: "the document tree must be a mapping with a `contents:` list",
+            ...(at.length ? position(text, at) : {}),
         });
         return { nodes, findings };
     }
-    walkSections(raw.contents, ["contents"], [], {}, { nodes, findings, text });
+    walkSections(raw.contents, [...at, "contents"], [], {}, { nodes, findings, text });
     return { nodes, findings };
 }
 
@@ -199,9 +205,11 @@ export function parseDocumentTree(raw, { text } = {}) {
  * @param {string[]} trail - Section titles above this level.
  * @param {object} inherited - Presentation from ancestors.
  * @param {object} ctx - `{ nodes, findings, text }`, accumulated.
+ * @param {Array<string|number>} [inheritedPageAt] - Where the `page:` mapping
+ *   the ancestors left in force is declared, when one is.
  * @returns {void}
  */
-function walkSections(contents, keyPath, trail, inherited, ctx) {
+function walkSections(contents, keyPath, trail, inherited, ctx, inheritedPageAt) {
     contents.forEach((entry, i) => {
         const at = [...keyPath, i];
         if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
@@ -241,6 +249,9 @@ function walkSections(contents, keyPath, trail, inherited, ctx) {
         for (const key of PRESENTATION_KEYS) {
             if (entry[key] !== undefined) presentation[key] = entry[key];
         }
+        // A section's own `page:` replaces the inherited one whole, so the
+        // mapping in force is declared on the nearest section that wrote one.
+        const pageAt = entry.page !== undefined ? [...at, "page"] : inheritedPageAt;
 
         const here = [...trail, title];
         const list = Array.isArray(entry.contents) ? entry.contents : [];
@@ -256,10 +267,11 @@ function walkSections(contents, keyPath, trail, inherited, ctx) {
             depth: here.length,
             keyPath: at,
             presentation,
+            pageAt,
             items: collectItems(list, [...at, "contents"], here, ctx),
         });
 
-        walkSections(list, [...at, "contents"], here, presentation, ctx);
+        walkSections(list, [...at, "contents"], here, presentation, ctx, pageAt);
     });
 }
 
@@ -357,14 +369,10 @@ function finding(ctx, keyPath, message, opts) {
  * something that is not a note, and unable to pick up the `doc<type>`
  * documentation rows that ride the same index as the notes they document.
  *
- * **A filter that selects nothing is an error**, and the distinction that makes
- * that consistent is worth stating. A *note* no clause selects is expected: the
- * book is a selection and a project decides what its own volume carries. A
- * *clause* that selects no note is not the same thing — a filter is a deliberate
- * act, so one matching nothing is either wrong or left over from a structure
- * that has moved on, and in both cases the tree should not carry it. Reported
- * with the section's name and the filter's position, so the choice between
- * fixing it and deleting it is the author's.
+ * **A filter that selects nothing is not a finding.** A section whose clauses
+ * select nothing is left out of the plan, and a book whose clauses select
+ * nothing at all is refused by the build. Notes that a mistyped clause fails to
+ * take are reported by the coverage check, which names each one.
  *
  * @param {object[]} nodes - From {@link parseDocumentTree}.
  * @param {{query: (sql: string) => Promise<{rows: object[]}>}} db - An open
@@ -383,18 +391,7 @@ export async function runTreeFilters(nodes, db, { keep = () => true, text } = {}
             const where = `\`${node.trail.join(" › ")}\``;
             try {
                 const { rows } = await db.query(`SELECT * FROM notes WHERE ${item.where}`);
-                const kept = rows.filter(keep);
-                selections.set(item.id, kept);
-                if (!kept.length) {
-                    findings.push({
-                        severity: "error",
-                        message:
-                            `${where}: the filter selected no notes — ` +
-                            `\`${item.where}\` matches nothing in this project, so ` +
-                            `either it is wrong or the section should not be here`,
-                        ...position(text, [...item.keyPath, "filter"]),
-                    });
-                }
+                selections.set(item.id, rows.filter(keep));
             } catch (err) {
                 findings.push({
                     severity: "error",
@@ -426,11 +423,8 @@ export async function runTreeFilters(nodes, db, { keep = () => true, text } = {}
  *
  * **A section with nothing in it does not print**, and emptiness is judged after
  * its descendants are: a section holding only sections that all resolved to
- * nothing is itself empty. In a correct tree this never fires — a filter that
- * selects nothing is reported by {@link runTreeFilters} as the error it is — so
- * this is the graceful half of that failure rather than a feature: a build whose
- * filters are broken still produces a readable document to look at while they
- * are fixed. A section holding only prose is not empty; it is a preface.
+ * nothing is itself empty. The omission is silent. A section holding only prose
+ * is not empty; it is a preface.
  *
  * @param {object[]} nodes - From {@link parseDocumentTree}.
  * @param {object} [opts] - Options.
@@ -502,6 +496,7 @@ function emitSection(node, nodes, ctx) {
         trail: node.trail,
         depth: node.depth,
         presentation: node.presentation,
+        pageAt: node.pageAt,
         anchor: anchorFor(slugify(node.trail.join(" ")) || "section", ctx.seen),
     });
 
@@ -521,6 +516,7 @@ function emitSection(node, nodes, ctx) {
                 trail: node.trail,
                 depth: node.depth,
                 presentation: node.presentation,
+                pageAt: node.pageAt,
                 anchor: anchorFor(slugify(item.file.replace(/\.md$/i, "")) || "prose", ctx.seen),
             });
             contributed++;
@@ -542,6 +538,7 @@ function emitSection(node, nodes, ctx) {
                 trail: node.trail,
                 depth: node.depth,
                 presentation: node.presentation,
+                pageAt: node.pageAt,
                 anchor,
             });
             contributed++;

package/engine/project-init.mjs

@@ -2,6 +2,12 @@
  * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
  * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
  *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
@@ -13,6 +19,7 @@ import YAML from "yaml";
 import prettier from "prettier";
 import prettierConfig from "../prettier-config.mjs";
 import { CONFIG_FILENAMES, configFromData } from "./pack-config.mjs";
+import { positionOfYamlPath } from "./diagnostics.mjs";
 import { checkLabelRegistry } from "../labels.mjs";
 import { formatNoteFrontmatter } from "./note-format.mjs";
 
@@ -128,6 +135,7 @@ function projectConfig(answers) {
     const config = {
         contentPackage: answers.contentPackage,
         packageKind: answers.kind,
+        authors: [{ name: answers.author }],
     };
     if (answers.kind !== "documentation") {
         config.compatibility = {
@@ -138,7 +146,19 @@ function projectConfig(answers) {
         config.packs = [{ name: "journals", label: "Journals", type: "JournalEntry" }];
     }
     config.publish = { address: { prefix: "" } };
-    config.pdf = { title: answers.title, document: "book.yaml", out: "build/pdf" };
+    // The stem is the package's own name, so the one book is
+    // `<package>-<version>.pdf` rather than `<package>-<id>-<version>.pdf`.
+    config.pdf = {
+        out: "build/pdf",
+        books: [
+            {
+                id: "book",
+                title: answers.title,
+                document: "book.yaml",
+                out: answers.contentPackage,
+            },
+        ],
+    };
     config.site = {
         ...(answers.kind === "documentation" ? { title: answers.title } : {}),
         assets: "https://cdn.heroiclands.org",
@@ -154,7 +174,6 @@ function projectConfig(answers) {
             manifest: {
                 title: answers.title,
                 descriptionHtml: answers.description,
-                authors: [{ name: answers.author }],
                 license: "LICENSE.md",
                 readme: "README.md",
                 languages: [{ lang: "en", name: "English", path: "lang/en.json" }],
@@ -451,10 +470,12 @@ export function checkProject(rootDir) {
         }
     }
     let config;
+    let configSource = "";
     if (names.length === 1 && names[0] !== "package-build.config.mjs") {
         const file = names[0];
         try {
             const source = fs.readFileSync(path.join(root, file), "utf8");
+            configSource = source;
             config = YAML.parse(source);
             configFromData(config, path.join(root, file));
         } catch (err) {
@@ -465,10 +486,29 @@ export function checkProject(rootDir) {
         if (!nonempty(config.site?.assets) || !nonempty(config.site?.description)) {
             add(names[0], "site.assets and site.description are required for the website");
         }
-        if (!nonempty(config.pdf?.title) || !nonempty(config.pdf?.document)) {
-            add(names[0], "pdf.title and pdf.document are required for the book");
-        } else if (!fs.existsSync(path.join(root, config.pdf.document))) {
-            add(config.pdf.document, "the book document tree is missing");
+        const books = config.pdf?.books;
+        if (!Array.isArray(books) || books.length === 0) {
+            add(names[0], "pdf.books is required for the book");
+        } else {
+            books.forEach((book, i) => {
+                for (const [keyPath, file, what] of [
+                    [["document"], book?.document, "document tree"],
+                    [["coverImage"], book?.coverImage, "cover image"],
+                    ...(Array.isArray(book?.front) ?
+                        book.front.map((entry, j) => [["front", j], entry, "front-matter file"])
+                    :   []),
+                ]) {
+                    if (nonempty(file) && !fs.existsSync(path.join(root, file))) {
+                        findings.push({
+                            file: names[0],
+                            ...positionOfYamlPath(configSource, ["pdf", "books", i, ...keyPath], {
+                                key: true,
+                            }),
+                            message: `book \`${book.id}\`: the ${what} \`${file}\` does not exist`,
+                        });
+                    }
+                }
+            });
         }
         if (config.packageKind !== "documentation") {
             if (!nonempty(config.packageBuild?.manifest?.title)) {

package/engine/prose-config.mjs

@@ -25,7 +25,7 @@
  * invokes it.
  *
  * **Neither of these is an override.** A consumer that declares its own
- * Prettier config or its own `.markdownlint-cli2.jsonc` wins; what ships here
+ * Prettier config or its own `.markdownlint-cli2.*` options file wins; what ships here
  * is the default a repository gets for declaring nothing. Repository *layout*
  * knowledge — which paths to skip — stays with the repository that has the
  * layout, in its own ignore files.

package/engine/prose-lint.mjs

@@ -21,12 +21,13 @@
  * shared configuration *as a default a local one overrides*, and reporting
  * findings in the one parseable form every check in this package emits.
  *
- * **Neither tool's own file discovery is reimplemented.** Prettier decides what
- * it formats and what an ignore file excludes, through `getFileInfo`;
- * markdownlint expands its own globs and honours `.gitignore` itself. A second
- * implementation of either would drift from the tool it stands in for, and the
- * whole point of the command is that `package-build format --check` and a bare
- * `prettier --check .` report the same thing.
+ * **Prettier's own file discovery is not reimplemented.** Prettier decides what
+ * it formats and what an ignore file excludes, through `getFileInfo`; a second
+ * implementation would drift from the tool it stands in for, and the whole point
+ * of the command is that `package-build format --check` and a bare
+ * `prettier --check .` report the same thing. Markdown linting walks the tree
+ * with `./markdownlint-run.mjs`, which applies
+ * `.gitignore` files and the configured globs itself.
  *
  * @module
  */
@@ -42,17 +43,8 @@ import {
     sharedPrettierDivergence,
     sharedPrettierOptionsFor,
 } from "./prose-config.mjs";
-
-/**
- * Directories never walked, whatever the ignore files say.
- *
- * `node_modules` is in every consumer's `.gitignore` and would be excluded
- * anyway; skipping it in the walk rather than per file is the difference
- * between a check that takes a second and one that stats a hundred thousand
- * files to be told each is ignored. `.git` is in nobody's `.gitignore`, so it
- * has to be named.
- */
-const NEVER_WALK = Object.freeze(new Set([".git", "node_modules"]));
+import { MarkdownConfigError, runMarkdownlint } from "./markdownlint-run.mjs";
+import { walkFiles } from "./walk-files.mjs";
 
 /**
  * The ignore files Prettier consults, in its own default order.
@@ -101,37 +93,6 @@ const CONVENTION_PROBES = Object.freeze({ code: "index.mjs", markdown: "README.m
 /** The one line a consumer writes to adopt the shared configuration verbatim. */
 const SHARED_CONFIG_RE_EXPORT = 'export { default } from "@heroiclands/package-build/prettier";';
 
-/**
- * Every file under a root, minus the directories nothing should walk.
- *
- * @param {string} root - Absolute path to walk.
- * @returns {string[]} Absolute file paths, in directory order.
- */
-function walkFiles(root) {
-    const out = [];
-    /** @param {string} dir - Directory to descend into. */
-    const descend = (dir) => {
-        let entries;
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        } catch {
-            // A directory that vanished or cannot be read is not a finding
-            // about prose; leave it to whatever owns it.
-            return;
-        }
-        for (const entry of entries) {
-            const abs = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                if (!NEVER_WALK.has(entry.name)) descend(abs);
-            } else if (entry.isFile()) {
-                out.push(abs);
-            }
-        }
-    };
-    descend(root);
-    return out;
-}
-
 /**
  * Check — or rewrite — every file Prettier claims, under one root.
  *
@@ -408,10 +369,10 @@ function toDiagnostic(directory, result) {
 /**
  * Lint a repository's markdown against the shared rule set.
  *
- * {@link MARKDOWNLINT_CONFIG} is passed as markdownlint's `optionsDefault`,
- * which is precisely the "shipped default, consumer overrides" behaviour the
- * command promises: a repository with no configuration of its own gets these
- * rules, and a `.markdownlint-cli2.jsonc` found in the tree overrides them.
+ * {@link MARKDOWNLINT_CONFIG} is the default rule set, which is precisely the
+ * "shipped default, consumer overrides" behaviour the command promises: a
+ * repository with no configuration of its own gets these rules, and a
+ * `.markdownlint-cli2.*` options file found in the tree overrides them.
  *
  * The override is **key by key, and each key wholesale** — which is not the same
  * as "replaces it", and the difference is the one worth stating. A consumer file
@@ -419,55 +380,58 @@ function toDiagnostic(directory, result) {
  * and every per-rule option; but its `ignores` *replaces*
  * {@link MARKDOWN_IGNORES} rather than extending it, so such a file must restate
  * every shared entry it still wants. Omitting `CHANGELOG.md` there silently
- * starts linting a generated file. `node_modules` stays excluded by the
- * command's glob even when a consumer replaces `ignores`.
+ * starts linting a generated file. `node_modules` stays excluded even when a
+ * consumer replaces `ignores`.
+ *
+ * A configuration file the contract refuses (an unknown option, a key that
+ * cannot mean anything where it is written, a syntax error) is returned as a
+ * finding located in that file, and nothing is linted.
  *
  * @param {string} root - Repository to lint.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.paths] - Globs to lint instead of every
  *   markdown file.
  * @param {boolean} [opts.fix=false] - Apply the fixes markdownlint can make.
- * @param {(params: object) => Promise<number>} [opts.run] - The
- *   markdownlint-cli2 entry point, for tests.
  * @returns {Promise<{findings: object[], exitCode: number}>} The findings, and
- *   markdownlint's own exit code.
+ *   an exit code that is 1 when there are any.
  */
 export async function lintMarkdown(root, opts = {}) {
     const { paths, fix = false } = opts;
-    const run = opts.run ?? (await import("markdownlint-cli2")).main;
     const directory = path.resolve(root);
 
-    /** @type {object[]} */
-    const collected = [];
-    // A formatter is normally a module id resolved from disk, but
-    // markdownlint-cli2 passes a non-string through untouched — so the results
-    // can be collected in process rather than parsed back out of its output.
-    const collect = ({ results }) => {
-        collected.push(...results);
-    };
-
-    const argv = [...(paths?.length ? paths : MARKDOWN_GLOBS), "!**/node_modules/**"];
-    if (fix) argv.push("--fix");
-
-    const exitCode = await run({
-        directory,
-        argv,
-        optionsDefault: {
-            config: MARKDOWNLINT_CONFIG,
-            // Generated markdown reports on its generator, not its author, and
-            // every consumer already lists its generated trees here.
-            gitignore: true,
-            ignores: [...MARKDOWN_IGNORES],
-            noProgress: true,
-            noBanner: true,
-        },
-        optionsOverride: { outputFormatters: [[collect]] },
-        logMessage: () => {},
-        logError: () => {},
-    });
+    let results;
+    try {
+        ({ results } = await runMarkdownlint({
+            directory,
+            globs: paths,
+            fix,
+            defaults: {
+                config: MARKDOWNLINT_CONFIG,
+                // Generated markdown reports on its generator, not its author,
+                // and every consumer already lists its generated trees here.
+                gitignore: true,
+                globs: MARKDOWN_GLOBS,
+                ignores: [...MARKDOWN_IGNORES],
+            },
+        }));
+    } catch (err) {
+        if (!(err instanceof MarkdownConfigError)) throw err;
+        return {
+            findings: [
+                {
+                    file: err.file,
+                    ...(err.line ? { line: err.line } : {}),
+                    ...(err.line && err.column ? { column: err.column } : {}),
+                    severity: "error",
+                    message: err.message,
+                },
+            ],
+            exitCode: 1,
+        };
+    }
 
     return {
-        findings: collected.map((result) => toDiagnostic(directory, result)),
-        exitCode,
+        findings: results.map((result) => toDiagnostic(directory, result)),
+        exitCode: results.length ? 1 : 0,
     };
 }