@heroiclands/package-build 22.21.0 → 22.23.0

package/ci/content-format-reference.mjs

@@ -9,9 +9,12 @@ import { formatGenerated } from "../engine/format-generated.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     BEING_ARCHETYPES,
+    NOTE_TOP_LEVEL_FIELDS,
     NOTE_VOCABULARY,
     SHARED_DATA_FIELDS,
 } from "../engine/note-vocabulary.mjs";
+import { EXPRESSION_HELPERS } from "../engine/markdown-expressions.mjs";
+import { PAGE_LIST_ATTRIBUTES } from "../engine/page-lists.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const output = path.join(root, "docs/reference/note-types.md");
@@ -39,6 +42,16 @@ const rows = [
     "",
     "The [first-note guide](../authoring/first-note.md) teaches the shape of a note. [Frontmatter](../authoring/frontmatter.md) explains shared and system-specific values. The [detailed reference](format-details.md) gives the full behavior and examples.",
     "",
+    "## Top-level keys",
+    "",
+    "These are the only keys a note writes at its top level, in the order the formatter puts them. A key absent from this table is a lint error at its own line: the region is closed, so the key reaches no document and no page. Facts about the subject belong under `data`, and values for one game system belong inside that system's block.",
+    "",
+    "| Key | Meaning |",
+    "| --- | --- |",
+    ...NOTE_TOP_LEVEL_FIELDS.map(
+        (field) => `| \`${cell(field.name)}\` | ${cell(field.describe)} |`,
+    ),
+    "",
     "## Shared `data` fields",
     "",
     "These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can.",
@@ -106,7 +119,61 @@ if (process.argv.includes("--check")) {
         process.exitCode = 1;
     }
 } else {
-    process.stdout.write(result);
+    fs.writeFileSync(output, result);
+}
+
+// The two tables `docs/authoring/links-and-markup.md` generates: every helper
+// an expression may call, and every attribute a page-list fence takes. Both are
+// written from the one list the engine reads, so neither document can fall
+// behind a new entry. Replaced in one pass and written once, so a `--check` run
+// names the file rather than one of the tables in it.
+const markupPath = path.join(root, "docs/authoring/links-and-markup.md");
+const markup = fs.readFileSync(markupPath, "utf8");
+const GENERATED_TABLES = [
+    {
+        marker: "expression-helpers",
+        rows: [
+            "| Helper | Parameters | What it gives you |",
+            "| ------ | ---------- | ----------------- |",
+            ...Object.entries(EXPRESSION_HELPERS).map(
+                ([name, { params, summary }]) =>
+                    `| \`${cell(name)}\` | \`${cell(params)}\` | ${cell(summary)} |`,
+            ),
+        ],
+    },
+    {
+        marker: "page-list-attributes",
+        rows: [
+            "| Attribute | Value | Default | What it does |",
+            "| --------- | ----- | ------- | ------------ |",
+            ...Object.entries(PAGE_LIST_ATTRIBUTES).map(
+                ([name, { value, default: fallback, summary }]) =>
+                    `| \`${name}\` | ${cell(value)} | ${cell(fallback)} | ${cell(summary)} |`,
+            ),
+        ],
+    },
+];
+let markupBody = markup;
+for (const { marker, rows } of GENERATED_TABLES) {
+    const region = new RegExp(`<!-- ${marker}:start -->[\\s\\S]*?<!-- ${marker}:end -->`);
+    if (!region.test(markupBody)) {
+        throw new Error(`The ${marker} reference requires its generation markers`);
+    }
+    markupBody = markupBody.replace(
+        region,
+        `<!-- ${marker}:start -->\n\n${rows.join("\n")}\n\n<!-- ${marker}:end -->`,
+    );
+}
+const updatedMarkup = await formatGenerated(markupBody, markupPath);
+if (process.argv.includes("--check")) {
+    if (markup !== updatedMarkup) {
+        console.error(
+            "docs/authoring/links-and-markup.md: error: run node ci/content-format-reference.mjs to refresh its generated tables",
+        );
+        process.exitCode = 1;
+    }
+} else {
+    fs.writeFileSync(markupPath, updatedMarkup);
 }
 
 const detailsPath = path.join(root, "docs/reference/format-details.md");

package/config.mjs

@@ -65,6 +65,7 @@ const SECTION_KEYS = [
     "stageDir",
     "assets",
     "assetTransform",
+    "baseStyles",
     "manifest",
     "manifestFlags",
     "schema",
@@ -205,6 +206,23 @@ function requireNonEmptyString(value, where) {
     return /** @type {string} */ (value);
 }
 
+/**
+ * A declared switch, with the behaviour that applies when it is not declared.
+ *
+ * A truthy string is refused rather than coerced: `baseStyles: "false"` reads
+ * as off and would be on, which is the one wrong answer available here.
+ *
+ * @param {unknown} value - What was declared, or `undefined`.
+ * @param {boolean} fallback - The undeclared behaviour.
+ * @param {string} where - Dotted path, for the error.
+ * @returns {boolean} The setting.
+ */
+function requireBoolean(value, fallback, where) {
+    if (value === undefined) return fallback;
+    if (typeof value !== "boolean") fail(where, "must be true or false");
+    return value;
+}
+
 /**
  * One staging copy: a source path in the repository, and where it lands under
  * the staged package root.
@@ -537,6 +555,9 @@ function normalizeExceptions(value, field, where) {
  * @property {string} stageDir      The staged package root, relative to
  *                                   `rootDir`. Every asset `to:` lands under it.
  * @property {readonly Readonly<AssetSpec>[]} assets
+ * @property {boolean} baseStyles    Whether the package takes the shared base
+ *                                   stylesheet, staged into `stageDir` and
+ *                                   named first in the manifest's `styles`.
  * @property {Readonly<Record<string, unknown>>} manifest  The manifest
  *                                   specification, emitted as declared.
  * @property {string|null} manifestFlags  Module to load a `flags` function
@@ -877,6 +898,11 @@ export function resolvePackageBuildConfig(shared) {
                 ARTIFACT_OF_KIND[/** @type {"systems"|"modules"} */ (shared.packageKind)]
             :   requireNonEmptyString(releaseInput.artifact, "packageBuild.release.artifact"),
         assets: Object.freeze(assets),
+        // On by default, because the rules it carries are what compiled content
+        // needs to be legible and a package that declined them by omission
+        // would ship the content unstyled without anything saying so. A package
+        // that wants the surface entirely to itself says so.
+        baseStyles: requireBoolean(section.baseStyles, true, "packageBuild.baseStyles"),
         schema: normalizeSchema(section.schema),
         assetTransform:
             section.assetTransform === undefined ?

package/content-config.mjs

@@ -368,7 +368,8 @@ export function publishesContentPages(config) {
  * @property {string} [stage]            Compiled LevelDB packs.
  * @property {string} [unpack]           Where `unpack` extracts JSON back to.
  * @property {string} [foreignCache]     Where a dependency declaring
- *                                       `itemCatalog: true` is unpacked.
+ *                                       `itemCatalog: true` or
+ *                                       `assetArchive: true` is unpacked.
  *                                       Inbound, and fetched rather than
  *                                       committed.
  * @property {string} [metadataCache]    Where a dependency's published content
@@ -486,6 +487,15 @@ export function publishesContentPages(config) {
  *                                   package this one targets — for a system
  *                                   relationship, `verified` is what
  *                                   `_stats.systemVersion` is stamped from.
+ * @property {boolean} [itemCatalog]  Whether `deps fetch` unpacks this
+ *                                   dependency's release archive and extracts
+ *                                   its Item packs, so the actors pass can
+ *                                   resolve embedded items this repository
+ *                                   does not hold. Needs a `manifest`.
+ * @property {boolean} [assetArchive]  Whether `deps fetch` unpacks this
+ *                                   dependency's release archive for its
+ *                                   asset bytes alone, building no item
+ *                                   catalogue from it. Needs a `manifest`.
  * @property {boolean} [contentIndex]  Whether `deps fetch` fetches this
  *                                   dependency's content index. Default
  *                                   `true`. `false` declares the dependency
@@ -494,6 +504,13 @@ export function publishesContentPages(config) {
  *                                   `itemCatalog: true` on the same entry,
  *                                   since a catalogue is fetched from the same
  *                                   index.
+ * @property {boolean} [assetReplacement]  Whether this dependency's asset
+ *                                   tree answers this package's own asset
+ *                                   addresses ahead of its local record.
+ *                                   Default `false`. Refuses `contentIndex:
+ *                                   false` on the same entry, since a
+ *                                   replacement with no fetched index to
+ *                                   check against resolves nothing.
  */
 
 /**
@@ -620,6 +637,9 @@ export function publishesContentPages(config) {
  * @property {string[]} [skipDirectories]   Directory names the content walk ignores
  *                                          wherever they appear (e.g. Obsidian's
  *                                          `Templates`). Default `[]`.
+ * @property {boolean} [forbidGeneratedArt]  Whether `lint` refuses an asset
+ *                                          record of this package carrying
+ *                                          `ai: true`. Default `false`.
  * @property {PackageBuildSection} [packageBuild]  Reserved for
  *                                          `@heroiclands/package-build`, which
  *                                          validates it. Not read here.
@@ -700,6 +720,8 @@ export function publishesContentPages(config) {
  *                                     types. The one set the compilers and the
  *                                     link-manifest emitter both read.
  * @property {readonly string[]} skipDirectories
+ * @property {boolean} forbidGeneratedArt  Whether `lint` refuses an asset
+ *                                     record of this package carrying `ai: true`.
  * @property {import("./engine/content-icons.mjs").IconRegistry} icons  The
  *                                     fonts this package ships and the names it
  *                                     draws from them; empty when it declares
@@ -728,6 +750,7 @@ const CONFIG_KEYS = [
     "itemBuilders",
     "paths",
     "skipDirectories",
+    "forbidGeneratedArt",
     "icons",
     "packs",
     "docs",
@@ -765,14 +788,25 @@ const PDF_FONT_KEYS = ["serif", "sans", "mono", "path"];
 const EMPTY_PDF_FONTS = Object.freeze({ serif: "", sans: "", mono: "", path: "" });
 const DOC_PAGE_KEYS = ["title", "out", "preamble", "frontmatter"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
-const RELATIONSHIP_KEYS = [
+/**
+ * Every key a declared relationship may carry.
+ *
+ * Read by the manifest writer as well as by the configuration check: the keys
+ * Foundry's own relationship schema does not name are the build's own, and the
+ * published manifest carries none of them.
+ *
+ * @type {readonly string[]}
+ */
+export const RELATIONSHIP_KEYS = [
     "id",
     "contentPackage",
     "type",
     "manifest",
     "compatibility",
     "itemCatalog",
+    "assetArchive",
     "contentIndex",
+    "assetReplacement",
 ];
 const AUTHOR_KEYS = ["name", "email", "url"];
 const ITEM_BUILDER_KEYS = ["system", "img", "fields"];
@@ -1580,6 +1614,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",
+    "markup.goldmark.extensions.taskList": "the toolchain, whose format has no checkbox",
     menu: "the navigation `package-build deps fetch` caches from heroiclands.org",
 });
 
@@ -1903,6 +1938,44 @@ function normalizePdf(value, rootDir) {
     });
 }
 
+/**
+ * A dotted version string as the three-element tuple Foundry compares.
+ *
+ * A missing component reads as `0`, so `"14"` compares as `14.0.0` — the
+ * common way an author writes a major-only floor or pin. A non-numeric
+ * component reads as `0` too, rather than throwing: this runs on values
+ * {@link requireNonEmptyString} has already accepted as non-empty strings,
+ * and a version with a qualifier (`"14.359.0-beta"`) is not this function's
+ * place to refuse.
+ *
+ * @param {string} version - A dotted version string.
+ * @returns {readonly [number, number, number]} Major, minor, patch.
+ */
+function versionTriple(version) {
+    const parts = version.split(".");
+    return [0, 1, 2].map((index) => {
+        const n = Number.parseInt(parts[index] ?? "0", 10);
+        return Number.isNaN(n) ? 0 : n;
+    });
+}
+
+/**
+ * Whether `verified` names a build below `minimum`, compared as version
+ * triples.
+ *
+ * @param {string} minimum - The declared floor.
+ * @param {string} verified - The declared verified build.
+ * @returns {boolean} `true` when `verified` sorts below `minimum`.
+ */
+function verifiedBelowMinimum(minimum, verified) {
+    const a = versionTriple(verified);
+    const b = versionTriple(minimum);
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i]) return a[i] < b[i];
+    }
+    return false;
+}
+
 /**
  * Validate a Foundry version range.
  *
@@ -1912,6 +1985,12 @@ function normalizePdf(value, rootDir) {
  * load-bearing there is `verified`, and a relationship may reasonably name a
  * package without pinning a floor at all.
  *
+ * **The two keys are a range, not two independent facts.** Foundry reads
+ * `verified` as the build inside `minimum`'s floor that was actually tested,
+ * so a `verified` below `minimum` names a build the package already refuses
+ * to install on. Caught only when both are present — a relationship naming
+ * `verified` alone has nothing to compare it against.
+ *
  * @param {unknown} value - The declared range, or `undefined`.
  * @param {string} where - Dotted path, for the error.
  * @param {boolean} [requireMinimum] - Whether `minimum` must be present.
@@ -1929,6 +2008,18 @@ function normalizeCompatibility(value, where, requireMinimum = true) {
     if (input.verified !== undefined) {
         out.verified = requireNonEmptyString(input.verified, `${where}.verified`);
     }
+    if (
+        out.minimum !== undefined &&
+        out.verified !== undefined &&
+        verifiedBelowMinimum(out.minimum, out.verified)
+    ) {
+        fail(
+            `${where}.verified`,
+            `declares \`${out.verified}\`, below \`${where}.minimum\`'s \`${out.minimum}\` — ` +
+                "Foundry reads the two as one range, so a build below the floor is " +
+                "never the one verified against it",
+        );
+    }
     return Object.freeze(out);
 }
 
@@ -2022,6 +2113,21 @@ function normalizeSystems(value) {
         // declaration that cannot answer "which version was this built
         // against" is the gap this block exists to close.
         const verified = requireNonEmptyString(compat.verified, `${at}.compatibility.verified`);
+        const minimum =
+            compat.minimum === undefined || compat.minimum === null ?
+                null
+            :   requireNonEmptyString(compat.minimum, `${at}.compatibility.minimum`);
+        // Caught here too: the shape is the one {@link normalizeCompatibility}
+        // validates, and the same contradiction is possible wherever it
+        // appears.
+        if (minimum !== null && verifiedBelowMinimum(minimum, verified)) {
+            fail(
+                `${at}.compatibility.verified`,
+                `declares \`${verified}\`, below \`${at}.compatibility.minimum\`'s ` +
+                    `\`${minimum}\` — Foundry reads the two as one range, so a build ` +
+                    "below the floor is never the one verified against it",
+            );
+        }
 
         out[id] = Object.freeze({
             manifest:
@@ -2029,10 +2135,7 @@ function normalizeSystems(value) {
                     null
                 :   requireNonEmptyString(spec.manifest, `${at}.manifest`),
             compatibility: Object.freeze({
-                minimum:
-                    compat.minimum === undefined || compat.minimum === null ?
-                        null
-                    :   requireNonEmptyString(compat.minimum, `${at}.compatibility.minimum`),
+                minimum,
                 verified,
             }),
         });
@@ -2129,6 +2232,23 @@ function normalizeRelationships(value) {
                     }
                     spec.itemCatalog = rel.itemCatalog;
                 }
+                // Opt-in, sibling to `itemCatalog`: unpack this dependency's
+                // release archive for its asset bytes alone, building no item
+                // catalogue from it. Buys the archive for a package with no
+                // items of its own to extract — an asset-replacement source
+                // ships no Item packs and has no use for `itemCatalog: true`.
+                if (rel.assetArchive !== undefined) {
+                    if (typeof rel.assetArchive !== "boolean") {
+                        fail(`${at}.assetArchive`, "must be true or false");
+                    }
+                    if (rel.assetArchive && spec.manifest === undefined) {
+                        fail(
+                            `${at}.assetArchive`,
+                            "needs a `manifest` naming the package to fetch",
+                        );
+                    }
+                    spec.assetArchive = rel.assetArchive;
+                }
                 // Opt-out: declares the dependency for the Foundry manifest
                 // only, so `deps fetch` fetches no content index for it and a
                 // wikilink into it is refused rather than silently dead. A
@@ -2147,6 +2267,26 @@ function normalizeRelationships(value) {
                     }
                     spec.contentIndex = rel.contentIndex;
                 }
+                // Opt-in: this dependency's asset tree answers this
+                // package's own asset addresses ahead of its local record —
+                // the "rewrite table" `engine/asset-replacement.mjs` reads.
+                // A replacement with no fetched index to check against
+                // resolves nothing, so it cannot pair with
+                // `contentIndex: false`.
+                if (rel.assetReplacement !== undefined) {
+                    if (typeof rel.assetReplacement !== "boolean") {
+                        fail(`${at}.assetReplacement`, "must be true or false");
+                    }
+                    if (rel.assetReplacement && rel.contentIndex === false) {
+                        fail(
+                            `${at}.assetReplacement`,
+                            "cannot be true together with `contentIndex: false` — a " +
+                                "replacement with no fetched index to check against resolves " +
+                                "nothing",
+                        );
+                    }
+                    spec.assetReplacement = rel.assetReplacement;
+                }
                 return Object.freeze(spec);
             }),
         );
@@ -2625,6 +2765,12 @@ export function defineConfig(config) {
         requireNonEmptyString(name, `skipDirectories[${index}]`),
     );
 
+    const forbidGeneratedArt = optionalBoolean(
+        input.forbidGeneratedArt,
+        "forbidGeneratedArt",
+        false,
+    );
+
     // Refused above for a documentation package, so there is nothing to read
     // and nothing to derive an asset root or a package-wide system from.
     const foundryPackage =
@@ -2731,6 +2877,7 @@ export function defineConfig(config) {
         itemTypes,
         docEntryTypes,
         skipDirectories: Object.freeze(skipDirectories),
+        forbidGeneratedArt,
         icons: normalizeIcons(input.icons, rootDir),
         packs: Object.freeze(packs),
         packDirectories: Object.freeze(packDirectories),