@heroiclands/package-build 20.3.1 → 20.4.0

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

@@ -2,11 +2,13 @@
  * The family an entry draws from, named or defaulted.
  *
  * @param {{family?: string}} entry - A registry entry.
- * @returns {string} The family name.
+ * @param {IconRegistry} [registry] - The registry it came from.
+ * @returns {string|undefined} The family name, or nothing when neither the
+ *   entry nor the registry says.
  */
 export function familyOf(entry: {
     family?: string;
-}): string;
+}, registry?: IconRegistry): string | undefined;
 /**
  * Read the brace of an icon token.
  *
@@ -26,15 +28,11 @@ export function parseIconAttributes(raw?: string): {
  * Look one name up.
  *
  * @param {string} name - The name written between the colons, without `icon-`.
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
- * @returns {{style: string, icon: string, label: string}|null} The entry, or
- *   `null` when the registry does not declare it.
+ * @param {IconRegistry} [registry] - The package's registry.
+ * @returns {object|null} The entry, or `null` when the registry does not
+ *   declare it.
  */
-export function resolveIcon(name: string, registry?: Record<string, object>): {
-    style: string;
-    icon: string;
-    label: string;
-} | null;
+export function resolveIcon(name: string, registry?: IconRegistry): object | null;
 /**
  * The HTML the journals and the website emit — what the system already renders.
  *
@@ -43,14 +41,13 @@ export function resolveIcon(name: string, registry?: Record<string, object>): {
  * an icon dropped into a sentence has no such parent, and "the ☆ toggles it"
  * read aloud as "the toggles it" is a sentence with a hole in it.
  *
- * @param {{style: string, icon: string, label: string}} entry - A registry entry.
+ * @param {object} entry - A registry entry.
+ * @param {Record<string, string>} [attrs] - The token's attributes.
+ * @param {IconRegistry} [registry] - The registry the entry came from, which is
+ *   what says how its family spells a class.
  * @returns {string} An `<i>` element.
  */
-export function iconHtml(entry: {
-    style: string;
-    icon: string;
-    label: string;
-}, attrs?: {}): string;
+export function iconHtml(entry: object, attrs?: Record<string, string>, registry?: IconRegistry): string;
 /**
  * Every icon a string names, in the order written.
  *
@@ -71,11 +68,11 @@ export function iconsIn(text: string): Array<{
  *
  * @param {string} text - The file's contents.
  * @param {string} file - Path to report.
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * @param {IconRegistry} [registry] - The package's registry.
  * @returns {Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>} The unknown names.
  */
-export function lintIcons(text: string, file: string, registry?: Record<string, object>): Array<{
+export function lintIcons(text: string, file: string, registry?: IconRegistry): Array<{
     file: string;
     line: number;
     column: number;
@@ -83,13 +80,27 @@ export function lintIcons(text: string, file: string, registry?: Record<string,
     message: string;
 }>;
 /**
- * Refuse a registry that names a style Font Awesome Free does not ship.
+ * What is wrong with a package's declared registry.
  *
- * @param {Record<string, object>} registry - A package's icon table.
+ * Both halves are checked, because either alone is unusable: an icon naming a
+ * family nothing declares has no class prefix, and a family nothing names is a
+ * font declared for no reason.
+ *
+ * A **style** is checked against the family's own `styles`, not against a list
+ * here. Font Awesome Free ships three weights and another font ships none or
+ * five, and only the declaration knows which — so a `duotone` entry is refused
+ * because the family that entry belongs to does not list `duotone`, which is a
+ * statement the consumer made about the font it actually ships.
+ *
+ * @param {{families?: object, icons?: object}} registry - A package's declared
+ *   registry, before it is resolved.
  * @param {string} [where="icons"] - Where to say the fault is.
  * @returns {Array<{severity: "warning", message: string}>} What is wrong with it.
  */
-export function checkIconRegistry(registry: Record<string, object>, where?: string): Array<{
+export function checkIconRegistry(registry: {
+    families?: object;
+    icons?: object;
+}, where?: string): Array<{
     severity: "warning";
     message: string;
 }>;
@@ -103,13 +114,13 @@ export function checkIconRegistry(registry: Record<string, object>, where?: stri
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
- * @param {Record<string, object>} [opts.registry] - The package's icon table.
+ * @param {IconRegistry} [opts.registry] - The package's registry.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} What it found.
  */
 export function lintContentIcons(contentBase: string, { skipDirectories, registry }?: {
     skipDirectories?: readonly string[] | undefined;
-    registry?: Record<string, object> | undefined;
+    registry?: IconRegistry | undefined;
 }): {
     findings: Array<{
         file: string;
@@ -127,52 +138,69 @@ export function lintContentIcons(contentBase: string, { skipDirectories, registr
  * is reported by {@link lintIcons}, and a rendered page that still shows
  * `:icon-stra:` is how the author finds it without reading a log.
  *
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * **A function is accepted as well as a table**, and resolved per render. The
+ * shared markdown-it instance is a module-level constant, so it is built before
+ * any configuration is read; a getter lets it draw the package's own registry
+ * without the module load order deciding whether that registry exists yet.
+ *
+ * @param {Record<string, object>|(() => Record<string, object>)} [registry] -
+ *   The registry, or something that returns it.
  * @returns {(md: object) => void} A markdown-it plugin.
  */
-export function iconPlugin(registry?: Record<string, object>): (md: object) => void;
+export function iconPlugin(registry?: Record<string, object> | (() => Record<string, object>)): (md: object) => void;
 /**
- * The Font Awesome styles a registry entry may name.
- *
- * Free ships these three and no others, so a `light` or `duotone` entry would
- * name a glyph the shipped font does not contain — refused here rather than
- * discovered as a blank space in a printed book.
- *
- * @type {readonly string[]}
+ * A **family** is an icon font, and a consumer declares the ones it ships.
+ *
+ * Nothing here names Font Awesome, or Game-Icons, or any other font. A registry
+ * entry is a promise that a glyph will render, and only the package that ships
+ * the font can keep it: the Game-Icons webfont is built by a consumer from its
+ * own templates, and even Font Awesome — which Foundry supplies in-app — is
+ * present on neither the knowledgebase nor the page of a book unless somebody
+ * puts it there. A toolchain that shipped a table would be promising on a
+ * consumer's behalf.
+ *
+ * The vocabulary is the consumer's for a second reason, independent of fonts. A
+ * name like `victory-star-tester` is one game system's concept; another system
+ * compiled by this same toolchain has different icons meaning different things.
+ * What is shared is the *mechanism* — the syntax, the resolution, the checks —
+ * and that is what lives here.
+ *
+ * A family declares:
+ *
+ * - `class` — the prefix its stylesheet uses (`fa`, `ginf`, `bi`).
+ * - `styles` — the weights it ships, in the spelling its classes use. An empty
+ *   list means the font has none, and then a `style` on an entry names
+ *   something that does not exist and is reported rather than rendered.
+ * - `describe` — one line, so a finding can say which font it means.
+ *
+ * @typedef {object} IconFamily
+ * @property {string} class - The stylesheet's class prefix.
+ * @property {readonly string[]} styles - The weights it ships; empty for none.
+ * @property {string} describe - One line, for a finding.
  */
-export const ICON_STYLES: readonly string[];
 /**
- * The icon families a registry entry may draw from.
- *
- * **Two, because the interface uses two.** The SoHL icon legend says so in its
- * own prose: Font Awesome for most things, and Game-Icons.net *"for the arms,
- * gear, and condition glyphs that Font Awesome does not cover"* — eighteen of
- * them, `ginf-broadsword` and its kin (#391).
+ * A resolved registry: the families a package ships, and the icons it names.
  *
- * They differ in more than a class prefix, which is why this is a family rather
- * than a naming convention:
+ * `defaultFamily` is what an entry that names none belongs to. It is optional,
+ * and where a package declares exactly one family that one is it — so a
+ * single-font package writes no `family` anywhere.
  *
- * - Font Awesome has **weights**, so an entry names a `style` and a filled and
- *   hollow pair is one icon twice. Game-Icons has none, so a `style` on such an
- *   entry names something that does not exist.
- * - They resolve to **different fonts**. A PDF has to embed both, and find each
- *   codepoint in its own table — Font Awesome's from the file it ships,
- *   Game-Icons' from the `game-icons-codepoints.json` the consumer's own
- *   `build-icon-font.mjs` writes.
+ * @typedef {object} IconRegistry
+ * @property {Readonly<Record<string, IconFamily>>} families
+ * @property {string|undefined} defaultFamily
+ * @property {Readonly<Record<string, object>>} icons
+ */
+/**
+ * The registry a package that declares none gets: nothing at all.
  *
- * `class` is the prefix the web surfaces use. `styled` says whether a `style`
- * belongs on the entry at all, which is what lets a mistake be reported rather
- * than rendered as a class nobody defined.
+ * Empty rather than a starter set, because a starter set is a promise about
+ * fonts this package does not ship. A tree with no `icons:` configured names no
+ * icons, and `:icon-star:` in one of its notes renders as its own literal text
+ * and is reported — which is the visible failure, not a silent one.
  *
- * @type {Readonly<Record<string, {class: string, styled: boolean, describe: string}>>}
+ * @type {IconRegistry}
  */
-export const ICON_FAMILIES: Readonly<Record<string, {
-    class: string;
-    styled: boolean;
-    describe: string;
-}>>;
-/** The family an entry that does not name one belongs to. */
-export const DEFAULT_ICON_FAMILY: "fontawesome";
+export const EMPTY_ICON_REGISTRY: IconRegistry;
 /**
  * The sizes a note may ask for, and what each means on a page.
  *
@@ -208,38 +236,6 @@ export const ICON_ATTRIBUTES: Readonly<Record<string, {
     values: readonly string[];
     describe: string;
 }>>;
-/**
- * The icons the user guide already depicts, under the names it should call them.
- *
- * Each entry is read off the interface it describes rather than invented, and
- * that is meant literally — the table was checked against the system's own
- * templates, which is how `delete` came to be `fa-trash` rather than the
- * `fa-trash-can` first written here. The sheets draw `fa-trash` twenty-five
- * times and `fa-trash-can` never, so the first spelling would have printed an
- * icon the reader has never seen on screen. A registry that is not checked
- * against the interface is just a second place to be wrong.
- *
- * The names are what a *writer* would reach for — `delete`, not `trash` —
- * because the writer is the one typing them; the Font Awesome spelling is this
- * table's business, not theirs.
- *
- * **Three entries share `xmark`, and that is the point of naming rather than
- * drawing.** A `✕` in the guide means "not applicable" in a Healing Rate
- * column, "remove this row" on a control, and "close" on a dialog's corner. One
- * glyph, three sentences, three different things for a reader who cannot see
- * it — so they are three names with three labels, and the fact that Font
- * Awesome happens to draw them identically stays in this table.
- *
- * `run` and `expand` are likewise distinct: `▶` runs an action, and its label
- * should say so. `fa-play` is what the sheets use for it.
- *
- * @type {Readonly<Record<string, {style: string, icon: string, label: string}>>}
- */
-export const DEFAULT_ICONS: Readonly<Record<string, {
-    style: string;
-    icon: string;
-    label: string;
-}>>;
 /**
  * The shape a note writes, and the one this module claims.
  *
@@ -247,7 +243,7 @@ export const DEFAULT_ICONS: Readonly<Record<string, {
  * surface that also renders `:smile:` can tell the two apart without a lookup,
  * and a reader can tell what `:icon-star:` is without knowing this module
  * exists. Names are lowercase, digits and hyphens — the charset an address
- * segment already uses (#59), so nothing new has to be explained.
+ * segment already uses, so nothing new has to be explained.
  *
  * Not `:name[content]`. That is remark-directive syntax, and this toolchain
  * parses with markdown-it; a directive would render as its own literal text.
@@ -270,3 +266,54 @@ export const DEFAULT_ICONS: Readonly<Record<string, {
  * @type {RegExp}
  */
 export const ICON_PATTERN: RegExp;
+/**
+ * A **family** is an icon font, and a consumer declares the ones it ships.
+ *
+ * Nothing here names Font Awesome, or Game-Icons, or any other font. A registry
+ * entry is a promise that a glyph will render, and only the package that ships
+ * the font can keep it: the Game-Icons webfont is built by a consumer from its
+ * own templates, and even Font Awesome — which Foundry supplies in-app — is
+ * present on neither the knowledgebase nor the page of a book unless somebody
+ * puts it there. A toolchain that shipped a table would be promising on a
+ * consumer's behalf.
+ *
+ * The vocabulary is the consumer's for a second reason, independent of fonts. A
+ * name like `victory-star-tester` is one game system's concept; another system
+ * compiled by this same toolchain has different icons meaning different things.
+ * What is shared is the *mechanism* — the syntax, the resolution, the checks —
+ * and that is what lives here.
+ *
+ * A family declares:
+ *
+ * - `class` — the prefix its stylesheet uses (`fa`, `ginf`, `bi`).
+ * - `styles` — the weights it ships, in the spelling its classes use. An empty
+ *   list means the font has none, and then a `style` on an entry names
+ *   something that does not exist and is reported rather than rendered.
+ * - `describe` — one line, so a finding can say which font it means.
+ */
+export type IconFamily = {
+    /**
+     * - The stylesheet's class prefix.
+     */
+    class: string;
+    /**
+     * - The weights it ships; empty for none.
+     */
+    styles: readonly string[];
+    /**
+     * - One line, for a finding.
+     */
+    describe: string;
+};
+/**
+ * A resolved registry: the families a package ships, and the icons it names.
+ *
+ * `defaultFamily` is what an entry that names none belongs to. It is optional,
+ * and where a package declares exactly one family that one is it — so a
+ * single-font package writes no `family` anywhere.
+ */
+export type IconRegistry = {
+    families: Readonly<Record<string, IconFamily>>;
+    defaultFamily: string | undefined;
+    icons: Readonly<Record<string, object>>;
+};

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

@@ -120,7 +120,7 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *
  * The half of {@link emitContentIndex} that derives rather than emits, so a
  * pass that needs the corpus in memory — a SQL content table, the link check,
- * and in time every reader #243 converts — builds it the same way the artifact
+ * and in time every converted reader — builds it the same way the artifact
  * is built, rather than by walking and parsing again with its own idea of the
  * scope.
  *
@@ -131,7 +131,7 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *   caller that resolved one of its own; defaults to the resolved
  *   configuration's. Stated separately from `config` because a caller that was
  *   *handed* a scope must be able to pass it on rather than have it silently
- *   replaced by the one its configuration happens to carry (#243).
+ *   replaced by the one its configuration happens to carry.
  * @param {object[]} [opts.problems] - Supplied by a **reader**: a note that
  *   cannot be recorded is pushed here as a diagnostic and skipped, instead of
  *   aborting the derivation. Omitted, the note throws — which is the contract

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

@@ -2,7 +2,7 @@
  * Every `{#anchor}` a note declares on a heading.
  *
  * **Read from the content index's reader, not a second one.** This module kept
- * its own until #243, and the two disagreed: it matched `{#([a-z0-9-]+)}` while
+ * its own, and the two disagreed: it matched `{#([a-z0-9-]+)}` while
  * {@link module:engine/content-index.collectAnchors} matches `{#([^}]+)}`, so
  * an anchor with a capital in it — `{#CalendarFormat}` — existed for the index
  * and for the compiler and did not exist for the link checker. Nothing links to
@@ -21,7 +21,7 @@ export function anchorsOf(body: string): Set<string>;
  * Read a content tree into the index a link resolves against.
  *
  * **The corpus comes from the content index, not from a walk of this module's
- * own** (#243). Every pass used to answer "which files are the content?" for
+ * own**. Every pass used to answer "which files are the content?" for
  * itself and throw the answer away; this one now reads
  * {@link module:engine/content-index.indexRecordsFor}, which is the same
  * derivation the published artifact and the compilers are driven from. So a
@@ -29,7 +29,7 @@ export function anchorsOf(body: string): Set<string>;
  * anchors it resolves against are the ones every other pass will emit — rather
  * than a second derivation that agrees with them only by inspection. That was
  * not hypothetical: this module carried its own anchor reader until the anchor
- * half of #243, and the two disagreed about which anchors existed.
+ * anchor half, and the two disagreed about which anchors existed.
  *
  * **The file is opened for its bytes and nothing else.** The index deliberately
  * carries no note *body*, and a link lives in the body — so each note is read
@@ -49,7 +49,7 @@ export function anchorsOf(body: string): Set<string>;
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {object} [opts.config] - The resolved build configuration, whose
- *   fetched dependency indexes foreign addresses resolve through (#239), and
+ *   fetched dependency indexes foreign addresses resolve through, and
  *   whose `contentPackage` every local address is built from. Omitted, the
  *   ambient configuration is resolved and no cross-package address resolves.
  * @param {readonly string[]} [opts.skipDirectories] - The walk's scope, passed
@@ -87,13 +87,13 @@ export function buildLinkIndex(contentBase: string, { config, skipDirectories, s
  * **What is checkable, stated plainly.** Only an address into this site is, and
  * only against facts this build already holds:
  *
- * - A **retired content type** in the path. The engine knows what used to exist
+ * - A **retired content type** in the path. The engine knows the retired names
  *   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
  *   a fetched index 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).
+ *   another package's landing.
  *
  *   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.
@@ -133,7 +133,7 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *
  * **How the link is *written* is a separate finding from where it points**, and
  * the two are kept apart because the corrections differ. An unlabelled link
- * (#180) has to become `[[type-shortcode|Text]]`; a labelled one whose target
+ * has to become `[[type-shortcode|Text]]`; a labelled one whose target
  * resolves nowhere has a shortcode to fix. Reporting a bare `[[Name]]` as a
  * dead address would send an author hunting for a note that was never named.
  *
@@ -145,7 +145,7 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *   carries a `reason` from {@link LINK_FINDING_REASONS} —
  *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
  *   `packages`), or `"unresolved"` — and every one of them is an **error**:
- *   the three resolvers agree on severity for every class (#184).
+ *   the three resolvers agree on severity for every class.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];

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

@@ -21,7 +21,7 @@ export function isValidShortcode(value: unknown): boolean;
  * @param {object} [opts.config] - The resolved build configuration, which the
  *   corpus is derived against.
  * @param {readonly object[]} [opts.records] - Index records the caller already
- *   derived, so a command reads one corpus (#243).
+ *   derived, so a command reads one corpus.
  * @param {object[]} [opts.problems] - Collects the notes the index cannot
  *   record, instead of letting one of them silence the lint.
  * @returns {{findings: Array<{file: string, line?: number, column?: number,
@@ -51,7 +51,7 @@ export function lintContentTree(contentBase: string, { skipDirectories, contentP
  * This is {@link ADDRESS_SEGMENT_PATTERN}, not a second copy of it. A shortcode
  * is the last segment of a canonical address, and the rule it is held to is the
  * rule *every* segment is held to — so the two are one constant rather than two
- * free to drift apart (#59). The name survives because this is where the rule
+ * free to drift apart. The name survives because this is where the rule
  * is applied to a note.
  *
  * Case is deliberately **not** constrained: hundreds of authored shortcodes are

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

@@ -9,13 +9,11 @@
  * repository's identity in the address space, not a switch — and never dead
  * configuration, whatever else changes.
  *
- * It was also, until #56, a **selector**: a note declared the same value in its
- * `package:` frontmatter and the compilers kept the ones that matched. Every
- * content tree is single-package — each is single-sourced in the repository that
- * ships it — so the field restated this constant once per note while a value
- * that matched nothing filtered the whole tree out in silence. That field is
- * retired and declaring it now fails the build; this value stays, here, where
- * it is declared once.
+ * It is not a **selector**. Every content tree is single-package — each is
+ * single-sourced in the repository that ships it — so a `package:` field on a
+ * note would restate this constant once per note, and a value matching nothing
+ * would filter the whole tree out in silence. That field is refused, and this
+ * value stays here, declared once.
  *
  * Stable across compilation targets. If this content were ever compiled for a
  * second game system, it would still be published as `sohl` — only the Foundry
@@ -36,7 +34,7 @@ export function contentPackage(): string;
  * here: a note is published under `sohl` and its documents are addressed as
  * `Compendium.sohl.<pack>.<Type>.<id>`. In `sohl-thalorna` the two differ
  * (`thalorna` vs `sohl-thalorna`), which is why they are separate values rather
- * than one — treating them as interchangeable is what #1498 was.
+ * than one — treating them as interchangeable is the mistake.
  *
  * Configured rather than read from the manifest so the link resolver stays
  * filesystem-free and unit-testable. `assertPackageIdMatchesManifestFile` in

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

@@ -0,0 +1,101 @@
+/**
+ * What a note authoring a derived key is told, in one place.
+ *
+ * Shared by every caller that can meet one, so an author meets the same
+ * sentence whichever runs first. It names the correction rather than only the
+ * fault, because "delete this" is not the fix here: the text is wanted, and
+ * there is somewhere it belongs.
+ *
+ * @param {string} key - The **whole key the note wrote**, from the region it
+ *   sits in down to the field: `sohl.system.docHtml`. Composed by the caller,
+ *   because only it knows where it found the value.
+ * @param {string} from - Where the compiler reads the value from, completing
+ *   "the compiler writes it from …". The declaration carries it.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function derivedMessage(key: string, from: string, file?: string): string;
+/**
+ * The derived keys a note actually writes, in declaration order.
+ *
+ * **Presence is the whole test**, as it is for a retired or a runtime-only
+ * field: an authored empty string is as much a claim on the key as prose is,
+ * and it is the same belief the message exists to correct. So the question is
+ * whether the path resolves to anything at all, never whether the value is a
+ * usable one.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives. A pass that derives nothing passes.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @returns {{key: string, from: string}[]} The offending declarations.
+ */
+export function authoredDerivedKeys(fm: object | null | undefined, keys?: readonly {
+    key: string;
+    from: string;
+}[], { block }?: {
+    block: string;
+}): {
+    key: string;
+    from: string;
+}[];
+/**
+ * The same question asked of a `system` block directly.
+ *
+ * A note's own block is reached through {@link authoredDerivedKeys}, but it is
+ * not the only place an author writes one: an actor note's `items:` entries
+ * carry a `system:` overlay that is deep-merged onto the template verbatim,
+ * with no field declaration in the path at all. That overlay is a `system`
+ * block by every meaning except where it sits, and a `docHtml` written there
+ * ships exactly as one written on the item's own note.
+ *
+ * @param {Record<string, unknown>|null|undefined} data - The authored `system`
+ *   data.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives.
+ * @returns {{key: string, from: string}[]} The offending declarations.
+ */
+export function derivedIn(data: Record<string, unknown> | null | undefined, keys?: readonly {
+    key: string;
+    from: string;
+}[]): {
+    key: string;
+    from: string;
+}[];
+/**
+ * Refuse a note that authors any key its compiler derives.
+ *
+ * Refused rather than reported, for the reason its two siblings are: the note
+ * is not compiled, so nothing it would have emitted reaches a pack, and each
+ * caller counts the refused note and emits a located diagnostic — a refusal is
+ * never a silent skip.
+ *
+ * The **first** offending key is thrown on. A note authoring two of them is one
+ * mistake with one fix, and the build stops on this note either way.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note authors one.
+ */
+export function assertNoDerivedFields(fm: object | null | undefined, keys?: readonly {
+    key: string;
+    from: string;
+}[], { block, file, absPath }?: {
+    block: string;
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): void;

package/types/engine/diagnostics.d.mts

@@ -115,7 +115,7 @@ export function positionInBody(body: string, offset: number, { bodyLine, bodyCol
  * same name answers when no top-level one is present — which is usually what a
  * reader wants, the key being unique in nearly every note. Pass `topLevel` where
  * it is not: `aliases` is both a retired top-level field and a **permitted**
- * `name.aliases` (#180), and a finding about the first must never open on the
+ * `name.aliases`, and a finding about the first must never open on the
  * second, which would tell an author to delete a field they are allowed to
  * write.
  *
@@ -232,7 +232,7 @@ export function yamlKeyPath(field: string): Array<string | number>;
  * the same name is legal in two regions — `data.weight` and a top-level
  * `weight` are different keys, and a search finds whichever comes first.
  *
- * So this is the located form for the closed regions (#128). It reuses
+ * So this is the located form for the closed regions. It reuses
  * {@link positionOfYamlPath} rather than repeating its parse, which is what
  * keeps a finding about `data.weight` pointing at `data.weight`.
  *

package/types/engine/document-subtypes.d.mts

@@ -58,7 +58,7 @@ export function defineDocumentSubtypes({ system, block, types }?: {
  * {@link mapsNoteType}, {@link noteTypesFor}'s consumers and
  * {@link systemOf} all arrive here. A note still spelling `armorgear` finds the
  * `armor` row, compiles into the `armorgear` document it always did, and keeps
- * the address it publishes at; only the *report* tells it to move (#78).
+ * the address it publishes at; only the *report* tells it to move.
  *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The note's declared `type`.
@@ -127,7 +127,7 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  * @property {string} [problem] - Why the reference names no document subtype.
  */
 /**
- * The document subtype a `(type, shortcode)` **reference** addresses (#140).
+ * The document subtype a `(type, shortcode)` **reference** addresses.
  *
  * A being's frontmatter names each embedded item by the *note's* type — the
  * vocabulary an author writes — while the predefined items it resolves against
@@ -164,7 +164,7 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  * retirement exists to stop.
  *
  * A **renamed** spelling is the opposite case and resolves normally, through
- * the same {@link currentType} every other lookup goes through (#78). It has to
+ * the same {@link currentType} every other lookup goes through. It has to
  * be this side as much as the note's own `type:`: the overwhelming majority of
  * the 31,000 occurrences of the old names are `(type, shortcode)` references
  * inside a being's `items:` list, so a window that resolved notes but not