@heroiclands/package-build 23.1.1 → 23.2.0

package/types/engine/pdf-build.d.mts

@@ -2,7 +2,7 @@
  * The file on disk an authored image pathname names, or `null`.
  *
  * Two of the four forms {@link module:engine/pathnames.resolvePathname}
- * derives, used together: `local` is the file in this repository's own tree,
+ * derives, taken together: `local` is the file in this repository's own tree,
  * and `pdf` is where the book stages a copy of it.
  *
  * **Typst decides where that copy goes.** It resolves a path against its root —
@@ -57,45 +57,123 @@ export function stagedImagePath(src: string, config: object, opts?: {
  * @param {object} config - The resolved configuration.
  * @param {string} outDir - Where the book is written.
  * @param {object[]} findings - Collected here rather than thrown.
+ * @param {string} treeFile - The file the book's tree was read from — its
+ *   `document`, or the configuration for a tree written inline — which is
+ *   where a banner is declared.
+ * @param {string} [treeText] - That file's source, so a finding is located at
+ *   the `banner:` key that declared the value.
  * @returns {Map<string, string>} Declared path → the staged file's path,
  *   relative to the `.typ`.
  */
-export function stageBanners(entries: object[], config: object, outDir: string, findings?: object[]): Map<string, string>;
+export function stageBanners(entries: object[], config: object, outDir: string, findings: object[], treeFile: string, treeText?: string): Map<string, string>;
 /**
  * The file name a downloaded book identifies itself by.
  *
  * The zip and the manifest take their names from the manifest, so an asset's
  * name and its advertised URL cannot disagree. A PDF has no advertised URL, so
- * its name is a free choice — which is exactly why it is fixed here rather than
- * left for each of six consumers to invent.
+ * its name is the book's own file stem — its `out`, default
+ * `<contentPackage>-<id>` — with the version appended.
  *
- * @param {string} artifact - The package's artifact name.
+ * @param {string} stem - The book's file stem.
  * @param {string} version - The version being released.
- * @returns {string} `<artifact>-<version>.pdf`, or `<artifact>.pdf` unversioned.
+ * @returns {string} `<stem>-<version>.pdf`, or `<stem>.pdf` unversioned.
  */
-export function pdfFileName(artifact: string, version: string): string;
+export function pdfFileName(stem: string, version: string): string;
 /**
- * Build the book.
+ * The release assets the declared books produce, in configuration order.
+ *
+ * Builds nothing and reads no note: each entry is the file {@link buildPdf}
+ * writes for that book at `version`, as a path relative to the working
+ * directory inside `out` (default the configured `pdf.out`, else
+ * `build/dist`). A package that publishes no book — no `pdf:` block, or a
+ * content tree holding only a homepage — lists none.
+ *
+ * @param {object} [opts] - Options.
+ * @param {object} [opts.config] - A resolved configuration; loaded when absent.
+ * @param {string} [opts.version] - The version stamped in each file name.
+ * @param {string} [opts.out] - Where the books are written, overriding `pdf.out`.
+ * @returns {Array<{id: string, title: string, file: string}>} One entry per book.
+ */
+export function listBookAssets({ config, version, out }?: {
+    config?: object | undefined;
+    version?: string | undefined;
+    out?: string | undefined;
+}): Array<{
+    id: string;
+    title: string;
+    file: string;
+}>;
+/**
+ * Build the books the `pdf:` block declares — every one, or the one `book`
+ * names.
+ *
+ * Every declared book's filters run against one corpus and one database first,
+ * so coverage and each note's home book are computed over the whole set
+ * whichever books are requested. A book whose filters select no note is an
+ * error at its `id` and is not built; a section that selects none is left out.
+ *
+ * A finding about a configured key — an unknown `--book`, a `coverImage`,
+ * `document` or `front` file that does not exist — names the configuration
+ * file and, for a YAML one, the line and column of that key. A book with a
+ * missing file is not built; the others still are.
  *
  * @param {object} [opts] - Options.
  * @param {object} [opts.config] - A resolved configuration; loaded when absent.
+ * @param {string} [opts.configPath] - The file `config` was read from, for
+ *   findings at a configured key. Defaults to the file the loader read, or to
+ *   the configuration file in `config.rootDir`.
+ * @param {string} [opts.book] - The `id` of the one book to build; every book
+ *   when absent.
  * @param {string} [opts.out] - Where to write, overriding `pdf.out`.
  * @param {string} [opts.version] - Stamped on the title page and the file name.
  * @param {boolean} [opts.compile] - Whether to run Typst. False leaves the
- *   `.typ` source, which is what the unit tests read.
+ *   `.typ` source, which is what the unit tests read, and runs a single pass:
+ *   a reference to a note another book is home to prints `p. ?`. True renders
+ *   every book, measures the page each entry starts on, writes `pages.json`
+ *   into the output directory, and renders again with those pages — see
+ *   {@link module:engine/pdf-pages}.
+ * @param {Function} [opts.readPages] - {@link
+ *   module:engine/pdf-pages.readEntryPages}, for tests.
  * @param {Function} [opts.resolveReplacement] - {@link
  *   module:engine/asset-replacement.resolveAssetReplacement}, for tests.
  *   Loaded from that module otherwise, and only when a relationship declares
  *   `assetReplacement: true` — a build with none never imports it.
- * @returns {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.
+ * @returns {Promise<{built: boolean, reason: string|null, findings: object[],
+ *   imageReports: object[], books: Array<{id: string, title: string,
+ *   built: boolean, typ: string, pdf: string|null, stats: object}>,
+ *   homes: Map<string, string>, summary: object|null}>}
+ *   `built` is true when every requested book was written (and compiled, when
+ *   asked); `books` holds each book whose source was written. `homes` maps a
+ *   selected note's canonical address to the id of the first book that selects
+ *   it, and `summary` is {@link module:engine/pdf-coverage.coverage}'s, over
+ *   every declared book whichever was requested; both are empty when a book's
+ *   selection could not be read.
  */
-export function buildPdf({ config, out, version, compile, resolveReplacement, }?: {
+export function buildPdf({ config, configPath, book, out, version, compile, readPages, resolveReplacement, }?: {
     config?: object | undefined;
+    configPath?: string | undefined;
+    book?: string | undefined;
     out?: string | undefined;
     version?: string | undefined;
     compile?: boolean | undefined;
+    readPages?: Function | undefined;
     resolveReplacement?: Function | undefined;
-}): Promise<object>;
+}): Promise<{
+    built: boolean;
+    reason: string | null;
+    findings: object[];
+    imageReports: object[];
+    books: Array<{
+        id: string;
+        title: string;
+        built: boolean;
+        typ: string;
+        pdf: string | null;
+        stats: object;
+    }>;
+    homes: Map<string, string>;
+    summary: object | null;
+}>;
 /**
  * The command line the compile runs, as data.
  *
@@ -109,6 +187,14 @@ export function buildPdf({ config, out, version, compile, resolveReplacement, }?
  * @returns {string[]} The arguments, in order.
  */
 export function typstArgs(typPath: string, pdfPath: string, pdf?: object): string[];
+/**
+ * The flags that decide which faces a layout uses, shared by the compile and by
+ * the page measurement so both lay the book out in the same metrics.
+ *
+ * @param {object} [pdf] - The resolved `pdf:` block.
+ * @returns {string[]} The arguments, in order.
+ */
+export function typstFontArgs(pdf?: object): string[];
 /**
  * The compiler's own warnings, as findings.
  *

package/types/engine/pdf-coverage.d.mts

@@ -0,0 +1,60 @@
+/**
+ * Whether a record is a note a book can print.
+ *
+ * @param {object} record - An index record.
+ * @returns {boolean} False for an asset, a documentation row, a stub and a `gm` note.
+ */
+export function isPrintable(record: object): boolean;
+/**
+ * The key a note is counted by: its canonical address as text. An index record
+ * holds the address as a tuple and a row of the notes database as a string;
+ * both give the same key.
+ *
+ * @param {object} record - A printable record.
+ * @returns {string} The key.
+ */
+export function recordKey(record: object): string;
+/**
+ * Compute coverage, homes and the summary.
+ *
+ * @param {object} input - Options.
+ * @param {Array<{id: string, records: object[]}>} input.books - Each book's
+ *   selected records, in configuration order; a record selected twice appears
+ *   twice.
+ * @param {object[]} input.corpus - Every record in the index.
+ * @param {object[]} [input.unprinted] - The records `pdf.unprinted` selects.
+ * @param {"warning"|"error"|"off"} [input.mode] - `pdf.coverage`.
+ * @param {(record: object) => {file?: string, line?: number, column?: number}} [input.locate]
+ *   Where a note's `type:` line sits; a field it cannot supply is dropped.
+ * @returns {{findings: object[], homes: Map<string, string>, summary: object}}
+ *   The findings in corpus order, each note's home book id by address, and the
+ *   summary: per-book counts, totals and every note several books select.
+ */
+export function coverage({ books, corpus, unprinted, mode, locate }: {
+    books: Array<{
+        id: string;
+        records: object[];
+    }>;
+    corpus: object[];
+    unprinted?: object[] | undefined;
+    mode?: "error" | "off" | "warning" | undefined;
+    locate?: ((record: object) => {
+        file?: string;
+        line?: number;
+        column?: number;
+    }) | undefined;
+}): {
+    findings: object[];
+    homes: Map<string, string>;
+    summary: object;
+};
+/**
+ * The summary as the lines the command prints.
+ *
+ * @param {object} summary - From {@link coverage}.
+ * @returns {string[]} One line per book, one for the totals, one per note
+ *   several books select.
+ */
+export function summaryLines(summary: object): string[];
+/** The message a note in no book carries. */
+export const UNCOVERED_MESSAGE: "no book selects this note; add it to a book's query or to `pdf.unprinted`";

package/types/engine/pdf-index.d.mts

@@ -9,27 +9,56 @@ export function indexMarker(slug: string, main?: boolean): string;
 /**
  * Every term the book's index lists, in index order.
  *
+ * A book lists the notes it is home to. An entry `owns` rejects is a reprint of
+ * another book's note: it prints there, and its term belongs to its home
+ * book's index.
+ *
  * @param {object[]} entries - The plan's entries.
- * @returns {Array<{letter: string, name: string, slug: string, see?: string}>}
- *   Terms with `see` set for a cross-reference to the main name it points at.
+ * @param {object} [opts] - Options.
+ * @param {(entry: object) => boolean} [opts.owns] - Whether this book is the
+ *   entry's home. Every entry when absent.
+ * @param {Array<{slug: string, name: string, title: string, page: string|number}>} [opts.foreign] -
+ *   Notes another book prints, listed as `Name: Book title, p. N` once this
+ *   book mentions them.
+ * @returns {Array<{letter: string, name: string, slug: string, see?: string,
+ *   foreign?: {title: string, page: string}}>} Terms with `see` set for a
+ *   cross-reference to the main name it points at.
  */
-export function indexTerms(entries: object[]): Array<{
+export function indexTerms(entries: object[], { owns, foreign }?: {
+    owns?: ((entry: object) => boolean) | undefined;
+    foreign?: {
+        slug: string;
+        name: string;
+        title: string;
+        page: string | number;
+    }[] | undefined;
+}): Array<{
     letter: string;
     name: string;
     slug: string;
     see?: string;
+    foreign?: {
+        title: string;
+        page: string;
+    };
 }>;
 /**
  * The Typst function definitions the markers and the chapter rely on.
  *
+ * @param {object} [opts] - Options.
+ * @param {boolean} [opts.seeAlso] - Whether the chapter may list notes another
+ *   book prints.
  * @returns {string} Typst source.
  */
-export function indexPreamble(): string;
+export function indexPreamble({ seeAlso }?: {
+    seeAlso?: boolean | undefined;
+}): string;
 /**
  * The index chapter, ready to follow the last entry.
  *
  * @param {object[]} entries - The plan's entries.
  * @param {string} title - The book's title, which kicks the chapter.
+ * @param {object} [opts] - As {@link indexTerms}.
  * @returns {string} Typst source, or "" when the book has nothing to index.
  */
-export function indexChapter(entries: object[], title: string): string;
+export function indexChapter(entries: object[], title: string, opts?: object): string;

package/types/engine/pdf-pages.d.mts

@@ -0,0 +1,143 @@
+/**
+ * The arguments that measure a book, as data.
+ *
+ * Fonts are the compile's, because a face with other metrics lays out other
+ * pages.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string[]} fontArgs - `--ignore-system-fonts --font-path …`, as the
+ *   compile passes them.
+ * @returns {string[]} The arguments, in order.
+ */
+export function evalArgs(typPath: string, fontArgs: string[]): string[];
+/**
+ * Measure the page each labelled entry of a book starts on.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string[]} fontArgs - The compile's font arguments.
+ * @param {string} [binary] - The Typst binary.
+ * @returns {{ok: boolean, message: string, pages: Map<string, number>}} The
+ *   printed page of every labelled heading, keyed by label.
+ */
+export function readEntryPages(typPath: string, fontArgs: string[], binary?: string): {
+    ok: boolean;
+    message: string;
+    pages: Map<string, number>;
+};
+/**
+ * Every note that has a home book, with the anchor its entry carries there.
+ *
+ * **A note a book prints twice has one page**: the first entry, which is the
+ * one the book's links reach. A note a book reprints from another book's home
+ * keeps its home book's page here, because the home is the first book in
+ * configuration order that selects it.
+ *
+ * @param {object} input - Options.
+ * @param {Array<{id: string, title: string, plan: {entries: object[]}}>} input.books -
+ *   The books that render, in configuration order.
+ * @param {Map<string, string>} input.homes - Each note's key → its home book's
+ *   id, from {@link module:engine/pdf-coverage.coverage}.
+ * @returns {Array<{key: string, book: string, title: string, anchor: string,
+ *   record: object, slug: string, aliases: string[]}>} One per homed note, in book order and
+ *   then entry order.
+ */
+export function homeEntries({ books, homes }: {
+    books: Array<{
+        id: string;
+        title: string;
+        plan: {
+            entries: object[];
+        };
+    }>;
+    homes: Map<string, string>;
+}): Array<{
+    key: string;
+    book: string;
+    title: string;
+    anchor: string;
+    record: object;
+    slug: string;
+    aliases: string[];
+}>;
+/**
+ * The table written as `pages.json`.
+ *
+ * @param {ReturnType<typeof homeEntries>} entries - From {@link homeEntries}.
+ * @param {Map<string, Map<string, number>>} measured - Book id → label → page.
+ * @returns {Record<string, {book: string, page: number}>} Keyed by the note's
+ *   key, in sorted key order. A note whose entry was not measured is absent.
+ */
+export function pageTable(entries: ReturnType<typeof homeEntries>, measured: Map<string, Map<string, number>>): Record<string, {
+    book: string;
+    page: number;
+}>;
+/**
+ * The notes whose page differs between two tables.
+ *
+ * @param {Record<string, {book: string, page: number}>} before - A table.
+ * @param {Record<string, {book: string, page: number}>} after - A later one.
+ * @returns {Array<{key: string, book: string, before: number|undefined,
+ *   after: number|undefined}>} In sorted key order.
+ */
+export function movedPages(before: Record<string, {
+    book: string;
+    page: number;
+}>, after: Record<string, {
+    book: string;
+    page: number;
+}>): Array<{
+    key: string;
+    book: string;
+    before: number | undefined;
+    after: number | undefined;
+}>;
+/**
+ * The lookup one book renders its cross-book references from.
+ *
+ * A note the book prints (a reprint included) is never in it: its link stays an
+ * internal destination. Keys are the three forms the book's own link map
+ * answers to — slug, canonical address and documentation address.
+ *
+ * `get` counts the references it answers, which is how the build knows whether
+ * a measured pass can change anything.
+ *
+ * @param {object} input - Options.
+ * @param {ReturnType<typeof homeEntries>} input.entries - From {@link homeEntries}.
+ * @param {string} input.book - The id of the book that renders.
+ * @param {Map<string, string>} input.printed - The book's own link map.
+ * @param {Record<string, {book: string, page: number}>} [input.table] - The
+ *   measured pages; every page is {@link UNMEASURED_PAGE} when absent.
+ * @param {boolean} [input.seeAlso] - Whether the book's index lists the notes
+ *   it mentions here (`pdf.indexSeeAlso`). `listed` is empty when not.
+ * @returns {{used: number, seeAlso: boolean,
+ *   listed: Array<{slug: string, name: string, title: string, page: string|number}>,
+ *   get: (key: string) => ({slug: string, title: string, page: string|number}|undefined)}}
+ *   The lookup. `listed` is every note another book prints, for the index to
+ *   show those this book mentions.
+ */
+export function elsewhereFor({ entries, book, printed, table, seeAlso }: {
+    entries: ReturnType<typeof homeEntries>;
+    book: string;
+    printed: Map<string, string>;
+    table?: Record<string, {
+        book: string;
+        page: number;
+    }> | undefined;
+    seeAlso?: boolean | undefined;
+}): {
+    used: number;
+    seeAlso: boolean;
+    listed: Array<{
+        slug: string;
+        name: string;
+        title: string;
+        page: string | number;
+    }>;
+    get: (key: string) => ({
+        slug: string;
+        title: string;
+        page: string | number;
+    } | undefined);
+};
+/** What a reference prints for a page that has not been measured. */
+export const UNMEASURED_PAGE: "?";

package/types/engine/pdf-render.d.mts

@@ -99,6 +99,9 @@ export function stripHtmlComments(markdown: string): string;
  *   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
@@ -129,6 +132,12 @@ export function markdownToTypst(markdown: string, opts?: {
     }[] | undefined;
     prepared?: boolean | undefined;
     url?: string | undefined;
+    elsewhere?: {
+        get: (key: string) => ({
+            title: string;
+            page: string | number;
+        } | undefined);
+    } | undefined;
     generated?: boolean | undefined;
 }): string;
 /**
@@ -155,6 +164,22 @@ export function markdownToTypst(markdown: string, opts?: {
  *   site to resolve it against or it is already absolute.
  */
 export function absolutePageUrl(url: string, site?: string): string;
+/**
+ * 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: string, away: {
+    title: string;
+    page: string | number;
+}): string;
 /**
  * The Typst definitions the book's page furniture is drawn with.
  *
@@ -298,9 +323,20 @@ export function bookTypstPreamble(): string;
  *   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({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners, maps, }?: {
+export function renderBook({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners, maps, coverImage, authors, copyright, license, index, }?: {
     plan: object;
     bodies: Map<string, string>;
     title: string;
@@ -314,6 +350,14 @@ export function renderBook({ plan, bodies, title, subtitle, front, fonts, versio
         path: string;
         title: string;
     }> | undefined;
+    coverImage?: string | undefined;
+    authors?: {
+        name: string;
+        role?: string;
+    }[] | undefined;
+    copyright?: string | undefined;
+    license?: string | undefined;
+    index?: object | undefined;
 }): string;
 /**
  * Point every internal link at a label the document actually declares.

package/types/engine/pdf-toc.d.mts

@@ -14,11 +14,16 @@
  * @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: unknown, { text }?: {
+export function parseDocumentTree(raw: unknown, { text, at }?: {
     text?: string | undefined;
+    at?: (string | number)[] | undefined;
 }): {
     nodes: object[];
     findings: object[];
@@ -33,14 +38,10 @@ export function parseDocumentTree(raw: unknown, { text }?: {
  * 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
@@ -78,11 +79,8 @@ export function runTreeFilters(nodes: object[], db: {
  *
  * **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.

package/types/engine/prose-config.d.mts

@@ -64,7 +64,7 @@ export function sharedPrettierDivergence(resolved: object | null | undefined, fi
  * 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/types/engine/prose-lint.d.mts

@@ -73,10 +73,10 @@ export function checkPrettierConventions(root: string, opts?: {
 /**
  * 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
@@ -84,23 +84,24 @@ export function checkPrettierConventions(root: string, opts?: {
  * 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 function lintMarkdown(root: string, opts?: {
     paths?: readonly string[] | undefined;
     fix?: boolean | undefined;
-    run?: ((params: object) => Promise<number>) | undefined;
 }): Promise<{
     findings: object[];
     exitCode: number;

package/types/engine/runtime-only-fields.d.mts

@@ -26,7 +26,7 @@ export function runtimeOnlyMessage(key: string, field: import("./field-spec.mjs"
 /**
  * The runtime-only fields a note actually writes, in declaration order.
  *
- * **Presence is the whole test**, as it is for every retired field: an authored
+ * **Presence is the whole test**: an authored
  * `onsetDate: null` is as much a claim about play state as a number is, and it
  * is exactly the belief the message exists to correct. So the question is
  * whether the path resolves to anything at all, never whether the value is a
@@ -34,7 +34,7 @@ export function runtimeOnlyMessage(key: string, field: import("./field-spec.mjs"
  *
  * Only `<block>.system.<to>` is searched, because it is the only position a
  * runtime-only field is reachable at. Such a declaration carries no `name`, so
- * it has neither a legacy in-block key nor a shared top-level source — and a
+ * it has neither an in-block key nor a shared top-level source — and a
  * bare `<block>.onsetDate` is an unrecognized block key, which
  * {@link module:engine/system-block.unknownBlockKeys} already reports as an
  * error naming the note and the line.