@heroiclands/package-build 22.15.0 → 22.16.0

package/engine/note-vocabulary.mjs

@@ -97,10 +97,18 @@ import {
 // question, asked the way `checkPlace` and `checkCalendarNote` are.
 import { checkBeingAge } from "./being-age.mjs";
 import { checkSocialTies } from "./social-ties.mjs";
+import { checkDatedOffices } from "./office-holders.mjs";
+import { checkCalendarChoice } from "./calendar-choice.mjs";
+import { checkCultureChoice } from "./culture-choice.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { checkHeld } from "./holdings.mjs";
+import {
+    checkBeingMeasurement,
+    parseBeingHeight,
+    parseBeingWeight,
+} from "./being-measurements.mjs";
 import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 // What trade a settlement supports — the scale and the check that holds a
 // value to it, read rather than restated, so the reference below and the
@@ -435,6 +443,9 @@ function checkPlacePurpose(note) {
  */
 export const DRAFT_TAG = "draft";
 
+/** A note intended for the GM rather than the player-facing outputs. */
+export const GM_TAG = "gm";
+
 /**
  * The tags that **classify** a note, grouped by what they classify.
  *
@@ -571,6 +582,8 @@ export const DECLARED_TAGS = Object.freeze({
     }),
     /** A note's working state, which any note may carry. */
     state: Object.freeze({ types: null, tags: Object.freeze([DRAFT_TAG]) }),
+    /** Who may read a completed note. */
+    audience: Object.freeze({ types: null, tags: Object.freeze([GM_TAG]) }),
 });
 
 /**
@@ -657,6 +670,11 @@ export function isDraftNote(fm) {
     return hasTag(fm, DRAFT_TAG);
 }
 
+/** Whether a note is restricted to GM-facing output. */
+export function isGmNote(fm) {
+    return hasTag(fm, GM_TAG);
+}
+
 /**
  * Every note type this toolchain compiles, and the closed vocabulary it
  * declares.
@@ -700,8 +718,15 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ref: "lore",
                 accepts: ["lore"],
                 describe:
-                    "Lore concerning this being — the people it is of, the standing it " +
-                    "holds, the law it lives under.",
+                    "Lore concerning this being, such as the standing it holds or the law it lives under.",
+            },
+            {
+                name: "culture",
+                ...LINK,
+                ref: "lore",
+                accepts: ["lore"],
+                check: checkCultureChoice,
+                describe: "The being's primary culture, as a culture lore note.",
             },
             {
                 name: "homes",
@@ -743,6 +768,14 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "When the being was born — a date, or `unknown` where the birth is " +
                     "unrecorded. Absent, the being was never born.",
             },
+            {
+                name: "calendar",
+                ...LINK,
+                ref: "lore",
+                accepts: ["lore"],
+                check: checkCalendarChoice,
+                describe: "Calendar used to display this being's dates.",
+            },
             {
                 name: "died",
                 ...TEXT,
@@ -770,8 +803,20 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "Written by the compiler beside an `age` estimate — the `~` stripped, " +
                     "the magnitude alone. A note never authors this.",
             },
-            { name: "height", ...NUM, describe: "Height in metres." },
-            { name: "weight", ...NUM, describe: "Weight in kilograms." },
+            {
+                name: "height",
+                shape: "metres or feet and inches",
+                kind: "string",
+                check: (note) => checkBeingMeasurement(note, "height", parseBeingHeight),
+                describe: "Height in metres or feet and inches.",
+            },
+            {
+                name: "weight",
+                shape: "kilograms or pounds",
+                kind: "string",
+                check: (note) => checkBeingMeasurement(note, "weight", parseBeingWeight),
+                describe: "Body weight in kilograms or pounds.",
+            },
             {
                 name: "frame",
                 ...TEXT,
@@ -849,7 +894,8 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "governance.offices",
                 ...ANY,
-                describe: "The named offices it appoints, each with what the office does.",
+                check: checkDatedOffices,
+                describe: "Named offices, each with a description and optional dated holders.",
             },
             {
                 name: "seat",
@@ -1241,20 +1287,21 @@ export const NOTE_VOCABULARY = Object.freeze({
     lore: Object.freeze({
         stubbable: true,
         subTypes: Object.freeze([
-            "cosmology",
-            "deity",
-            "theology",
-            "arcana",
-            "spirit",
-            "economy",
-            "law",
-            "calendar",
-            "history",
-            "material",
-            "folk",
-            "culture",
-            "bestiary",
-            "gathering",
+            "cosmology", // The structure and origin of reality.
+            "deity", // An individual god and its attributed nature.
+            "theology", // Beliefs about divinity, worship, and the afterlife.
+            "arcana", // Beliefs and traditions concerning magic.
+            "spirit", // Non-divine supernatural beings and their natures.
+            "economy", // Trade, money, and the movement of wealth.
+            "law", // Obligations, rights, courts, and tenure.
+            "calendar", // The reckoning and marking of time.
+            "history", // Events, eras, and chronicles of the past.
+            "material", // Physical constituents and their qualities, including regional varieties.
+            "folk", // A kindred or ancestry of related sapient beings.
+            "culture", // A people sharing beliefs, mores, and values.
+            "custom", // How a people practices a rite, observance, or usage.
+            "bestiary", // A kind of creature that is not a people.
+            "gathering", // A recurring public assembly, such as a fair or tournament.
         ]),
         // A lore note is prose, and what it *is* about is its subType — with
         // one exception. A calendar is a division of the year, and a division
@@ -1286,6 +1333,14 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
         check: checkPlace,
         data: Object.freeze([
+            {
+                name: "calendar",
+                ...LINK,
+                ref: "lore",
+                accepts: ["lore"],
+                check: checkCalendarChoice,
+                describe: "Calendar used to display this place's dates.",
+            },
             {
                 name: "demonym",
                 ...TEXT,

package/engine/number-words.mjs

@@ -0,0 +1,75 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+/** English cardinal words for finite whole numbers. */
+const ONES = [
+    "zero",
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+    "eleven",
+    "twelve",
+    "thirteen",
+    "fourteen",
+    "fifteen",
+    "sixteen",
+    "seventeen",
+    "eighteen",
+    "nineteen",
+];
+const TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"];
+const SCALES = ["", "thousand", "million", "billion", "trillion", "quadrillion", "quintillion"];
+
+function underThousand(value) {
+    const parts = [];
+    const hundreds = Math.floor(value / 100);
+    if (hundreds) parts.push(`${ONES[hundreds]} hundred`);
+    const rest = value % 100;
+    if (rest >= 20) {
+        const ten = TENS[Math.floor(rest / 10)];
+        parts.push(rest % 10 ? `${ten}-${ONES[rest % 10]}` : ten);
+    } else if (rest) parts.push(ONES[rest]);
+    return parts.join(" ");
+}
+
+/** Spell a SQL integer in running prose, using American cardinal style. */
+export function numberWords(value) {
+    if (typeof value !== "bigint" && (typeof value !== "number" || !Number.isSafeInteger(value))) {
+        throw new TypeError("words needs a whole number; use digits for decimals");
+    }
+    let remaining = BigInt(value);
+    if (remaining === 0n) return "zero";
+    const negative = remaining < 0n;
+    if (negative) remaining = -remaining;
+    const parts = [];
+    let scale = 0;
+    while (remaining > 0n) {
+        if (scale >= SCALES.length) throw new RangeError("words cannot spell a number this large");
+        const group = Number(remaining % 1000n);
+        if (group)
+            parts.unshift(`${underThousand(group)}${SCALES[scale] ? ` ${SCALES[scale]}` : ""}`);
+        remaining /= 1000n;
+        scale++;
+    }
+    return `${negative ? "minus " : ""}${parts.join(" ")}`;
+}
+
+/** Render a SQL number with grouped thousands and its fractional part. */
+export function numberDigits(value) {
+    if (typeof value === "bigint") return value.toLocaleString("en-US");
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new TypeError("digits needs a finite number");
+    }
+    if (/[eE]/.test(String(value))) {
+        return new Intl.NumberFormat("en-US", { maximumFractionDigits: 20 }).format(value);
+    }
+    const [whole, fraction] = String(value).split(".");
+    const grouped = BigInt(whole).toLocaleString("en-US");
+    return fraction === undefined ? grouped : `${grouped}.${fraction}`;
+}

package/engine/office-holders.mjs

@@ -0,0 +1,188 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { parseAddress, renderAddress } from "./address.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { parseNoteDate } from "./note-dates.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
+
+const OFFICE_KEYS = new Set(["description", "holders"]);
+const HOLDER_KEYS = new Set(["being", "start", "end", "contested"]);
+const mapping = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * Validate one affiliation's office roster against dated beings in the corpus.
+ * @param {object} note
+ * @param {{index?: object}} [options]
+ */
+export function checkDatedOffices(note, { index } = {}) {
+    const offices = note.fm?.data?.governance?.offices;
+    if (offices === undefined || offices === null) return [];
+    const findings = [];
+    const at = (path, message) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(note.raw ?? "", path),
+        severity: "error",
+        message,
+    });
+    if (!mapping(offices))
+        return [
+            at(
+                ["data", "governance", "offices"],
+                "data.governance.offices must be a map of named offices",
+            ),
+        ];
+
+    const dates = reckoningContext(index);
+    for (const [office, value] of Object.entries(offices)) {
+        const base = ["data", "governance", "offices", office];
+        if (typeof value === "string") continue;
+        if (!mapping(value)) {
+            findings.push(
+                at(base, `office ${office} must be a description or a {description, holders} map`),
+            );
+            continue;
+        }
+        for (const key of Object.keys(value))
+            if (!OFFICE_KEYS.has(key))
+                findings.push(
+                    at(
+                        [...base, key],
+                        `office ${office} has unknown key ${key}; use description or holders`,
+                    ),
+                );
+        if (typeof value.description !== "string")
+            findings.push(
+                at([...base, "description"], `office ${office} needs a string description`),
+            );
+        if (!Array.isArray(value.holders)) {
+            findings.push(at([...base, "holders"], `office ${office} needs a holders list`));
+            continue;
+        }
+        const terms = [];
+        value.holders.forEach((row, position) => {
+            const rowPath = [...base, "holders", position];
+            if (!mapping(row)) {
+                findings.push(at(rowPath, `office ${office} holder must be a map`));
+                return;
+            }
+            for (const key of Object.keys(row))
+                if (!HOLDER_KEYS.has(key))
+                    findings.push(
+                        at([...rowPath, key], `office ${office} holder has unknown key ${key}`),
+                    );
+            if (row.contested !== undefined && typeof row.contested !== "boolean")
+                findings.push(
+                    at(
+                        [...rowPath, "contested"],
+                        `office ${office} contested must be true or false`,
+                    ),
+                );
+
+            if (typeof row.being !== "string" || !row.being.trim()) {
+                findings.push(
+                    at([...rowPath, "being"], `office ${office} holder needs a being Address`),
+                );
+            } else {
+                const tuple = parseAddress(row.being, {
+                    package: index?.contentPackage,
+                    system: "note",
+                    type: "being",
+                    types: index?.types,
+                    packages: index?.packages,
+                });
+                if (tuple.reason || tuple.type !== "being") {
+                    findings.push(
+                        at(
+                            [...rowPath, "being"],
+                            `office ${office} holder ${row.being} must name a being Address`,
+                        ),
+                    );
+                } else if (index?.addressHit) {
+                    const target = index.addressHit(renderAddress(tuple));
+                    if (!target)
+                        findings.push(
+                            at(
+                                [...rowPath, "being"],
+                                `office ${office} holder ${row.being} does not resolve`,
+                            ),
+                        );
+                    else if ((target.fm ?? target).data?.died != null && row.end == null)
+                        findings.push(
+                            at(
+                                [...rowPath, "being"],
+                                `office ${office} claims a current holder ${row.being} whose died value is present`,
+                            ),
+                        );
+                }
+            }
+
+            const bounds = {};
+            let invalidDate = false;
+            for (const key of ["start", "end"]) {
+                if (row[key] === undefined || row[key] === null) continue;
+                const parsed = parseNoteDate(row[key], {
+                    ...dates,
+                    allowUnknown: false,
+                    field: `data.governance.offices.${office}.holders.${key}`,
+                    file: note.file,
+                    raw: note.raw,
+                    keyPath: [...rowPath, key],
+                });
+                findings.push(...parsed.findings);
+                if (
+                    parsed.date &&
+                    parsed.date.month !== null &&
+                    parsed.date.canonicalDay === undefined
+                ) {
+                    findings.push(
+                        at(
+                            [...rowPath, key],
+                            `office ${office} holder ${key} needs a marker or canonical day to order it`,
+                        ),
+                    );
+                    invalidDate = true;
+                } else if (parsed.date && Number.isFinite(parsed.date.sort))
+                    bounds[key] =
+                        parsed.date.sort +
+                        (key === "end" ?
+                            ((parsed.date.spanDays ?? 1) - 1) / (dates.daysPerYear ?? 365)
+                        :   0);
+                else {
+                    if (parsed.date)
+                        findings.push(
+                            at(
+                                [...rowPath, key],
+                                `office ${office} holder ${key} needs a resolved date`,
+                            ),
+                        );
+                    invalidDate = true;
+                }
+            }
+            if (bounds.start !== undefined && bounds.end !== undefined && bounds.end < bounds.start)
+                findings.push(
+                    at([...rowPath, "end"], `office ${office} holder ends before its start`),
+                );
+            if (!invalidDate)
+                terms.push({
+                    start: bounds.start ?? -Infinity,
+                    end: bounds.end ?? Infinity,
+                    contested: row.contested === true,
+                    rowPath,
+                });
+        });
+        for (let i = 0; i < terms.length; i++)
+            for (let j = i + 1; j < terms.length; j++)
+                if (
+                    !terms[i].contested &&
+                    !terms[j].contested &&
+                    terms[i].start <= terms[j].end &&
+                    terms[j].start <= terms[i].end
+                )
+                    findings.push(
+                        at(terms[j].rowPath, `office ${office} has overlapping holder terms`),
+                    );
+    }
+    return findings;
+}

package/engine/pack-config.mjs

@@ -123,7 +123,7 @@ export const CONFIG_BASENAME = "package-build.config";
  * the order the names are *reported* in, which is the order a reader should
  * reach for them: YAML first, `.mjs` last.
  *
- * The `content-build.config.*` stem this package read before the two toolchains
+ * The `package-build.config.*` stem this package read before the two toolchains
  * merged is **not** resolved. 3.0.0 renames the file rather than accepting both:
  * a deprecation window here would mean a repository could sit indefinitely on a
  * name for a package that no longer exists, and the upgrade already requires
@@ -570,22 +570,9 @@ export function configFromData(data, configPath) {
             );
         }
     }
-    const { manifestPath, pkg } = readPackageJson(rootDir);
+    const { pkg } = readPackageJson(rootDir);
     if (pkg.homepage !== undefined) input.homepage = pkg.homepage;
     if (pkg.author !== undefined) input.author = pkg.author;
-    // `description` is npm metadata nothing displays for a private package —
-    // read by neither the manifest nor the site, so a declared one is a
-    // warning rather than a silent no-op that looks like it did something.
-    if (pkg.description !== undefined) {
-        emitDiagnostic({
-            file: manifestPath,
-            severity: "warning",
-            message:
-                "`description` is read by nothing; the Foundry pitch is " +
-                "`packageBuild.manifest.descriptionHtml` and the site's is " +
-                "`site.description`",
-        });
-    }
 
     if (input.itemBuilders !== undefined) {
         const declared = input.itemBuilders;

package/engine/pack-router.mjs

@@ -44,9 +44,9 @@
  *   another document type, or a companion pack, which no note may address —
  *   fails the build, naming the note and what it asked for. A silent fall-back
  *   to the default would publish an address into the wrong compendium.
- * - A note's **derived** documents are routed by the default of *their* type,
- *   not by the note's declaration: an item note's prose compiles into a
- *   JournalEntry, and `pack:` names where the *item* goes.
+ * - A note's **derived** documents use the default of their type. GM-only
+ *   prose uses a private pack of that type. An item's `pack:` names where the
+ *   item goes, not its prose JournalEntry.
  * - A note feeding **more than one system** declares `pack:` inside the block
  *   that differs. `pack` needed no new mechanism for that: it is an
  *   ordinary shared property, so `<system>.pack` overrides the top-level one
@@ -83,6 +83,7 @@
 import { NO_PACK, packForType } from "./ids.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { blockDataProperty, systemBlock } from "./system-block.mjs";
+import { isGmNote } from "./note-vocabulary.mjs";
 
 /**
  * A note that cannot be routed to a pack. Thrown rather than returned so no
@@ -236,7 +237,7 @@ export function createPackRouter(packs) {
      * asking, only a pack of that system answers, or one that declares no
      * system at all and so belongs to all of them. The type-wide default is
      * otherwise free to be a neighbour's — `actors-sohl` is what
-     * `CONTENT.md`'s two-system layout marks `default: true` — and returning it
+     * the package's two-system layout marks `default: true` — and returning it
      * to the HM3 pass would either route an HM3 document into the SoHL pack or,
      * as it actually did, have the HM3 pass see a pack name that is not its own
      * and skip every note in the tree. The second is worse: it is silent, and
@@ -364,7 +365,20 @@ export function createPackRouter(packs) {
             return declared;
         }
 
-        const fallback = defaultFor(docType, system);
+        let fallback = defaultFor(docType, system);
+        if (isGmNote(fm) && docType !== ownDocType) {
+            const privatePacks = (byType.get(docType) ?? []).filter(
+                (name) => byName.get(name)?.private === true && !byName.get(name)?.system,
+            );
+            if (!fallback || !byName.get(fallback)?.private) {
+                fallback = privatePacks.length === 1 ? privatePacks[0] : undefined;
+            }
+            if (!fallback) {
+                throw new PackRoutingError(
+                    `${noteLabel(fm)} needs one private ${docType} pack for its GM-only prose.`,
+                );
+            }
+        }
         if (!fallback) {
             const candidates =
                 system === undefined ?
@@ -466,6 +480,11 @@ export function createPackRouter(packs) {
             return byName.get(name)?.system || undefined;
         },
 
+        /** Whether Foundry restricts this pack to GMs. */
+        privateOf(name) {
+            return byName.get(name)?.private === true;
+        },
+
         /**
          * The pack of a type that receives notes declaring none.
          *

package/engine/packages.mjs

@@ -25,8 +25,9 @@
  * with, which is the whole point: the alternative is every package depending on
  * one of the others just to borrow a banner.
  *
- * So nothing may create a real package that collides with the name, and its
- * resolution is special-cased, because no installed directory sits behind it.
+ * Only this toolchain's own documentation package may share the name. Other
+ * repositories cannot claim it, and asset resolution is special-cased because
+ * no installed Foundry directory sits behind it.
  *
  * This module is a **leaf with no local imports**, so the configuration
  * validator can name it without closing a cycle around `content-config.mjs`.

package/engine/pathnames.mjs

@@ -36,22 +36,21 @@
  * being built, and the whole of it is the suffix. That is the ordinary case and
  * the one nearly every note writes.
  *
- * The four forms, for a `thalorna` note writing `images/map.webp` (`thalorna`
- * ships as the Foundry module `sohl-thalorna`):
+ * The four forms, for a `harnensemble` note writing `images/map.webp`
+ * (`harnensemble` ships as the Foundry module `harn-ensemble`):
  *
- * | Form      | Address                                            |
- * | --------- | -------------------------------------------------- |
- * | `foundry` | `modules/sohl-thalorna/assets/images/map.webp`      |
- * | `local`   | `assets/images/map.webp`                            |
- * | `web`     | `https://cdn.heroiclands.org/thalorna/images/map.webp` |
- * | `pdf`     | `assets/images/map.webp`                            |
+ * | Form      | Address                                                       |
+ * | --------- | ------------------------------------------------------------- |
+ * | `foundry` | `modules/harn-ensemble/assets/images/map.webp`               |
+ * | `local`   | `assets/images/map.webp`                                      |
+ * | `web`     | `https://cdn.heroiclands.org/harnensemble/images/map.webp`   |
+ * | `pdf`     | `assets/images/map.webp`                                      |
  *
  * **`<package>` and `<foundry-id>` are two different names.** The package is
- * `thalorna` — what the content is called, what the website serves it under,
- * and what a note writes. The Foundry id is `sohl-thalorna` — what Foundry
- * installs the module as, and the only place that name appears. They coincide
- * for `sohl` and `hm3`, which is exactly why the two are kept apart here rather
- * than treated as one value.
+ * `harnensemble` — what the content is called, what the website serves it under,
+ * and what a note writes. The Foundry id is `harn-ensemble` — what Foundry
+ * installs the module as. The values coincide for `thalorna`, `sohl`, and
+ * `hm3`, but pathname resolution uses each in its own surface.
  *
  * `local` and `pdf` read the same and mean different places: `local` is the file
  * in the owning repository's working tree, `pdf` is where the book stages a copy
@@ -338,16 +337,14 @@ function declaredSystemIds(config) {
 export function packageAddresses(config) {
     /** @type {Map<string, {root: string|null, id: string|null, own: boolean}>} */
     const out = new Map();
-    if (config.contentPackage) {
-        out.set(config.contentPackage, {
-            // `assetRoot` is `<root>/<id>/assets`, and `null` for a
-            // `documentation` package — which is the same "Foundry serves no
-            // files for this" the `root` below says.
-            root: config.assetRoot ? config.packageKind : null,
-            id: config.foundryPackage ?? null,
-            own: true,
-        });
-    }
+    out.set(config.contentPackage, {
+        // `assetRoot` is `<root>/<id>/assets`, and `null` for a
+        // `documentation` package — which is the same "Foundry serves no
+        // files for this" the `root` below says.
+        root: config.assetRoot ? config.packageKind : null,
+        id: config.foundryPackage ?? null,
+        own: true,
+    });
     // The package being built wins every collision: it is the one whose files
     // this repository actually holds, and another declaration of the same name
     // describes that very package from outside.
@@ -420,7 +417,7 @@ export function resolvePathname(raw, config) {
     // reading it as this package's own would put one package's name inside
     // another's tree and report nothing.
     const named = segments.length > 2 && segments[1] === ASSETS_SEGMENT ? segments[0] : "";
-    const owner = named || (config.contentPackage ?? null);
+    const owner = named || config.contentPackage;
     const suffix = named ? segments.slice(2).join("/") : authored;
     const entry = owner ? packages.get(owner) : undefined;
     const host = String(config.site?.assets ?? "").replace(/\/+$/, "");