@heroiclands/package-build 11.1.0 → 13.0.0

package/content-config.mjs

@@ -116,28 +116,45 @@ export const PACK_DOCUMENT_TYPES = /** @type {const} */ ([
 ]);
 
 /**
- * The landing-page rules a repository may route by.
+ * The landing-page rules a repository may route by. **Inert since #204.**
  *
- * A *landing page* is a note that addresses a whole section rather than a page
- * within one, so it has no slug of its own. Which note that is differs between
- * repositories, and both live rules are represented here because switching
- * either one on for the other repository moves addresses that are already
- * published:
+ * 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.
  *
- * - `readme` — a `README.md` **is** its section's landing page. This is `sohl`'s
- *   rule, and a `doc` note routes by its `category` like any other, so `sohl`'s
- *   eleven `category: collection` notes publish under a literal `collection/`
- *   section (`kb/collection/skills/`).
- * - `collection` — a `doc` note whose `category` is `collection` addresses the
- *   section it introduces, named by its authored `section`. This is `thalorna`'s
- *   rule, under which the same note publishes at `creature/`.
- *
- * The two are not disjoint and cannot simply both apply: each tree holds notes
- * the other rule would move.
+ * 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 = Object.freeze(["readme", "collection"]);
+export const LANDING_RULES = Object.freeze(["readme"]);
+
+/**
+ * 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.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const RETIRED_LANDING_RULES = Object.freeze({
+    collection:
+        "the `collection` landing rule is retired, and so is the mechanism it " +
+        "chose between: a section is a Hugo directory the note format does not " +
+        "carry, so no note lands one. Delete this key. A page that introduces " +
+        "the notes of a type is an ordinary note — `type: doc`, " +
+        "`subType: reference`, `shortcode: <type>` — addressed `doc-<type>`; " +
+        "the `section:` frontmatter key the rule read is retired with it",
+});
 
 /**
  * A repository's address scheme, with the defaults an unconfigured one gets.
@@ -148,6 +165,8 @@ export const LANDING_RULES = Object.freeze(["readme", "collection"]);
  * own mount point: where the package itself is served is the consuming build's
  * 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}.
  */
 export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
     prefix: "",
@@ -210,34 +229,6 @@ export function publishesContentPages(config) {
     return config.publish.site === "content";
 }
 
-/**
- * Every URL section this repository names, in declaration order (#197).
- *
- * A section is *declared* by describing it: `site.sections` for one whose
- * landing this build generates, `site.readmeSections` for one whose landing is
- * a `README`. Between them they are the open set of addresses a repository
- * says it publishes under — which is what a `README` landing's `subType` names,
- * since `sectionOf` reads that field as the section rather than as a genre.
- *
- * Read from the same two maps the site build renders each landing from, so the
- * set a note is checked against and the set a landing is written from cannot
- * come to disagree. A repository that describes no section declares none, and
- * the answer is empty rather than a guess assembled from the tree.
- *
- * @param {{site: {sections: object, readmeSections: object}}} config - A
- *   resolved configuration.
- * @returns {readonly string[]} The section names, deduplicated.
- */
-export function declaredSections(config) {
-    const site = config?.site ?? {};
-    return Object.freeze([
-        ...new Set([
-            ...Object.keys(site.sections ?? {}),
-            ...Object.keys(site.readmeSections ?? {}),
-        ]),
-    ]);
-}
-
 /**
  * @typedef {"systems" | "modules"} PackageKind
  */
@@ -481,7 +472,9 @@ export function declaredSections(config) {
 /**
  * @typedef {object} AddressSchemeInput
  * @property {string} [prefix]   Where the content tree mounts inside the package.
- * @property {string} [landing]  Which note addresses a whole section.
+ * @property {string} [landing]  Which note addressed a whole section. Inert
+ *   since #204 retired sections from the note format — see
+ *   {@link LANDING_RULES}.
  */
 
 /**
@@ -1120,10 +1113,11 @@ function normalizeDocs(value) {
  * One section's landing metadata — what a section says about itself on the
  * `_index.md` this build generates for it.
  *
- * A generated landing is the *only* place a section can speak: a content
- * package has no authored `_index.md` for `weapongear` or `affliction`, so the
- * file the theme reads is the one the site build writes. This is therefore the
- * whole vocabulary, and it is deliberately a **closed** one.
+ * A generated landing is the *only* place a section can speak, and since #204 it
+ * is the only place a section **exists**: a content page is addressed
+ * `(type, shortcode)` and written flat under the mount, so no page creates a
+ * directory and nothing else makes `<prefix><section>/` answer. This is
+ * therefore the whole vocabulary, and it is deliberately a **closed** one.
  *
  * The alternative — passing whatever a section declared straight through, as
  * `site.landing` does — was weighed and refused. `landing` is written once, for
@@ -1759,6 +1753,13 @@ function normalizePublish(value) {
         address.landing === undefined ?
             DEFAULT_ADDRESS_SCHEME.landing
         :   optionalString(address.landing, "publish.address.landing");
+    // A retired rule is refused by name, before the vocabulary check: reported
+    // as merely unrecognized it would read as a misspelling of the one that
+    // survives, and the author would correct the value rather than learn that
+    // the mechanism is gone (#202).
+    if (Object.hasOwn(RETIRED_LANDING_RULES, landing)) {
+        fail("publish.address.landing", RETIRED_LANDING_RULES[landing]);
+    }
     if (!LANDING_RULES.includes(landing)) {
         fail("publish.address.landing", `must be one of ${LANDING_RULES.join(", ")}`);
     }

package/docs/content-format.md

@@ -233,10 +233,33 @@ field to supply it, so a bare shortcode is resolved across types and must match
 exactly one; an ambiguity is an error naming the candidates.
 
 **Parsing is positional counting from the right, and nothing else.** Every
-segment is alphanumeric — shortcodes are `^[A-Za-z0-9]+$`, types are bare words,
-systems come from a closed registry, and `contentPackage` is alphanumeric — so
-the hyphen is purely a separator. There is no longest-match against a roster and
-no vocabulary check before splitting.
+segment is alphanumeric — shortcodes, **types** and **subTypes** are all
+`^[A-Za-z0-9]+$`, systems come from a closed registry, and `contentPackage` is
+alphanumeric — so the hyphen is purely a separator. There is no longest-match
+against a roster and no vocabulary check before splitting.
+
+**`type` and `subType` are held to that charset, not merely expected to meet
+it** (#206). A type is the first segment of every address, so a hyphen in one is
+read back as a segment boundary that was never meant as one. A `subType` reaches
+no address since #204 retired sections, but it is held to the same rule all the
+same: it is a vocabulary term the whole toolchain keys on, one closed set away
+from being an address again, and a charset that holds for two of the three
+segments and half of a fourth is a rule nobody can state. Both are checked
+against the same constant a shortcode is checked against, and a note carrying a
+hyphenated value is reported where it wrote it:
+
+```text
+Trauma/Blood_Loss.md:3:1: error: `subType` "blood-loss" is not an address segment — a subType is letters and digits only (^[A-Za-z0-9]+$), 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
+```
+
+One declared value broke the rule and has been renamed: a `doc`'s `user-guide`
+is now **`userguide`**. The old spelling is accepted for one transitional
+release and reported as a **warning** naming the replacement, so a tree that has
+not yet swept still builds:
+
+```text
+User_Guide/Actions.md:3:1: warning: `subType` "user-guide" is a retired spelling of "userguide" on a doc; write "userguide". …
+```
 
 That is a guarantee rather than an observation, and it holds: of **4,456 distinct
 shortcodes** across the four content trees, not one contains a character outside
@@ -267,7 +290,7 @@ was measured before it was retired, and the namespace was empty in practice:
 across 8,305 wikilinks in three content trees, **not one** bare link resolved to
 a note. What the index behind it did do was fold every note's `name.full` into
 itself, so two notes of one type could not share a display name — a rules page
-and a user-guide page both called "Gear" were a build failure whose every
+and a user guide page both called "Gear" were a build failure whose every
 available fix moved a published URL (#179).
 
 The top-level `aliases:` that fed it is **retired** and refused. The nested
@@ -1356,29 +1379,30 @@ subType:
 subType:
 
 - rules: The rules of the game, independent of medium — valid at a table with paper and dice.
-- user-guide: How to operate the Foundry implementation to play by the rules.
+- userguide: How to operate the Foundry implementation to play by the rules.
 - reference: Out-of-world lookup material about the setting or system — correspondences, conversions, glossaries.
-- collection: A note whose content is **derived from the tree** — a roster, a table of
-  settlements, an index of languages, almost always a query. It differs from `reference` in
-  where its content comes from, not in who reads it: a reference **states** facts of its own,
-  and a collection **derives** them. The author's test is whether the page would still say
-  anything if every other note vanished. A collection can therefore collect nothing and still
-  render — an empty table looks exactly like a full one until you read it — which is the
-  failure this value exists to make nameable.
-
-| `data` property | Values   | Description                                                                                               |
-| --------------- | -------- | --------------------------------------------------------------------------------------------------------- |
-| `section`       | `string` | For a `collection` only: the URL segment of the section it heads. Omit it and the note's own slug is used |
-
-**`section` is the segment, not a label.** A collection is a section's landing
-page, so what it names is where that section lives — and two collections may not
-claim the same one. A collection that lists a _subset_ of a section therefore
-names none: five of `sohl-thalorna`'s list places and three list affiliations, and
-each falls back to its own slug rather than fighting over `/place/`.
-
-It is authored rather than derived because the note's own title is presentation:
-a collection called "Creatures" heads the `being` section, and slugging the title
-would put it somewhere else.
+
+A `doc` declares no properties of its own.
+
+**A page that introduces a type is an ordinary note, named by convention.**
+Write `type: doc`, `subType: reference`, `shortcode: <type>` — so the
+affiliations introduction is `doc-affiliation`, addressed and linked like
+anything else, and typically carrying a generated table of what it introduces.
+It has no build path of its own; the package's own front page already works this
+way (`homepage-root`).
+
+There is no landing page and no section. A `README.md` used to _be_ its
+section's landing, and a `subType: collection` note with a top-level `section:`
+key was a second way to say the same thing. All of it is retired — the second
+rule in #202, the first in #204 — because a section appears in **no address**: a
+page publishes at `/<package>/<type>-<shortcode>/`, which names no directory. A
+section is what Hugo calls a content directory, and the note format does not
+carry one.
+
+So a `doc`'s `subType` is a **genre** and nothing else, closed to the three
+values above. It briefly had to accept a content type as well, because a
+landing's `subType` named the section it addressed; with no landings, one field
+has one reading again.
 
 ### type: macro
 

package/engine/base-compiler.mjs

@@ -77,7 +77,11 @@ import {
 } from "./helpers.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
-import { assertNoAliasesField, assertNoDraftField } from "./retired-fields.mjs";
+import {
+    assertNoAliasesField,
+    assertNoDraftField,
+    assertNoSectionField,
+} from "./retired-fields.mjs";
 import { assertTypeNotRetired, packForType } from "./ids.mjs";
 import { carriesSystemBlock } from "./system-block.mjs";
 import { checkAuthoredSystemData, checkEmittedSystemData } from "./schema-check.mjs";
@@ -784,6 +788,7 @@ export class BasePackCompiler {
                 assertNoDeclaredPackage(fm, { absPath });
                 assertNoDraftField(fm, { absPath });
                 assertNoAliasesField(fm, { absPath });
+                assertNoSectionField(fm, { absPath });
             } catch (err) {
                 stats.declined++;
                 this.errorCount++;

package/engine/content-address.mjs

@@ -42,20 +42,6 @@ export { DEFAULT_ADDRESS_SCHEME, LANDING_RULES };
 /** The knowledgebase's mount within this package's site (#1470). */
 export const KB_PREFIX = "kb/";
 
-/**
- * The URL section a note routes to.
- *
- * A `doc` is narrative content whose only identity is its subtype label, so it
- * routes by `subType`; every other type names its own section.
- *
- * @param {object} fm - Parsed frontmatter.
- * @returns {string|undefined} The section, or `undefined` when the note has
- *   none — a `doc` with no subtype has no address and is not published.
- */
-export function sectionOf(fm) {
-    return fm.type === "doc" ? fm.subType : fm.type;
-}
-
 /**
  * The single path segment a note is addressed by: `type-shortcode`.
  *
@@ -95,40 +81,17 @@ export function addressSlug(fm) {
 /**
  * A note's address below the knowledgebase mount, e.g. `affliction-aconite/`.
  *
- * A `README.md` **is** its section's landing page rather than a page within it,
- * so it addresses the section itself and has no address of its own.
+ * Every note, without exception. A `README.md` used to be its section's landing
+ * page and to address the section instead of itself; a section is a Hugo
+ * directory concept the note format no longer carries (#204), so a file's name
+ * decides nothing about where it publishes.
  *
  * @param {object} fm - Parsed frontmatter.
- * @param {boolean} isReadme - Whether the file is a `README.md`.
  * @returns {string} The mount-relative address, with a trailing slash.
  * @throws {Error} When the note has no address.
  */
-export function contentAddress(fm, isReadme) {
-    return isReadme ? `${sectionOf(fm)}/` : `${addressSlug(fm)}/`;
-}
-
-/**
- * Whether a note is a landing page under a scheme, and what it lands at.
- *
- * @param {object} fm - Parsed frontmatter.
- * @param {boolean} isReadme - Whether the file is a `README.md`.
- * @param {string} landing - The landing rule, one of {@link LANDING_RULES}.
- * @returns {{landing: true, segment: string}|{landing: false}|{landing: true, segment: undefined}}
- *   `segment` is the single path segment the note addresses. A `collection`
- *   note that declares no `section` is a landing page with no segment — an
- *   error rather than a page, since it names nowhere to land.
- */
-function landingOf(fm, isReadme, landing) {
-    if (landing === "readme") {
-        return isReadme ? { landing: true, segment: sectionOf(fm) } : { landing: false };
-    }
-    // `collection`. The section is authored rather than derived: it is the
-    // identity of the section being introduced, and the note's own title
-    // ("Creatures") is presentation, which would slug to something else.
-    if (fm.type === "doc" && fm.subType === "collection") {
-        return { landing: true, segment: fm.section || fm.slug };
-    }
-    return { landing: false };
+export function contentAddress(fm) {
+    return `${addressSlug(fm)}/`;
 }
 
 /**
@@ -139,52 +102,40 @@ function landingOf(fm, isReadme, landing) {
  * address the site does not publish resolves at build time and 404s for the
  * reader, which is the failure this module exists to prevent.
  *
+ * **It is a pure function of the frontmatter.** Nothing about the file the note
+ * was read from reaches it: the `README.md` convention that made one note
+ * address a whole section is retired with the section itself (#204), so there
+ * is one rule and no branch.
+ *
  * **The prefix does not apply to a page's own address.** `prefix` says where the
- * content tree *mounts inside the package* — where its section directories and
- * their landing pages live — and a landing page is addressed by that mount
- * (`kb/rules/`). An ordinary page is addressed by `(type, shortcode)`, which is
- * a package-wide identity and takes no mount: `sohl` publishes
- * `/sohl/affliction-aconite/` while its section landings stay at
- * `/sohl/kb/affliction/`. The `type-` half is what keeps that flat namespace
- * clear of the package's fixed mounts — `/<package>/` for the landing,
+ * content tree *mounts inside the package* — the Hugo directory its pages are
+ * written under — and an address is `(type, shortcode)`, a package-wide identity
+ * that takes no mount: `sohl` publishes `/sohl/affliction-aconite/` from a file
+ * written under `kb/`. The `type-` half is what keeps that flat namespace clear
+ * of the package's fixed mounts — `/<package>/` for the landing,
  * `/<package>/api/` for generated API docs, neither of which contains a hyphen
  * or names a type.
  *
- * **The section still decides where the *file* is written**, which is why a
- * note without one still has no address: Hugo derives a section from a page's
- * directory rather than from its URL, so a page with nowhere to be filed is a
- * page with no section landing, no `.CurrentSection` and no per-section layout.
- *
  * @param {object} fm - Parsed frontmatter.
  * @param {object} [options] - Options.
- * @param {boolean} [options.isReadme] - Whether the file is a `README.md`.
  * @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 address — no section, a landing page
- *   naming no section, or no shortcode to be addressed by. Each is a note that
- *   is not published, and inventing an address for one would put a dead entry
- *   in the manifest.
+ * @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, { isReadme = false, scheme } = {}) {
-    const { prefix, landing } = { ...DEFAULT_ADDRESS_SCHEME, ...scheme };
+export function packageAddress(fm, { scheme } = {}) {
+    const { landing } = { ...DEFAULT_ADDRESS_SCHEME, ...scheme };
     if (!LANDING_RULES.includes(landing)) {
         throw new Error(
             `unknown landing rule ${JSON.stringify(landing)} — expected one ` +
                 `of ${LANDING_RULES.join(", ")}`,
         );
     }
-    const land = landingOf(fm, isReadme, landing);
-    if (land.landing) {
-        if (typeof land.segment !== "string" || !land.segment) {
-            throw new Error(`landing note declares no section, so it lands nowhere`);
-        }
-        return `${prefix}${land.segment}/`;
-    }
-    const sec = sectionOf(fm);
-    if (typeof sec !== "string" || !sec) {
-        throw new Error(`type "${fm.type}" has no section`);
-    }
     return `${addressSlug(fm)}/`;
 }