@heroiclands/package-build 18.2.0 → 20.0.0

package/CONTENT.md

@@ -85,7 +85,7 @@ paths:
 # order is worked out separately, from what each pass reads (see "Declaration
 # order is presentation" below).
 packs:
-  - { name: items, type: Item, label: Items, folders: item-folders.yaml }
+  - { name: items, type: Item, label: Items }
   - { name: journals, type: JournalEntry, label: Journals }
   # A companion is written by its parent's pass rather than one of its own.
   - name: scenes
@@ -96,7 +96,7 @@ packs:
   # A pack whose per-document JSON is already built — checked in rather than
   # generated. `prebuilt` names where it lives, generation is skipped for it,
   # and `cleanPackEntry` and the Scene/Level integrity check still run. It may
-  # not carry `folders`, `companions` or `default`, and may not be a companion:
+  # not carry `companions` or `default`, and may not be a companion:
   # each of those describes a generation pass a prebuilt pack does not have.
   # When every configured pack is prebuilt the content walk is skipped
   # entirely, so a package with no `assets/content` builds.
@@ -388,6 +388,24 @@ exactly once, here, and read through `loadPackConfig()` everywhere. There is one
 resolved set at runtime; the compilers and the link-manifest emitter cannot come
 to disagree about which notes carry documentation.
 
+**Every note compiling into a system-bearing document carries documentation, and
+that includes actors** (#337). `docEntryTypes` is `itemTypes` plus the actor
+types the shipped subtype maps declare (`ACTOR_TYPES`, derived from them rather
+than listed again), plus `macro` and the map types. Only `doc` is outside it, for
+the reason that actually applies to it: its single document _is_ the prose.
+
+A being therefore has the same two addresses an item has — `<pkg>-<system>-being-<shortcode>`
+for the Actor and `<pkg>-none-docbeing-<shortcode>` for the page — where before
+it had only the first, and was the one system-bearing note a prose link could not
+name.
+
+**An actor keeps its prose inline as well, and that asymmetry is deliberate.** An
+item's description is an `@UUID` pointer into its journal, because one item is
+embedded across hundreds of beings and baking long prose into every copy bloats
+the compendium by the length of the text times the number of carriers. An actor
+is singular, so the same indirection costs a reader a click and saves nothing:
+`system.appearance` and `system.dossier` stay as rendered prose.
+
 The Item compiler **dispatches through that same resolved table**, via
 `engine/item-registry.mjs` (`itemTypes()` and `itemBuilder(type)`), so the types a
 consumer's notes are accepted for and the builders they compile with are one
@@ -534,9 +552,46 @@ Both spellings are equal; the difference is only whether the type brings art.
 whitelist without a builder behind it.
 
 **The path is spelled the way a note spells it.** Registry art goes through the
-same `resolveImg` rule as a note's `img:`, so `icons/relic.svg` means _this_
-repository's asset root — `modules/sohl-relics/assets/icons/relic.svg` — and an
-already-served path (`systems/sohl/assets/icons/…`) passes through untouched.
+same `resolveImg` rule as a note's `img:`, so one spelling means one thing
+wherever it is written.
+
+#### An asset path's first segment says which package owns it
+
+Every authored asset path — a registry `img:`, a note's `img:`, an actor's
+`portrait:` — answers "which package holds this file?" in its **first segment**,
+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>` |
+
+`assetRoot` is derived, never authored: it is
+`<packageKind>/<foundryPackage>/assets`, and it is the one place `systems/sohl`
+(or `modules/sohl-thalorna`) is ever spelled. So `icons/relic.svg` in a module's
+registry compiles to `modules/sohl-relics/assets/icons/relic.svg`, and the same
+string in the system's compiles to `systems/sohl/assets/icons/relic.svg`. An
+already-served `systems/sohl/assets/icons/…` passes through untouched — which is
+what lets a module pair a SoHL default with one of its own types.
+
+**"Anything else" is the rule, not a list of directories.** A package owns its
+whole `assets/` tree, so a directory this toolchain has never heard of is still
+that package's: art under `assets/artwork/` is addressed `artwork/deity.webp`
+and rooted exactly as `icons/…` and `images/…` are. An address naming no package
+at all — an absolute URL, a `data:` URI, a `/`-rooted path — passes through, on
+the same rule rather than as an exception.
+
+`worlds/` is deliberately not exempt: a package may not ship art out of a world,
+so prefixing such a path produces a plainly broken one rather than a plausible
+one that 404s in Foundry unreported.
+
+**`banner:` is a path that does not follow this rule.** It reaches no compiled
+document; it is a top-level key the Hugo theme reads, and the theme prefixes a
+relative value with `images/` and joins it onto `params.cdnBaseURL`. The two
+address different places — `img:` a file Foundry serves, `banner:` a file the
+CDN serves — so they are stated apart rather than reconciled. See the
+[content format specification](docs/content-format.md#banner-addresses-the-cdn-not-the-foundry-install).
 
 #### "Names no art" and "wants no art" are different (#218)
 
@@ -570,12 +625,20 @@ rather than two.
 > (`sohl/item-fields.mjs`, "the style of address the office carries"), so one
 > authored key fed two unrelated destinations that disagreed about what empty
 > means — and `title: null` stringified into the compiled document as the literal
-> `"null"`. That collision is gone: the field declares `topLevelMeans`, and the
-> top-level key is no longer a source for it (#218).
+> `"null"`. The field declares `topLevelMeans` now, so the top-level key is no
+> longer a source for it (#218).
 >
-> So `title: null` is now a note declining to state a heading, and the site
-> emitter's `fm.title ?? name` falls back to `name.full`. `title: ""` still
-> publishes a deliberately blank heading, and nothing warns about that yet.
+> So `title: null` is a note declining to state a heading, and the site emitter's
+> `fm.title ?? name` falls back to `name.full`. `title: ""` publishes a
+> deliberately blank heading and is warned about on its own account — as the
+> page's heading, not as an art path.
+>
+> **That warning reads the note's top level only.** The two spellings still name
+> unrelated quantities, so a `sohl.title` — the office's style of address — must
+> not answer for the page's heading. Twenty-eight `sohl-kethira-basic`
+> affiliations write `sohl.title: ""`, meaning an office with no style of
+> address, and every one of them was reported as publishing a blank heading
+> until the check honoured the declaration (#312).
 
 Because `""` used to mean "unset", a note still carrying that spelling has
 quietly changed meaning, and the frontmatter lint says so — for either art
@@ -712,6 +775,14 @@ state the same quantity, which is nearly everywhere: `subType` is the other
 declared item field spelled like a note-level key, and there the two agree by
 design.
 
+**The statement is symmetric, and the frontmatter linter reads it from the other
+side too.** If the two positions hold unrelated quantities, then the _in-block_
+position is not the note-level field either — so a check about a note-level field
+(the page's heading, an art path) reads past a block key the note's own type
+claims for something else. Declaring `topLevelMeans` settles both directions at
+once; it was read for the emitted field alone until #312, which is how an
+affiliation's office style came to answer for its page heading.
+
 **An exempted field is still authorable**, at the two positions that describe the
 document rather than the note:
 

package/bin/content-build.mjs

@@ -136,7 +136,7 @@ import {
     locateAddressFinding,
     addressFindingMessage,
 } from "../engine/address-diff.mjs";
-import { itemPackJsonDirs } from "../engine/generate.mjs";
+import { emittedArtFor, itemPackJsonDirs } from "../engine/generate.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -799,6 +799,12 @@ function lintCommand() {
                     // the compile asks the map for whichever pack it is
                     // writing, and a companion is a pack it writes.
                     packs: config.packDirectories,
+                    // What art each type actually reaches its document through,
+                    // asked of the passes rather than listed here (#349). This
+                    // is the one place that decides what a tree is held to, so
+                    // it is where the derivation is handed over — the linter
+                    // states no list of iconless types of its own.
+                    emittedArt: emittedArtFor,
                     references: argv.references,
                 });
 

package/ci/ci-docker.mjs

@@ -110,6 +110,27 @@ function exportHead() {
     }
     const untar = spawnSync("tar", ["-x", "-C", dir], { input: archive.stdout });
     if (untar.status !== 0) throw new Error("could not unpack the export");
+
+    // Make the export a repository. `git archive` yields a bare directory, and
+    // a workflow step that shells out to git — `git ls-files` in a
+    // tracked-artifact check, say — then fails for want of a `.git`, which
+    // reads as the check failing rather than as this harness lacking something
+    // the runner has. GitHub's own step is a *checkout*, so the faithful export
+    // is one too.
+    //
+    // Initialised and staged rather than committed: `git ls-files` lists the
+    // index, so staging every extracted file reproduces exactly the set the
+    // runner would see, without needing an identity configured to commit with.
+    const init = spawnSync("git", ["init", "-q"], { cwd: dir });
+    if (init.status === 0) {
+        spawnSync("git", ["add", "-A"], { cwd: dir });
+    } else {
+        console.error(
+            "ci-docker: NOTE — could not make the export a git repository, so a " +
+                "workflow step that shells out to git will fail here in a way it " +
+                "would not on the runner.",
+        );
+    }
     return dir;
 }
 

package/content-config.mjs

@@ -27,7 +27,7 @@
  * itemBuilders: sohl
  * skipDirectories: [Templates]
  * packs:
- *     - { name: items, type: Item, folders: item-folders.yaml }
+ *     - { name: items, type: Item }
  *     - { name: journals, type: JournalEntry, label: Journals }
  * packageBuild:
  *     assets:
@@ -69,6 +69,7 @@ import path from "node:path";
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
 import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
+import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "./engine/note-vocabulary.mjs";
 
 /**
@@ -258,9 +259,6 @@ export function publishesContentPages(config) {
  * @property {PackDocumentType} type    Foundry document type the pack holds.
  * @property {string} [label]           Human-readable label. Defaults to `name`.
  * @property {boolean} [private]        Whether the pack is GM-only. Default `false`.
- * @property {string|null} [folders]    The pack's folder-hierarchy file, relative
- *                                      to `paths.content`. Default `null` — no
- *                                      folder documents are emitted.
  * @property {string} [prebuilt]        Directory holding this pack's per-document
  *                                     JSON, already built. Declaring it skips
  *                                     generation for the pack and compiles from
@@ -295,7 +293,6 @@ export function publishesContentPages(config) {
  * @property {PackDocumentType} type
  * @property {string} label
  * @property {boolean} private
- * @property {string|null} folders
  * @property {string|null} prebuilt
  * @property {string|null} system
  * @property {readonly Readonly<ResolvedPackSpec>[]} companions
@@ -658,7 +655,6 @@ const PACK_KEYS = [
     "type",
     "label",
     "private",
-    "folders",
     "companions",
     "mayBeEmpty",
     "default",
@@ -854,6 +850,19 @@ function optionalString(value, field) {
 function normalizePack(value, where, nested = false) {
     if (!isPlainObject(value)) fail(where, "must be an object");
     const pack = /** @type {Record<string, unknown>} */ (value);
+    // Retired with the YAML it named (#260). Refused explicitly rather than
+    // left to the unknown-key check, because the useful thing to say is not
+    // "no such key" but where the folders went: they are notes, and a pack
+    // materialises the ones its documents reference.
+    if (pack.folders !== undefined) {
+        fail(
+            `${where}.folders`,
+            "is retired — delete it. A folder is a note (`type: folder`) now, " +
+                "and a pack materialises the folders its documents reference " +
+                "through `packFolder`, so there is no per-pack hierarchy file " +
+                "to name",
+        );
+    }
     rejectUnknownKeys(pack, PACK_KEYS, `${where}.`);
 
     const name = requireNonEmptyString(pack.name, `${where}.name`);
@@ -865,10 +874,6 @@ function normalizePack(value, where, nested = false) {
         fail(`${where}.type`, `must be one of: ${PACK_DOCUMENT_TYPES.join(", ")}`);
     }
 
-    if (pack.folders !== undefined && pack.folders !== null) {
-        requireNonEmptyString(pack.folders, `${where}.folders`);
-    }
-
     const companionsInput = pack.companions;
     if (companionsInput !== undefined && !Array.isArray(companionsInput)) {
         fail(`${where}.companions`, "must be an array");
@@ -893,8 +898,8 @@ function normalizePack(value, where, nested = false) {
 
     // A prebuilt pack's per-document JSON already exists, so it has no
     // generation pass. Every key below describes one, which is why none of them
-    // may accompany it: silently ignoring a `folders` file that can never be
-    // read is worse than refusing the configuration that declares it.
+    // may accompany it: silently ignoring a key that can never be read is
+    // worse than refusing the configuration that declares it.
     const prebuilt =
         pack.prebuilt === undefined || pack.prebuilt === null ?
             null
@@ -907,13 +912,6 @@ function normalizePack(value, where, nested = false) {
                     "another pack's pass, and a prebuilt pack has no pass",
             );
         }
-        if (pack.folders !== undefined && pack.folders !== null) {
-            fail(
-                `${where}.folders`,
-                "may not accompany `prebuilt`: the folder hierarchy is built " +
-                    "during generation, which a prebuilt pack skips",
-            );
-        }
         if (Array.isArray(companionsInput) && companionsInput.length) {
             fail(
                 `${where}.companions`,
@@ -946,10 +944,6 @@ function normalizePack(value, where, nested = false) {
         label:
             pack.label === undefined ? name : requireNonEmptyString(pack.label, `${where}.label`),
         private: optionalBoolean(pack.private, `${where}.private`, false),
-        folders:
-            pack.folders === undefined || pack.folders === null ?
-                null
-            :   /** @type {string} */ (pack.folders),
         companions: Object.freeze(companions),
         mayBeEmpty: optionalBoolean(pack.mayBeEmpty, `${where}.mayBeEmpty`, false),
         // Which pack of a type receives a note that declares none. Validated
@@ -1960,7 +1954,15 @@ export function defineConfig(config) {
     // holds every key any of them declares, so this stays "the registry's keys"
     // rather than becoming a second list to keep in step (#1504).
     const itemTypes = Object.freeze(new Set(Object.keys(itemBuilders)));
-    const docEntryTypes = Object.freeze(new Set([...itemTypes, "macro", ...MAP_TYPES]));
+    // Every note that compiles into a *system-bearing* document publishes its
+    // prose as a documentation JournalEntry, and that includes actors (#337).
+    // A being was the one such note with no `none` address — its only address
+    // named the Actor — so nothing a prose link wrote could land on its page.
+    // `doc` stays out for the reason that actually applies to it: its single
+    // document *is* the prose.
+    const docEntryTypes = Object.freeze(
+        new Set([...itemTypes, ...ACTOR_TYPES, "macro", ...MAP_TYPES]),
+    );
 
     return Object.freeze({
         rootDir,