@heroiclands/package-build 6.0.0 → 7.0.0

package/types/content-config.d.mts

@@ -131,6 +131,20 @@ export const DEFAULT_ADDRESS_SCHEME: Readonly<{
  * @satisfies {readonly SiteMode[]}
  */
 export const SITE_MODES: readonly ["homepage", "content"];
+/**
+ * How the loader hands {@link defineConfig} the system version it resolved.
+ *
+ * A **Symbol**, deliberately. `stats.systemVersion` is refused from an authored
+ * configuration (#48), but the value still has to reach here from the loader —
+ * which is the half that may do I/O, and which reads a system package's version
+ * out of the adjacent `package.json`. A string key would be a second spelling of
+ * the refused one, forgeable from YAML and reachable by `rejectUnknownKeys`; a
+ * symbol key cannot be written in YAML at all and does not appear in
+ * `Object.keys`, so the refusal has no back door.
+ *
+ * @type {symbol}
+ */
+export const DERIVED_SYSTEM_VERSION: symbol;
 /**
  * How much of a package reaches the web.
  *

package/types/engine/address-diff.d.mts

@@ -0,0 +1,108 @@
+/**
+ * The address space a set of compiled Item pack directories publishes.
+ *
+ * The directories are read as one space for the same reason the actors pass
+ * reads them as one: a being names an item by `(type, shortcode)` and never by
+ * the pack it happens to ship in. Both sides of a diff are built by this one
+ * function, so a released catalogue extracted by `deps fetch` and a freshly
+ * compiled pack are indexed identically and a difference between them is a real
+ * one rather than an artefact of two readers.
+ *
+ * A missing directory throws rather than reading as an empty space: an empty
+ * baseline would report every address in the package as withdrawn, and an empty
+ * current side would report every address as gone — the loudest possible
+ * output from the quietest possible mistake.
+ *
+ * @param {readonly string[]} dirs - Directories of item JSON.
+ * @returns {Map<string, {id: string, name: string, type: string, shortcode: string, file: string}>}
+ *   Every item, keyed `type:shortcode`.
+ */
+export function readItemAddresses(dirs: readonly string[]): Map<string, {
+    id: string;
+    name: string;
+    type: string;
+    shortcode: string;
+    file: string;
+}>;
+/**
+ * Every address the baseline published that this build does not.
+ *
+ * An address that merely *arrived* is not a finding: adding one breaks nobody.
+ * The arrivals are read only to answer the one question that matters about a
+ * departure — is the document still here under another name?
+ *
+ * @param {Map<string, object>} baseline - The released address space.
+ * @param {Map<string, object>} current - This build's address space.
+ * @param {object} opts
+ * @param {string} opts.baseline - What the baseline is, for the message —
+ *   conventionally `<package>@<version>`.
+ * @returns {Array<object>} One finding per departed address, in address order
+ *   so two runs read the same. `kind` is `"renamed"` (with `to`) or
+ *   `"withdrawn"`.
+ */
+export function diffItemAddresses(baseline: Map<string, object>, current: Map<string, object>, { baseline: label }: {
+    baseline: string;
+}): Array<object>;
+/**
+ * Every content note in a tree, indexed by the document id it authors.
+ *
+ * The address space is read from compiled output because that is what actually
+ * ships; the tree is read only to place a finding somewhere a reader can open
+ * and fix it. Each source answers the question it is good at, and the id is the
+ * exact key that joins them.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Passed to the walk.
+ * @returns {Map<string, string>} Document id → the note's absolute path.
+ */
+export function noteFilesById(contentBase: string, { skipDirectories }?: {
+    skipDirectories?: readonly string[] | undefined;
+}): Map<string, string>;
+/**
+ * Where to send the reader for one finding.
+ *
+ * A rename is fixed in the note that made it, so a finding whose id is still in
+ * this tree is reported at that note's `shortcode:` line — the line the author
+ * just edited. A withdrawal has no such note by definition, so it degrades to
+ * the baseline document, which is the only artefact left that records the
+ * address existing. When neither is readable the position is **dropped**, never
+ * defaulted to `1:1`.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @param {Map<string, string>} noteFiles - From {@link noteFilesById}.
+ * @returns {{file?: string, line?: number, column?: number}} Spreadable
+ *   position fields for {@link formatDiagnostic}.
+ */
+export function locateAddressFinding(finding: object, noteFiles: Map<string, string>): {
+    file?: string;
+    line?: number;
+    column?: number;
+};
+/**
+ * What one finding says, without a locator or a severity.
+ *
+ * The rename message names the identity it matched on, because that is what
+ * separates this from a spelling suggestion: the reader can check the id in
+ * both artefacts. The withdrawal message names no successor, because none is
+ * known — and says so, rather than leaving the reader to wonder whether one was
+ * looked for.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @returns {string} The message.
+ */
+export function addressFindingMessage(finding: object): string;
+/**
+ * One finding, in the standard `file:line:column: severity: message` form.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @param {{file?: string, line?: number, column?: number}} at - From
+ *   {@link locateAddressFinding}.
+ * @param {"warning"|"error"} [severity] - `error` when the caller is gating.
+ * @returns {string} The formatted diagnostic, path first on the line.
+ */
+export function formatAddressFinding(finding: object, at: {
+    file?: string;
+    line?: number;
+    column?: number;
+}, severity?: "warning" | "error"): string;

package/types/engine/base-compiler.d.mts

@@ -92,7 +92,7 @@ export class BasePackCompiler {
      * @param {boolean} [options.routingReporter] - Whether this pass reports a
      *   note of its type that routes nowhere.
      */
-    constructor({ contentBase, dest, folderResolver, packName, docType, router, routingReporter, }?: {
+    constructor({ contentBase, dest, folderResolver, packName, packSystem, docType, router, routingReporter, }?: {
         contentBase: string;
         dest: string;
         folderResolver?: ((path: string | null) => string | null) | undefined;
@@ -153,6 +153,22 @@ export class BasePackCompiler {
      * @type {number}
      */
     unresolvedLinks: number;
+    packSystem: any;
+    /**
+     * The `_stats` block every entry this pass emits is stamped with (#48).
+     *
+     * Per pack rather than per package, because a module may ship the same
+     * content for two systems — `harn-ensemble` has an `actors-hm3` pack and an
+     * `actors-sohl` pack — and those documents were built against different
+     * system versions. A single global block stamped both identically.
+     *
+     * Memoised on the instance: one pass, one pack, one system, so the block is
+     * constant for the life of the compiler. The previous module-level memo
+     * could not be, because it was shared across passes for different packs.
+     *
+     * @returns {object} The block, built once per compiler.
+     */
+    get stats(): object;
     /**
      * Whether this pass's pack is the one a claimed note belongs in.
      *
@@ -326,6 +342,7 @@ export class BasePackCompiler {
         bodyLine: number | undefined;
         bodyColumn: number | undefined;
     } | undefined;
+    #private;
 }
 /**
  * The tallies one pass accumulates while walking the tree.

package/types/engine/content-links.d.mts

@@ -46,9 +46,17 @@ export function buildLinkIndex(contentBase: string, { manifestDir, skipDirectori
  *   and what replaced it, so this is a fact rather than a guess — and it is
  *   exactly the SoHL defect.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
- *   vendored manifest names. Both have a better form to write, which is why they
- *   are reported; a bare `/<package>/` is left alone, because a package
- *   homepage is in no manifest and there is nothing better to write.
+ *   vendored manifest names. Every one of them has a better form to write, which
+ *   is why every one is reported — including a bare `/<package>/`, which names
+ *   another package's landing (#87).
+ *
+ *   That last case was exempt until the better form was identified, on the
+ *   reasoning that a landing is in no link manifest so nothing could resolve it.
+ *   True, and beside the point: it does not need resolving. A landing's address
+ *   *is* its package prefix, so `/<package>/` is the absolute URL with the host
+ *   struck off — host-free, emitted verbatim, and needing no index, which is
+ *   what lets it hold in homepage-only mode where the tree is never walked. The
+ *   form was already accepted here; nothing had ever named it as the one to use.
  * - A **root-relative `url:`**, which the theme's `relURL` prefixes a second
  *   time. `href:` means "already resolved, use verbatim", so the same leading
  *   slash is correct there and is not reported.

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

@@ -16,12 +16,15 @@ export function isValidShortcode(value: unknown): boolean;
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names the walk
  *   ignores. Defaults to the configured list.
+ * @param {string} [opts.contentPackage] - The package this tree builds, for the
+ *   homepage rule. Dropped from that finding when unknown rather than guessed.
  * @returns {{findings: Array<{file: string, line?: number, column?: number,
  *   severity: "error"|"warning", message: string}>, notes: number,
  *   keys: number}} The findings, and what was inspected to produce them.
  */
-export function lintContentTree(contentBase: string, { skipDirectories }?: {
+export function lintContentTree(contentBase: string, { skipDirectories, contentPackage }?: {
     skipDirectories?: readonly string[] | undefined;
+    contentPackage?: string | undefined;
 }): {
     findings: Array<{
         file: string;

package/types/engine/diagnostics.d.mts

@@ -169,12 +169,44 @@ export function positionOfLiteral(text: string, needle: string, occurrence?: num
  * resolves to nothing — yields `{}`, so a caller spreads the result and the
  * position is dropped rather than guessed.
  *
+ * **`key: true` addresses the declaration rather than the value.** A finding
+ * about a *value* — this pack name is not in `packs[]` — belongs on the value,
+ * which is the default. A finding that names a **field** — `\`site.sections.x\`
+ * is not a recognized option` — sends the reader to look for that field, so the
+ * position should be the field's own, and in a flow mapping
+ * (`{ title: X, banner: Y }`) the two are different columns on one line. The
+ * key's node is found through the same parse, so this stays one locator rather
+ * than a second one free to disagree with it.
+ *
  * @param {string} text - The document's contents.
  * @param {ReadonlyArray<string|number>} keyPath - Path to the node: map keys as
  *   strings, sequence entries as numbers.
+ * @param {object} [opts]
+ * @param {boolean} [opts.key=false] - Report where the last segment is
+ *   *declared* rather than where its value sits. Ignored for a sequence entry,
+ *   which has no key.
  * @returns {{line?: number, column?: number}} Spreadable position fields.
  */
-export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string | number>): {
+export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string | number>, { key }?: {
+    key?: boolean | undefined;
+}): {
     line?: number;
     column?: number;
 };
+/**
+ * The YAML key path a **dotted field path** addresses.
+ *
+ * Configuration checks report the offending key as the path a reader would
+ * write it — `packs[1].name`, `site.sections.affliction.title` — because that
+ * is what the message has to say. {@link positionOfYamlPath} addresses a node
+ * by segments instead, so this is the one translation between them: `.`
+ * separates map keys, and a bracketed suffix is a sequence index.
+ *
+ * A path this cannot parse yields `[]`, which {@link positionOfYamlPath} in
+ * turn resolves to no position — dropped rather than guessed, as everything
+ * else here is.
+ *
+ * @param {string} field - The dotted path, as a diagnostic spells it.
+ * @returns {Array<string|number>} Its segments, sequence indices as numbers.
+ */
+export function yamlKeyPath(field: string): Array<string | number>;

package/types/engine/generate.d.mts

@@ -13,8 +13,9 @@
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
  * @returns {string[]} Each Item pack's JSON directory. Empty when the
- *   repository ships no items at all — the actors pass, which is the only
- *   caller that needs one, refuses that itself.
+ *   repository ships no items at all, which is a legitimate package: the actors
+ *   pass accepts an empty list and reports an item it cannot resolve per
+ *   `(type, shortcode)` instead, naming the being (#49).
  */
 export function itemPackJsonDirs(config?: object): string[];
 /**

package/types/engine/helpers.d.mts

@@ -19,7 +19,7 @@ export function parseMarkdownFile(filePath: any): {
 } | {
     frontmatter: any;
     body: string;
-    description: any;
+    description: string;
     bodyLine: number;
     bodyColumn: number;
 };
@@ -56,7 +56,7 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
     absPath: string;
     frontmatter: any;
     body: string;
-    description: any;
+    description: string;
     bodyLine: number;
     bodyColumn: number;
 }, void, unknown>;
@@ -190,6 +190,32 @@ export function buildStats(systemVersion?: string, config?: {
         packageManifest: string;
     };
 }): object;
+/**
+ * The `_stats` block for one pack, stamped with the system that pack is for
+ * (#48).
+ *
+ * **`systemId` travels with `systemVersion`.** They are one decision, so where
+ * one is omitted both are. Stamping a per-pack version against a package-wide
+ * id would emit `systemId: sohl, systemVersion: 1.6.3` on HM3 documents — a
+ * *plausible lie*, which is worse than the missing value #43 fixed, because
+ * nothing about it looks wrong.
+ *
+ * Resolution, in order:
+ *
+ * 1. The pack's own `system:`, looked up in the `systems:` block. That is the
+ *    case a module shipping for two systems needs, and the one no
+ *    package-wide value could express.
+ * 2. Failing that, the package-wide `stats` — a package whose packs are all for
+ *    one system, which is every package that worked before this existed.
+ *
+ * A pack naming a system is validated against `systems:` at configuration time,
+ * so an unresolvable name never reaches here.
+ *
+ * @param {string|null|undefined} packSystem - The pack's declared `system:`.
+ * @param {object} [config] - The resolved configuration.
+ * @returns {object} The `_stats` block for that pack.
+ */
+export function statsForPack(packSystem: string | null | undefined, config?: object): object;
 /**
  * The `_stats` block every compiler stamps on an entry it emits, built once.
  *
@@ -342,7 +368,7 @@ export function folderFilename(name: any, id: any): string;
  * pack, `"JournalEntry"` for the journals pack.
  */
 export function writeFolderDocs(folders: any, stats: any, destDir: any, documentType: any): void;
-export const md: any;
+export const md: import("markdown-it").MarkdownIt;
 export { slugify } from "./content-slug.mjs";
 export { makeId } from "./ids.mjs";
 export { getFrontmatter, sohlField, resolveCharges, resolveSkillAptitudes, resolveRelation, requireSubType, parseValueDesc } from "./frontmatter.mjs";

package/types/engine/homepage.d.mts

@@ -5,6 +5,87 @@
  * @returns {boolean} Whether it is a homepage note.
  */
 export function isHomepage(fm: object | null | undefined): boolean;
+/**
+ * The address-bearing fields one note authors, in the order it authored them.
+ *
+ * Authoring order rather than declaration order, so a caller emitting one
+ * diagnostic per finding emits them top to bottom down the file — the order a
+ * reader and a compiler-output parser both expect.
+ *
+ * Presence is the whole test: `shortcode:` authored empty still says "this page
+ * has an address of its own", and a value cannot make the claim true.
+ *
+ * Returned without a locator, because the two things that would supply one —
+ * the raw note text and the position helper — belong to the caller. This
+ * mirrors {@link module:engine/retired-fields}, whose retired-field messages
+ * are likewise positioned by whoever reports them.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {Array<{key: string, message: string}>} One entry per field the note
+ *   authored, empty for any note that is not a homepage.
+ */
+export function checkHomepageAddressFields(fm: object | null | undefined): Array<{
+    key: string;
+    message: string;
+}>;
+/**
+ * Require exactly one homepage note in a content tree (#52).
+ *
+ * "Exactly one" is two rules, and they are **one severity** because they are
+ * one defect: a package whose front page is not the page a person chose.
+ *
+ * - _None_ and the package serves nothing at `/<package>/`. That is the failure
+ *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
+ *   homepage(s)` and exits 0.
+ * - _Two_ and it serves a page nobody chose. Every homepage is written to the
+ *   same {@link HOMEPAGE_DESTINATION}, so the second overwrites the first and
+ *   the package's front page is decided by the order the walk happened to reach
+ *   the files in — by *filename*, on a type whose whole point is that it is
+ *   routed by frontmatter. There is no "first wins" convention to fall back on,
+ *   so nothing here can pick the right one.
+ *
+ * Neither has a safe default, so neither is a warning. A warning is the right
+ * severity for something a build can proceed past correctly, and a build that
+ * proceeds past either of these publishes the wrong front page while reporting
+ * success — which is the exact outcome a warning would be tolerating.
+ *
+ * **Two is reported once per note, not once for the tree.** Each note is a
+ * place an author has to open and edit, and a single finding saying "there are
+ * two" sends them hunting for the second.
+ *
+ * **None is located at the tree, honestly.** There is no file to name, so the
+ * locator is the content root — the directory the note is missing from, which
+ * is a real path and the one the author adds it to. No line and no column are
+ * invented for it, per the diagnostic rules in
+ * {@link module:engine/diagnostics}. {@link lintContentTree} already reports an
+ * empty walk against the same locator.
+ *
+ * The rule reads no `site:` configuration and does not vary by
+ * `publish.site`: that setting chooses whether the *content* surfaces are
+ * published, and the homepage is the floor underneath both modes.
+ *
+ * @param {ReadonlyArray<{file: string}>} found - The homepage notes, in walk
+ *   order. Paths may be absolute or relative to the working directory.
+ * @param {object} options - Options.
+ * @param {string} options.contentBase - Root of the content tree, for the
+ *   locator when there is no file to name.
+ * @param {string} [options.contentPackage] - The package this tree builds.
+ *   Dropped from the message when unknown rather than guessed.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string}>} The findings, one per offending note.
+ */
+export function checkHomepageCount(found: ReadonlyArray<{
+    file: string;
+}>, { contentBase, contentPackage }: {
+    contentBase: string;
+    contentPackage?: string | undefined;
+}): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "error";
+    message: string;
+}>;
 /**
  * The title a homepage publishes under.
  *
@@ -107,6 +188,42 @@ export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
  * @type {string}
  */
 export const HOMEPAGE_DESTINATION: string;
+/**
+ * The top-level fields a homepage refuses, and what each one would decide (#53).
+ *
+ * A note's URL derives from `name.full` and its identity from
+ * `(type, shortcode)`. The homepage is the one page for which neither holds: it
+ * publishes at `/<package>/`, fixed by the package id. An author fluent in the
+ * conventions writes them here expecting exactly what they do everywhere else,
+ * and gets none of it.
+ *
+ * **They were never inert, which is why ignoring them was the wrong answer.** A
+ * `shortcode` puts the note in the address index and in the `dataview` link
+ * universe, so `[[homepage-<shortcode>]]` resolves *green* — to
+ * `homepage/<slug>/`, an address derived from `name.full` and published by
+ * nothing, because a homepage is written to {@link HOMEPAGE_DESTINATION} at the
+ * package root. A build that reports a live link to a 404 is worse than one
+ * that says nothing. It also inflates `content-build lint`'s address tally, so
+ * the lint and the link manifest disagree about what the package publishes.
+ *
+ * **A named class, not an allow-list, and that boundary is the decision.** The
+ * documented envelope is `type` plus an optional `title`, and `landing`,
+ * `description` and `banner` are legitimate beside them — but a homepage's
+ * frontmatter is *emitted into the published page*
+ * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
+ * parameter this build has never heard of and has no standing to refuse.
+ * Rejecting unknown keys would make every new theme parameter wait on a
+ * package-build release. What is refused is the specific class that makes a
+ * false claim about *where this page is*.
+ *
+ * `aliases` is deliberately not in the class: {@link homepageFrontmatter}
+ * already drops it from every emitted page, with a reason of its own, so
+ * authoring one is the same no-op it is on any other page rather than a wrong
+ * belief about this one's address.
+ *
+ * @type {ReadonlyMap<string, string>}
+ */
+export const HOMEPAGE_REFUSED_FIELDS: ReadonlyMap<string, string>;
 /**
  * The two frontmatter keys that hold an address, and what each one means.
  *

package/types/engine/journals.d.mts

@@ -93,15 +93,21 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   heading; see {@link splitPages}.
  * @param {string|null} [params.folder] - The folder id, or `null`.
  * @param {object} [params.flags] - Document flags.
+ * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
+ *   caller because it is a property of the *pack* being written, not of the
+ *   entry: a module may ship the same content for two systems, and each pack's
+ *   documents record the system version they were built against (#48). A
+ *   caller with no pack in hand gets the package-wide block.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, }: {
     id: string;
     name: string;
     markdown: string;
     leadName?: string | undefined;
     folder?: string | null | undefined;
     flags?: object | undefined;
+    stats?: object | undefined;
 }): object;
 export class Journals extends BasePackCompiler {
     /**

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

@@ -14,6 +14,28 @@
  *   {@link CONFIG_FILENAMES}.
  */
 export function findConfigFile(from: string): string | undefined;
+/**
+ * Attach the position of the key a configuration error names.
+ *
+ * Eighty-one checks across `content-config.mjs` and `config.mjs` report through
+ * one `fail()`, which knows the offending key's dotted path and nothing
+ * about where it was written. Locating one of them and not the rest would be
+ * worse than locating none — a reader would learn that some configuration
+ * errors carry a position and could not predict which — so the path rides on
+ * the error and every one of them is located here, at the boundary that knows
+ * which file was read (#95).
+ *
+ * The message keeps its body and gains the `file:line:column: error: ` prefix
+ * every other finding in this build already uses, so nothing a reader has today
+ * is lost. `located` marks it done, so an error crossing two boundaries is
+ * decorated once; the fields are also left on the error, for a caller that
+ * wants to re-render it.
+ *
+ * @param {unknown} err - What was thrown.
+ * @param {string} [configPath] - The configuration file that was read.
+ * @returns {unknown} The same error, decorated when it named a field.
+ */
+export function locateConfigError(err: unknown, configPath?: string): unknown;
 /**
  * Turn a parsed YAML configuration into the frozen one the engine reads.
  *

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

@@ -36,8 +36,16 @@ export function checkFormatting(root: string, opts?: {
  *
  * {@link MARKDOWNLINT_CONFIG} is passed as markdownlint's `optionsDefault`,
  * which is precisely the "shipped default, consumer overrides" behaviour the
- * command promises: a `.markdownlint-cli2.jsonc` found in the tree replaces it,
- * and a repository with none gets these rules.
+ * command promises: a repository with no configuration of its own gets these
+ * rules, and a `.markdownlint-cli2.jsonc` 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
+ * declaring only `ignores` keeps this rule set intact, including `default: false`
+ * 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.
  *
  * @param {string} root - Repository to lint.
  * @param {object} [opts]

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

@@ -50,9 +50,9 @@ export function collectTreePages(tree: object, ctx: object): {
  * packages ship under is a property of the code path rather than of a
  * configuration that happens to be empty (#55).
  *
- * Returned as a list rather than as the one note there should be. Requiring
- * exactly one is #52's, and it is a separate decision — this reports what it
- * found so a count is visible either way.
+ * 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
+ * what it found, and {@link buildSite} decides whether that is one.
  *
  * @param {string} contentBase - Absolute path to the content tree.
  * @param {object} ctx - `{ skipDirectories }`.
@@ -129,6 +129,31 @@ export function gatesFailed(gates: any): boolean;
  * @returns {Map<string, object[]>} Package → the notes it may tabulate.
  */
 export function tableUniverse(pages: object[]): Map<string, object[]>;
+/**
+ * The front matter a section's landing states about itself.
+ *
+ * The section metadata a configuration resolved, ready to be written or merged
+ * onto a page. Two things happen here and nothing else does:
+ *
+ * - **`title` leads.** It is the one key every landing has carried since the
+ *   first one, and a landing whose block opened with `banner:` would be a
+ *   gratuitous diff on every consumer's tree.
+ * - **An absent value is left off**, not written as `undefined` — which is not
+ *   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
+ * 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
+ * keeping (see `normalizeSectionMeta`, which refuses a key it does not know and
+ * names it); a second, silent bound in the writers is not.
+ *
+ * @param {object} meta - A resolved `site.sections` / `site.readmeSections`
+ *   entry.
+ * @returns {object} Its front matter, `title` first.
+ */
+export function sectionFrontmatter(meta: object): object;
 /**
  * The frontmatter a page publishes with.
  *

package/types/engine/wikilink-syntax.d.mts

@@ -23,6 +23,30 @@
  * @returns {ParsedWikilink} The parts, each trimmed.
  */
 export function parseWikilink(rawInner: string): ParsedWikilink;
+/**
+ * The label an author actually supplied, or `null` when they supplied none.
+ *
+ * **An empty label is not a label.** `[[x|]]` is deliberately writable — it
+ * means "address this target, and show the target's own name" — so `display:
+ * ""` has to read as *absent* everywhere a fallback is chosen, exactly as
+ * `display: null` does. The two are still distinguishable through
+ * {@link ParsedWikilink.labelled}, which is the thing that genuinely differs
+ * and which #1409 depends on.
+ *
+ * Stated here because the two resolvers had already drawn the line in two
+ * places and drawn it differently: the packs tested falsiness and were right,
+ * the web tested `??` — which falls through on `null` only — and emitted
+ * `[](/url/)`, a link with no clickable text, through every build (#113). That
+ * is the same drift this module exists to prevent, in the case its own
+ * {@link ParsedWikilink} docstring calls out. One reading, one place.
+ *
+ * @param {{display: string|null}} parsed - A parsed wikilink, or anything
+ *   carrying its `display`.
+ * @returns {string|null} The label, or `null` when there is none to show.
+ */
+export function authoredLabel({ display }: {
+    display: string | null;
+}): string | null;
 /**
  * Whether a parsed link addresses a section of the page it is written on.
  *

package/types/sohl/actors.d.mts

@@ -1,7 +1,7 @@
 export class Actors extends BasePackCompiler {
     constructor({ itemsSourceDirs, foreignSourceDirs, ...options }: {
         [x: string]: any;
-        itemsSourceDirs: any;
+        itemsSourceDirs?: never[] | undefined;
         foreignSourceDirs?: never[] | undefined;
     });
     /** @type {readonly string[]} */
@@ -60,8 +60,8 @@ export class Actors extends BasePackCompiler {
         system: {
             shortcode: any;
             portrait: string;
-            appearance: any;
-            dossier: any;
+            appearance: string;
+            dossier: string;
         };
         items: any[];
         prototypeToken: {