@heroiclands/package-build 20.3.1 → 20.5.0

package/engine/content-lint.mjs

@@ -15,43 +15,43 @@
  * Linting a content tree's **addresses** — the rules every package's notes are
  * authored against, wherever those notes live.
  *
- * These rules used to live in the SoHL repository's `utils/`, which had two
- * consequences and no upside (#20). `thalorna` and `kethira` notes were checked
+ * These rules do not live in a consumer's `utils/`, which has two
+ * consequences and no upside. `thalorna` and `kethira` notes were checked
  * by nothing at all, so the packages most likely to carry authoring mistakes
  * were the ones nothing inspected. And one rule with two implementations can
  * disagree without anything detecting it, which the canonical-separator
  * handling already did once on each side.
  *
- * Four rules, all about a note's identity:
+ * Five rules, all about a note's identity:
  *
- * 1. **Shape** — a `shortcode` is strictly ASCII-alphanumeric. It is the
- *    identity key referenced from saved world data, and it is half of the
+ * 1. **Shape** — a `shortcode` is strictly lowercase ASCII-alphanumeric. It is
+ *    the identity key referenced from saved world data, and it is half of the
  *    `type-shortcode` address, whose parse depends on the separating hyphen
  *    being the only hyphen in the string.
  * 2. **Uniqueness** — `(type, shortcode)` names one note.
  * 3. **The package's own address** — exactly one note claims `/<package>/`,
- *    which is {@link checkHomepageCount} (#52). It belongs here for the same
+ *    which is {@link checkHomepageCount}. It belongs here for the same
  *    reason the other two do: it is a statement about which note holds which
  *    address, it needs no `site:` configuration to decide, and a package with
  *    no front page is misconfigured whether or not anyone runs a site build.
  * 4. **Vacated addresses** — a `renamedFrom:` entry names an address this note
- *    used to hold and nothing holds now (#278). It is the same statement as
+ *    once held and nothing holds now. It is the same statement as
  *    rule 2 read backwards, and it needs the same whole-tree view: an entry can
  *    only be checked against every *other* note's address, and two notes
  *    claiming one predecessor is the uniqueness rule applied to the past.
+ * 5. **The vocabulary a package's kind leaves it** — a package compiling no
+ *    Foundry documents publishes `doc` and `homepage` notes and nothing else.
+ *    It is here rather than with the claim check in `note-claims.mjs` because
+ *    that check runs at compile, and this is the case where no compile runs.
  *
  * **Nothing here writes.** A check reports and an author fixes.
  *
- * **A third rule was retired (#79).** Every note used to be required to repeat
- * its own `type-shortcode` address in the top-level `aliases:` list. That
- * served exactly one reader — **Obsidian**, so `[[type-shortcode]]` resolved in
- * the editor — and nothing else ever read it: both resolvers parse the hyphen
- * qualifier themselves. The project no longer authors in Obsidian, so the rule
- * required a line of frontmatter per note for a reader that does not exist. The
- * field itself is retired now (#180), refused from `retired-fields.mjs`. Removing it was
- * verified output-neutral beforehand: across 1,735 stripped notes,
- * `package compile` produced byte-identical `build/packs-json` and the site
- * build byte-identical `site/content`.
+ * **There is deliberately no third rule** requiring every note to repeat its
+ * own `type-shortcode` address in a top-level `aliases:` list. It would serve
+ * exactly one reader — **Obsidian**, so `[[type-shortcode]]` resolves in the
+ * editor — and nothing in the build reads it: both resolvers parse the hyphen
+ * qualifier themselves. The field is retired, refused from
+ * `retired-fields.mjs`.
  *
  * **What is deliberately absent.** Corpus reachability — "every Rules document
  * is reachable from the book's root" — is a statement about what one package
@@ -65,25 +65,30 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
+// The kind that compiles nothing, and the vocabulary that leaves a tree with.
+import { DOCUMENTATION_KIND, compilesFoundryDocuments } from "../content-config.mjs";
+import { DOCUMENTATION_NOTE_TYPES } from "./note-claims.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { assertStatedScope } from "./helpers.mjs";
-// The corpus, read from the one pass that derives it (#243).
+// The corpus, read from the one pass that derives it.
 import { authoredFrontmatter, indexRecordsFor, isNoteRecord, noteFile } from "./content-index.mjs";
 import { checkHomepageCount, isHomepage } from "./homepage.mjs";
 import { declaresRenamedFrom, renamedFrom, renamedFromEntries } from "./note-renames.mjs";
 
 /**
- * The shape every `shortcode` must match: ASCII letters and digits only.
+ * The shape every `shortcode` must match: lowercase ASCII letters and digits
+ * only.
  *
  * 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
- * mixed-case and collide with nothing, so tightening that is a separate
- * decision from this one.
+ * Case is held to that rule with no exception: two shortcodes differing only
+ * in case are two names nobody can tell apart, and `canonicalKey` lowercases
+ * every address it builds regardless, so a mixed-case shortcode addresses the
+ * same document as its lowercase spelling.
  *
  * A consuming system's *runtime* keeps its own copy of this pattern — it cannot
  * import a build-time dependency into shipped code — and is expected to pin the
@@ -112,7 +117,7 @@ export function isValidShortcode(value) {
  * `Templates/`, a `README`, a repository's own `CLAUDE.md` — has no type, is
  * neither addressed nor addressable, and would fail rules it can never satisfy.
  *
- * **Read from the index, not from a walk of this pass's own** (#243). The
+ * **Read from the index, not from a walk of this pass's own**. The
  * `lint` command already derives the index — its link check and its `sql`
  * tables are built from it — and then walked the tree a second time to get
  * here, so one command held two answers to "which files are the corpus?" and
@@ -162,7 +167,7 @@ function collectNotes(contentBase, { skipDirectories, config, records, problems
 }
 
 /**
- * What one note's `renamedFrom:` says, checked against itself (#278).
+ * What one note's `renamedFrom:` says, checked against itself.
  *
  * The entries a note can be wrong about on its own: a value that is not a
  * shortcode, one naming the address the note holds *now*, one written twice.
@@ -229,8 +234,9 @@ function checkRenamedFrom({ fm, file }, raw) {
                 ...at(value),
                 severity: "error",
                 message:
-                    `\`renamedFrom: ${value}\` is not strictly alphanumeric, so ` +
-                    `it is not an address this package ever published — a ` +
+                    `\`renamedFrom: ${value}\` is not strictly alphanumeric — ` +
+                    `lowercase letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}) — ` +
+                    `so it is not an address this package ever published — a ` +
                     `shortcode is held to one charset whether it is current or past`,
             });
             continue;
@@ -276,7 +282,7 @@ function checkRenamedFrom({ fm, file }, raw) {
  * @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,
@@ -289,6 +295,12 @@ export function lintContentTree(
 ) {
     const findings = [];
     const notes = collectNotes(contentBase, { skipDirectories, config, records, problems });
+    // Whether this package's note vocabulary is the narrowed one. Asked of the
+    // configuration once rather than per note, and defaulted to the wide
+    // vocabulary when a caller supplies none — an unconfigured lint holds a
+    // tree to the rules every package shares.
+    const narrowed =
+        Boolean(config) && !compilesFoundryDocuments(/** @type {{packageKind: string}} */ (config));
 
     /** @type {Map<string, Array<{file: string, absPath: string}>>} */
     const byKey = new Map();
@@ -303,6 +315,23 @@ export function lintContentTree(
         // tree costs one pass rather than two.
         const raw = () => fs.readFileSync(absPath, "utf8");
 
+        // Rule 5, and it is the whole of the check for a package that compiles
+        // nothing: no pass downstream would report the note, because the pass
+        // that reports an unclaimed type is a compile pass and none runs.
+        const type = typeof fm.type === "string" ? fm.type.trim() : "";
+        if (narrowed && type && !DOCUMENTATION_NOTE_TYPES.has(type)) {
+            findings.push({
+                file,
+                ...positionInFrontmatter(raw(), "type", type),
+                severity: "error",
+                message:
+                    `\`type: ${type}\` compiles to a Foundry document, and a ` +
+                    `\`${DOCUMENTATION_KIND}\` package compiles none — so the ` +
+                    `note has no destination. Its vocabulary is ` +
+                    `${[...DOCUMENTATION_NOTE_TYPES].map((t) => `\`${t}\``).join(" and ")}`,
+            });
+        }
+
         // Before the keyless `continue` below, because a note declaring a
         // rename while carrying no address of its own is exactly one of the
         // things this reports — and reaching it after the skip would mean it
@@ -336,7 +365,8 @@ export function lintContentTree(
                 ...positionInFrontmatter(raw(), "shortcode", String(shortcode)),
                 severity: "error",
                 message:
-                    `shortcode "${shortcode}" is not strictly alphanumeric; it ` +
+                    `shortcode "${shortcode}" is not strictly alphanumeric — ` +
+                    `lowercase letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}); it ` +
                     `is the identity key and half of the ` +
                     `"${fm.type}-${shortcode}" address, whose parse needs the ` +
                     `separator to be the only hyphen`,
@@ -348,17 +378,17 @@ export function lintContentTree(
     // what a tree that failed to check out produces — so the lint would go
     // green on the one state it most needs to catch.
     //
-    // The state that catches is an **empty walk**, not an empty key set (#77).
+    // The state that catches is an **empty walk**, not an empty key set.
     // Notes may be keyless: a folder document carries no `shortcode`, and a
     // tree of them is populated, correct, and unkeyed. Reporting that as a
     // missing checkout trains its author to stop reading the output — the one
     // thing this guard needs them to do. A tree holding notes is therefore a
     // tree; only a tree holding none is the absent one.
     //
-    // The homepage used to be the headline example, because it was addressed
+    // The homepage is not the headline example, though it was once addressed
     // by the package rather than by a slug — so a `publish.site: homepage`
     // package had a tree with exactly one note and no key at all. It carries an
-    // address like every other note now (#182); the guard is unchanged, because
+    // address like every other note now; the guard is unchanged, because
     // what it reads was never the key count.
     if (notes.length === 0) {
         findings.push({
@@ -401,8 +431,8 @@ export function lintContentTree(
         }
     }
 
-    // The two questions about a declared rename that need the whole tree
-    // (#278). Both are the uniqueness rule above, applied to the past: an
+    // The two questions about a declared rename that need the whole tree.
+    // Both are the uniqueness rule above, applied to the past: an
     // address has one holder, so it has one successor and it cannot be both
     // vacated and occupied.
     for (const [claim, claimants] of claimedPredecessors) {

package/engine/content-package.mjs

@@ -16,7 +16,7 @@
  * ships them — read from the repository's `package-build.config.yaml`.
  *
  * Both values are **derived**, not declared: `config.mjs` is the single place
- * the configuration is resolved (#1508). This module survives as the import
+ * the configuration is resolved. This module survives as the import
  * path the link resolver and the compilers have always used, so that the values
  * can still be mocked in one place and so no consumer has to learn a new
  * spelling for them.
@@ -35,13 +35,11 @@ import { loadPackConfig } from "./pack-config.mjs";
  * 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
@@ -65,7 +63,7 @@ export function contentPackage() {
  * 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/engine/content-slug.mjs

@@ -17,9 +17,9 @@
  * {@link slugify} reduces a piece of prose — a heading, a document name — to a
  * URL-safe token. It is **not** how a page is addressed: a note's URL is its
  * address, `type-shortcode`, derived in `engine/content-address.mjs` and
- * touching no display string at all (#181).
+ * touching no display string at all.
  *
- * That used to be the other way round. This module carried a `contentSlug` that
+ * It is not the other way round: a `contentSlug` here that
  * derived a page's URL from `name.full`, abbreviating it through a table of 200
  * words so the result stayed short, and a `findSlugCollisions` to catch the two
  * notes that would then claim one URL. Its own header justified the readability

package/engine/content-tables.mjs

@@ -59,7 +59,7 @@
 
 // The fence syntax is stated once, in `code-fences.mjs`, so the scanner that
 // *skips* code and the one that expands a `dataview` block cannot disagree
-// about where a block begins and ends (#1505).
+// about where a block begins and ends.
 import { FENCE_LINE } from "./code-fences.mjs";
 
 /** What a cell shows when its expression resolves to nothing. */
@@ -1059,17 +1059,32 @@ export function renderContentTable(spec, rows, linkable, self) {
 /* ------------------------------------------------------------------------ */
 
 /**
- * Expand every fenced `dataview` block in a markdown body.
+ * The `WHERE` clause of a query, as authored, for a message that has to name
+ * what matched nothing.
+ *
+ * The parsed spec holds an expression tree, and rendering that back to text
+ * would be a second dialect of the query language to keep in step. The authored
+ * line is what the author wrote and what they will edit, so it is what the
+ * finding quotes.
+ *
+ * @param {string} query - The fence's contents.
+ * @returns {string} The clause, or "" when the query has none.
+ */
+function whereText(query) {
+    const match = /^\s*WHERE\s+(.+?)\s*$/im.exec(String(query ?? ""));
+    return match ? `\`${match[1]}\`` : "";
+}
+
+/**
+ * Expand every fenced `dataview` and `sql` block in a markdown body.
  *
  * A block that cannot be honoured — malformed or unsupported — is left in the
  * body verbatim and reported in `errors`, so the failure is visible in the
  * output as well as on the console. Every other code fence, and every code
  * span, is left alone (that is how the syntax is documented).
  *
- * A query that matches **no** note is not an error: it renders as an empty
- * table (headers only), which is what the author already sees in Obsidian, and
- * a category with no content yet is a normal state of the corpus rather than a
- * broken build.
+ * A query that selects **no** note is an error unless the fence says
+ * `allow-empty`, which states that an empty table is the intended result.
  *
  * @param {string} markdown - The note body, frontmatter already stripped.
  * @param {object} ctx
@@ -1080,30 +1095,20 @@ export function renderContentTable(spec, rows, linkable, self) {
  * @param {string} [ctx.source] - The note being expanded, for error reports.
  * @param {ContentTableDoc} [ctx.self] - The note being expanded, as a searchable
  *   doc: what a query's `this` reads.
+ * @param {object[]} [ctx.sqlTables] - This note's prepared `sql` results, in
+ *   document order, from
+ *   {@link module:engine/sql-tables.prepareSqlTables}. An `sql` directive with
+ *   no prepared result is an error: nothing here runs a query.
  * @returns {{markdown: string, errors: Array<{source: string, directive: string,
- *   reason: string, line: number}>, lineMap: Array<{line: number,
- *   generated: boolean}>}} `lineMap` is parallel to the emitted lines and says
- *   which authored line each came from, so a diagnostic about the expanded
- *   body can name an authored position (#17). An `errors` entry carries the
- *   0-based line of the directive that failed, for the same reason.
+ *   reason: string, line: number, column?: number}>,
+ *   warnings: Array<{source: string, line: number, column: number,
+ *   reason: string}>, lineMap: Array<{line: number, generated: boolean}>}}
+ *   `lineMap` is parallel to the emitted lines and says which authored line
+ *   each came from, so a diagnostic about the expanded body can name an
+ *   authored position. An `errors` entry carries the 0-based line of the
+ *   directive that failed, for the same reason. `warnings` holds one entry per
+ *   `dataview` directive the body still authors.
  */
-/**
- * The `WHERE` clause of a query, as authored, for a message that has to name
- * what matched nothing.
- *
- * The parsed spec holds an expression tree, and rendering that back to text
- * would be a second dialect of the query language to keep in step. The authored
- * line is what the author wrote and what they will edit, so it is what the
- * finding quotes.
- *
- * @param {string} query - The fence's contents.
- * @returns {string} The clause, or "" when the query has none.
- */
-function whereText(query) {
-    const match = /^\s*WHERE\s+(.+?)\s*$/im.exec(String(query ?? ""));
-    return match ? `\`${match[1]}\`` : "";
-}
-
 export function expandContentTables(
     markdown,
     {
@@ -1121,12 +1126,12 @@ export function expandContentTables(
     let sqlOrdinal = 0;
     // One entry per `dataview` directive still authored, so a caller can say how
     // much of the corpus is still on the retiring language without this pass
-    // failing a build over it (#246).
+    // failing a build over it.
     const warnings = [];
     const lines = String(markdown ?? "").split("\n");
     const out = [];
     // Which authored line each emitted line came from, so a later pass can
-    // report an authored position for text this one moved (#17). A generated
+    // report an authored position for text this one moved. A generated
     // row has no authored line of its own, so it is blamed on the directive
     // that produced it — the thing an author can actually edit — and marked,
     // because its columns mean nothing.
@@ -1203,8 +1208,7 @@ export function expandContentTables(
             line: i,
             column: indent.length + 1,
             reason:
-                "`dataview` content tables are being replaced by `sql` over the " +
-                "content index (#246)",
+                "`dataview` content tables are being replaced by `sql` over the " + "content index",
         });
         // `dataview allow-empty` says a table selecting nothing is the intended
         // state. Spelled on the fence rather than in the query, because it is a
@@ -1219,7 +1223,7 @@ export function expandContentTables(
             // a header with nothing under it makes that indistinguishable from
             // a category that is legitimately empty. Eight tables in `sohl`'s
             // `Rules/Bestiary.md` published that way for months after the
-            // `creature` → `being` rename, and no build said a word (#223).
+            // `creature` → `being` rename, and no build said a word.
             if (rows.length === 0 && !allowEmpty) {
                 errors.push({
                     source,
@@ -1239,7 +1243,7 @@ export function expandContentTables(
                 directive: block.join("\n"),
                 reason: err.message,
                 // The fence's own line, so a table error is as locatable as
-                // everything else the build reports (#17).
+                // everything else the build reports.
                 line: i,
             });
             block.forEach((text, k) => emit(text, i + k));

package/engine/content-tree.mjs

@@ -20,7 +20,7 @@
  * notices — the LevelDB packs are written, the deploy mirrors them, and the
  * defect surfaces as "my compendiums are blank" long after the build went green.
  *
- * `assets/content/` is this repository's own source (#1445), but an empty or
+ * `assets/content/` is this repository's own source, but an empty or
  * partial tree is still possible — a bad checkout, or a sparse clone. This
  * counts what is actually there so the build can refuse.
  */

package/engine/derived-fields.mjs

@@ -0,0 +1,174 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * `system` keys a note may **never** author, because the *compiler* writes them
+ * from the note itself.
+ *
+ * The third of three refusals that read alike and state different facts:
+ *
+ * | module | refuses a field | because |
+ * | --- | --- | --- |
+ * | `retired-fields.mjs` | a note may no longer declare | it has been withdrawn |
+ * | `runtime-only-fields.mjs` | a note never could | the *document* writes it in play |
+ * | this one | a note never could | the *compiler* writes it, from the note |
+ *
+ * The distinction between the last two is where the value comes from, and it
+ * decides what an author is told. A runtime-only field has no compile-time
+ * value at all, so the fix is to delete the key. A derived one **does** have a
+ * compile-time value — it is already being written, from somewhere else in the
+ * same note — so the fix is to move the content to wherever the compiler reads
+ * it from, and the message has to say where that is.
+ *
+ * ## Why an authored value cannot be the source of anything
+ *
+ * The compiler writes the key unconditionally. An authored one is therefore at
+ * best redundant, and at worst the wrong type in a shipped document: SoHL's
+ * `docHtml` holds a `@UUID` pointing at the JournalEntry a note's prose
+ * compiled into, so a note writing prose there ships a string where every
+ * reader expects a pointer, with nothing to report it.
+ *
+ * Either way the text is not reaching a reader the way its author intended. It
+ * was written as a description, and the field it was written into is not where
+ * descriptions live — the note's own body is.
+ *
+ * ## Declared by the compiler, not named here
+ *
+ * A derived key is a fact about a *pass*, not about a schema: it exists because
+ * that compiler chose to write it. So the list is a static on the compiler and
+ * this module knows no key names, which is what lets a second system declare
+ * its own — HM3 derives `description` from an anchored prose section exactly as
+ * SoHL derives `docHtml` from the body.
+ *
+ * @module
+ */
+
+import { getFrontmatter } from "./frontmatter.mjs";
+import { locateFrontmatterKey } from "./retired-fields.mjs";
+import { SYSTEM_DATA_KEY, systemData } from "./system-block.mjs";
+
+/**
+ * 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, from, file) {
+    return (
+        `\`${key}:\` is written by the compiler, not authored` +
+        (file ? ` — ${file}` : "") +
+        `. It is derived from ${from}, and the compiler writes it ` +
+        `unconditionally, so an authored value is overwritten or ships the ` +
+        `wrong type. Move the text to ${from} and delete the key`
+    );
+}
+
+/**
+ * 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, keys, { block } = {}) {
+    if (!fm || typeof fm !== "object" || !block) return [];
+    return derivedIn(systemData(fm, block), keys);
+}
+
+/**
+ * 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, keys) {
+    if (!data || typeof data !== "object") return [];
+    return (keys ?? []).filter(
+        (entry) =>
+            typeof entry?.key === "string" &&
+            entry.key !== "" &&
+            getFrontmatter(data, entry.key, undefined) !== undefined,
+    );
+}
+
+/**
+ * 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, keys, { block, file, absPath } = {}) {
+    const [entry] = authoredDerivedKeys(fm, keys, { block });
+    if (!entry) return;
+
+    const wrote = `${block}.${SYSTEM_DATA_KEY}.${entry.key}`;
+    const err = new Error(`${derivedMessage(wrote, entry.from, file)}.`);
+    // The **leaf** of the key, which is how the note writes it: a locator
+    // handed a dotted path would find nothing. Deliberately not anchored at
+    // column 1 — the key lives two levels in, under `<block>.system`.
+    const leaf = entry.key.split(".").pop();
+    const position = locateFrontmatterKey(absPath, /** @type {string} */ (leaf));
+    if (position) err.position = position;
+    throw err;
+}

package/engine/diagnostics.mjs

@@ -18,8 +18,7 @@
  * in "The Capital Nome"` — has told the author what is wrong and not where it
  * is. A name is not an address: finding it means searching the tree for a note
  * whose `name.full` matches and then searching that file for the link, and
- * four identical warnings on one note are indistinguishable from one another
- * (#17).
+ * four identical warnings on one note are indistinguishable from one another.
  *
  * So every diagnostic about a note is emitted in the form every C-family
  * compiler, `tsc` and ESLint already use:
@@ -185,7 +184,7 @@ export function positionInBody(body, offset, { bodyLine = 1, bodyColumn = 1, lin
  * 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.
  *
@@ -387,7 +386,7 @@ export function yamlKeyPath(field) {
  * 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`.
  *