@heroiclands/package-build 22.15.1 → 22.16.0

package/content-config.mjs

@@ -31,8 +31,6 @@
  * packageBuild:
  *     assets:
  *         - { from: assets/icons, to: assets/icons }
- * publish:
- *     site: content
  * ```
  *
  * `defineConfig` is the whole of the contract: it validates the object, fills
@@ -65,6 +63,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 
 // Leaves with no local imports of their own, so naming them here cannot close
@@ -246,59 +245,45 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
     prefix: "",
 });
 
-/**
- * How much of a package reaches the web.
- *
- * Every HeroicLands package publishes something: a top-level, human-authored
- * homepage at `https://www.heroiclands.org/<contentPackage>/` saying what the
- * module is, which system it needs and how to install it. So there is no
- * value here meaning *no web presence at all* — homepage-only is the **floor**,
- * and the default.
- *
- * - `homepage` — the authored homepage, and **no other page**. The content tree
- *   is not walked for pages, and nothing serves a page for its addresses.
- * - `content` — the homepage *plus* every page the content tree publishes, one
- *   per note.
- *
- * **Homepage-only is a first-class mode, not an accommodation.**
- * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
- * Fan Material Guidelines) and `harn-adventures` (HârnFanon under Lythia's
- * terms) must each publish a homepage and nothing beneath it — two packages
- * under two different fan-content licences. The boundary is **published
- * content**: journal text, artwork, item descriptions, compiled notes. A
- * human-authored page announcing the module discloses none of it. Because the
- * failure mode is silent — a `site:` block added later ships licensed content
- * with nobody noticing — the mode fences the content surfaces off rather than
- * trusting a configuration to stay empty.
- *
- * This was a boolean until 5.0.0, and `false` read as "no web presence", which
- * no longer describes any package. Both spellings are refused rather than
- * mapped: a value silently reinterpreted reads to its author as though it still
- * means what it said.
- *
- * @typedef {"homepage" | "content"} SiteMode
- */
-
-/**
- * The publishing modes {@link PublishSwitches.site} may name, floor first.
- *
- * @satisfies {readonly SiteMode[]}
- */
-export const SITE_MODES = /** @type {const} */ (["homepage", "content"]);
-
 /**
  * Whether this package publishes the pages its content tree compiles to.
  *
- * The one question every reader of the mode actually asks — the site build, to
- * decide whether to walk the tree at all, and the content index, to
- * decide whether an entry carries a web `path`. Written once here so the two
- * cannot come to disagree about what a mode means.
+ * Every package publishes an authored homepage. Other authored notes provide
+ * content pages; a tree containing only the homepage publishes only that page.
+ *
+ * Site, PDF, index, and Foundry address emission use the same source-tree
+ * decision. A file without note frontmatter is not a content page.
  *
- * @param {{publish: {site: SiteMode}}} config - A resolved configuration.
+ * @param {{paths: {content: string}, skipDirectories: readonly string[]}} config -
+ *   A resolved configuration with content and skip paths.
  * @returns {boolean} Whether content pages are published.
  */
 export function publishesContentPages(config) {
-    return config.publish.site === "content";
+    const root = config.paths.content;
+    if (!fs.existsSync(root)) return false;
+    const skipped = new Set(config.skipDirectories);
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!skipped.has(entry.name)) stack.push(file);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+            const match = fs
+                .readFileSync(file, "utf8")
+                .match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+            if (!match) continue;
+            try {
+                if (YAML.parse(match[1])?.type !== "homepage") return true;
+            } catch {
+                return true;
+            }
+        }
+    }
+    return false;
 }
 
 /**
@@ -447,8 +432,7 @@ export function publishesContentPages(config) {
 
 /**
  * @typedef {object} PublishSwitches
- * @property {SiteMode} site          How much of this package reaches the web.
- *                                    See {@link SITE_MODES}.
+ * @property {Readonly<{prefix: string}>} address  Where content pages mount within the package.
  */
 
 /**
@@ -539,13 +523,12 @@ export function publishesContentPages(config) {
  *
  * @typedef {object} DocsSpec
  * @property {DocPageSpec} [itemFields]  The item-frontmatter reference,
- *                                       rendered by `content-build docs
+ *                                       rendered by `package-build docs
  *                                       item-fields`.
  */
 
 /**
  * @typedef {object} PublishSwitchesInput
- * @property {SiteMode} [site]
  * @property {AddressSchemeInput} [address]
  */
 
@@ -764,6 +747,7 @@ const DOCS_KEYS = ["itemFields"];
 const CHANGELOG_KEYS = ["labels"];
 const SITE_KEYS = [
     "base",
+    "title",
     "assets",
     "description",
     "packages",
@@ -821,7 +805,7 @@ const STATS_KEYS = ["lastModifiedBy"];
  * @type {symbol}
  */
 export const DERIVED_SYSTEM_VERSION = Symbol.for("package-build.derivedSystemVersion");
-const PUBLISH_KEYS = ["site", "address"];
+const PUBLISH_KEYS = ["address"];
 const ADDRESS_KEYS = ["prefix"];
 
 /** @param {unknown} value */
@@ -906,9 +890,10 @@ function requireNonEmptyString(value, field) {
  *    package's id to *be* its system id, and `sohl-sohl-skill-clmb` is the
  *    honest address that results — which is the reason to prevent the ones that
  *    are avoidable.
- * 3. _Not reserved_. `packagebuild` addresses the files this toolchain ships
- *    itself, so a repository claiming the name would publish addresses that
- *    collide with them — see {@link module:engine/packages}.
+ * 3. _Not reserved for another repository_. `packagebuild` addresses assets
+ *    and documentation this toolchain ships itself. Only this repository's
+ *    documentation build can use that namespace — see
+ *    {@link module:engine/packages}.
  *
  * The type vocabulary rule reaches the **asset** types too: `icon`, `image` and
  * `audio` are types an address names exactly as it names a being, so a package
@@ -919,9 +904,11 @@ function requireNonEmptyString(value, field) {
  *   to a documentation entry: the item types plus `macro` and the map types.
  *   With {@link PACK_BY_TYPE}, {@link NOTE_VOCABULARY} and the `doc`-prefixed
  *   forms, this is the whole type vocabulary an address may write.
+ * @param {{rootDir: string, packageKind: string}} scope - The source claiming
+ *   the namespace; this toolchain owns `packagebuild` for its documentation.
  * @returns {string} The value, unchanged.
  */
-function requireContentPackage(value, docEntryTypes) {
+function requireContentPackage(value, docEntryTypes, { rootDir, packageKind }) {
     const pkg = requireNonEmptyString(value, "contentPackage");
     if (!isAddressSegment(pkg)) {
         fail(
@@ -935,7 +922,12 @@ function requireContentPackage(value, docEntryTypes) {
                 "than merely ugly. `harn-adventures` became `harnadventures`",
         );
     }
-    if (isReservedPackage(pkg)) {
+    // This toolchain's own documentation shares the asset namespace it owns.
+    // Other repositories cannot claim that namespace.
+    const ownDocumentation =
+        packageKind === DOCUMENTATION_KIND &&
+        path.resolve(rootDir) === path.dirname(fileURLToPath(import.meta.url));
+    if (isReservedPackage(pkg) && !ownDocumentation) {
         fail(
             "contentPackage",
             `is \`${pkg}\`, which is a reserved package name. ` +
@@ -1270,7 +1262,7 @@ function normalizeIcons(value, rootDir) {
         if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
             fail(
                 `${where}.icons.${name}`,
-                "is not a name a note can write — `:icon-…:` takes lowercase " +
+                "is not a name a note can write — `:icon …:` takes lowercase " +
                     "letters, digits and hyphens, the charset an address segment uses",
             );
         }
@@ -1567,7 +1559,7 @@ function normalizeSiteDescription(value) {
  */
 export const DERIVED_HUGO_KEYS = Object.freeze({
     baseURL: "package.json `homepage`",
-    title: "`packageBuild.manifest.title`",
+    title: "`site.title` or `packageBuild.manifest.title`",
     locale: "the organisation's locale, in `engine/site-config.mjs`",
     publishDir: "`contentPackage`, under the deployment root `build/site`",
     contentDir: "the fixed content mount, `build/hugo/content`",
@@ -1588,7 +1580,7 @@ export const DERIVED_HUGO_KEYS = Object.freeze({
     "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
     "params.notfound": "`site.notfound`",
     "markup.goldmark.renderer.unsafe": "the toolchain, whose pages carry raw HTML",
-    menu: "the navigation `content-build deps fetch` caches from heroiclands.org",
+    menu: "the navigation `package-build deps fetch` caches from heroiclands.org",
 });
 
 /**
@@ -1706,7 +1698,7 @@ const SITE_INDEX_MESSAGE =
  * Everything here is *framing*: which named pass bundle supplies the
  * repository's own body rewrites, and the residue of the generated Hugo
  * configuration that is genuinely this repository's own. Where the Hugo tree
- * is written is not a choice: `content-build site` writes it under
+ * is written is not a choice: `package-build site` writes it under
  * `build/hugo/`, and a `site.out` is refused by name. How a page gets its
  * **address** is deliberately not here either — that is `publish.address`,
  * shared with the link manifest so the two cannot disagree about where a
@@ -1714,7 +1706,7 @@ const SITE_INDEX_MESSAGE =
  *
  * Two switches sit here, both on by default. `search` is whether
  * `package-build site-root` writes a search index beside the rendered pages.
- * `maps` is whether `content-build site` draws the map from each place that
+ * `maps` is whether `package-build site` draws the map from each place that
  * states a border or a route and writes it into that place's page — a site
  * carries both unless it says otherwise.
  *
@@ -1734,6 +1726,7 @@ const SITE_INDEX_MESSAGE =
 function normalizeSite(value) {
     const empty = Object.freeze({
         base: "",
+        title: "",
         assets: "",
         description: "",
         packages: Object.freeze([]),
@@ -1788,6 +1781,7 @@ function normalizeSite(value) {
 
     return Object.freeze({
         base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
+        title: input.title === undefined ? "" : requireNonEmptyString(input.title, "site.title"),
         assets: normalizeSiteAssets(input.assets),
         description: normalizeSiteDescription(input.description),
         packages: Object.freeze(packages),
@@ -1818,10 +1812,8 @@ function normalizeSite(value) {
  * choose, which is the whole reason they are configuration: the engine that
  * sets the book must be able to set somebody else's book.
  *
- * **Declaring the block is not the switch.** Whether a PDF is built at all is
- * `publish.site` — `content` builds one, `homepage` does not — so a package
- * cannot end up with two switches that disagree about whether it publishes its
- * content tree. See {@link publishesContentPages}.
+ * A PDF is built when the authored tree contains content pages and the `pdf`
+ * block names a document tree. See {@link publishesContentPages}.
  *
  * @param {unknown} value - The `pdf` block, or `undefined`.
  * @param {string} rootDir - The repository root configured paths resolve against.
@@ -1874,7 +1866,7 @@ function normalizePdf(value, rootDir) {
         });
     }
 
-    // Family name to the font file carrying its glyphs, for `:icon-…:`. A file
+    // Family name to the font file carrying its glyphs, for `:icon …:`. A file
     // rather than a codepoint, because the font's own tables are the only
     // trustworthy source of which glyph a name resolves to — see
     // {@link module:engine/content-icons}, which states the style and the name
@@ -2103,8 +2095,8 @@ function normalizeRelationships(value) {
                 };
                 // What the other package's *content* is called, where that
                 // differs from its Foundry id. A note addresses a file by the
-                // content package that owns it — `thalorna/assets/…` — and the
-                // Foundry id (`sohl-thalorna`) appears only in the install
+                // content package that owns it — `harnensemble/assets/…` — and the
+                // Foundry id (`harn-ensemble`) appears only in the install
                 // path this derives. Omitted where the two are the same word,
                 // which they are for every system.
                 if (rel.contentPackage !== undefined) {
@@ -2397,43 +2389,6 @@ function normalizeItemBuilders(value) {
     };
 }
 
-/**
- * The publishing mode, refusing a boolean.
- *
- * A boolean is refused rather than mapped onto the nearest mode, because the
- * reading `false` invited — *this package has no web presence* — is exactly the
- * belief the change exists to correct, and a value quietly reinterpreted reads
- * to its author as though it still means what it said. So the message names the
- * mode to write instead of the value to fix.
- *
- * @param {unknown} value - The authored `publish.site`.
- * @returns {SiteMode} The mode.
- */
-function normalizeSiteMode(value) {
-    if (value === undefined) return "homepage";
-    if (typeof value === "boolean") {
-        fail(
-            "publish.site",
-            `is no longer a boolean — write \`site: ${value ? "content" : "homepage"}\`. ` +
-                `Every package publishes an authored homepage at ` +
-                `/<contentPackage>/, so no value means "no web presence": ` +
-                `\`homepage\` publishes that page and nothing else, and ` +
-                `\`content\` publishes it plus every page the content tree ` +
-                `compiles to`,
-        );
-    }
-    if (
-        typeof value !== "string" ||
-        !(/** @type {readonly string[]} */ (SITE_MODES).includes(value))
-    ) {
-        fail(
-            "publish.site",
-            `must be one of ${SITE_MODES.join(", ")} (got ${JSON.stringify(value)})`,
-        );
-    }
-    return /** @type {SiteMode} */ (value);
-}
-
 /**
  * @param {unknown} value
  * @returns {Readonly<PublishSwitches>}
@@ -2441,12 +2396,14 @@ function normalizeSiteMode(value) {
 function normalizePublish(value) {
     if (value === undefined) {
         return Object.freeze({
-            site: "homepage",
             address: Object.freeze({ ...DEFAULT_ADDRESS_SCHEME }),
         });
     }
     if (!isPlainObject(value)) fail("publish", "must be an object");
     const publish = /** @type {Record<string, unknown>} */ (value);
+    if (Object.hasOwn(publish, "site")) {
+        fail("publish.site", "is not configured; publishing follows the authored content tree");
+    }
     rejectUnknownKeys(publish, PUBLISH_KEYS, "publish.");
 
     const addressInput = publish.address;
@@ -2482,7 +2439,6 @@ function normalizePublish(value) {
     }
 
     return Object.freeze({
-        site: normalizeSiteMode(publish.site),
         address: Object.freeze({ prefix }),
     });
 }
@@ -2534,28 +2490,6 @@ export function defineConfig(config) {
             if (input[key] === undefined) continue;
             fail(key, `is refused in a \`${DOCUMENTATION_KIND}\` package, which ${why}`);
         }
-        // Publishing is what a documentation package is *for*, so the floor
-        // every other package may sit at is not available to it: `homepage`
-        // would leave a package that publishes one authored page, builds no
-        // book, and compiles nothing at all.
-        if (!isPlainObject(input.publish)) {
-            fail(
-                "publish",
-                `is required in a \`${DOCUMENTATION_KIND}\` package: publishing ` +
-                    "the content tree is the whole of what it does. Write " +
-                    "`publish: {site: content}`",
-            );
-        }
-        const mode = /** @type {Record<string, unknown>} */ (input.publish).site;
-        if (mode !== "content") {
-            fail(
-                "publish.site",
-                `must be \`content\` in a \`${DOCUMENTATION_KIND}\` package — ` +
-                    "`homepage` fences the content surfaces off, and a package " +
-                    "that compiles nothing and publishes nothing from its tree " +
-                    "would produce a single authored page and no book",
-            );
-        }
     }
 
     // A Foundry package need not compile anything. A module may ship assets and
@@ -2718,10 +2652,16 @@ export function defineConfig(config) {
     const docEntryTypes = Object.freeze(
         new Set([...itemTypes, ...ACTOR_TYPES, "macro", ...MAP_TYPES]),
     );
+    const compatibility = normalizeCompatibility(input.compatibility, "compatibility");
+    if (!documentation && compatibility === null)
+        fail("compatibility.minimum", "is required for a Foundry package");
 
     return Object.freeze({
         rootDir,
-        contentPackage: requireContentPackage(input.contentPackage, docEntryTypes),
+        contentPackage: requireContentPackage(input.contentPackage, docEntryTypes, {
+            rootDir,
+            packageKind,
+        }),
         foundryPackage,
         // `package.json`'s own address and byline. `homepage` is checked by
         // `checkHomepage` in `config.mjs`.
@@ -2730,7 +2670,7 @@ export function defineConfig(config) {
         author: normalizeAuthor(input.author),
         packageKind: /** @type {PackageKind} */ (packageKind),
         // Foundry serves a package's files from `<kind>/<id>/`, so this is the
-        // one place `systems/sohl` (or `modules/sohl-thalorna`) is spelled.
+        // one place `systems/sohl` (or `modules/harn-ensemble`) is spelled.
         //
         // **Conditional on the kind.** `documentation` names no directory
         // Foundry serves, and there is no package id to put under one either, so
@@ -2797,7 +2737,7 @@ export function defineConfig(config) {
         docs: normalizeDocs(input.docs),
         site: normalizeSite(input.site),
         pdf: normalizePdf(input.pdf, rootDir),
-        compatibility: normalizeCompatibility(input.compatibility, "compatibility"),
+        compatibility,
         relationships: normalizeRelationships(input.relationships),
         systems,
         requiresSystem,