@heroiclands/package-build 20.3.1 → 20.5.0

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

@@ -0,0 +1,114 @@
+/**
+ * Validate the raw tree and flatten it into nodes.
+ *
+ * The format has no chapter/section distinction: every node is a section, and
+ * the leaves of the *document* are the notes and prose its contents resolve to.
+ * Depth is whatever the tree says, so nothing here caps or normalises it.
+ *
+ * `contents` is an **ordered, heterogeneous** list — prose, filters and child
+ * sections interleave in the sequence written, and that sequence is preserved
+ * exactly. A section that opens with a `file:` and then lists its entries is
+ * saying something different from one that does the reverse.
+ *
+ * @param {unknown} raw - The parsed document, as YAML returns it.
+ * @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.
+ * @returns {{nodes: object[], findings: object[]}} The flattened tree and what
+ *   was wrong with it.
+ */
+export function parseDocumentTree(raw: unknown, { text }?: {
+    text?: string | undefined;
+}): {
+    nodes: object[];
+    findings: object[];
+};
+/**
+ * Run every filter, and report the ones that would not run.
+ *
+ * The I/O half, kept apart from the planner for the reason the whole engine
+ * keeps them apart: the plan is then assertable without a database. The build
+ * owns the statement — `SELECT * FROM notes WHERE <clause>` — which is what
+ * makes a filter unable to reach another package's schema, unable to project
+ * 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.
+ *
+ * @param {object[]} nodes - From {@link parseDocumentTree}.
+ * @param {{query: (sql: string) => Promise<{rows: object[]}>}} db - An open
+ *   database, from {@link module:engine/sql-tables.openNotesDatabase}.
+ * @param {object} [opts] - Options.
+ * @param {(record: object) => boolean} [opts.keep] - Which rows are notes.
+ * @param {string} [opts.text] - The document's source, for finding positions.
+ * @returns {Promise<{selections: Map<string, object[]>, findings: object[]}>}
+ */
+export function runTreeFilters(nodes: object[], db: {
+    query: (sql: string) => Promise<{
+        rows: object[];
+    }>;
+}, { keep, text }?: {
+    keep?: ((record: object) => boolean) | undefined;
+    text?: string | undefined;
+}): Promise<{
+    selections: Map<string, object[]>;
+    findings: object[];
+}>;
+/**
+ * Resolve the flattened tree into the document plan.
+ *
+ * The plan is an ordered list of entries — `section`, `prose`, `note` — and it
+ * is the artifact worth having. Order, depth, the outline, the table of
+ * contents, anchor uniqueness and every link destination are all readable from
+ * it, so nearly the whole of what #316 asks for can be asserted here, on data,
+ * without a renderer or a PDF. Only how the result *looks* needs eyes.
+ *
+ * **Notes are sorted, prose is not.** A section's entries come out in
+ * `nameAscii` order — the ASCII fold `buildIndexRecord` already derives, so a
+ * circumflex sorts with its letter instead of after `Z` as a raw codepoint
+ * comparison would put it. Prose keeps the position it was written in, because
+ * its place in the sequence is the author's statement.
+ *
+ * **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.
+ *
+ * @param {object[]} nodes - From {@link parseDocumentTree}.
+ * @param {object} [opts] - Options.
+ * @param {Map<string, object[]>} [opts.selections] - Records each filter
+ *   selected, keyed by item id. Run by the caller: DuckDB is async and this is
+ *   not.
+ * @returns {{entries: object[], links: Map<string, string>, stats: object}}
+ *   The plan, the address→anchor map inbound wikilinks resolve through, and
+ *   what the selection came to.
+ */
+export function planDocument(nodes: object[], { selections }?: {
+    selections?: Map<string, object[]> | undefined;
+}): {
+    entries: object[];
+    links: Map<string, string>;
+    stats: object;
+};
+/**
+ * Presentation a node may declare, and that its descendants inherit.
+ *
+ * Reserved now although the first release renders none of them, because the
+ * shape of the file is the thing consumers commit to: a book that has to be
+ * restructured to gain a running head has the wrong format, not the wrong
+ * renderer. Inheritance is what makes them worth declaring at all — `Gear` says
+ * once which infobox its entries use, and nine sections beneath it agree.
+ *
+ * @type {readonly string[]}
+ */
+export const PRESENTATION_KEYS: readonly string[];

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

@@ -6,7 +6,7 @@
  *
  * @param {string} file - Path of the file about to be formatted.
  * @returns {object} Options to hand Prettier directly. Never carries
- *   `overrides`: passing that inline is what silently did nothing (#76).
+ *   `overrides`: passing that inline is what silently did nothing.
  */
 export function sharedPrettierOptionsFor(file: string): object;
 /**
@@ -15,11 +15,11 @@ export function sharedPrettierOptionsFor(file: string): object;
  * The runner resolves each file's options as *either* the consumer's own config
  * or {@link sharedPrettierOptionsFor}, never a merge. That is what bare Prettier
  * does and it is the contract — but it means the conventions this package exists
- * to publish hold by convention alone, and they lapse in two opposite directions
- * (#133). A consumer that declares any config of its own gets whatever that
+ * to publish hold by convention alone, and they lapse in two opposite directions.
+ * A consumer that declares any config of its own gets whatever that
  * config says: spread {@link PRETTIER_BASE} without the markdown override and
- * every note reindents at 4, the reindentation the override was added to prevent
- * (#76); write a partial `.prettierrc` such as `{"tabWidth": 2}` and
+ * every note reindents at 4, the reindentation the override was added to prevent;
+ * write a partial `.prettierrc` such as `{"tabWidth": 2}` and
  * `printWidth`, `trailingComma`, `experimentalTernaries` and the rest fall back
  * to Prettier's own defaults. A consumer that declares *nothing* formats one way
  * under this command and another under a bare `npx prettier`.
@@ -53,14 +53,14 @@ export function sharedPrettierDivergence(resolved: object | null | undefined, fi
 /**
  * The prose conventions every content repository writes to — one Prettier
  * configuration and one markdownlint rule set, declared here so a note
- * formatted in one repository is formatted the same way in the next (#69).
+ * formatted in one repository is formatted the same way in the next.
  *
- * These used to exist in exactly one consumer. The SoHL repository carried
+ * These belong in no single consumer. The SoHL repository carried
  * both; `sohl-thalorna` had Prettier but never ran it from `lint`; and
  * `sohl-kethira-basic` had neither, so the package least likely to have been
  * proofread was checked for addresses and nothing else. A rule set copied into
  * three repositories is one rule with three implementations, which is the drift
- * #20 exists to remove — so it is declared once, here, and every consumer
+ * this exists to remove — so it is declared once, here, and every consumer
  * invokes it.
  *
  * **Neither of these is an override.** A consumer that declares its own
@@ -95,7 +95,7 @@ export const PRETTIER_BASE: Readonly<object>;
  * **Declared apart from the `overrides` block, not derived from it.** Prettier
  * applies `overrides` only while resolving a config *file*; options handed to
  * it directly keep the global values, so a consumer with no config of its own
- * silently got markdown at 4 (#76). The runner needs the adjustment as data it
+ * silently got markdown at 4. The runner needs the adjustment as data it
  * can apply itself, and {@link PRETTIER_CONFIG} composes the same values into
  * the shape a config file wants — one source, two presentations.
  *

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

@@ -14,8 +14,7 @@
  * @param {boolean} [opts.write=false] - Rewrite unformatted files in place
  *   rather than reporting them. Each file is formatted to a fixpoint (up to
  *   {@link MAX_FORMAT_PASSES} passes), so a written tree is one a second run
- *   leaves alone; a file that will not converge is reported and left unchanged
- *   (#125).
+ *   leaves alone; a file that will not converge is reported and left unchanged.
  * @param {object} [opts.prettier] - The Prettier module, for tests.
  * @returns {Promise<{findings: Array<{file: string, severity: string,
  *   message: string}>, checked: number, written: string[]}>} The findings, how
@@ -37,7 +36,7 @@ export function checkFormatting(root: string, opts?: {
 }>;
 /**
  * Report where a repository's own Prettier configuration parts from the shared
- * one — or that it has none at all (#133).
+ * one — or that it has none at all.
  *
  * **Warnings, every one of them.** A consumer's config wins by design and this
  * does not change that; it only refuses to let the divergence be silent, which
@@ -58,7 +57,7 @@ export function checkFormatting(root: string, opts?: {
  * @returns {Promise<{findings: Array<{file?: string, severity: string,
  *   message: string}>, configFile: string|null}>} The findings and the config
  *   file they are about, which is `null` when the repository declares none. A
- *   finding about a missing file carries no `file`: #17's rule is to drop a
+ *   finding about a missing file carries no `file`: the rule is to drop a
  *   field rather than invent one.
  */
 export function checkPrettierConventions(root: string, opts?: {

package/types/engine/region-events.d.mts

@@ -9,10 +9,10 @@
  * runtime bridge from drifting apart.
  *
  * It sits in this package rather than in the system's `src/` tree because the
- * map-note compiler that reads it is installed as a dependency (#1501), and a
+ * map-note compiler that reads it is installed as a dependency, and a
  * relative path out of the package would resolve to garbage from
  * `node_modules`. The runtime reaches it back through the package's
- * `./engine/region-events` entry point (#1510). It is engine-side, not
+ * `./engine/region-events` entry point. It is engine-side, not
  * SoHL-side, because any content module that authors a scene region — an
  * adventure module included — needs this vocabulary.
  *

package/types/engine/retired-fields.d.mts

@@ -43,11 +43,11 @@ export function assertNoDraftField(fm: object | null | undefined, { file, absPat
  * It says what the field fed and what to write instead, rather than which value
  * to correct: no value makes declaring it right.
  *
- * **What it did (#180).** It was the authored half of the alias index — the
+ * **What it did.** It was the authored half of the alias index — the
  * namespace a bare `[[Alias]]` was looked up in. Across the three content trees
  * not one bare link resolved through it, while the collision rule that kept it
  * unambiguous folded in every note's `name.full` and so dictated what a note
- * could be named (#179). The form is retired, so the list has no reader.
+ * could be named. The form is retired, so the list has no reader.
  *
  * **`name.aliases` is a different field and is not retired.** It fed the same
  * index, but unlike the top-level list it is being kept — reserved, unread,
@@ -114,10 +114,10 @@ export function declaresRetiredAliasesField(fm: object | null | undefined): bool
  * It names what lands a section now rather than a value to correct: no value
  * makes declaring the field right.
  *
- * **What it did (#202).** It named the section a `collection` note headed,
+ * **What it did.** It named the section a `collection` note headed,
  * under the `collection` landing rule — the only reader it ever had, in the
  * second branch of `landingOf` (`engine/content-address.mjs`). That rule went
- * first, and the whole mechanism went with it (#204): a section is a Hugo
+ * first, and the whole mechanism went with it: a section is a Hugo
  * directory the note format does not carry, so no note lands one and a page
  * that introduces a type is an ordinary note addressed `doc-<type>`. Nothing
  * else read the field, and no schema or vocabulary declared it, so left in
@@ -237,7 +237,7 @@ export function retiredAliasMessage(retired: string, current: string, file?: str
  * What a note writing a field at its **legacy in-block position** is told.
  *
  * The same three-step retirement `retiredAliasMessage` announces, applied to a
- * *position* rather than a spelling (#305). A field whose shared source moved
+ * *position* rather than a spelling. A field whose shared source moved
  * under `data:` keeps reading the key its block still carries, that read wins,
  * and it is reported here so a sweep has something to count down — without it,
  * moving a field into `data:` would be a flag day across every repository that
@@ -260,9 +260,10 @@ export function legacyKeyMessage(block: string, field: {
 }, file?: string): string;
 /**
  * What a note writing a field at the **top-level key `data:` gathered it off**
- * is told (#332).
+ * is told.
  *
- * {@link legacyKeyMessage}'s counterpart for the other retiring position. #128
+ * {@link legacyKeyMessage}'s counterpart for the other retiring position. The
+ * sweep
  * did not invent the facts `data:` holds — it collected them out of the note's
  * open top level — so `portrait:` beside `img:` is the *pre-`data:`* spelling
  * of `data.portrait`, and both are read for the same reason both in-block
@@ -322,14 +323,14 @@ export function readAliasedField(fm: object | null | undefined, current: string)
  * `relation` is retired on an affiliation — which declares `relations` — and
  * remains an unknown key anywhere else.
  *
- * **`templatePriority` (#266).** The number that decides which of several
+ * **`templatePriority`.** The number that decides which of several
  * competing templates the Create dialog offers was called `archetype`, and
  * `archetypes` — one letter apart — is a list of what *sort* a character is.
  * A priority and a taxonomy cannot be told apart by a plural `s`, so the
  * priority takes the name that says what it is. The specification already
  * called it `templatePriority` on two of its three sides.
  *
- * **`relations` (SoHL#1781).** The field holds a *map* of standings, one per
+ * **`relations`.** The field holds a *map* of standings, one per
  * affiliation — its own description says so, and `resolveRelation` has always
  * read it that way. `relation` named the many as one, which every author had to
  * read past. Only `affiliation` declares the field, so the alias is reported

package/types/engine/scenes.d.mts

@@ -13,6 +13,15 @@
  * @returns {Set<string>} The known action names.
  */
 export function collectKnownActionNames(repoRoot: string): Set<string>;
+/**
+ * Scenes pack compiler.
+ *
+ * Walks the content tree and compiles every map note into one Scene, resolving
+ * what one note says about another through an index built before any scene is
+ * written. It also writes one Adventure per place, bundling those scenes with
+ * the JournalEntries their prose compiled into, which is what makes a pinned
+ * scene's id-based references resolve on import.
+ */
 export class Scenes extends BasePackCompiler {
     constructor({ contentBase, dest, skipDirectories, companionDests, folderResolver, repoRoot, }: {
         contentBase: any;
@@ -31,7 +40,7 @@ export class Scenes extends BasePackCompiler {
      */
     adventureCount: number;
     index: Map<string, object> | undefined;
-    effectsByAddress: Map<any, any> | undefined;
+    effectsByAddress: Map<string, object> | undefined;
     knownActions: Set<string> | undefined;
     /** place key → `{name, img, scenes: [], journal: []}` */
     places: Map<any, any> | undefined;

package/types/engine/schema-check.d.mts

@@ -46,7 +46,7 @@ export function declaredFields(artifact: SchemaArtifact, documentType: string, s
  * the path beneath it separately, so a comparison that knew only the leaf would
  * report the container as unemitted and the leaf as undeclared.
  *
- * **A runtime-only field is not in it** (#330). It declares a `to` in order to
+ * **A runtime-only field is not in it**. It declares a `to` in order to
  * *claim* the path — so the verbatim passthrough leaves it alone and the
  * refusal has something to name — and `buildFromFields` deliberately skips it,
  * because the document writes that field in play. Counting it here would make
@@ -76,7 +76,7 @@ export function emittedFields(fields: readonly {
  *   compile into.
  * @param {(type: string) => string} [opts.subtypeOf] - Maps a builder's type to
  *   the document subtype it emits. Defaults to identity, which is what the
- *   coincidence of names amounts to today (#79) — stated as a seam so that the
+ *   coincidence of names amounts to today — stated as a seam so that the
  *   explicit map replaces a default rather than a hard-coded assumption.
  * @returns {{undeclared: object[], unemitted: object[], skipped: string[]}}
  *   `undeclared` fails a build; `unemitted` is reported; `skipped` names the
@@ -96,7 +96,7 @@ export function compareFields({ builders, artifact, documentType, subtypeOf, }:
 };
 /**
  * What a **compiled document** carries in `system`, against what the receiving
- * subtype declares (#155).
+ * subtype declares.
  *
  * The third of the three checks, and the only one whose emitted set is
  * *observed*. {@link compareFields} reads the `itemBuilders` declarations and
@@ -148,7 +148,7 @@ export function compareEmittedSystem({ system, artifact, documentType, subtype,
  * The published schema this build should check itself against, or `null`.
  *
  * **Which system, and which version, are already settled.** `stats.systemId`
- * and `stats.systemVersion` are derived rather than authored (#48) — a system
+ * and `stats.systemVersion` are derived rather than authored — a system
  * package is its own system, and a module takes the one it requires — and the
  * version is the `compatibility.verified` it pins. So the question "whose
  * schema, at what version" has one answer here rather than a second set of
@@ -168,12 +168,12 @@ export function compareEmittedSystem({ system, artifact, documentType, subtype,
  * stamps no system at all, and a system that has not adopted the artifact yet
  * is simply unchecked. Neither is an error, and the caller says which it was.
  *
- * **A build may have more than one system, and then the caller names it (#139).**
+ * **A build may have more than one system, and then the caller names it.**
  * `stats.systemId` is the package-wide answer, and a repository shipping content
  * for two systems has no package-wide answer — it is deliberately `null` there,
  * because a module feeding both `sohl` and `hm3` targets neither. Left at that,
  * every schema check in such a build would be skipped in silence, which is the
- * state #60 exists to remove: the five type names the two systems *share* are
+ * state this exists to remove: the five type names the two systems *share* are
  * exactly the ones a wrong-system emission hides in. So a pass supplies the
  * system its pack declares, and the version comes from that system's own
  * `systems:` entry rather than from a package-wide stamp.
@@ -236,7 +236,7 @@ export function unemittedMessage(finding: object): string;
 export function emittedUndeclaredMessage(finding: EmissionFinding): string;
 /**
  * What a note authors under `<system>.system`, against what the receiving
- * subtype declares (#58).
+ * subtype declares.
  *
  * The **note-side** half of the check `compareFields` performs on the
  * declarations. A field list is checked once for the whole build because it is
@@ -261,7 +261,7 @@ export function emittedUndeclaredMessage(finding: EmissionFinding): string;
  * @param {string} opts.documentType - `Item`, `Actor`, …
  * @param {string} opts.subType - The document subtype the note compiles into.
  * @param {string} [opts.system] - The system whose published schema to read,
- *   where a build has more than one (#139). Defaults to the package-wide
+ *   where a build has more than one. Defaults to the package-wide
  *   `stats.systemId`.
  * @param {object} [opts.config] - The resolved build configuration.
  * @returns {{path: string, message: string}[]} One finding per undeclared path,
@@ -279,7 +279,7 @@ export function checkAuthoredSystemData(fm: object, { block, documentType, subTy
 }[];
 /**
  * The `system` block a compiler just assembled, against what the receiving
- * subtype declares (#155).
+ * subtype declares.
  *
  * The build-time face of {@link compareEmittedSystem}: it resolves the schema
  * the way every other check here does — the system's own committed artifact, or
@@ -291,7 +291,7 @@ export function checkAuthoredSystemData(fm: object, { block, documentType, subTy
  * existed, or a subtype the artifact does not name, produces no findings.
  * `content-build lint` is where a missing artifact is said out loud, once.
  *
- * @param {object} system - The `system` block the compiler produced.
+ * @param {object} emitted - The `system` block the compiler produced.
  * @param {object} opts
  * @param {object} opts.fm - The note's frontmatter, for the authored paths this
  *   check leaves to {@link checkAuthoredSystemData}.
@@ -302,12 +302,12 @@ export function checkAuthoredSystemData(fm: object, { block, documentType, subTy
  * @param {readonly {to?: string}[]} [opts.fields] - The type's field
  *   declaration, which decides each finding's origin.
  * @param {string} [opts.system] - The system whose published schema to read,
- *   where a build has more than one (#139). Defaults to the package-wide
+ *   where a build has more than one. Defaults to the package-wide
  *   `stats.systemId`.
  * @param {object} [opts.config] - The resolved build configuration.
  * @returns {(EmissionFinding & {message: string})[]} One per undeclared path.
  */
-export function checkEmittedSystemData(emitted: any, { fm, block, documentType, subType, type, fields, system, config, }: {
+export function checkEmittedSystemData(emitted: object, { fm, block, documentType, subType, type, fields, system, config, }: {
     fm: object;
     block: string;
     documentType: string;
@@ -326,7 +326,7 @@ export function checkEmittedSystemData(emitted: any, { fm, block, documentType,
  *
  * A mismatch stops the check rather than resolving anyway: a schema read under
  * the wrong shape would report confident nonsense in both directions, and a
- * silently skipped check is the state #60 exists to leave.
+ * silently skipped check is the state this exists to leave.
  *
  * @type {number}
  */

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

@@ -5,7 +5,7 @@
  * tree in reverse. Order was load-bearing here when the address index carried
  * first-writer-wins fallbacks for a page's name, filename and slug — reversing
  * the walk silently changed which page an ambiguous name resolved to. Those
- * fallbacks are gone with the bare `[[Name]]` form (#180), so this is now
+ * fallbacks are gone with the bare `[[Name]]` form, so this is now
  * ordinary reading order rather than a dependency; it is kept because a site's
  * emitted pages should not reorder for no reason.
  *
@@ -51,13 +51,13 @@ export function collectTreePages(tree: object, ctx: object): {
  * it, because in homepage-only mode it is the **whole** of the site build: the
  * content tree is never read for pages at all, so the licensing constraint two
  * packages ship under is a property of the code path rather than of a
- * configuration that happens to be empty (#55).
+ * configuration that happens to be empty.
  *
  * Returned as a list rather than as the one note there should be, because the
- * count is what {@link checkHomepageCount} judges (#52) — this walk reports
+ * count is what {@link checkHomepageCount} judges — this walk reports
  * what it found, and {@link buildSite} decides whether that is one.
  *
- * A homepage that declares no `shortcode` has no address (#182), and is
+ * A homepage that declares no `shortcode` has no address, and is
  * reported rather than written: it is the same finding a content page's missing
  * shortcode produces, and it has to be available in homepage-only mode, where
  * no other gate runs.
@@ -85,13 +85,13 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * for, and would make homepage-only mode depend on the index, the foreign
  * manifests and the table universe that mode exists to not build.
  *
- * **Verbatim is the answer to #54, not a gap left by it.** A landing's links
+ * **Verbatim is the answer, not a gap.** A landing's links
  * could not be *resolved* here without giving `homepage` mode the index its
  * licensing fence exists to not build, so they are **checked** instead:
  * {@link auditHomepageLinks} reads the `landing:` addresses and the body's
  * markdown links, and reports a wikilink on the page rather than resolving one.
  *
- * **Its destination is no longer fixed** (#182). The file is written at the
+ * **Its destination is no longer fixed**. The file is written at the
  * note's address, flat at the package's site root, and the page states that
  * address as its `url` — the same separation of file from URL every other page
  * has. Nothing is written at `/<package>/` itself: that becomes a redirect the
@@ -117,8 +117,7 @@ export function writeHomepages(outRoot: string, pages: readonly object[], config
  * - **Addresses** next: a note that has no address — no shortcode to be
  *   addressed by, or no section to be filed under — would silently drop a page.
  *   There is no collision gate beside it: an address is `(type, shortcode)`,
- *   which is unique within a package by rule, so two pages cannot claim one URL
- *   (#181).
+ *   which is unique within a package by rule, so two pages cannot claim one URL.
  * - **Foreign manifests** last, in two steps. *Unusable* is a file this build
  *   cannot read; *unaddressable* is one it can read but cannot look anything up
  *   in — a distinction worth keeping, because the second surfaces as a pile of
@@ -127,10 +126,13 @@ export function writeHomepages(outRoot: string, pages: readonly object[], config
  * @param {object[]} pages - Every page, from both walks.
  * @param {object} findings - `{ addressFindings, fmLinkFindings }` from
  *   collection.
- * @param {object} options - `{ config }`.
+ * @param {object} options
+ * @param {object} options.config - The resolved build configuration.
  * @returns {object} The gate results and, when they pass, the built index.
  */
-export function siteGates(pages: object[], findings: object, { config }: object): object;
+export function siteGates(pages: object[], findings: object, { config }: {
+    config: object;
+}): object;
 /**
  * The gate result of a build that ran none of them.
  *
@@ -167,7 +169,7 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  *   a value YAML can carry, and would abort the serializer.
  *
  * Everything else the section declared is passed through. That is the point of
- * the function: before #91 both writers transcribed `title` and `banner` by
+ * the function: two writers transcribing `title` and `banner` by
  * name, so the vocabulary lived in three places — the schema that admits a key
  * and the two writers that copy it — and a key added to the schema alone
  * validated cleanly and then reached no page. The *schema* is the bound worth
@@ -182,7 +184,7 @@ export function sectionFrontmatter(meta: object): object;
 /**
  * The frontmatter a page publishes with.
  *
- * An authored `aliases` is retired (#180) and refused before a build reaches
+ * An authored `aliases` is retired and refused before a build reaches
  * here, which makes this a guard rather than a working path. It was Obsidian's
  * — a list of *names* a reader might call
  * the note, which is vault addressing and stays in the vault. Hugo reads
@@ -191,13 +193,13 @@ export function sectionFrontmatter(meta: object): object;
  * redirects of its own.
  *
  * A content page states its own **`url`**, which is its address rather than its
- * path (#181). It is written flat under the content mount (#204), so Hugo would
+ * path. It is written flat under the content mount, so Hugo would
  * otherwise publish it at `<mount><type>-<shortcode>/` rather than at the
  * package-wide address the link manifest records — the same address, one
  * segment too deep. So the address is stated and the mount does not reach it.
  *
- * **It is stated relative to the site root, and so carries no package base**
- * (#217). Hugo resolves a `url` against `baseURL`, whose path is already where
+ * **It is stated relative to the site root, and so carries no package base**.
+ * Hugo resolves a `url` against `baseURL`, whose path is already where
  * the package is served — a consumer's Hugo site *is* its package — so writing
  * `page.url`, which carries the base for every href this build renders, wrote
  * that base a second time and published every content page a segment too deep
@@ -206,8 +208,8 @@ export function sectionFrontmatter(meta: object): object;
  * index a wikilink resolves through, and the link manifest — composes
  * `<base><slug>/`.
  *
- * A content page carries the package the build **derived** (#65). No note
- * declares one — `package:` is retired (#56) — so the note's frontmatter alone
+ * A content page carries the package the build **derived**. No note
+ * declares one — `package:` is retired — so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The
  * emitted page is what a
  * theme reads: `breadcrumbs.html` builds its middle crumb from
@@ -221,16 +223,24 @@ export function sectionFrontmatter(meta: object): object;
  * section's landing and takes the title and hero the section declares.
  *
  * @param {object} page - The page.
- * @param {object} options - `{ readmeSections, decorate }`.
+ * @param {object} options
+ * @param {Record<string, object>} [options.readmeSections] - The sections a
+ *   published tree declares, which a tree page's own `README` is the landing
+ *   for.
+ * @param {(data: object, page: object) => void} [options.decorate] - Called
+ *   with each page's frontmatter, for whatever a consumer's own pass adds.
  * @returns {object} The frontmatter to write.
  */
-export function pageFrontmatter(page: object, { readmeSections, decorate }: object): object;
+export function pageFrontmatter(page: object, { readmeSections, decorate }: {
+    readmeSections?: Record<string, object> | undefined;
+    decorate?: ((data: object, page: object) => void) | undefined;
+}): object;
 /**
  * Where a page is written, relative to the output root.
  *
- * **Flat, under the mount, named by its address** (#204). A content page's URL
+ * **Flat, under the mount, named by its address**. A content page's URL
  * is its address — `/<package>/<type>-<shortcode>/` — and the file is now named
- * the same way, so the two agree. It used to be filed into `<section>/` so that
+ * the same way, so the two agree. Filing it into `<section>/` so that
  * Hugo would read a section off its path; a section appears in no address, and
  * a directory chosen only to satisfy a rendering engine's idea of what a
  * section is has no business in the note format.
@@ -238,7 +248,7 @@ export function pageFrontmatter(page: object, { readmeSections, decorate }: obje
  * The name is the *whole* address rather than a section-relative half of it, so
  * two types cannot fight over one file: a `doc` note's `subType` may be spelled
  * the same as another note's `type`, and `doc-gear.md` and `weapongear-gear.md`
- * are distinct whatever the sections used to be.
+ * are distinct whatever the sections.
  *
  * **A `trees` entry is the exception, and always was.** Those pages preserve
  * their source layout below a named section — they are a book with chapters,
@@ -274,7 +284,7 @@ export function renderPages(pages: object[], options: object): {
 /**
  * Writes the Hugo sections a published tree declares.
  *
- * **This is where a section lives now, and the only place** (#204). A content
+ * **This is where a section lives now, and the only place**. A content
  * note carries none: it is addressed by `(type, shortcode)` and emitted flat
  * under the mount, so nothing a page does creates a directory. A site that wants
  * `/<package>/<prefix><section>/` to answer — with a title, a hero, and whatever
@@ -311,10 +321,21 @@ export function renderPages(pages: object[], options: object): {
  * navigation of every page inside it.
  *
  * @param {string} outRoot - The mount directory.
- * @param {object} options - `{ sections, landing, sectionTitle }`.
+ * @param {object} options
+ * @param {Record<string, object>} [options.sections] - The declared sections,
+ *   each written as a titled `_index.md` carrying its own frontmatter.
+ * @param {object} [options.landing] - The mount's own landing frontmatter.
+ *   Omitted, the mount gets no `_index.md` of its own.
+ * @param {((name: string) => string)|null} [options.sectionTitle] - Titles a
+ *   directory below the mount that declared no section. `null` leaves such a
+ *   directory without an `_index.md`.
  * @returns {number} How many landings were written.
  */
-export function writeSectionLandings(outRoot: string, { sections, landing, sectionTitle }: object): number;
+export function writeSectionLandings(outRoot: string, { sections, landing, sectionTitle }: {
+    sections?: Record<string, object> | undefined;
+    landing?: object | undefined;
+    sectionTitle?: ((name: string) => string) | null | undefined;
+}): number;
 /**
  * A section landing's title, from its directory name — `macro` → `Macros`.
  *
@@ -371,12 +392,18 @@ export function resolveOutputRoot(rootDir: string, out: string): string;
  * @param {object} [options.config] - A resolved configuration; loaded when
  *   omitted.
  * @param {string} [options.outRoot] - Override the configured output mount.
+ * @param {Map<string, object[]>} [options.sqlTables] - Prepared `sql` results,
+ *   keyed by the note's absolute file, from
+ *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
+ *   `sql` directive with none prepared is a table error: nothing here runs a
+ *   query.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
  *   wikiErrors: object[], manifests: object|null}}
  */
 export function buildSite({ config, outRoot, sqlTables }?: {
     config?: object | undefined;
     outRoot?: string | undefined;
+    sqlTables?: Map<string, object[]> | undefined;
 }): {
     gates: object;
     stats: object | null;

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

@@ -38,7 +38,7 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex }?:
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
  * soften an unresolved cross-package address while any package's manifest was
- * missing; #184 retired the softening, since the pack compilers and the link
+ * missing; the softening is retired, since the pack compilers and the link
  * checker never had it and one authored link must not get two verdicts. A
  * caller still passing it is ignored rather than obeyed.
  */
@@ -76,8 +76,7 @@ export type SiteEntry = {
      * The Hugo section a **tree** page is filed under, and
      *   the first segment of the `<sec>/<slug>` address it
      *   is reachable by. A content page has none: it is
-     *   addressed by `(type, shortcode)` and emitted flat
-     *   (#204).
+     *   addressed by `(type, shortcode)` and emitted flat.
      */
     sec?: string | undefined;
     /**
@@ -101,7 +100,7 @@ export type SiteIndex = {
     /**
      *                                       Address → page. `draft` says the page
      *                                       carries the `draft` tag, which marks a
-     *                                       link *into* it (#183).
+     *                                       link *into* it.
      */
     index: Map<string, {
         url: string;