@heroiclands/package-build 22.15.0 → 22.16.0

package/engine/culture-choice.mjs

@@ -0,0 +1,32 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/**
+ * Require a being's primary culture to address a culture lore note.
+ * @param {object} note
+ * @param {{index?: object}} [options]
+ */
+export function checkCultureChoice(note, { index } = {}) {
+    const value = note.fm?.data?.culture;
+    if (value === undefined || value === null || !index?.addressHit) return [];
+    const tuple = parseAddress(value, {
+        package: index.contentPackage,
+        system: "note",
+        type: "lore",
+        types: index.types,
+        packages: index.packages,
+    });
+    if (tuple.reason || tuple.type !== "lore") return [];
+    const target = index.addressHit(renderAddress(tuple));
+    if (!target || (target.fm ?? target).subType === "culture") return [];
+    return [
+        {
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", ["data", "culture"]),
+            severity: "error",
+            message: `data.culture ${isAddressTuple(value) ? renderAddress(value) : value} names lore whose subType is not culture`,
+        },
+    ];
+}

package/engine/date-conversion.mjs

@@ -0,0 +1,47 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+import { formatCanonicalDate, parseCanonicalDate } from "./calendars.mjs";
+import { addressedCalendarDate } from "./calendar-human.mjs";
+import { calendarEras, eraCovering, formatNoteDate, parseNoteDate } from "./note-dates.mjs";
+
+/** Convert a day in an addressed calendar to its canonical spelling. */
+export function dateFromCalendar(reference, value, context) {
+    const eras = calendarEras(reference, context);
+    const text = String(value ?? "").trim();
+    const approximate = text.startsWith("~");
+    const named = addressedCalendarDate(approximate ? text.slice(1).trim() : text, eras);
+    if (!named) throw new RangeError("datefrom needs a named calendar date precise to the day");
+    const authored = `${approximate ? "~" : ""}${named}`;
+    const parsed = parseNoteDate(authored, { ...context, allowUnknown: false });
+    const error = parsed.findings.find((finding) => finding.severity === "error");
+    if (error) throw new RangeError(error.message);
+    const date = parsed.date;
+    if (!date || date.precision !== "day" || !Number.isSafeInteger(date.canonicalDay))
+        throw new RangeError("datefrom needs a calendar date precise to the day");
+    if (!eras.includes(context.eras.get(date.qualifier)))
+        throw new RangeError(`date belongs to a different calendar than ${reference}`);
+    if (eraCovering(date, eras, context.daysPerYear) !== context.eras.get(date.qualifier))
+        throw new RangeError(`date falls outside calendar ${reference}`);
+    return `${date.approximate ? "~" : ""}${formatCanonicalDate(
+        { year: date.canonicalYear, day: date.canonicalDay, seconds: date.seconds },
+        context.daysPerYear,
+    )}`;
+}
+
+/** Convert a canonical day to the date in the covering era of a calendar. */
+export function dateToCalendar(reference, value, context) {
+    const text = String(value ?? "");
+    const canonical = parseCanonicalDate(
+        text.startsWith("~") ? text.slice(1) : text,
+        context?.daysPerYear,
+    );
+    if (!canonical)
+        throw new RangeError("dateto needs <year>.<day>[:HHMMSS] within the world's year");
+    const parsed = parseNoteDate(value, context).date;
+    const era = eraCovering(parsed, calendarEras(reference, context), context.daysPerYear);
+    if (!era) throw new RangeError(`canonical date falls outside calendar ${reference}`);
+    const printed = formatNoteDate(parsed, era, context.daysPerYear);
+    if (!printed || printed.day === null)
+        throw new RangeError(`canonical date cannot be expressed in calendar ${reference}`);
+    return printed.text;
+}

package/engine/declaration-check.mjs

@@ -0,0 +1,87 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { globSync } from "glob";
+import ts from "typescript";
+
+/** All declaration entry points advertised by a package's exports map. */
+export function exportedDeclarationFiles(root) {
+    const manifest = path.join(root, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(manifest, "utf8"));
+    const files = new Set();
+    const findings = [];
+    for (const entry of Object.values(pkg.exports ?? {})) {
+        const declared = typeof entry === "object" && entry !== null ? entry.types : null;
+        if (typeof declared !== "string") continue;
+        const pattern = path.resolve(root, declared);
+        const matches = pattern.includes("*") ? globSync(pattern) : [pattern];
+        if (!matches.length || matches.some((file) => !fs.existsSync(file))) {
+            findings.push({
+                file: manifest,
+                severity: "error",
+                message: `exported declaration ${declared} does not exist`,
+            });
+        }
+        for (const file of matches) {
+            if (fs.existsSync(file)) files.add(file);
+        }
+    }
+    return { files: [...files].sort(), findings };
+}
+
+/**
+ * Type-check project declarations with library checking enabled.
+ * @param {string} project - TypeScript project file.
+ * @param {{exports?: boolean}} [options]
+ * @returns {Array<{file: string, line?: number, column?: number, severity: "error", message: string}>}
+ */
+export function checkDeclarations(project, options = {}) {
+    const requestedProject = path.resolve(project);
+    const configFile =
+        fs.existsSync(requestedProject) ? fs.realpathSync(requestedProject) : requestedProject;
+    const root = path.dirname(configFile);
+    const findings = [];
+    const report = (diagnostic) => {
+        if (diagnostic.file?.fileName.split(path.sep).includes("node_modules")) return;
+        const position =
+            diagnostic.file && diagnostic.start !== undefined ?
+                diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start)
+            :   null;
+        findings.push({
+            file: diagnostic.file?.fileName ?? configFile,
+            ...(position ? { line: position.line + 1, column: position.character + 1 } : {}),
+            severity: "error",
+            message: `TS${diagnostic.code}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, " ")}`,
+        });
+    };
+    const source = ts.readConfigFile(configFile, ts.sys.readFile);
+    if (source.error) {
+        report(source.error);
+        return findings;
+    }
+    const parsed = ts.parseJsonConfigFileContent(
+        source.config,
+        ts.sys,
+        root,
+        {
+            skipLibCheck: false,
+            noEmit: true,
+        },
+        configFile,
+    );
+    for (const diagnostic of parsed.errors) {
+        if (!(options.exports && diagnostic.code === 18003)) report(diagnostic);
+    }
+    const roots = new Set(parsed.fileNames);
+    if (options.exports) {
+        const exported = exportedDeclarationFiles(root);
+        findings.push(...exported.findings);
+        for (const file of exported.files) roots.add(file);
+    }
+    const program = ts.createProgram([...roots], parsed.options);
+    for (const diagnostic of ts.getPreEmitDiagnostics(program)) report(diagnostic);
+    return findings;
+}

package/engine/docs-checks.mjs

@@ -0,0 +1,140 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** @param {string} root */
+function* markdownFiles(root) {
+    for (const entry of fs
+        .readdirSync(root, { withFileTypes: true })
+        .sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = path.join(root, entry.name);
+        if (entry.isDirectory()) yield* markdownFiles(file);
+        else if (entry.isFile() && file.endsWith(".md")) yield file;
+    }
+}
+
+/** Preserve offsets while excluding literal examples from link scanning. */
+export function maskMarkdownCode(source, spans = true) {
+    const pattern =
+        spans ?
+            /```[\s\S]*?```|~~~[\s\S]*?~~~|``[^`]*``|`[^`]*`/g
+        :   /```[\s\S]*?```|~~~[\s\S]*?~~~/g;
+    return source.replace(pattern, (match) => match.replace(/[^\n]/g, " "));
+}
+
+/** GitHub heading slug, retaining separate spaces after punctuation removal. */
+export function docHeadingSlug(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/\s/g, "-");
+}
+
+/** @param {string} source */
+export function docAnchors(source) {
+    const body = maskMarkdownCode(source, false);
+    const anchors = new Set();
+    for (const [, heading] of body.matchAll(/^#{1,6}\s+(.+?)\s*#*$/gm)) {
+        const explicit = heading.match(/\{#([^}]+)\}\s*$/);
+        anchors.add(
+            explicit ?
+                explicit[1].trim()
+            :   docHeadingSlug(heading.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")),
+        );
+    }
+    for (const [, anchor] of body.matchAll(/<a\s[^>]*(?:id|name)="([^"]+)"/g)) {
+        anchors.add(anchor);
+    }
+    return anchors;
+}
+
+/**
+ * Check relative Markdown links beneath a documentation root.
+ * @param {string} root
+ * @returns {Array<{file: string, line: number, column: number, severity: "error", message: string}>}
+ */
+export function checkDocLinks(root) {
+    const findings = [];
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return [{ file: root, severity: "error", message: "documentation root does not exist" }];
+    }
+    const anchors = new Map();
+    for (const file of markdownFiles(root)) {
+        const body = maskMarkdownCode(fs.readFileSync(file, "utf8"));
+        for (const match of body.matchAll(/\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+            const link = match[1];
+            if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(link) || link.startsWith("/")) continue;
+            const hash = link.indexOf("#");
+            const relative = hash < 0 ? link : link.slice(0, hash);
+            const anchor = hash < 0 ? "" : link.slice(hash + 1);
+            const offset = match.index + 2;
+            const location = {
+                file,
+                line: body.slice(0, match.index).split("\n").length,
+                column: offset - body.lastIndexOf("\n", offset),
+                severity: /** @type {const} */ ("error"),
+            };
+            let target;
+            try {
+                target = relative ? path.resolve(path.dirname(file), decodeURI(relative)) : file;
+            } catch {
+                findings.push({ ...location, message: `link ${link} has invalid URI encoding` });
+                continue;
+            }
+            if (!fs.existsSync(target)) {
+                findings.push({
+                    ...location,
+                    message: `link ${link} resolves to ${path.relative(process.cwd(), target)}, which does not exist`,
+                });
+            } else if (anchor && target.endsWith(".md")) {
+                if (!anchors.has(target))
+                    anchors.set(target, docAnchors(fs.readFileSync(target, "utf8")));
+                if (!anchors.get(target).has(anchor)) {
+                    findings.push({
+                        ...location,
+                        message: `link ${link} points at an anchor nobody declares`,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+
+/**
+ * Check each direct Markdown page in each section against the root README.
+ * @param {string} root
+ * @returns {Array<{file: string, severity: "error", message: string}>}
+ */
+export function checkDocIndex(root) {
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return [{ file: root, severity: "error", message: "documentation root does not exist" }];
+    }
+    const index = path.join(root, "README.md");
+    if (!fs.existsSync(index))
+        return [{ file: index, severity: "error", message: "documentation index does not exist" }];
+    const readme = fs.readFileSync(index, "utf8");
+    const findings = [];
+    for (const section of fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())) {
+        const dir = path.join(root, section.name);
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+            const relative = `${section.name}/${entry.name}`;
+            if (!readme.includes(relative)) {
+                findings.push({
+                    file: path.join(dir, entry.name),
+                    severity: /** @type {const} */ ("error"),
+                    message: `not linked from ${index}`,
+                });
+            }
+        }
+    }
+    return findings;
+}

package/engine/documentation-links.mjs

@@ -0,0 +1,31 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { parseMarkdownFile } from "./helpers.mjs";
+
+const LOCAL_MARKDOWN_LINK = /\[([^\]\n]+)\]\(([^\s)]+\.md(?:#[^\s)]*)?)\)/g;
+
+/** Keep repository-relative documentation links usable on addressed pages. */
+export function documentationLinksPass({ config, book = false }) {
+    const root = config.paths.content;
+    const cache = new Map();
+    return {
+        beforeLinks(text, page) {
+            return text.replace(LOCAL_MARKDOWN_LINK, (whole, label, target) => {
+                const [fileName, fragment] = target.split("#", 2);
+                const file = path.resolve(path.dirname(page.file), fileName);
+                if (!file.startsWith(`${root}${path.sep}`) || !fs.existsSync(file)) return whole;
+                let address = cache.get(file);
+                if (!address) {
+                    const { frontmatter } = parseMarkdownFile(file);
+                    if (!frontmatter?.type || !frontmatter?.shortcode) return whole;
+                    address = `/${config.contentPackage}/${frontmatter.type}-${frontmatter.shortcode}/`;
+                    cache.set(file, address);
+                }
+                return `[${label}](${address}${fragment && !book ? `#${fragment}` : ""})`;
+            });
+        },
+    };
+}

package/engine/exported-scene.mjs

@@ -147,7 +147,7 @@ function keyDocument(doc, collection, parentIds, sceneId) {
  *
  * @param {object} fm - The map note's frontmatter.
  * @param {string} markdown - Its converted Markdown body.
- * @param {object} [opts] - Pack metadata, derived JournalEntry ID, and asset resolver.
+ * @param {{journalEntryId?: string, stats?: object, resolveAddress?: Function}} [opts] - Pack metadata, derived JournalEntry ID, and asset resolver.
  * @returns {object} The keyed Scene document.
  */
 export function buildExportedScene(fm, markdown, { journalEntryId, stats, resolveAddress } = {}) {

package/engine/extension-attributes.mjs

@@ -0,0 +1,74 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+/**
+ * Read the shared braced attribute grammar used by body extensions.
+ * Callers validate which names and classes their extension understands.
+ * @param {string} source - Text inside the braces.
+ * @returns {{id: string, classes: string[], values: Record<string, string>, problems: string[]}}
+ */
+export function parseExtensionAttributes(source) {
+    const text = String(source ?? "");
+    const result = { id: "", classes: [], values: {}, problems: [] };
+    let at = 0;
+    while (at < text.length) {
+        while (/\s/.test(text[at] ?? "")) at++;
+        if (at >= text.length) break;
+        const start = at;
+        if (text[at] === "#" || text[at] === ".") {
+            const kind = text[at++];
+            while (at < text.length && !/\s/.test(text[at])) at++;
+            const name = text.slice(start + 1, at);
+            if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
+                result.problems.push(
+                    `invalid ${kind === "#" ? "id" : "class"} attribute ${text.slice(start, at)}`,
+                );
+            } else if (kind === "#") {
+                if (result.id) result.problems.push("an attribute list has more than one id");
+                else result.id = name;
+            } else if (result.classes.includes(name)) {
+                result.problems.push(`class .${name} is written twice`);
+            } else result.classes.push(name);
+            continue;
+        }
+        const key = /^[A-Za-z][A-Za-z0-9_-]*/.exec(text.slice(at))?.[0];
+        if (!key || text[at + key.length] !== "=") {
+            while (at < text.length && !/\s/.test(text[at])) at++;
+            result.problems.push(`${text.slice(start, at)} is not a key=value attribute`);
+            continue;
+        }
+        at += key.length + 1;
+        let value = "";
+        if (text[at] === '"') {
+            at++;
+            let closed = false;
+            while (at < text.length) {
+                if (text[at] === '"') {
+                    at++;
+                    closed = true;
+                    break;
+                }
+                if (text[at] === "\\" && ["\\", '"'].includes(text[at + 1])) at++;
+                value += text[at++];
+            }
+            if (!closed) result.problems.push(`${key} has an unclosed quoted value`);
+            if (at < text.length && !/\s/.test(text[at])) {
+                while (at < text.length && !/\s/.test(text[at])) at++;
+                result.problems.push(`${key} has text after its quoted value`);
+            }
+        } else {
+            while (at < text.length && !/\s/.test(text[at])) value += text[at++];
+            if (/[{},"\[\]]/.test(value)) result.problems.push(`${key} needs a quoted value`);
+        }
+        if (!value) result.problems.push(`${key} needs a value`);
+        if (Object.hasOwn(result.values, key)) result.problems.push(`${key} is written twice`);
+        else result.values[key] = value;
+    }
+    return result;
+}
+
+/** A Boolean attribute is spelled exactly `true` or `false`. */
+export function booleanAttribute(value, key) {
+    if (value === "true") return true;
+    if (value === "false") return false;
+    throw new TypeError(`${key} needs the literal value true or false`);
+}

package/engine/field-reference.mjs

@@ -248,7 +248,7 @@ function workedExample(type, fields) {
 export function renderItemFieldReference({
     title = "Item Note Frontmatter",
     preamble = [],
-    generatedBy = "the content-build field reference generator",
+    generatedBy = "the package-build field reference generator",
     config = loadPackConfig(),
 } = {}) {
     const declared = config.itemFields ?? {};

package/engine/field-spec.mjs

@@ -161,6 +161,9 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   which is a Shortcode at both ends and resolves nothing.
  * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
  *   the constant, or a function deriving it from the frontmatter.
+ * @property {(fm: object, out: object) => boolean} [when] - Emit this field
+ *   only when the note and fields already built meet the condition. The path
+ *   remains declared for schema checks and authoring validation.
  * @property {boolean} [omitWhenAbsent] - **The key is left out entirely when
  *   the note does not carry the field**, rather than written from a
  *   declared default.
@@ -460,6 +463,7 @@ export function buildFromFields(fields, { block = "sohl", onLegacyKey, onRetired
     return function buildDeclaredSystem(fm) {
         const out = {};
         for (const field of fields) {
+            if (field.when && !field.when(fm, out)) continue;
             // A runtime-only field is not this builder's to write. It is
             // declared so that the path is *claimed* — so the verbatim
             // passthrough leaves it alone and the refusal has a name — not so

package/engine/foreign-catalog.mjs

@@ -39,7 +39,7 @@
  * item came from.
  *
  * **The network is never touched by a compile.** Fetching is its own command
- * (`content-build deps fetch`), and a compile whose cache is cold fails saying
+ * (`package-build deps fetch`), and a compile whose cache is cold fails saying
  * so. A build that silently downloads is not reproducible, fails strangely
  * offline, and hides a version change behind a passing run.
  *
@@ -223,7 +223,7 @@ function cachedItemPacks(dir) {
  * ways of proceeding without it are both wrong: reading every pack resolves an
  * `hm3` reference against `sohl` documents — the silent-wrong-output failure
  * this scoping exists to remove — and reading none fails a build that was
- * working. Treating it as incomplete makes `content-build deps fetch` refill
+ * working. Treating it as incomplete makes `package-build deps fetch` refill
  * it, which is a command the cold-cache path already tells anyone to run.
  *
  * @param {string} dir - The dependency's cache directory.
@@ -481,7 +481,7 @@ export async function fetchCatalogFromPath(config, rel, source) {
         throw new Error(`${rel.id}: nothing at ${source}`);
     }
 
-    const staging = fs.mkdtempSync(path.join(os.tmpdir(), `content-build-${rel.id}-`));
+    const staging = fs.mkdtempSync(path.join(os.tmpdir(), `package-build-${rel.id}-`));
     try {
         let root;
         if (fs.statSync(source).isDirectory()) {
@@ -608,7 +608,7 @@ export async function fetchMetadataFromPath(config, rel, source) {
         throw new Error(`${rel.id}: nothing at ${source}`);
     }
 
-    const staging = fs.mkdtempSync(path.join(os.tmpdir(), `content-build-meta-${rel.id}-`));
+    const staging = fs.mkdtempSync(path.join(os.tmpdir(), `package-build-meta-${rel.id}-`));
     try {
         let root = source;
         if (!fs.statSync(source).isDirectory()) {
@@ -752,7 +752,7 @@ export function foreignItemCatalogDirs(config, system = null) {
         if (!cached.length) {
             throw new Error(
                 `${rel.id} declares \`itemCatalog: true\` but has not been ` +
-                    `fetched. Run \`content-build deps fetch\` first.`,
+                    `fetched. Run \`package-build deps fetch\` first.`,
             );
         }
         // Newest wins if several versions are cached; a fetch always writes

package/engine/format-generated.mjs

@@ -0,0 +1,15 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Format generated text using the destination file's Prettier configuration.
+ * @param {string} text
+ * @param {string} filepath
+ * @returns {Promise<string>}
+ */
+export async function formatGenerated(text, filepath) {
+    const prettier = await import("prettier");
+    const config = await prettier.resolveConfig(filepath);
+    return prettier.format(text, { ...config, filepath });
+}

package/engine/foundry-entries.mjs

@@ -59,6 +59,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { noteAddressContext } from "./note-addresses.mjs";
+import { isGmNote } from "./note-vocabulary.mjs";
 import { canonicalKey, packageAddress } from "./content-address.mjs";
 import { ownDocumentSystem } from "./address.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
@@ -211,6 +212,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
             routeFm ?
                 packRouter.resolveOrNull(routeFm, docType, system)
             :   packRouter.defaultOf("JournalEntry");
+        if (isGmNote(fm) && !packRouter.privateOf?.(pack)) return undefined;
 
         // **A system block is what makes a game document**, so a note carrying
         // none compiles into no Actor and no Item — and an address naming one
@@ -255,7 +257,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
         // however many system blocks the note carries.
         const docKey = canonicalKey(contentPackage, NOTE_SYSTEM, fm.type, fm.shortcode);
         const docEntryId = fm.id ? itemDocEntryId(fm.id) : undefined;
-        const docUuid = uuidFor("doc", docEntryId);
+        const docUuid = uuidFor("doc", docEntryId, isGmNote(fm) ? fm : undefined);
         return [
             {
                 key,

package/engine/frontmatter-lint.mjs

@@ -1689,7 +1689,11 @@ export function lintNote(
                 `\`${field.name}\``
             :   `\`sohl.${field.name}\``;
 
-        if (field.required && absent) {
+        if (
+            field.required &&
+            absent &&
+            (!field.when || field.when(fm, { subType: fm.subType ?? fm.sohl?.subType }))
+        ) {
             findings.push({
                 file: note.file,
                 ...at("type", type),

package/engine/frontmatter.mjs

@@ -36,6 +36,10 @@ import { AFFILIATION_STANDINGS } from "../sohl/affiliation-standings.mjs";
 /**
  * Resolves a dotted frontmatter key (e.g., "name.full") into the nested
  * value. Returns `defaultValue` if any path segment is missing.
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} key - A top-level or dotted property path.
+ * @param {unknown} [defaultValue] - Value for a missing property.
+ * @returns {unknown} The property value or default.
  */
 export function getFrontmatter(fm, key, defaultValue = undefined) {
     if (fm == null || typeof fm !== "object") return defaultValue;
@@ -53,6 +57,10 @@ export function getFrontmatter(fm, key, defaultValue = undefined) {
  * Reads a key from `fm.sohl` (the vault's nested system-fields block).
  * Supports dotted notation, e.g. sohlField(fm, "charges.value", 0).
  * Falls back to top-level `fm[key]` if `sohl` doesn't carry the key.
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} key - A top-level or dotted property path.
+ * @param {unknown} [defaultValue] - Value for a missing property.
+ * @returns {unknown} The system value, top-level value, or default.
  */
 export function sohlField(fm, key, defaultValue = undefined) {
     if (fm == null || typeof fm !== "object") return defaultValue;
@@ -321,6 +329,8 @@ export function requireSubType(fm, ctx) {
  *   - Array of "Label:MaxValue" strings, e.g. ["Ugly:4", "Plain:12"]
  *   - Array of objects, e.g. [{ label, maxValue }]
  * Returns a normalized array of `{ label, maxValue: number }`.
+ * @param {unknown} raw - An authored threshold array.
+ * @returns {Array<{label: string, maxValue: number}>} Normalized thresholds.
  */
 export function parseValueDesc(raw) {
     if (!raw || !Array.isArray(raw)) return [];

package/engine/generate.mjs

@@ -430,7 +430,7 @@ export function orderPassesByDependency(packs) {
  * would produce them is not in it.
  *
  * Ordering answers the whole-package build; a run restricted to one pack
- * (`content-build package compile <name>`) cannot conjure the passes it left
+ * (`package-build package compile <name>`) cannot conjure the passes it left
  * out. Where their output is already on disk from an earlier run that is fine
  * — it is how compiling one pack at a time is meant to work — so this reports
  * only what is genuinely absent, and names the pack that would write it rather
@@ -573,7 +573,7 @@ async function generatePack(
         // The catalogue of a package this repository depends on but does
         // not contain, for a repository that authors beings without
         // holding the items they are assembled from. Cache-only: a cold
-        // cache throws naming `content-build deps fetch` rather than
+        // cache throws naming `package-build deps fetch` rather than
         // downloading inside a compile. Scoped to this pack's system for the
         // reason the local half is: both halves answer one lookup, so a
         // dependency shipping two systems' items would otherwise supply the