@heroiclands/package-build 11.1.0 → 14.0.0

package/engine/frontmatter-lint.mjs

@@ -55,15 +55,13 @@
  * @module
  */
 
-import path from "node:path";
-
 import { authoredFields } from "./field-spec.mjs";
-import { DEFAULT_ADDRESS_SCHEME, sectionOf } from "./content-address.mjs";
 import { resolveFieldValue, SYSTEM_BLOCK_KEYS, unknownBlockKeys } from "./system-block.mjs";
 import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
-import { declaredTags } from "./note-vocabulary.mjs";
+import { isAddressSegment } from "./address-charset.mjs";
+import { declaredTags, subTypeCharsetMessage, typeCharsetMessage } from "./note-vocabulary.mjs";
 import {
     RETIRED_FIELD_ALIASES,
     declaresRetiredAlias,
@@ -72,6 +70,7 @@ import {
     draftRetiredMessage,
     readAliasedField,
     retiredAliasMessage,
+    sectionRetiredMessage,
 } from "./retired-fields.mjs";
 
 /**
@@ -316,83 +315,47 @@ function checkDataContainer(note, { type, fields }) {
     return findings;
 }
 
-/**
- * Whether this note's `subType` names the **section it lands at** rather than a
- * sub-kind of its type (#197).
- *
- * Under `landing: readme` a `README.md` addresses its whole section, and the
- * segment is what `sectionOf` reads — for a `doc`, its `subType`. So that one
- * field is spelled once and read twice: as a genre on an ordinary note, and as
- * an address on a landing. The two vocabularies are not the same set, and the
- * closed one cannot answer for the open one.
- *
- * Asked of {@link sectionOf} rather than by naming a type, because which types
- * route by their `subType` is address knowledge and this module deliberately
- * knows no type names of its own.
- *
- * @param {object} note - The note.
- * @param {string} landing - The repository's landing rule.
- * @returns {boolean} Whether the value is an address.
- */
-function subTypeIsSection(note, landing) {
-    if (landing !== "readme") return false;
-    const file = typeof note.file === "string" ? note.file : "";
-    if (path.basename(file).toLowerCase() !== "readme.md") return false;
-    const fm = note.fm ?? {};
-    return typeof fm.subType === "string" && sectionOf(fm) === fm.subType;
-}
-
 /**
  * Check a note's top-level `subType` against the values its type declares
- * (#128), or — for a `README` landing — against the sections that can exist
- * (#197, #200).
+ * (#128).
  *
  * `subType` stays at the top level — it is what each system's map reads to
  * derive a document type, so it describes the note rather than the subject —
  * but it is not open like the rest of that region: a type either declares a
  * `subType` or does not, and a type that does declares its values.
  *
- * **A landing page's is an address, and an address is checked against the
- * addresses that exist.** A `README` under `landing: readme` addresses its
- * section through this field, and a section is `weapongear` or `being` as
- * readily as it is `rules`. What can legitimately appear there is the range of
- * {@link sectionOf} over every note the format permits, plus whatever the
- * repository names:
- *
- * 1. **Every declared content type.** `sectionOf` returns `fm.type` for a
- *    non-`doc` note, so `being`, `lore` and `weapongear` are sections *by
- *    construction*, configured or not.
- * 2. **The type's own subtypes** — `rules`, `user-guide`, `reference` for a
- *    `doc`, since a `doc` routes by its subtype.
- * 3. **The configured sections**, which may name one that is neither: `sohl`
- *    configures `credits` and `dev-docs`.
- *
- * Checking only (3) was #197's fix and keyed on configuration a consumer may
- * legitimately not have: `sohl-thalorna` has no `site:` block at all, so five
- * of its landings were refused for naming their own content type (#200).
- *
- * **The guard survives.** A misspelling is none of the three, so it still
- * fails, with the near miss drawn from the whole union. What is deliberately no
- * longer caught is a landing for a section that exists but is empty — which is
- * legitimate, and is why the set is the types the format *declares* rather than
- * the types *present in the tree*: `sohl` ships two such landings above tables
- * that stay empty until the first note of each type does.
+ * **It is a genre, and only a genre.** #197 gave the field a second reading: a
+ * `README.md` was its section's landing page, and the segment it landed at was
+ * its `subType`, so the value had to be checked against the sections that could
+ * exist — every content type, plus whatever a repository configured — rather
+ * than against the genres its type declares. Two vocabularies in one field is
+ * what #198, #200 and #201 were each spent on, and #204 removed the cause rather
+ * than the symptom: a section is a Hugo directory the note format does not
+ * carry, and a page introducing a type is an ordinary note addressed
+ * `doc-<type>`. So the closed list answers for every note, whatever it is
+ * called, and `rules`, `userguide`, `reference` mean three genres and nothing
+ * else.
+ *
+ * **Two checks, in this order** — the charset, then the closed set (#206,
+ * #204). The charset is first because it is the more general statement about
+ * the same value: a value outside `^[A-Za-z0-9]+$` is refused whatever the type
+ * declares, and only once it is a well-formed term is the type's own list the
+ * reason to refuse it.
+ *
+ * There were three. #206 ran a retired-spelling check ahead of both, accepting
+ * `user-guide` as a warning naming `userguide`, so the 43 `sohl` notes
+ * authoring it were not invalidated by the release that renamed it. Every
+ * consumer tree has swept, so the acceptance guarded nothing and is gone: the
+ * old spelling now falls through to the charset check, which refuses it for the
+ * reason that always applied — it contains a hyphen (#210).
  *
  * @param {object} note - The note.
  * @param {object} opts
  * @param {string} opts.type - The note's type, for the message.
  * @param {object} opts.entry - The type's vocabulary entry.
- * @param {boolean} [opts.asSection] - Whether the value is a section address —
- *   see {@link subTypeIsSection}.
- * @param {readonly string[]} [opts.types] - The content types the format
- *   declares. Empty leaves a landing checked against its genres and the
- *   configured sections alone.
- * @param {readonly string[]} [opts.sections] - The sections the repository
- *   configures. Empty when it configures none, which is ordinary rather than a
- *   defect.
  * @returns {object[]} Findings.
  */
-function checkSubType(note, { type, entry, asSection = false, types = [], sections = [] }) {
+function checkSubType(note, { type, entry }) {
     const fm = note.fm ?? {};
     if (!Object.hasOwn(fm, "subType") || fm.subType == null || fm.subType === "") return [];
 
@@ -412,33 +375,27 @@ function checkSubType(note, { type, entry, asSection = false, types = [], sectio
         ];
     }
 
-    const values = entry.subTypes;
-    // `null` is "declared, values not yet enumerated" — presence is legal and
-    // the value is nobody's to check yet.
-    if (values == null || values.includes(value)) return [];
-
-    if (asSection) {
-        if (types.includes(value) || sections.includes(value)) return [];
-        const guess = nearest(value, [...types, ...values, ...sections]);
+    // The charset, before the closed set: a value outside it is refused
+    // whatever the type declares, and the type's list is not the reason it is
+    // refused. Reported here rather than only for an enumerated type, so a
+    // `subTypes: null` type — whose values nothing may yet check — is still
+    // held to the one rule that does not depend on knowing them.
+    if (!isAddressSegment(value)) {
         return [
             {
                 file: note.file,
                 ...at,
                 severity: "error",
-                message:
-                    `\`subType\` "${value}" is the section this README lands ` +
-                    `at, and nothing declares it. A section is a content type ` +
-                    `(${types.join(", ")}), a subtype ${type} declares ` +
-                    `(${values.join(", ")})` +
-                    (sections.length ?
-                        `, or a section configured under \`site.sections\` / ` +
-                        `\`site.readmeSections\` (${sections.join(", ")})`
-                    :   "") +
-                    (guess ? `. Did you mean "${guess}"?` : ""),
+                message: subTypeCharsetMessage(value),
             },
         ];
     }
 
+    const values = entry.subTypes;
+    // `null` is "declared, values not yet enumerated" — presence is legal and
+    // the value is nobody's to check yet.
+    if (values == null || values.includes(value)) return [];
+
     const guess = nearest(value, values);
     return [
         {
@@ -521,33 +478,9 @@ function checkTags(note, { type }) {
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
- * @param {string} [opts.landing] - The repository's landing rule, from
- *   `publish.address.landing`. It decides which note addresses a whole section,
- *   and so whether a `subType` is a genre or an address (#197).
- * @param {readonly string[]} [opts.types] - The content types the format
- *   declares — the sections that exist by construction (#200). Read from
- *   `docs/content-format.md` rather than from `schemas`, because the two answer
- *   different questions: whether an address is real, and whether this build can
- *   check a note's fields. A type the specification declares and no schema
- *   covers is a real section, and its notes are reported on their own account.
- * @param {readonly string[]} [opts.sections] - The sections the repository
- *   configures, from `declaredSections`. Supplied by the caller for the same
- *   reason `vocabulary` is: this module checks a note against what it is
- *   handed.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(
-    note,
-    {
-        schemas,
-        index,
-        vocabulary,
-        systems = DEFAULT_SYSTEM_BLOCKS,
-        landing = DEFAULT_ADDRESS_SCHEME.landing,
-        types = [],
-        sections = [],
-    },
-) {
+export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_SYSTEM_BLOCKS }) {
     const findings = [];
     const fm = note.fm ?? {};
     const type = String(fm.type ?? "");
@@ -578,6 +511,17 @@ export function lintNote(
             message: draftRetiredMessage(),
         });
     }
+    // Anchored at column 1 for the same reason `aliases` is: `section` names a
+    // configuration key too (`site.trees[].section`), and a nested one under
+    // some other block is not this field (#202).
+    if (Object.hasOwn(fm, "section")) {
+        findings.push({
+            file: note.file,
+            ...positionInFrontmatter(raw(), "section", undefined, { topLevel: true }),
+            severity: "error",
+            message: sectionRetiredMessage(),
+        });
+    }
     // Only the top-level `aliases` is retired. `name.aliases` writes the same
     // key indented under `name:` and is **permitted** — reserved and unread —
     // so both the test and the locator are anchored at column 1 (#180).
@@ -609,6 +553,25 @@ export function lintNote(
         });
     }
 
+    // The type's charset, before anything that looks the type up (#206). A
+    // hyphenated type is unaddressable, and every lookup below would report it
+    // as a type nobody declared — true, but not the reason, and it would send
+    // the author to declare one rather than to rename it.
+    //
+    // Guarded on a non-empty type: an absent one is a missing key, not a
+    // charset violation, and is reported as the missing schema it causes.
+    // There is **no transitional path** here, deliberately: no tree authors a
+    // hyphenated type, so an acceptance would guard a case that does not exist.
+    if (type && !isAddressSegment(type)) {
+        findings.push({
+            file: note.file,
+            ...at("type", type),
+            severity: "error",
+            message: typeCharsetMessage(type),
+        });
+        return findings;
+    }
+
     const replacement = RETIRED_TYPES[type];
     if (replacement) {
         findings.push({
@@ -644,15 +607,7 @@ export function lintNote(
     const entry = vocabulary?.[type];
     if (entry) {
         findings.push(...checkDataContainer(note, { type, fields: entry.data ?? [] }));
-        findings.push(
-            ...checkSubType(note, {
-                type,
-                entry,
-                asSection: subTypeIsSection(note, landing),
-                types,
-                sections,
-            }),
-        );
+        findings.push(...checkSubType(note, { type, entry }));
     }
 
     const fields = authoredFields(schema);
@@ -809,19 +764,10 @@ export function lintNote(
  * @param {boolean} [opts.references=true] - Whether to check references.
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
- * @param {string} [opts.landing] - The repository's landing rule; see
- *   {@link lintNote}.
- * @param {readonly string[]} [opts.types] - The content types the format
- *   declares; see {@link lintNote}.
- * @param {readonly string[]} [opts.sections] - The sections the repository
- *   configures; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(
-    index,
-    { schemas, vocabulary, references = true, systems, landing, types, sections },
-) {
+export function lintFrontmatter(index, { schemas, vocabulary, references = true, systems }) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
         a.file < b.file ? -1
@@ -835,9 +781,6 @@ export function lintFrontmatter(
                 vocabulary,
                 index: references ? index : undefined,
                 ...(systems ? { systems } : {}),
-                ...(landing ? { landing } : {}),
-                ...(types ? { types } : {}),
-                ...(sections ? { sections } : {}),
             }),
         );
     }

package/engine/manifest-emit.mjs

@@ -32,19 +32,16 @@
  * **An entry's `path` is derivable from the key it is filed under** (#181).
  * `sohl-affliction-aconite` publishes at `affliction-aconite/`, because a page's
  * URL *is* its address; nothing in it comes from a display name, so a rename
- * moves no URL and no uniqueness check stands between the two. The field is
- * still written rather than left for a consumer to compute, because a landing
- * page is the one entry that is not derivable — it addresses its section under
- * the configured mount — and because an absent `path` already means something
- * else entirely (a package that publishes no pages).
+ * moves no URL and no uniqueness check stands between the two. Every entry is
+ * derivable that way since #204 retired the section landing, which was the one
+ * that was not. The field is still written rather than left for a consumer to
+ * compute, because an absent `path` already means something else entirely (a
+ * package that publishes no pages).
  *
- * **The address scheme is configuration, and it is shared with the site build.**
- * Where the content tree mounts inside the package and which note is a section's
- * landing page differ between repositories and are both load-bearing — `sohl`
- * records `kb/rules/` for the landing of its rules section and `thalorna`
- * records `affiliation/` for its own. Reading one setting here and in the page
- * emitter is what stops a manifest asserting an address the site does not
- * publish, which resolves at build time and 404s for the reader.
+ * **The address is derived by one function, shared with the site build.** An
+ * address is `(type, shortcode)` in both, so a manifest cannot assert an address
+ * the site does not publish — the failure that resolves at build time and 404s
+ * for the reader.
  *
  * **Anchors are computed, not approximated.** The pass that splits a note into
  * journal pages is {@link splitPages}, a pure function over the markdown body,
@@ -65,7 +62,11 @@ import { compendiumUuid, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { isHomepage } from "./homepage.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
-import { assertNoAliasesField, assertNoDraftField } from "./retired-fields.mjs";
+import {
+    assertNoAliasesField,
+    assertNoDraftField,
+    assertNoSectionField,
+} from "./retired-fields.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
@@ -209,8 +210,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
  * exist.
  *
  * @param {string} contentBase - Absolute path to the content tree.
- * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter,
- *   scheme }`.
+ * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter }`.
  * @returns {{entries: Array<object>, notes: number,
  *   skipped: Array<{file: string, reason: string}>}}
  */
@@ -233,6 +233,7 @@ export function collectManifestEntries(contentBase, ctx) {
         });
         assertNoDraftField(fm, { file: rel, absPath });
         assertNoAliasesField(fm, { file: rel, absPath });
+        assertNoSectionField(fm, { file: rel, absPath });
         if (!fm.type || !fm.shortcode) continue;
         // A homepage is addressed like every other note since #182, and a
         // shortcode alone would now put it here. It stays out for the reason it
@@ -243,15 +244,11 @@ export function collectManifestEntries(contentBase, ctx) {
         // no index.
         if (isHomepage(fm)) continue;
 
-        const base = path.basename(absPath);
         const name = fm.name?.full ?? path.basename(absPath, ".md");
 
         let address;
         try {
-            address = packageAddress(fm, {
-                isReadme: base.toLowerCase() === "readme.md",
-                scheme: ctx.scheme,
-            });
+            address = packageAddress(fm);
         } catch (err) {
             skipped.push({ file: rel, reason: err.message });
             continue;
@@ -263,7 +260,7 @@ export function collectManifestEntries(contentBase, ctx) {
 }
 
 /**
- * The identities and scheme an emission runs against, from configuration.
+ * The identities an emission runs against, from configuration.
  *
  * Resolved in one place and passed down, rather than read at each use, so the
  * pass itself is a pure function of its context and a test can drive it without
@@ -271,15 +268,13 @@ export function collectManifestEntries(contentBase, ctx) {
  *
  * @param {object} [config] - A resolved configuration; loaded when omitted.
  * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
- *   scheme: {prefix: string, landing: string}, web: boolean,
- *   skipDirectories: readonly string[]}}
+ *   web: boolean, skipDirectories: readonly string[]}}
  */
 export function manifestContext(config = loadPackConfig()) {
     return {
         contentPackage: config.contentPackage,
         foundryPackageId: config.foundryPackage,
         packRouter: routerFor(config),
-        scheme: config.publish.address,
         web: publishesContentPages(config),
         // The walk's own configuration, threaded through rather than left to
         // its default, so a caller that passes a config drives every read.

package/engine/note-vocabulary.mjs

@@ -53,9 +53,31 @@
  * one is already reported as a type no schema declares, which is the finding it
  * deserves until the type exists.
  *
+ * **A type name and a subType value are held to the address charset** (#206), so
+ * both are `^[A-Za-z0-9]+$` — the charset `engine/address-charset.mjs` states
+ * and the shortcode is already held to. For a type that is literal: it is the
+ * first segment of every address (`type-shortcode`), the hyphen is the
+ * separator between segments and can therefore never occur inside one, and a
+ * hyphenated name would be read back as two segments and resolve to nothing,
+ * reporting nothing about why.
+ *
+ * A subType reaches no address of its own. It did when this rule was written —
+ * a `doc`'s was its section, a path segment — and #204 retired sections from
+ * the note format one release later. It keeps the rule regardless, and the
+ * reason is not inertia: a subType is a vocabulary term the whole toolchain
+ * keys on, it is one closed set away from being an address again, and a charset
+ * that held for a type, a shortcode and a package but not for a subType would
+ * be a rule nobody could state in one sentence. The registry below is checked
+ * against it as this module loads, so a declaration that breaks it cannot be
+ * imported, let alone shipped.
+ *
  * @module
  */
 
+// The one charset, read rather than restated. A second spelling of the pattern
+// is how the three disagreements found in #202/#203 happened.
+import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
+
 /**
  * One `data:` key a note type may carry.
  *
@@ -641,7 +663,12 @@ export const NOTE_VOCABULARY = Object.freeze({
     /* ----- core documents ------------------------------------------- */
 
     doc: Object.freeze({
-        subTypes: Object.freeze(["rules", "user-guide", "reference"]),
+        // `userguide`, not `user-guide`: a subType is held to the address
+        // charset, and a segment carries no hyphen (#206). The old spelling was
+        // accepted transitionally for one release so the consumer trees could
+        // sweep; they have, so it is refused by the charset check now, with no
+        // retirement-specific code left over (#210).
+        subTypes: Object.freeze(["rules", "userguide", "reference"]),
         data: Object.freeze([]),
     }),
 
@@ -704,6 +731,95 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 });
 
+/**
+ * What a note carrying a subType outside the address charset is told.
+ *
+ * **Why the charset holds for a subType, which reaches no address.** #206 said
+ * "the hyphen separates the segments of an address", and that was true of a
+ * subType when it shipped: `sectionOf` returned a `doc`'s subType, so the value
+ * was a URL path segment. #204 retired sections and it is not one now. The rule
+ * stays, on its own footing: a subType is a vocabulary term the whole toolchain
+ * keys on, and it is one closed set away from being an address segment again —
+ * so the reason to spell it in the address charset is that a charset holding
+ * for a type, a shortcode and a `contentPackage` but not for a subType is a
+ * rule nobody can state in a sentence.
+ *
+ * Contrast {@link typeCharsetMessage}, which keeps the address reasoning
+ * because a type genuinely is the first segment of every address.
+ *
+ * @param {string} value - The authored `subType`.
+ * @returns {string} The message.
+ */
+export function subTypeCharsetMessage(value) {
+    return (
+        `\`subType\` "${value}" is not a well-formed subType — a subType is ` +
+        `letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}), the same ` +
+        `charset a type, a shortcode and a contentPackage are held to. It is a ` +
+        `vocabulary term the whole toolchain keys on, and one closed set away ` +
+        `from being an address segment again, so a charset that held for every ` +
+        `term but this one would be a rule nobody could state in a sentence`
+    );
+}
+
+/**
+ * What a note carrying a type outside the address charset is told.
+ *
+ * @param {string} type - The authored `type`.
+ * @returns {string} The message.
+ */
+export function typeCharsetMessage(type) {
+    return (
+        `content type "${type}" is not an address segment — a type is letters ` +
+        `and digits only (${ADDRESS_SEGMENT_PATTERN.source}), the same charset ` +
+        `a shortcode is held to. A type is the first segment of every address ` +
+        `("type-shortcode"), so a hyphenated one is read back as two segments ` +
+        `and resolves to nothing`
+    );
+}
+
+/**
+ * Refuse a vocabulary that declares a type or subType outside the charset.
+ *
+ * Run over {@link NOTE_VOCABULARY} as this module loads, so a declaration that
+ * breaks the rule cannot be imported. That is stricter than a lint on purpose:
+ * a note's bad value is one author's mistake and belongs in a report, while a
+ * bad *declaration* would tell every author to write something unaddressable.
+ *
+ * The message states the reason **per key**, as {@link typeCharsetMessage} and
+ * {@link subTypeCharsetMessage} do: a type is an address segment, and a subType
+ * has not been one since #204 retired sections, so a single claim covering both
+ * would be half wrong (#210).
+ *
+ * @param {Readonly<Record<string, TypeVocabulary>>} vocabulary - The registry.
+ * @param {string} [where] - What declares it, for the message.
+ * @throws {Error} Naming every offending type and subType at once, rather than
+ *   stopping at the first — a reader fixing a list wants the whole list.
+ */
+export function assertVocabularyCharset(vocabulary, where = "the note vocabulary") {
+    const bad = [];
+    for (const [type, entry] of Object.entries(vocabulary ?? {})) {
+        if (!isAddressSegment(type)) bad.push(`type "${type}"`);
+        const values = entry?.subTypes;
+        if (!Array.isArray(values)) continue;
+        for (const value of values) {
+            if (!isAddressSegment(value)) bad.push(`subType "${value}" on ${type}`);
+        }
+    }
+    if (!bad.length) return;
+    throw new Error(
+        `${where} declares ${bad.join(", ")}, which ${bad.length === 1 ? "is" : "are"} ` +
+            `not ${ADDRESS_SEGMENT_PATTERN.source}. A type is an address segment, ` +
+            `and the hyphen separates segments rather than occurring inside one. ` +
+            `A subType reaches no address since #204 retired sections, and is ` +
+            `held to the same charset anyway: it is a vocabulary term the whole ` +
+            `toolchain keys on, one closed set away from being a segment again, ` +
+            `and a charset holding for every term but that one would be a rule ` +
+            `nobody could state in a sentence.`,
+    );
+}
+
+assertVocabularyCharset(NOTE_VOCABULARY);
+
 /**
  * The `data:` keys a note type may carry.
  *

package/engine/retired-fields.mjs

@@ -22,9 +22,9 @@
  * says what to write instead rather than which value to correct.
  *
  * `package:` is retired the same way and is refused from `note-package.mjs`,
- * where the concept it belonged to still lives. `draft:` and the top-level
- * `aliases:` have no such home — there is no surviving concept either was part
- * of — so they are refused here.
+ * where the concept it belonged to still lives. `draft:`, the top-level
+ * `aliases:` and `section:` have no such home — there is no surviving concept
+ * any of them was part of — so they are refused here.
  *
  * **What `draft:` did (#69).** It excluded a note from the compiled packs, from
  * the link manifest and from a consuming site build. Nothing reported the
@@ -41,6 +41,13 @@
  * `name.full` and so decided what a note could be named (#179). The form and
  * the index are retired together, leaving the field with no reader at all.
  *
+ * **What `section:` did (#202).** It named the section a `collection` note
+ * headed, under the `collection` landing rule — its only reader anywhere. That
+ * rule is retired, a section being landed by the `README.md` in its directory,
+ * so the field has none. No schema or vocabulary ever declared it either, and
+ * nothing checks unrecognized top-level keys, so left in place it would be
+ * silently ignored rather than reported.
+ *
  * **`name.aliases` fed the same index and is nonetheless kept.** It is
  * **reserved** — held for a use that does not exist yet — so it is the one
  * field here that is neither retired nor read. Nothing consults it: no index,
@@ -216,6 +223,72 @@ export function declaresRetiredAliasesField(fm) {
     return Boolean(fm) && typeof fm === "object" && Object.hasOwn(fm, "aliases");
 }
 
+/**
+ * What a note declaring `section:` is told, in one place.
+ *
+ * Shared by the compile-time refusal and the frontmatter lint, because an
+ * author meets whichever of the two runs first and they should read the same.
+ * It names what lands a section now rather than a value to correct: no value
+ * makes declaring the field right.
+ *
+ * **What it did (#202).** It named the section a `collection` note headed,
+ * under the `collection` landing rule — the only reader it ever had, in the
+ * second branch of `landingOf` (`engine/content-address.mjs`). That rule went
+ * first, and the whole mechanism went with it (#204): a section is a Hugo
+ * directory the note format does not carry, so no note lands one and a page
+ * that introduces a type is an ordinary note addressed `doc-<type>`. Nothing
+ * else read the field, and no schema or vocabulary declared it, so left in
+ * place it would be ignored in silence — the note saying one thing and the
+ * build doing another.
+ *
+ * @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 sectionRetiredMessage(file) {
+    return (
+        "`section:` is a retired frontmatter field — delete it" +
+        (file ? ` — ${file}` : "") +
+        ". It named the section a `collection` note headed, and both the rule " +
+        "and the sections it routed to are retired: a page that introduces " +
+        "the notes of a type is an ordinary note — `type: doc`, " +
+        "`subType: reference`, `shortcode: <type>` — addressed `doc-<type>`. " +
+        "Nothing else ever read the field"
+    );
+}
+
+/**
+ * Refuse a note that declares `section:` at all.
+ *
+ * Presence is the whole test, as it is for `draft:` and `aliases:`: an empty
+ * value reads as "this note heads a section and names none", a statement about
+ * a rule that no longer exists.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @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 — repeating it prints the path twice.
+ * @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 declares the field.
+ */
+export function assertNoSectionField(fm, { file, absPath } = {}) {
+    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "section")) return;
+
+    const err = new Error(`${sectionRetiredMessage(file)}.`);
+    // Anchored at column 1: `site.trees[].section` is a *configuration* key of
+    // the same name, and a nested `section:` inside some other block is not
+    // this field — a finding about the top-level one must not open on it.
+    const position = locateFrontmatterKey(absPath, "section", undefined, { topLevel: true });
+    if (position) err.position = position;
+    throw err;
+}
+
 /**
  * A frontmatter key's position in a note's file, or nothing.
  *