@heroiclands/package-build 22.21.0 → 22.23.0

package/docs/reference/note-types.md

@@ -11,18 +11,35 @@ Choose a note's `type` for the subject it describes. Use `subType` when its type
 
 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                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `shortcode`   | The note's own address segment, unique within its type.                                   |
+| `name`        | The display names — a required `full`, and any `aliases`.                                 |
+| `type`        | What the note is about, which decides its vocabulary and its document.                    |
+| `subType`     | The type's own genre, where it declares one.                                              |
+| `description` | The short page summary.                                                                   |
+| `tags`        | Draft state, GM routing, and the descriptive labels a page list reads.                    |
+| `data`        | The facts about the subject itself, shared by every system.                               |
+| `dnd5e`       | What the `dnd5e` system makes of the subject — its document's mechanics, routing and art. |
+| `hm3`         | What the `hm3` system makes of the subject — its document's mechanics, routing and art.   |
+| `sohl`        | What the `sohl` system makes of the subject — its document's mechanics, routing and art.  |
+
 ## 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.
 
-| Field             | Shape                                           | Meaning                                                                   |
-| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
-| `data.id`         | string                                          | A fixed document identity when the derived identity is unsuitable.        |
-| `data.pack`       | string                                          | The shared compendium route, with a system block overriding it.           |
-| `data.packFolder` | an Address, or a map of Addresses keyed by pack | The shared compendium folder Address, with a system block overriding it.  |
-| `data.harnworld`  | map                                             | HârnWorld source details shared by every system.                          |
-| `data.icon`       | an Address                                      | The document's profile art — an `icon` address, resolved into `img`.      |
-| `data.banner`     | an Address                                      | The page's hero image — an `image` address. Reaches no compiled document. |
+| Field             | Shape                                           | Meaning                                                                                    |
+| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `data.id`         | string                                          | A fixed document identity when the derived identity is unsuitable.                         |
+| `data.pack`       | string                                          | The shared compendium route, with a system block overriding it.                            |
+| `data.packFolder` | an Address, or a map of Addresses keyed by pack | The shared compendium folder Address, with a system block overriding it.                   |
+| `data.harnworld`  | map                                             | HârnWorld source details shared by every system.                                           |
+| `data.icon`       | an Address                                      | The document's profile art — an `icon` address, resolved into `img`.                       |
+| `data.banner`     | an Address                                      | The page's hero image — an `image` address, cut to 1792×768. Reaches no compiled document. |
 
 ## Type-specific fields
 
@@ -41,9 +58,9 @@ These fields are accepted by every note type. A field's value can still be irrel
 | `data.lore`                      | list of Addresses                                       | Lore concerning this being — the law it lives under, the customs it is subject to, the traditions it was raised in.                                                                                                                                                                                                                                                                                                                 |
 | `data.culture`                   | an Address                                              | The being's primary culture, as a culture lore note.                                                                                                                                                                                                                                                                                                                                                                                |
 | `data.homes`                     | list of Addresses                                       | Places the being calls home.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `data.affiliations`              | a standing map keyed by Address, or a list of Addresses | Bodies the being belongs to, keyed by Address, each entry holding the standing it holds there — `rank`, a level on that body's own ladder, and `office`, a post that body names.                                                                                                                                                                                                                                                    |
+| `data.affiliations`              | a standing map keyed by Address, or a list of Addresses | Bodies the being belongs to, keyed by Address, each entry holding the standing it holds there — `rank`, required, a level on that body's own ladder, and `office`, optional, a post that body names.                                                                                                                                                                                                                                |
 | `data.socialTies`                | a map keyed by Address                                  | Defining ties directed from this being to others: `patron` (Supports the subject from greater power, wealth, or status.); `friend` (Supports the subject out of goodwill.); `dependent` (Relies on the subject's support or protection.); `acquaintance` (Knows the subject without a strong disposition.); `rival` (Opposes the subject without implacable hostility.); `nemesis` (Opposes the subject personally and implacably.) |
-| `data.gender`                    | string                                                  | `male`, `female` or `other`.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `data.gender`                    | string                                                  | One of `male`, `female`, `nonbinary`, `none` or `other`. `none` says the being has no gender; an absent field says its gender is unrecorded.                                                                                                                                                                                                                                                                                        |
 | `data.species`                   | an Address                                              | The being's species, as a lore note.                                                                                                                                                                                                                                                                                                                                                                                                |
 | `data.born`                      | string                                                  | When the being was born — a date, or `unknown` where the birth is unrecorded. Absent, the being was never born.                                                                                                                                                                                                                                                                                                                     |
 | `data.calendar`                  | an Address                                              | Calendar used to display this being's dates.                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -52,11 +69,11 @@ These fields are accepted by every note type. A field's value can still be irrel
 | `data.ageYears`                  | number                                                  | Written by the compiler beside an `age` estimate — the `~` stripped, the magnitude alone. A note never authors this.                                                                                                                                                                                                                                                                                                                |
 | `data.height`                    | metres or feet and inches                               | Height in metres or feet and inches.                                                                                                                                                                                                                                                                                                                                                                                                |
 | `data.weight`                    | kilograms or pounds                                     | Body weight in kilograms or pounds.                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `data.frame`                     | string                                                  | Relative frame — `scant`, `light`, `medium`, `large` or `massive`.                                                                                                                                                                                                                                                                                                                                                                  |
+| `data.frame`                     | string                                                  | Relative frame — one of `scant`, `light`, `medium`, `heavy` or `massive`.                                                                                                                                                                                                                                                                                                                                                           |
 | `data.appearance.eye_color`      | string                                                  | Eye colour.                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `data.appearance.hair_color`     | string                                                  | Hair colour.                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `data.appearance.skin_color`     | string                                                  | Skin colour.                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `data.appearance.complexion`     | string                                                  | Complexion.                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `data.appearance.complexion`     | string or list                                          | The skin's condition — one value, or several, because a face carries more than one at once. A single value means a list of one.                                                                                                                                                                                                                                                                                                     |
 | `data.appearance.extra_features` | list                                                    | Anything else a stranger would notice.                                                                                                                                                                                                                                                                                                                                                                                              |
 
 **System mappings**
@@ -415,7 +432,7 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 | `data.namedDays` | list of `{ name, abbreviation?, day }`                                              | Names assigned to particular days of the year.                                                                                       |
 | `data.eras`      | list of `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, label? }` | The year-counts kept in this calendar. A marker names one era and uses these months.                                                 |
 | `data.formats`   | map of named Calendaria format strings                                              | Named patterns for reading and writing this calendar's dates.                                                                        |
-| `data.event`     | event metadata map                                                                  | A dated occurrence and its relationships to other events and places.                                                                 |
+| `data.events`    | list of `{ when, until?, recurs? }`                                                 | This note's dated occurrences — a founding once, an anniversary that recurs, or a list of recorded happenings.                       |
 
 ### map
 

package/engine/actor-compiler.mjs

@@ -56,6 +56,7 @@ import { emitDiagnostic } from "./diagnostics.mjs";
 // The `{#appearance}` / `{#dossier}` convention is the note format's, so the
 // extraction is shared; which field a section lands in stays the system's.
 export { extractAnchorSection, renderSection } from "./anchored-sections.mjs";
+import { misplacedAnchorSection } from "./anchored-sections.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { beingDefaultArt } from "./art-fields.mjs";
 import { contentPackage } from "./content-package.mjs";
@@ -472,6 +473,28 @@ export class SystemActorCompiler extends BasePackCompiler {
         return { img, token: this.artPath(fm, "tokenIcon") ?? img };
     }
 
+    /**
+     * Report an `{#appearance}` or `{#dossier}` anchor on a heading
+     * {@link extractAnchorSection} cannot read, rather than letting the field
+     * it feeds compile blank with nothing to say why.
+     *
+     * @param {string} body - The note body.
+     * @param {string} anchorId - `"appearance"` or `"dossier"`.
+     * @param {string} ctx - The actor's label, for the message.
+     * @returns {void}
+     */
+    checkAnchoredSection(body, anchorId, ctx) {
+        const misplaced = misplacedAnchorSection(body, anchorId, this.currentNote?.bodyLine);
+        if (!misplaced) return;
+        this.noteError(
+            `${ctx}: {#${anchorId}} sits on a heading below the top level, and only ` +
+                `an H1 feeds the ${anchorId} field — move the heading to the top level ` +
+                "or drop the anchor",
+            { line: misplaced.line },
+        );
+        this.errorCount++;
+    }
+
     /**
      * Which `(actor, subType:identity)` each resolved entry claimed, and the
      * entry that claimed it first.

package/engine/anchored-sections.mjs

@@ -15,8 +15,8 @@
  * **Anchored body sections** — the `# Heading {#anchor}` convention, and how a
  * compiler pulls one section out of a note's prose.
  *
- * The content format gives three anchors a document meaning: `{#appearance}`,
- * `{#dossier}` and `{#spoilers}`. *Which field* each lands in is a system's
+ * The content format gives two anchors a document meaning: `{#appearance}` and
+ * `{#dossier}`. *Which field* each lands in is a system's
  * business — SoHL writes the first to an actor's `appearance`, HM3 to an
  * actor's and an item's `description` — but *finding* it is not, so the
  * extraction lives here where every compiler reaches it.
@@ -30,6 +30,8 @@
  */
 
 import { renderFoundryMarkdown } from "./helpers.mjs";
+import { collectAnchors } from "./anchors.mjs";
+import { splitHeadingAttributes } from "./heading-attributes.mjs";
 
 /**
  * Extract the body of an H1 section whose heading carries the explicit
@@ -39,6 +41,11 @@ import { renderFoundryMarkdown } from "./helpers.mjs";
  * heading exists. Fenced code blocks are respected so `# foo` inside
  * ``` blocks does not trigger a match.
  *
+ * An anchor declared on a lower heading is found by {@link collectAnchors}
+ * but not by the `#\s+` match below, so it extracts as absent rather than as
+ * wrong — {@link misplacedAnchorSection} is the check a caller runs first to
+ * tell the two apart.
+ *
  * @param {string} body - The note body.
  * @param {string} anchorId - The anchor to find.
  * @returns {string} The section's markdown, or "".
@@ -57,8 +64,7 @@ export function extractAnchorSection(body, anchorId) {
         }
         const h1Match = !inCodeBlock ? line.match(/^\s*#\s+(.+?)\s*#*\s*$/) : null;
         if (h1Match) {
-            const anchor = h1Match[1].match(/\{#([^}]+)\}\s*$/);
-            const id = anchor?.[1]?.trim().toLowerCase() || null;
+            const id = splitHeadingAttributes(h1Match[1]).id.toLowerCase() || null;
             if (capturing) break;
             if (id === wanted) {
                 capturing = true;
@@ -81,3 +87,28 @@ export function renderSection(body, anchorId) {
     const slice = extractAnchorSection(body, anchorId);
     return slice ? renderFoundryMarkdown(slice) : "";
 }
+
+/**
+ * Where an `{#appearance}` or `{#dossier}` anchor sits on a heading below the
+ * top level, which {@link extractAnchorSection} cannot read.
+ *
+ * {@link module:engine/anchors.collectAnchors} finds the anchor at any
+ * level, because a lower heading legitimately starts a journal page. It does
+ * not feed an actor field: an H1-only extractor reads nothing from one, and a
+ * caller that trusts the empty result as "no such section" rather than
+ * "found, but unreadable" compiles a blank field with nothing to say why.
+ *
+ * @param {string} body - The note body.
+ * @param {string} anchorId - The anchor to check, case-insensitively.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on.
+ * @returns {{line: number}|null} The misplaced anchor's line, or `null` when
+ *   it is absent or already on an H1.
+ */
+export function misplacedAnchorSection(body, anchorId, bodyLine = 1) {
+    const wanted = String(anchorId).toLowerCase();
+    const found = collectAnchors(body, bodyLine).find(
+        (anchor) => anchor.slug.toLowerCase() === wanted,
+    );
+    if (!found || found.level === 1) return null;
+    return { line: found.line };
+}

package/engine/anchors.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The anchors a note declares on headings and captioned blocks.
+ * The anchors a note declares on headings and figure fences.
  *
  * **A leaf, deliberately.** This is asked by the link checker, by the content
  * index, and by the builds that emit a link, and they cannot all import one
@@ -22,37 +22,35 @@
  * anchors does this note declare?" had two answers and they disagreed on
  * `{#CalendarFormat}`.
  *
+ * The suffix itself is read by {@link module:engine/heading-attributes}, which
+ * {@link module:engine/journals.splitPages} also reads it through — so the index
+ * cannot name an anchor the pages do not carry.
+ *
  * @module
  */
 
-import { scanCaptions } from "./content-captions.mjs";
+import { scanFigures } from "./content-figures.mjs";
+import { HEADING_LINE, splitHeadingAttributes } from "./heading-attributes.mjs";
 
 /**
- * A heading, and the `{#slug}` anchor it declares.
+ * The `{#slug}` and `:::figure {#slug}` anchors a note declares.
  *
- * Kept identical to the pair {@link splitPages} matches, because the two must
- * agree about what an anchor is: that pass decides which sections become
- * addressable journal pages, and an index naming an anchor it does not produce
- * would advertise a link that resolves nowhere. `tests/content-index.test.ts`
- * asserts the two find the same anchors, so drift fails the suite rather than
- * shipping.
- */
-const HEADING = /^\s*(#{1,6})\s+(.+?)\s*#*\s*$/;
-const ANCHOR = /^(.*?)\s*\{#([^}]+)\}\s*$/;
-/**
- * The `{#slug}` and `:::caption {#slug}` anchors a note declares.
- *
- * A bare `#` heading starts a journal page without declaring a slug. Captioned
- * blocks declare a slug and start an addressable journal page.
+ * A bare `#` heading starts a journal page without declaring a slug, and so
+ * does a figure fence that declares no id. A fence that declares one declares a
+ * slug and starts an addressable journal page.
  *
  * @param {string} body - The note's markdown body, frontmatter already removed.
  * @param {number} [bodyLine] - The 1-based file line the body starts on, from
  *   `parseMarkdownFile`. Anchors are reported at their position in the **file**,
  *   so an editor can jump straight to one; passing nothing numbers from the body.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares, so a figure anchor's
+ *   `name` reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Array<{slug: string, name: string, level: number, line: number}>}
  *   In document order.
  */
-export function collectAnchors(body, bodyLine = 1) {
+export function collectAnchors(body, bodyLine = 1, resolveRole) {
     const anchors = [];
     let inCodeBlock = false;
     const lines = String(body ?? "").split("\n");
@@ -66,26 +64,24 @@ export function collectAnchors(body, bodyLine = 1) {
         }
         if (inCodeBlock) continue;
 
-        const heading = HEADING.exec(lines[i]);
+        const heading = HEADING_LINE.exec(lines[i]);
         if (!heading) continue;
-        const anchor = ANCHOR.exec(heading[2].trim());
-        if (!anchor) continue;
-
-        const slug = anchor[2].trim();
-        if (!slug) continue;
+        const attributes = splitHeadingAttributes(heading[2]);
+        if (!attributes.id) continue;
         anchors.push({
-            slug,
-            name: anchor[1].trim(),
+            slug: attributes.id,
+            name: attributes.text,
             level: heading[1].length,
             line: bodyLine + i,
         });
     }
-    for (const caption of scanCaptions(body).captions) {
+    for (const figure of scanFigures(body, { resolveRole }).figures) {
+        if (!figure.id) continue;
         anchors.push({
-            slug: caption.id,
-            name: caption.label,
+            slug: figure.id,
+            name: figure.label,
             level: 1,
-            line: bodyLine + caption.line - 1,
+            line: bodyLine + figure.line - 1,
         });
     }
     return anchors.sort((a, b) => a.line - b.line);

package/engine/art-fields.mjs

@@ -44,6 +44,8 @@
  * @module
  */
 
+import path from "node:path";
+
 import { encodeAddresses } from "./address-values.mjs";
 import { ASSET_SYSTEM, isAssetType } from "./asset-types.mjs";
 import { ASSETS_SEGMENT } from "./pathnames.mjs";
@@ -129,9 +131,49 @@ export function assetAddressIndex(records = [], { config, foreign, types = [] }
                 .filter(([key]) => key),
         ),
         foreign: foreign?.index ?? new Map(),
+        // Foreign first, local last: a renderer sizing a picture looks it up
+        // by the pathname the record resolved to, never by address, and a
+        // local record is entered after a foreign one so it wins the lookup on
+        // the collision neither should ever cause.
+        byPath: assetImageInfoByPathname([
+            ...(foreign?.index?.values() ?? []),
+            ...records.filter(isAssetRecord),
+        ]),
     };
 }
 
+/**
+ * What a renderer needs to size one picture, keyed by the pathname its
+ * address resolves to.
+ *
+ * An image reaches a renderer as the resolved pathname an embed or an authored
+ * body image already carries — see {@link readAssetAddress} — never as the
+ * address that produced it, so the lookup a renderer wants is by pathname, not
+ * by {@link assetAddressIndex}'s own `assets` map.
+ *
+ * @param {readonly object[]} records - Asset records, local or foreign.
+ * @returns {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ *   One entry per addressable file, carrying only what a renderer sizes a
+ *   picture from. `role` is omitted when the record states none; `width` and
+ *   `height` are always present, blank (`""`) for a vector — the record's own
+ *   convention, carried through rather than collapsed into an absence a
+ *   renderer could not tell apart from "no asset resolved at all".
+ */
+export function assetImageInfoByPathname(records = []) {
+    const map = new Map();
+    for (const record of records) {
+        if (!record?.asset?.path || !record.package) continue;
+        const key = `${record.package}/${ASSETS_SEGMENT}/${record.asset.path}`;
+        map.set(key, {
+            type: record.type,
+            role: record.asset.role || undefined,
+            width: typeof record.asset.width === "number" ? record.asset.width : "",
+            height: typeof record.asset.height === "number" ? record.asset.height : "",
+        });
+    }
+    return map;
+}
+
 /**
  * The asset one authored value names, or why it names none.
  *
@@ -200,6 +242,82 @@ export function resolveArtRecord(index, value, defaultType, accepts) {
     return readAssetAddress(index, value, defaultType, accepts).record;
 }
 
+/**
+ * Every asset's role, keyed by the pathname it resolves to — the form a body
+ * carries once an embed's address has been rewritten into the ordinary image
+ * every surface renders ({@link module:engine/content-embeds.resolveEmbeds}).
+ *
+ * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` —
+ * for a caller that reads a body after that rewrite: a Foundry journal, an
+ * item or actor's documentation, and the book.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @returns {Map<string, string>} Pathname → role, one entry per asset that
+ *   declares one.
+ */
+export function pathnameRoles(index) {
+    const roles = new Map();
+    for (const record of [
+        ...(index?.assets?.values() ?? []),
+        ...(index?.foreign?.values() ?? []),
+    ]) {
+        const role = record?.asset?.role;
+        if (!role || !record.asset?.path || !record.package) continue;
+        roles.set(`${record.package}/${ASSETS_SEGMENT}/${record.asset.path}`, role);
+    }
+    return roles;
+}
+
+/**
+ * Flag a note whose art slot names a picture that is not the size that slot
+ * is cut to.
+ *
+ * The size is stated by the slot itself, in
+ * {@link module:engine/art-slots.ART_SLOTS}, so it is written once and a slot
+ * that states none asks nothing of the picture it names. Today the hero image
+ * is the one slot with a fixed strip to fill; a picture written in prose is
+ * fitted to the room it has and is never measured here.
+ *
+ * A vector carries no pixel size to compare, and neither does a raster whose
+ * header cannot be read; neither is flagged.
+ *
+ * @param {readonly object[]} records - The corpus, notes and assets together.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {string} [opts.assetsBase] - Where the asset roots sit, so a finding
+ *   names the file from the working directory as every other finding does.
+ * @returns {object[]} A finding per picture off its slot's size,
+ *   `severity: "error"`.
+ */
+export function checkArtSlotSizes(records = [], { config, assetsBase = "" } = {}) {
+    const sized = ART_SLOTS.filter((slot) => slot.size);
+    if (!sized.length) return [];
+    const index = assetAddressIndex(records, { config });
+    const findings = [];
+    for (const record of records) {
+        const data = record?.data;
+        if (!data) continue;
+        for (const slot of sized) {
+            const value = data[slot.key];
+            if (!value) continue;
+            const asset = resolveArtRecord(index, value, slot.type, slot.accepts);
+            const { path: file, width, height } = asset?.asset ?? {};
+            if (!file || !width || !height) continue;
+            if (Number(width) === slot.size.width && Number(height) === slot.size.height) continue;
+            findings.push({
+                file: path.join(assetsBase, file),
+                severity: "error",
+                message:
+                    `${width}×${height} is not the ${slot.size.width}×${slot.size.height} ` +
+                    `a \`${slot.key}\` is cut to`,
+            });
+        }
+    }
+    return findings;
+}
+
 /**
  * The pathname an art value names, in the form an authored one takes.
  *

package/engine/art-slots.mjs

@@ -76,6 +76,12 @@ export const ART_SLOTS = Object.freeze([
         type: "image",
         accepts: ART_TYPES,
         document: false,
-        describe: "The page's hero image. Reaches no compiled document.",
+        // A hero image fills one fixed strip wherever it is drawn, so every
+        // banner is cut to one size and a picture of another size is resized
+        // to it. A picture written in prose fills no fixed strip and is
+        // fitted to whatever room it has, so no slot but this one states a
+        // size.
+        size: Object.freeze({ width: 1792, height: 768 }),
+        describe: "The page's hero image, cut to 1792×768. Reaches no compiled document.",
     }),
 ]);