@heroiclands/package-build 19.0.0 → 20.2.0

package/engine/generate.mjs

@@ -23,10 +23,12 @@
  * Each `*` compiler walks the whole content tree and selects its own entries by
  * the note's `type` — every note in the tree belongs to this repository's
  * `contentPackage` (#56) — so routing is directory-agnostic: a file lands in a
- * pack because of its `type`, not its location. Which packs exist and which
- * folder hierarchy each one loads are declared in
- * `package-build.config.yaml`; folder files live under the content root and are
- * referenced from entry frontmatter via `sohl.folder: <id>`.
+ * pack because of its `type`, not its location. Which packs exist is declared
+ * in `package-build.config.yaml`; the **folder hierarchy is not declared
+ * anywhere**. A folder is a note like any other (#256), named by `packFolder`
+ * — its address — and it materialises in every pack that holds a document
+ * naming it, its ancestors with it (#257). So no pack loads a folder list, and
+ * two packs can no longer disagree about a folder they both hold.
  *
  * **The order the passes run in is derived, not declared** — see
  * {@link orderPassesByDependency}. The declared list is the manifest's `packs`
@@ -66,7 +68,10 @@ import { buildCompileCorpus } from "./compile-corpus.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
-import { unclaimedNoteFindings } from "./note-claims.mjs";
+import { NEVER_PACKED_TYPES, unclaimedNoteFindings } from "./note-claims.mjs";
+// Which document a content type compiles into, so the art declaration below is
+// answered from the same routing the compile uses (#349).
+import { RETIRED_TYPES, currentType, packForType } from "./ids.mjs";
 import { contentPackage } from "./content-package.mjs";
 
 /**
@@ -131,6 +136,56 @@ export function compilerFor(docType, system = null) {
     return (system && SYSTEM_COMPILERS[system]?.[docType]) || COMPILERS[docType];
 }
 
+/**
+ * The art fields a note of one content type reaches its document through, and
+ * the document it reaches (#349).
+ *
+ * **Derived, never listed.** A note's type routes to a document type
+ * ({@link packForType}), a document type routes to the pass that compiles it
+ * ({@link compilerFor}), and the pass declares which art it emits
+ * ({@link BasePackCompiler.emitsArt}). So the answer is assembled from the same
+ * three statements the compile itself follows, and a pass that starts or stops
+ * emitting art changes this by changing its own declaration. A second table of
+ * "types with no image" would be a table free to drift from what is emitted,
+ * which is the defect this exists to report rather than to reproduce.
+ *
+ * **The union across systems**, because a note is compiled by whichever pack
+ * claims it: a tree feeding both SoHL and HM3 has two Actor passes, and a field
+ * either of them emits is live for the note. Only a field *no* pass emits is
+ * inert, and that is the finding this supports.
+ *
+ * @param {string} type - The note's content type.
+ * @returns {{document: string|null, art: readonly string[]}|null} What the type
+ *   compiles into and the art it carries there, or `null` where no claim can be
+ *   made — a retired type, which is reported as retired instead.
+ */
+export function emittedArtFor(type) {
+    const name = String(type ?? "");
+    if (!name || Object.hasOwn(RETIRED_TYPES, name)) return null;
+
+    // A homepage compiles into a *page*, not a compendium document, so nothing
+    // it authors reaches one. It is the one type whose absence from every pack
+    // is the intended state (`NEVER_PACKED_TYPES`).
+    if (NEVER_PACKED_TYPES.has(currentType(name))) return { document: null, art: [] };
+
+    // A folder reaches a pack by a route of its own — it materialises in every
+    // pack holding a document that references it — so `packForType` has no
+    // answer for it and no compiler class writes it. `folderDocument` does, and
+    // a Foundry `Folder` has no artwork at all.
+    if (currentType(name) === FOLDER_TYPE) return { document: "Folder", art: [] };
+
+    const { docType } = packForType(name);
+    const passes = [
+        COMPILERS[docType],
+        ...Object.values(SYSTEM_COMPILERS).map((bySystem) => bySystem[docType]),
+    ].filter(Boolean);
+    if (!passes.length) return null;
+
+    const art = new Set();
+    for (const pass of passes) for (const field of pass.emitsArt ?? []) art.add(field);
+    return { document: docType, art: Object.freeze([...art]) };
+}
+
 /**
  * Root of the build-only JSON tree for one pack.
  *
@@ -442,8 +497,11 @@ async function generatePack(
         // 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
-        // downloading inside a compile.
-        foreignSourceDirs: foreignItemCatalogDirs(config),
+        // downloading inside a compile. Scoped to this pack's system for the
+        // reason the local half is (#58): both halves answer one lookup, so a
+        // dependency shipping two systems' items would otherwise supply the
+        // wrong vocabulary's document for an address that exists in both.
+        foreignSourceDirs: foreignItemCatalogDirs(config, system ?? null),
         // The bundles pass resolves each Adventure's members against the output
         // of every pass that produces one. Stated from the configured pack list
         // for the same reason `itemsSourceDirs` is (#1508), and scoped to this
@@ -656,11 +714,13 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
                 // which wins over the id it derives under the folder namespace.
                 // A record's `id` is not that: the index fills it in for every
                 // addressable note (#270), so handing records straight over
-                // would make every folder look pinned and file each one under a
-                // different id than the packs address it by. The index cannot
-                // tell a pin from a derivation, so the note is read — and only
-                // folder notes are, 79 of `sohl`'s 1,685 rather than all of
-                // them.
+                // would make every folder look pinned. Since #310 the *value*
+                // would be right either way — the index derives a folder's id
+                // under the folder namespace, so the two agree — but `derivedId`
+                // would not, and it is what tells an author whether a duplicate
+                // id was two pins or two addresses. The index cannot tell a pin
+                // from a derivation, so the note is read — and only folder notes
+                // are, 79 of `sohl`'s 1,685 rather than all of them.
                 corpus.records
                     .filter(
                         (record) =>

package/engine/helpers.mjs

@@ -31,6 +31,7 @@ import path from "path";
 import yaml from "yaml";
 import unidecode from "unidecode";
 import markdownit from "markdown-it";
+import { iconPlugin } from "./content-icons.mjs";
 import log from "loglevel";
 
 import { loadPackConfig } from "./pack-config.mjs";
@@ -68,7 +69,15 @@ export {
     parseValueDesc,
 } from "./frontmatter.mjs";
 
-export const md = markdownit({ html: true });
+/**
+ * The markdown renderer every surface shares.
+ *
+ * `html: true` is long-standing and load-bearing — notes carry raw blocks — and
+ * it is also why {@link module:engine/content-icons} exists rather than an
+ * instruction to write `<i class="fa-solid …">` by hand: that would render on
+ * the two HTML surfaces and be silently dropped by the third (#378).
+ */
+export const md = markdownit({ html: true }).use(iconPlugin());
 
 /**
  * Parses a markdown file with YAML frontmatter.
@@ -400,15 +409,92 @@ export function makeFilename(name, id) {
  * non-alphanumerics collapsed to single hyphens.
  */
 
+/**
+ * The path prefixes that name a package other than the one being compiled.
+ *
+ * Foundry serves every installed package from a root named for its kind, so a
+ * path opening with one of these is already a served address and belongs to
+ * somebody else — most often `systems/sohl/assets/…`, where every default this
+ * toolchain ships lives, and which a module's content cites as readily as the
+ * system's own does.
+ *
+ * **Two, not "the ones we happen to use".** `worlds/` is left out on purpose: a
+ * package may not ship art out of a world, so a note that writes one has made a
+ * mistake, and prefixing it yields a plainly broken path rather than a
+ * plausible one that fails silently much later.
+ *
+ * @type {readonly string[]}
+ */
+const FOREIGN_PACKAGE_ROOTS = Object.freeze(["systems/", "modules/"]);
+
+/**
+ * Whether a path already addresses something this package does not own, and so
+ * must be emitted exactly as authored.
+ *
+ * Three shapes qualify, each a different kind of "not mine":
+ *
+ * - **Another package** — `systems/…` or `modules/…`, per
+ *   {@link FOREIGN_PACKAGE_ROOTS}.
+ * - **Somewhere off this install** — a URI scheme (`https:`, `data:`) or a
+ *   protocol-relative `//cdn…`.
+ * - **The data root itself** — a leading `/`, which Foundry serves from the
+ *   install rather than from any package.
+ *
+ * @param {string} s - A non-empty authored path.
+ * @returns {boolean} Whether it passes through untranslated.
+ */
+function addressesAnotherPackage(s) {
+    if (FOREIGN_PACKAGE_ROOTS.some((root) => s.startsWith(root))) return true;
+    // `//host/x.png` — protocol-relative, so it leaves this origin entirely.
+    // Checked before the single-slash case, which would otherwise claim it.
+    if (s.startsWith("//")) return true;
+    // `/x.png` — rooted at the Foundry data root, not at any package.
+    if (s.startsWith("/")) return true;
+    // `https://…`, `data:…`, `file:…` — a scheme, so not a path at all.
+    return /^[a-z][a-z0-9+.-]*:/i.test(s);
+}
+
 /**
  * Translate a content-relative image path into its Foundry-relative form.
  *
  * Content frontmatter (`img` / `portrait`) authors a single path that has to
- * work for Foundry, the knowledgebase, and the website. For Foundry the bundled
- * asset roots — `icons/...` and `images/...` — are served from the package
- * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
- * for this repository, `modules/<id>/assets` for a module (#1508). Any other
- * path (already package-rooted, an absolute URL) is returned unchanged.
+ * work for Foundry, the knowledgebase, and the website. **Its first segment
+ * says which package owns the file** (#331), and there are exactly three
+ * answers:
+ *
+ * | Authored path starts with | Owner                 | Emitted              |
+ * | ------------------------- | --------------------- | -------------------- |
+ * | `systems/`                | a separate **system** | unchanged            |
+ * | `modules/`                | a separate **module** | unchanged            |
+ * | anything else             | **this package**      | `<assetRoot>/<path>` |
+ *
+ * So `icons/relic.svg` compiles to `systems/sohl/assets/icons/relic.svg` here
+ * and to `modules/sohl-thalorna/assets/icons/relic.svg` in a module — the asset
+ * root is derived from the configuration, and is the one place `systems/sohl`
+ * is ever spelled (#1508). An authored
+ * `systems/sohl/assets/icons/noun/shield.svg` is left exactly as written,
+ * whichever package is compiling it.
+ *
+ * **This is a rule about ownership, not an allowlist of directories.** It used
+ * to prefix `icons/…` and `images/…` and pass everything else through — the
+ * same answer for every path any tree authors today, and the wrong one for the
+ * next directory a package ships. `sohl-kethira-basic` keeps art under
+ * `assets/artwork/`, so an authored `artwork/deity.webp` would have shipped
+ * unprefixed: a 404 in Foundry, reported by nothing. That a package owns its
+ * own tree is the fact; the directory names inside it are that package's
+ * business (#331).
+ *
+ * **Off-install addresses pass through too**, which is the same rule rather
+ * than a fourth: a URL, a `data:` URI, or a `/`-rooted path names something no
+ * package owns. See {@link addressesAnotherPackage}.
+ *
+ * **`banner:` does not follow this rule, deliberately (#331).** It is not an
+ * asset path inside a Foundry install at all: it reaches no compiled document,
+ * and its only consumer is the Hugo theme, which prefixes a relative value with
+ * `images/` and joins it onto `params.cdnBaseURL`. The two fields look alike
+ * and address different places — `img:` a file Foundry serves, `banner:` a file
+ * the CDN serves — so they are documented apart rather than reconciled into one
+ * rule that would be true of neither.
  *
  * **Two empties, and they mean opposite things (#218).** `null` — or an absent
  * key, which reaches here as `undefined` — means _unset_: the note names no art
@@ -453,10 +539,10 @@ export function resolveImg(raw, config = loadPackConfig()) {
     const s = String(raw);
     // Blank on purpose — the caller's default must not apply.
     if (s === "") return "";
-    if (s.startsWith("icons/") || s.startsWith("images/")) {
-        return `${config.assetRoot}/${s}`;
-    }
-    return s;
+    // Somebody else's to serve — emit it exactly as authored.
+    if (addressesAnotherPackage(s)) return s;
+    // Ours, so root it where Foundry serves this package's files from.
+    return `${config.assetRoot}/${s}`;
 }
 
 /**

package/engine/index.mjs

@@ -69,6 +69,9 @@ export * as notePackage from "./note-package.mjs";
 /** Frontmatter fields a note may no longer declare, and the refusal of them. */
 export * as retiredFields from "./retired-fields.mjs";
 
+/** Schema fields a note may never declare, because play writes them. */
+export * as runtimeOnlyFields from "./runtime-only-fields.mjs";
+
 /** The package homepage: the note type that compiles to a page, not a document. */
 export * as homepage from "./homepage.mjs";
 
@@ -113,6 +116,12 @@ export * as siteBuild from "./site-build.mjs";
 /** Address rules every content tree is linted against: shape, uniqueness, alias. */
 export * as contentLint from "./content-lint.mjs";
 
+/** The charset authored content is held to, so a book can choose its face. */
+export * as contentCharset from "./content-charset.mjs";
+
+/** Naming an interface icon in a note, without drawing one there. */
+export * as contentIcons from "./content-icons.mjs";
+
 /** Resolving every link in a tree, and the ones that land nowhere. */
 export * as contentLinks from "./content-links.mjs";
 

package/engine/item-compiler.mjs

@@ -66,6 +66,9 @@ import { documentSubtype, subtypeRow } from "./document-subtypes.mjs";
 // `system` verbatim, and `<system>.img` / `.effects` / `.flags` overriding
 // their shared top-level forms for this system alone (#58).
 import { blockField, blockProperty, claimedPaths, mergeSystemData } from "./system-block.mjs";
+// The other direction of the same declaration: a field the *document* writes in
+// play, which a note may not author and the builder does not emit (#330).
+import { assertNoRuntimeOnlyFields } from "./runtime-only-fields.mjs";
 
 /**
  * The description an item carries: a pointer to its **item doc**, the
@@ -113,6 +116,17 @@ export class SystemItemCompiler extends BasePackCompiler {
      */
     static requiresSystemBlock = true;
 
+    /**
+     * An Item carries an `img` — its icon — which this pass writes from the
+     * note's own path, falling back to the type's default art.
+     *
+     * `portrait` is **not** among them: a portrait is a being's sheet picture,
+     * and an item has nowhere to put one.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img"]);
+
     /**
      * The note-type → document-subtype map this pass compiles against.
      *
@@ -174,6 +188,29 @@ export class SystemItemCompiler extends BasePackCompiler {
         return !row || row.document === "Item";
     }
 
+    /**
+     * Refuse a note authoring one of its type's **runtime-only** fields (#330).
+     *
+     * A schema declares fields the document writes for itself — an affliction's
+     * `onsetDate` is the world time its onset fired at — and a note authoring
+     * one used to compile, because `<system>.system` is a verbatim passthrough
+     * and the field really is in the schema. The result was shipped content
+     * carrying one world's play state, with the build reporting success.
+     *
+     * The declaration says which, so nothing here knows a field name; see
+     * {@link module:engine/runtime-only-fields}.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {void}
+     * @throws {Error} When the note authors one.
+     */
+    assertAuthorable(fm) {
+        assertNoRuntimeOnlyFields(fm, itemFields(fm.type, this.system), {
+            block: this.system,
+            absPath: this.currentNote?.absPath,
+        });
+    }
+
     /**
      * The Foundry Item subtype a note compiles into.
      *

package/engine/journals.mjs

@@ -30,10 +30,13 @@
  * any other: the macro pass reads the same page independently, and withholds
  * nothing from the journal (#1514).
  *
- * Folder placement is identical to the items pack: `sohl.folder` in
- * frontmatter is the target folder's id (from folders.yaml), resolved
- * against a folders.yaml list via the constructor's `folderResolver`. A
- * documentation entry reuses its document's folder id verbatim.
+ * Folder placement is identical to the items pack: `sohl.packFolder` in
+ * frontmatter is a folder **note's address**, resolved through the shared
+ * address index by the constructor's `folderResolver` (#255, #260). A folder
+ * materialises in every pack holding a document that names it, so a journals
+ * pack needs to declare nothing (#257) — which is what stopped this pass
+ * filing documentation into folders its own pack had never heard of. A
+ * documentation entry reuses its document's folder verbatim.
  *
  * Not a standalone script — exports the `Journals` compiler class, imported
  * and driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
@@ -311,6 +314,20 @@ export class Journals extends BasePackCompiler {
      */
     static requiresId = false;
 
+    /**
+     * **None.** A JournalEntry has no artwork — no `img` property, and no
+     * nested place for one — so a note whose whole document is prose has
+     * nowhere to put an authored path (#349).
+     *
+     * The emptiness is the declaration, in the sense `JOURNAL_ONLY_FIELDS` is:
+     * it is what separates a pass that emits no art from one that has simply
+     * not said, and it is the fact the frontmatter lint reports a `lore` note's
+     * inert `img:` from.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze([]);
+
     /**
      * How many of the compiled entries were documentation for a document
      * compiled elsewhere, for the summary.

package/engine/macros.mjs

@@ -295,6 +295,14 @@ export class Macros extends BasePackCompiler {
      */
     static convertsWikilinks = false;
 
+    /**
+     * A Macro carries an `img` — the tile art Foundry shows on the hotbar —
+     * defaulting to {@link DEFAULT_MACRO_IMG} where the note names none.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img"]);
+
     /**
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True for a `macro` note.

package/engine/map-notes.mjs

@@ -56,9 +56,9 @@ import { compendiumUuid, makeId, MAP_SUBTYPES, MAP_TYPES } from "./ids.mjs";
 // bridge (`SohlRegionTriggerBehavior`), so an event this build accepts is
 // exactly one the bridge forwards.
 import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.mjs";
-// A map's background art is `img`, as every other note type's art is; `image`
-// is the retired spelling, still read through the retirement window (#142).
-import { readAliasedField } from "./retired-fields.mjs";
+// A map's background art is `img`, as every other note type's art is. `image`,
+// the spelling a map alone once used, is retired and gone (#149).
+import { sohlField } from "./frontmatter.mjs";
 
 /* -------------------------------------------------------------------- */
 /*  Note types and their canvas profiles                                */
@@ -907,7 +907,7 @@ export function buildScene(fm, ctx) {
     // Read from the note rather than from its `sohl:` block: art is not
     // system-specific, so `img` is authored at the top level like every other
     // type's, and `sohlField` honours the block for anything already there.
-    const img = readAliasedField(fm, "img");
+    const img = sohlField(fm, "img");
     if (!img) throw new Error("a map note needs an `img`");
 
     const warn = (message) => {
@@ -981,11 +981,11 @@ export function buildScene(fm, ctx) {
  * @param {string} sceneId - The owning scene's `_id`.
  * @param {string} [img] - The background art, already resolved from the note.
  *   Passed by {@link buildScene}, which reads it from the note rather than from
- *   the block; defaults to whichever spelling the block itself carries, so a
- *   direct two-argument call still works (#142).
+ *   the block; defaults to the block's own `img`, so a direct two-argument call
+ *   still works.
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl, sceneId, img = readAliasedField({ sohl }, "img")) {
+export function buildLevel(sohl, sceneId, img = sohlField({ sohl }, "img")) {
     const level = {
         _id: DEFAULT_LEVEL_ID,
         name: sohl.levelName ?? "Ground",