@heroiclands/package-build 13.0.0 → 15.0.0

package/engine/helpers.mjs

@@ -234,25 +234,51 @@ export function makeFilename(name, id) {
  * asset roots — `icons/...` and `images/...` — are served from the package
  * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
  * for this repository, `modules/<id>/assets` for a module (#1508). Any other
- * path (already package-rooted, an absolute URL) is returned unchanged, and an
- * empty path yields `""`.
- *
- * This is translation only: the per-type default for an empty result is
- * domain-specific (actors default differently from items, and gear differently
- * again), so each compiler owns its own default and applies it to the result —
- * `resolveImg(fm.img) || <default>`. For items that default is the art paired
- * with the type's builder, reached through `itemArt()`, which runs the path
- * back through this function so a registry entry and a note's `img:` are
- * spelled the same way (#7).
+ * path (already package-rooted, an absolute URL) is returned unchanged.
+ *
+ * **Two empties, and they mean opposite things (#218).** `null` — or an absent
+ * key, which reaches here as `undefined` — means _unset_: the note names no art
+ * and the caller's default applies. `""` means _blank on purpose_: the note
+ * names no art **and wants none**, so no default may replace it. Both come back
+ * distinguishable, `null` and `""` respectively, and neither is invented from
+ * the other.
+ *
+ * This used to open `if (!raw) return ""`, which made the two one case: every
+ * caller then applied its default with `||`, so a deliberate blank was
+ * unspellable and an unset key and an empty string compiled identically. That
+ * is the convention the project already rejects for an optional "not specified"
+ * DataModel string, where `nullable, initial: null` keeps "unset" a single
+ * honest value rather than two.
+ *
+ * **`title` does not follow this rule**, and must not be made to. On a
+ * `type: affiliation` note `title` is *also* a declared item field whose default
+ * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
+ * key the site emitter reads as the page title — so `title: null` stringifies
+ * into the compiled document as the literal `"null"`. One key, two destinations
+ * that disagree about what empty means; see #218.
+ *
+ * This is translation only: the default for an unset path is domain-specific
+ * (actors default differently from items, and gear differently again), so each
+ * compiler owns its own default and applies it to the result with **nullish**
+ * coalescing — `resolveImg(fm.img) ?? <default>`. Not `||`: that would collapse
+ * a deliberate blank back into the default and undo the distinction. For items
+ * that default is the art paired with the type's builder, reached through
+ * `itemArt()`, which runs the path back through this function so a registry
+ * entry and a note's `img:` are spelled the same way (#7).
  *
  * @param {string | null | undefined} raw - content-relative path from frontmatter.
  * @param {{assetRoot: string}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
- * @returns {string} the Foundry-relative path, or `""` when `raw` is empty.
+ * @returns {string | null} the Foundry-relative path; `""` for a deliberate
+ *   blank, and `null` when the note names no art at all.
  */
 export function resolveImg(raw, config = loadPackConfig()) {
-    if (!raw) return "";
+    // Unset — the caller's default applies. An absent key arrives as
+    // `undefined`, an authored one as `null`; they say the same thing.
+    if (raw == null) return null;
     const s = String(raw);
+    // Blank on purpose — the caller's default must not apply.
+    if (s === "") return "";
     if (s.startsWith("icons/") || s.startsWith("images/")) {
         return `${config.assetRoot}/${s}`;
     }

package/engine/homepage.mjs

@@ -371,6 +371,13 @@ export function homepageTitle(fm, config) {
  * for one; it decides nothing while `url` is present, but a page carrying only
  * `url` would report a slug Hugo had inferred from the filename.
  *
+ * **Site-root relative, and so carrying no package base** (#217), exactly as
+ * `pageFrontmatter` states a content page's: Hugo resolves a `url`
+ * against `baseURL`, whose path is already where the package is served, so a
+ * stated base was written twice and published the landing at
+ * `/<package>/<package>/homepage-root/`. Where the package is served is what
+ * every *href* is composed from and it reaches this page's address not at all.
+ *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
  * redirect stub at each one. The field is retired (#180) and refused before a
@@ -380,14 +387,12 @@ export function homepageTitle(fm, config) {
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
- * @param {string} options.base - Where the package is served, with both
- *   slashes — `/<package>/`.
  * @returns {object} The frontmatter to write.
  * @throws {Error} When the note declares no shortcode, and so has no address.
  */
-export function homepageFrontmatter(fm, { contentPackage, title, base }) {
+export function homepageFrontmatter(fm, { contentPackage, title }) {
     const slug = addressSlug(fm);
-    const data = { ...fm, package: contentPackage, title, slug, url: `${base}${slug}/` };
+    const data = { ...fm, package: contentPackage, title, slug, url: `/${slug}/` };
     delete data.aliases;
     return data;
 }

package/engine/item-registry.mjs

@@ -188,5 +188,8 @@ export function itemArt(type, system) {
                 `note an \`img:\` of its own.`,
         );
     }
-    return resolveImg(art);
+    // `art` is non-empty by the guard above, so the translation never returns
+    // the `null` a note's unset `img:` would (#218); the coalesce states that
+    // rather than leaving the declared `string` return a half-truth.
+    return resolveImg(art) ?? "";
 }

package/engine/macros.mjs

@@ -261,7 +261,9 @@ export function buildMacroEntry(fm, { command, folder = null, stats = defaultSta
         // into chat instead of running.
         type: resolveMacroType(fm, name),
         author: null,
-        img: resolveImg(fm.img) || DEFAULT_MACRO_IMG,
+        // Nullish, not `||` (#218): a macro note that names no art gets the
+        // shared default, one that writes `img: ""` ships blank on purpose.
+        img: resolveImg(fm.img) ?? DEFAULT_MACRO_IMG,
         scope: resolveMacroScope(fm, name),
         command,
         folder,

package/engine/manifest-emit.mjs

@@ -210,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}>}}
  */
@@ -249,7 +248,7 @@ export function collectManifestEntries(contentBase, ctx) {
 
         let address;
         try {
-            address = packageAddress(fm, { scheme: ctx.scheme });
+            address = packageAddress(fm);
         } catch (err) {
             skipped.push({ file: rel, reason: err.message });
             continue;
@@ -261,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
@@ -269,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

@@ -663,11 +663,11 @@ export const NOTE_VOCABULARY = Object.freeze({
     /* ----- core documents ------------------------------------------- */
 
     doc: Object.freeze({
-        // `userguide`, not `user-guide`: a `doc` routes by its subType, so the
-        // value is a path segment, and a segment carries no hyphen (#206). The
-        // old spelling is accepted transitionally — see {@link RETIRED_SUBTYPES}
-        // — but it is not declared here, because this list is what the format
-        // says a note *should* write.
+        // `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([]),
     }),
@@ -732,83 +732,32 @@ export const NOTE_VOCABULARY = Object.freeze({
 });
 
 /**
- * The retired spelling of a subType a type declares → what to write now (#206).
- *
- * Keyed by type, because a retirement is a statement about *that type's*
- * vocabulary: `user-guide` on a `doc` is the old spelling of `userguide`, while
- * the same string on any other type is nothing but a charset violation, and
- * saying "did you mean userguide" there would be a guess dressed as a fact.
- *
- * **Recorded here rather than left in `subTypes`** so the declared list stays
- * the list of values a note *should* write. A retired value is accepted, not
- * declared — the difference is exactly what makes the finding possible.
- *
- * **Deliberately not the shape of a type rename** ({@link
- * import("./ids.mjs").RETIRED_TYPES}), which is an error: a retired type routes
- * a note to the wrong pack, whereas a retired subType still compiles to the
- * correct page. The sweep is the consumer's, and the ordering is the reverse of
- * the usual — the acceptance ships *first*, because declaring only the new
- * spelling while 43 `sohl` notes still author the old one would invalidate all
- * 43 with a release they had no chance to sweep ahead of. A later change
- * removes this map, and the old spelling then falls through to the ordinary
- * undeclared-value error with no code left to remove.
- *
- * @type {Readonly<Record<string, Readonly<Record<string, string>>>>}
- */
-export const RETIRED_SUBTYPES = Object.freeze({
-    doc: Object.freeze({ "user-guide": "userguide" }),
-});
-
-/**
- * What to write in place of a retired subType value, if it is one.
+ * What a note carrying a subType outside the address charset is told.
  *
- * @param {string} type - The note's `type`.
- * @param {string} value - The authored `subType`.
- * @param {Readonly<Record<string, Readonly<Record<string, string>>>>} [retired]
- *   The map to read, defaulting to {@link RETIRED_SUBTYPES}.
- * @returns {string|undefined} The current spelling, or `undefined` when the
- *   value is not a retired one — which is not the same as it being valid.
- */
-export function retiredSubType(type, value, retired = RETIRED_SUBTYPES) {
-    const forType = retired?.[type];
-    if (!forType || !Object.hasOwn(forType, value)) return undefined;
-    return forType[value];
-}
-
-/**
- * What a note carrying a retired subType 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.
  *
- * One message, so the lint and any later refusal cannot describe the same
- * retirement differently.
- *
- * @param {string} type - The note's `type`.
- * @param {string} value - The retired spelling the note carries.
- * @param {string} replacement - What to write instead.
- * @returns {string} The message.
- */
-export function retiredSubTypeMessage(type, value, replacement) {
-    return (
-        `\`subType\` "${value}" is a retired spelling of "${replacement}" on a ` +
-        `${type}; write "${replacement}". A subType is an address segment, and ` +
-        `a segment is ${ADDRESS_SEGMENT_PATTERN.source} — the hyphen separates ` +
-        `segments, so it can never occur inside one. The old spelling is still ` +
-        `accepted, and will stop being accepted once the trees have swept`
-    );
-}
-
-/**
- * What a note carrying a subType outside the address charset is told.
+ * 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 an address segment — a subType is ` +
+        `\`subType\` "${value}" is not a well-formed subType — a subType is ` +
         `letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}), the same ` +
-        `charset a shortcode is held to. The hyphen separates the segments of ` +
-        `an address, so a value containing one is read back as two segments ` +
-        `and resolves to nothing`
+        `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`
     );
 }
 
@@ -836,6 +785,11 @@ export function typeCharsetMessage(type) {
  * 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
@@ -854,9 +808,13 @@ export function assertVocabularyCharset(vocabulary, where = "the note vocabulary
     if (!bad.length) return;
     throw new Error(
         `${where} declares ${bad.join(", ")}, which ${bad.length === 1 ? "is" : "are"} ` +
-            `not ${ADDRESS_SEGMENT_PATTERN.source}. A type and a subType are both ` +
-            `address segments, and the hyphen separates segments rather than ` +
-            `occurring inside one.`,
+            `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.`,
     );
 }
 

package/engine/site-build.mjs

@@ -343,18 +343,13 @@ export function collectHomepages(contentBase, ctx) {
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
- * @param {object} [options] - Options.
- * @param {string} [options.base] - Where the package is served; defaults to the
- *   configured `site.base`, and to `/<contentPackage>/` below that.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot, pages, config, { base } = {}) {
-    const at = base || config.site?.base || `/${config.contentPackage}/`;
+export function writeHomepages(outRoot, pages, config) {
     for (const page of pages) {
         const data = homepageFrontmatter(page.fm, {
             contentPackage: config.contentPackage,
             title: homepageTitle(page.fm, config),
-            base: at,
         });
         const dest = path.join(outRoot, homepageDestination(page.fm));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -544,6 +539,16 @@ export function sectionFrontmatter(meta) {
  * package-wide address the link manifest records — the same address, one
  * segment too deep. So the address is stated and the mount does not reach it.
  *
+ * **It is stated relative to the site root, and so carries no package base**
+ * (#217). Hugo resolves a `url` against `baseURL`, whose path is already where
+ * the package is served — a consumer's Hugo site *is* its package — so writing
+ * `page.url`, which carries the base for every href this build renders, wrote
+ * that base a second time and published every content page a segment too deep
+ * (`/sohl/sohl/doc-rulesintro/`). The two are separate quantities: the page
+ * states `/<slug>/`, and everything that points *at* the page — the address
+ * index a wikilink resolves through, and the link manifest — composes
+ * `<base><slug>/`.
+ *
  * A content page carries the package the build **derived** (#65). No note
  * declares one — `package:` is retired (#56) — so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The
@@ -571,13 +576,14 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
             // Spread after the note's own frontmatter. Guarded because
             // `package: undefined` is not a value YAML can carry.
             ...(page.pkg ? { package: page.pkg } : {}),
-            // The address, stated. `slug` is written beside it because it is
-            // the last segment of that address and Hugo's own key for one; it
-            // decides nothing while `url` is present, but a page that carried
-            // only `url` would report a slug Hugo had inferred from the
-            // filename.
+            // The address, stated — site-root relative, because Hugo prefixes
+            // the site's own base to it (#217). `slug` is written beside it
+            // because it is the last segment of that address and Hugo's own key
+            // for one; it decides nothing while `url` is present, but a page
+            // that carried only `url` would report a slug Hugo had inferred
+            // from the filename.
             slug,
-            url: page.url,
+            url: `/${slug}/`,
             title: fm.title ?? name,
             kbfolder: page.folder,
         };
@@ -993,7 +999,7 @@ export function buildSite({ config, outRoot } = {}) {
             tableErrors: [],
             wikiErrors: [],
             stats: {
-                homepages: writeHomepages(homeRoot, homepages, resolved, { base }),
+                homepages: writeHomepages(homeRoot, homepages, resolved),
                 landings: 0,
                 out: homeRoot,
             },
@@ -1078,7 +1084,7 @@ export function buildSite({ config, outRoot } = {}) {
 
     // Last, and outside the mount: the package's front page is not part of the
     // content tree it introduces.
-    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved, { base });
+    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved);
 
     return {
         gates,

package/engine/system-block.mjs

@@ -52,6 +52,28 @@
  *    may be a dotted path (`data.portrait`) rather than a sibling key;
  * 4. the field's own default.
  *
+ * ## A name that collides across the two vocabularies skips step 3
+ *
+ * A field's `name` is both its identity and the shared property it draws from,
+ * and those coincide only while the two vocabularies agree about what the
+ * spelling means. They do not always. An `affiliation` item's `system.title` is
+ * the style of address an office carries — "Ajaw", "Warden"; a note's top-level
+ * `title` is the note's own heading, which the site emitter publishes. Two
+ * unrelated quantities, one spelling, and step 3 fed the first from the second.
+ *
+ * It was not a harmless coincidence either, because step 3 answers **without**
+ * applying `field.default` — only step 2 does — so an authored `title: null`
+ * reached the field's coercion unguarded and shipped as the literal string
+ * `"null"` in fifteen documents (#218).
+ *
+ * So a field may declare `topLevelMeans`: what the top-level key of that name
+ * means *instead*. Declaring it removes step 3 for that field, leaving the two
+ * positions that describe the document rather than the note. It is deliberately
+ * a per-field opt-out rather than a change to the order — step 3 is right
+ * wherever the two levels state the same quantity, which is nearly everywhere —
+ * and its value is the reason rather than a bare flag, so the collision is
+ * legible where the field is declared. See {@link module:engine/field-spec.FieldSpec}.
+ *
  * `sohlField()` — read `fm.sohl[key]`, fall back to `fm[key]` — is the
  * degenerate case where source and destination happen to share a name. It stops
  * being the general rule; {@link blockField} is what remains of it.
@@ -347,9 +369,13 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
         if (nested !== undefined) return { value: nested, from: "block" };
     }
 
-    // 3. The shared property this field declares as its source.
-    const shared = getFrontmatter(fm, field.name, undefined);
-    if (shared !== undefined) return { value: shared, from: "shared" };
+    // 3. The shared property this field declares as its source — unless the
+    //    field declares that the top-level key of that name means something
+    //    else, in which case there is no shared position to read (#218).
+    if (field.topLevelMeans === undefined) {
+        const shared = getFrontmatter(fm, field.name, undefined);
+        if (shared !== undefined) return { value: shared, from: "shared" };
+    }
 
     // 4. The field's own default.
     return { value: field.default, from: "default" };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "13.0.0",
+    "version": "15.0.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/sohl/actors.mjs

@@ -763,7 +763,9 @@ export class Actors extends BasePackCompiler {
             // Required nullable number: a priority, or `null` for a being that
             // is not an archetype (#126 / archetype contract #604).
             archetype: systemArchetype(fm, ctx),
-            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) || defaultImg,
+            // Nullish, not `||` (#218): a note that names no portrait gets the
+            // subtype's default, one that writes `""` ships blank on purpose.
+            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) ?? defaultImg,
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };
@@ -815,7 +817,8 @@ export class Actors extends BasePackCompiler {
         return {
             name,
             type: subType,
-            img: resolveImg(blockProperty(fm, SYSTEM, "img")) || defaultImg,
+            // Nullish, not `||` — see the portrait above (#218).
+            img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg,
             _id: id,
             system,
             items,
@@ -823,7 +826,7 @@ export class Actors extends BasePackCompiler {
                 name,
                 displayName: 0,
                 actorLink: false,
-                texture: { src: resolveImg(blockProperty(fm, SYSTEM, "img")) || defaultImg },
+                texture: { src: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg },
                 width: 1,
                 height: 1,
                 sight: { enabled: false },

package/sohl/item-fields.mjs

@@ -265,6 +265,12 @@ export const ITEM_FIELDS = Object.freeze({
             to: "title",
             ...STRING,
             default: "",
+            topLevelMeans:
+                "the note's own title — the heading its page is published under, " +
+                "which has nothing to do with the style of address an office " +
+                "carries. Author this on the membership instead: `sohl.system.title` " +
+                "on the item, or the `system.title` of the entry in a being's " +
+                "`sohl.items`.",
             describe: "The style of address the office carries.",
         },
         {

package/sohl/items.mjs

@@ -255,7 +255,10 @@ export class Items extends BasePackCompiler {
             // both registries are keyed by content type — while the document's
             // own subtype comes from the system's map (#79).
             type: subType,
-            img: resolveImg(blockProperty(fm, SYSTEM, "img")) || itemArt(type, SYSTEM),
+            // Nullish, not `||` (#218): `resolveImg` returns `null` for a note
+            // that names no art and `""` for one that wants none, and only the
+            // first may be replaced by the type's default.
+            img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? itemArt(type, SYSTEM),
             _id: id,
             system,
             effects: Array.isArray(effects) ? [...effects] : [],

package/types/content-config.d.mts

@@ -56,36 +56,31 @@ export namespace DEFAULT_PATHS {
  */
 export const PACK_DOCUMENT_TYPES: readonly ["Actor", "Adventure", "Item", "JournalEntry", "Macro", "Scene"];
 /**
- * The landing-page rules a repository may route by. **Inert since #204.**
- *
- * A *landing page* was a note that addressed a whole section rather than a page
- * within one, so it had no slug of its own. There are no sections in the note
- * format any more — a section is a Hugo content directory, and a page's address
- * names no directory — so there are no landings and this selects nothing.
- *
- * The key survives its own mechanism on purpose. Both publishing consumers
- * declare `landing: readme`, which stated something true when they wrote it;
- * refusing it now would break them over a correct statement, and silently
- * ignoring an unknown value would be worse. So `readme` stays accepted, the
- * retired `collection` stays refused by name (below), and the key is deleted
- * once no configuration writes it — `content-config.mjs` has no warning channel
- * with which to say "accepted, and does nothing" in between.
- *
- * @type {readonly string[]}
- */
-export const LANDING_RULES: readonly string[];
-/**
- * What a configuration naming the retired `collection` landing rule is told.
- *
- * A retired *value* is refused the way a retired *field* is (see
- * `engine/retired-fields.mjs`): left merely unrecognized it would be reported
- * as a bad value, which names something to correct and leaves the author to
- * work out for themselves that the mechanism is gone. The message says the rule
- * is retired, what lands a section instead, and what to do with the key.
+ * Address-scheme keys a configuration may no longer declare.
+ *
+ * A retired key has exactly two possible fates, and only one of them is honest
+ * — the same reasoning `engine/retired-fields.mjs` applies to a retired
+ * frontmatter field. Left honoured, it keeps doing whatever it did, which is
+ * why it was retired. Left *ignored*, it reads to its author as though it still
+ * works: the configuration says one thing and the build does another, and
+ * nothing says so. This module has no third option, because it has no warning
+ * channel — every finding goes through `fail()`, which throws. So a retired
+ * key is **refused**, at the line it was written on, with a message that says
+ * the mechanism is gone rather than naming a value to correct.
+ *
+ * **What `landing` did (#204).** It named which note addressed a whole section
+ * rather than a page within one — a *landing page*, which therefore had no slug
+ * of its own. #203 retired the second of its two rules and #204 retired the
+ * concept both rules chose between: a section is a Hugo content directory that
+ * the note format does not carry, a page's address names no directory, and so
+ * no note lands anything. The key outlived its mechanism by one release only
+ * because both publishing consumers still declared the then-true
+ * `landing: readme`, and neither breaking them over a correct statement nor
+ * accepting the key in silence was acceptable. Neither declares it now.
  *
  * @type {Readonly<Record<string, string>>}
  */
-export const RETIRED_LANDING_RULES: Readonly<Record<string, string>>;
+export const RETIRED_ADDRESS_KEYS: Readonly<Record<string, string>>;
 /**
  * A repository's address scheme, with the defaults an unconfigured one gets.
  *
@@ -96,11 +91,12 @@ export const RETIRED_LANDING_RULES: Readonly<Record<string, string>>;
  * knowledge, held in `PACKAGE_BASE` (`engine/kb-manifest.mjs`) and prefixed at
  * resolve time, so it is never recorded here (#1465).
  *
- * `landing` is inert — see {@link LANDING_RULES}.
+ * It is the whole scheme: `landing`, the key that named which note addressed a
+ * whole section, is retired with the sections themselves — see
+ * {@link RETIRED_ADDRESS_KEYS}.
  */
 export const DEFAULT_ADDRESS_SCHEME: Readonly<{
     prefix: "";
-    landing: "readme";
 }>;
 /**
  * How much of a package reaches the web.
@@ -515,12 +511,6 @@ export type AddressSchemeInput = {
      * Where the content tree mounts inside the package.
      */
     prefix?: string | undefined;
-    /**
-     * Which note addressed a whole section. Inert
-     * since #204 retired sections from the note format — see
-     * {@link LANDING_RULES}.
-     */
-    landing?: string | undefined;
 };
 /**
  * One entry of a consumer's `itemBuilders` registry.

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

@@ -55,27 +55,20 @@ export function contentAddress(fm: object): string;
  * `/<package>/api/` for generated API docs, neither of which contains a hyphen
  * or names a type.
  *
+ * **It takes no address scheme.** It took one until #215, to validate the
+ * `landing` rule it then discarded; with that key retired, `prefix` was the
+ * only thing left in the scheme and the paragraph above is the reason it never
+ * applied. A parameter read by nothing is the defect this deletion is about.
+ *
  * @param {object} fm - Parsed frontmatter.
- * @param {object} [options] - Options.
- * @param {{prefix?: string, landing?: string}} [options.scheme] - The
- *   repository's address scheme; defaults to {@link DEFAULT_ADDRESS_SCHEME}.
- *   `landing` is validated against {@link LANDING_RULES} and selects nothing —
- *   it is accepted so a configuration declaring the still-true `landing: readme`
- *   keeps loading, and is removed once none does.
  * @returns {string} The package-relative address, with a trailing slash and no
  *   leading one.
  * @throws {Error} When the note has no type or no shortcode to be addressed by.
  *   Such a note is not published, and inventing an address for one would put a
  *   dead entry in the manifest.
  */
-export function packageAddress(fm: object, { scheme }?: {
-    scheme?: {
-        prefix?: string;
-        landing?: string;
-    } | undefined;
-}): string;
+export function packageAddress(fm: object): string;
+export { DEFAULT_ADDRESS_SCHEME };
 /** The knowledgebase's mount within this package's site (#1470). */
 export const KB_PREFIX: "kb/";
 import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
-import { LANDING_RULES } from "../content-config.mjs";
-export { DEFAULT_ADDRESS_SCHEME, LANDING_RULES };