@heroiclands/package-build 22.28.0 → 23.1.0

package/engine/exported-scene.mjs

@@ -128,32 +128,45 @@ function applyFixups(scene, fixups, resolveAddress) {
     }
 }
 
-/** Add a compendium key to one exported embedded document. */
-function keyDocument(doc, collection, parentIds, sceneId) {
-    if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
-        throw new Error(`data.scene.${collection} contains a non-document value`);
-    }
-    if (!/^[A-Za-z0-9]{16}$/.test(doc._id ?? "")) {
-        throw new Error(`data.scene.${collection} needs a 16-character _id on every document`);
+/**
+ * Add a compendium key to every embedded document that carries an `_id`.
+ *
+ * The keys are what the compendium CLI splits embedded documents by. A value
+ * that is not a document, or one carrying no `_id`, passes through as exported.
+ *
+ * @param {unknown} docs - One embedded collection, as exported.
+ * @param {string} collection - Its key path, such as `regions.behaviors`.
+ * @param {string[]} parentIds - The ids of the documents it is embedded in.
+ * @param {string} sceneId - The Scene's derived id.
+ * @returns {void}
+ */
+function keyDocuments(docs, collection, parentIds, sceneId) {
+    if (!Array.isArray(docs)) return;
+    for (const doc of docs) {
+        if (!doc || typeof doc !== "object" || Array.isArray(doc)) continue;
+        if (typeof doc._id !== "string" || !doc._id) continue;
+        doc._key = `!scenes.${collection}!${[sceneId, ...parentIds, doc._id].join(".")}`;
+        if (collection === "regions") {
+            keyDocuments(doc.behaviors, "regions.behaviors", [doc._id], sceneId);
+        }
     }
-    doc._key = `!scenes.${collection}!${[sceneId, ...parentIds, doc._id].join(".")}`;
 }
 
 /**
  * Compile a Foundry Scene export into a pack document.
  *
- * Only the note-derived Scene ID, compendium metadata, and pins marked
- * `#anchor` change. Every other authored Scene field passes through.
+ * The Scene passes through as exported. Only the note-derived Scene ID,
+ * compendium metadata, `data.fixup` and pins marked `#anchor` change; nothing
+ * else inside the Scene is read or checked.
  *
  * @param {object} fm - The map note's frontmatter.
  * @param {string} markdown - Its converted Markdown body.
  * @param {{journalEntryId?: string, stats?: object, resolveAddress?: Function}} [opts] - Pack metadata, derived JournalEntry ID, and asset resolver.
  * @returns {object} The keyed Scene document.
+ * @throws {Error} When `data.scene` is not an object, or a fixup or pin anchor
+ *   names something the Scene or the note does not have.
  */
 export function buildExportedScene(fm, markdown, { journalEntryId, stats, resolveAddress } = {}) {
-    if (!["battlemap", "localmap"].includes(fm.subType)) {
-        throw new Error("`data.scene` is for battlemap and localmap notes");
-    }
     const source = fm.data?.scene;
     if (!source || typeof source !== "object" || Array.isArray(source)) {
         throw new Error("a map note needs a Foundry Scene object at `data.scene`");
@@ -163,48 +176,10 @@ export function buildExportedScene(fm, markdown, { journalEntryId, stats, resolv
     }
     const scene = structuredClone(source);
     applyFixups(scene, fm.data?.fixup, resolveAddress);
-    if (
-        !(Number.isInteger(scene.width) && scene.width > 0) ||
-        !(Number.isInteger(scene.height) && scene.height > 0)
-    ) {
-        throw new Error("`data.scene` needs positive whole-number width and height");
-    }
-    if (!Array.isArray(scene.levels) || scene.levels.length === 0) {
-        throw new Error("`data.scene.levels` needs at least one Level");
-    }
     scene._id = fm.id;
     scene._key = `!scenes!${fm.id}`;
     if (stats) scene._stats = stats;
-
-    for (const collection of EMBEDDED) {
-        const docs = scene[collection];
-        if (docs === undefined) continue;
-        if (!Array.isArray(docs)) {
-            throw new Error(`data.scene.${collection} must be an array`);
-        }
-        const ids = new Set();
-        for (const doc of docs) {
-            keyDocument(doc, collection, [], fm.id);
-            if (ids.has(doc._id))
-                throw new Error(`data.scene.${collection} repeats _id ${doc._id}`);
-            ids.add(doc._id);
-            if (collection !== "regions" || doc.behaviors === undefined) continue;
-            if (!Array.isArray(doc.behaviors)) {
-                throw new Error("data.scene.regions.behaviors must be an array");
-            }
-            const behaviorIds = new Set();
-            for (const behavior of doc.behaviors) {
-                keyDocument(behavior, "regions.behaviors", [doc._id], fm.id);
-                if (behaviorIds.has(behavior._id)) {
-                    throw new Error(`data.scene.regions.behaviors repeats _id ${behavior._id}`);
-                }
-                behaviorIds.add(behavior._id);
-            }
-        }
-    }
-    if (scene.initialLevel && !scene.levels.some((level) => level._id === scene.initialLevel)) {
-        throw new Error(`data.scene.initialLevel "${scene.initialLevel}" names no Level`);
-    }
+    for (const collection of EMBEDDED) keyDocuments(scene[collection], collection, [], fm.id);
 
     const pages = new Map();
     for (const page of splitPages(markdown, fm.name?.full ?? scene.name)) {
@@ -214,7 +189,8 @@ export function buildExportedScene(fm, markdown, { journalEntryId, stats, resolv
         }
         pages.set(page.anchorSlug, page);
     }
-    for (const pin of scene.notes ?? []) {
+    for (const pin of Array.isArray(scene.notes) ? scene.notes : []) {
+        if (!pin || typeof pin !== "object") continue;
         const match = /^#([A-Za-z0-9][A-Za-z0-9_-]*)$/.exec(String(pin.text ?? ""));
         if (!match) continue;
         const page = pages.get(match[1]);

package/engine/frontmatter-lint.mjs

@@ -55,6 +55,8 @@
  */
 
 import { isAddressTuple } from "./address.mjs";
+import { listed, nearest } from "./near-miss.mjs";
+import { checkDataKeys } from "./data-keys.mjs";
 import {
     authoredNoteKeys,
     CHARACTER_NAME_KEYS,
@@ -62,7 +64,8 @@ import {
     NOTE_TOP_LEVEL_KEY_SET,
     NOTE_TOP_LEVEL_KEYS,
 } from "./note-frontmatter.mjs";
-import { AddressEntries } from "./address-values.mjs";
+import { AddressEntries, AddressLink } from "./address-values.mjs";
+import { resolveEventReference } from "./note-events.mjs";
 import { addressPositions } from "./note-addresses.mjs";
 import { authoredFields, readsLegacyKey, readsRetiredTopLevel } from "./field-spec.mjs";
 import {
@@ -74,11 +77,15 @@ import {
     SYSTEM_BLOCK_KEYS,
     unknownBlockKeys,
 } from "./system-block.mjs";
-import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
+import {
+    frontmatterValueAt,
+    positionInFrontmatter,
+    positionOfFrontmatterPath,
+} from "./diagnostics.mjs";
 import { pathnameProblem } from "./pathnames.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES, RENAMED_TYPES, currentType, renamedTypeMessage } from "./ids.mjs";
-import { parseAddress, acceptsType, renderAddress } from "./address.mjs";
+import { parseAddress, acceptsType, renderAddress, hasAnchor } from "./address.mjs";
 import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
 // The one place the "every pack not named" key is spelled. Imported rather
@@ -88,7 +95,6 @@ import { DEFAULT_PARENT } from "./folder-notes.mjs";
 import {
     BEING_ARCHETYPES,
     dataFields,
-    isLegacyDataField,
     declaredTags,
     subTypeCharsetMessage,
     typeCharsetMessage,
@@ -280,72 +286,6 @@ export { declaredSystems } from "./system-vocabulary.mjs";
  */
 export { systemBlocksFor } from "./system-vocabulary.mjs";
 
-/**
- * Edit distance, capped — enough to answer "did you mean".
- *
- * A misspelled property is the failure class this check exists for, and a
- * finding that names the key the author *meant* turns a hunt through the
- * reference into a one-character fix.
- *
- * @param {string} a - One string.
- * @param {string} b - The other.
- * @returns {number} The Levenshtein distance.
- */
-function distance(a, b) {
-    const rows = a.length + 1;
-    const cols = b.length + 1;
-    let prev = Array.from({ length: cols }, (_, j) => j);
-    for (let i = 1; i < rows; i += 1) {
-        const row = [i];
-        for (let j = 1; j < cols; j += 1) {
-            row[j] = Math.min(
-                prev[j] + 1,
-                row[j - 1] + 1,
-                prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
-            );
-        }
-        prev = row;
-    }
-    return prev[cols - 1];
-}
-
-/**
- * A closed vocabulary as an English list, for the message that names it.
- *
- * Written from the declaration rather than spelled into the message, so a key
- * the vocabulary gains cannot go unmentioned by the finding that refuses its
- * neighbours.
- *
- * @param {readonly string[]} keys - The declared keys, in declared order.
- * @returns {string} `"a, b, or c"`.
- */
-function listed(keys) {
-    if (keys.length < 2) return keys.join("");
-    return `${keys.slice(0, -1).join(", ")}, or ${keys[keys.length - 1]}`;
-}
-
-/**
- * The declared key an unknown one was most likely meant to be.
- *
- * @param {string} key - The unknown key.
- * @param {Iterable<string>} candidates - The declared keys.
- * @returns {string|undefined} The nearest, when it is near enough to suggest.
- */
-function nearest(key, candidates) {
-    let best;
-    let bestAt = Infinity;
-    for (const candidate of candidates) {
-        const d = distance(key.toLowerCase(), candidate.toLowerCase());
-        if (d < bestAt) {
-            bestAt = d;
-            best = candidate;
-        }
-    }
-    // A third of the key's length, so a suggestion is a plausible typo rather
-    // than the least-bad of a list of unrelated words.
-    return bestAt <= Math.max(1, Math.floor(key.length / 3)) ? best : undefined;
-}
-
 /**
  * Whether a value satisfies a declared {@link FieldSpec.kind}.
  *
@@ -503,7 +443,7 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
     }
 
     for (const key of Object.keys(entries)) {
-        if (declared.has(key) || isLegacyDataField(type, key)) continue;
+        if (declared.has(key)) continue;
         const current = renamed.get(key);
         if (current) {
             findings.push({
@@ -546,7 +486,19 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
             value = value && typeof value === "object" ? value[segment] : undefined;
         }
         if (value === undefined || value === null) continue;
-        if (!matchesKind(value, field.kind, { ...addressContext, type: field.ref })) {
+        if (field.kind === "address" && hasAnchor(value) && !field.anchors) {
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(raw, ["data", ...segments]),
+                severity: "error",
+                message: `\`data.${field.name}\` ${NO_ANCHOR}, but reads ${JSON.stringify(value)}`,
+            });
+            continue;
+        }
+        if (
+            !(field.kind === "address" && field.anchors && anchored(value)) &&
+            !matchesKind(value, field.kind, { ...addressContext, type: field.ref })
+        ) {
             findings.push({
                 file: note.file,
                 ...positionOfFrontmatterPath(raw, ["data", ...segments]),
@@ -570,9 +522,75 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
         }
     }
 
+    // One level down and every level below: each field's value is closed to
+    // the inner keys its declaration states, as the container is to its own.
+    findings.push(...checkDataKeys(note, fields));
+
     return findings;
 }
 
+/** What a finding says of an anchor on a field that declares no anchor kind. */
+const NO_ANCHOR = "takes no anchor — it names a whole note, so write the Address without `#…`";
+
+/**
+ * Whether an Address value names an anchor: written with `#<anchor>`, or read
+ * into an {@link AddressLink}.
+ *
+ * @param {unknown} value - The value as the note holds it.
+ * @returns {boolean} Whether it carries an anchor.
+ */
+function anchored(value) {
+    return value instanceof AddressLink || hasAnchor(value);
+}
+
+/**
+ * The value as an author wrote it, for a message: a read Address back to its
+ * canonical text, with `#<anchor>` where it has one.
+ *
+ * @param {unknown} value - The value as the note holds it.
+ * @returns {unknown} Its written form.
+ */
+function writtenForm(value) {
+    if (value instanceof AddressLink) return `${renderAddress(value.target)}#${value.anchor}`;
+    if (isAddressTuple(value)) return renderAddress(value);
+    return value;
+}
+
+/**
+ * Why an Address on a field declaring anchor kinds names nothing it accepts, or
+ * `undefined` when it does.
+ *
+ * With an index, the Address is resolved as an event's own `follows` is —
+ * the anchor must exist and be of a kind the field declares, and a field
+ * declaring `single` must name exactly one event. Without one, only its form is
+ * checked.
+ *
+ * @param {unknown} value - The value as the note holds it.
+ * @param {object} field - The field's declaration.
+ * @param {object} defaults - The Address context, with the field's default type.
+ * @param {object} [index] - The link index.
+ * @returns {string|undefined} The reason.
+ */
+function eventReferenceProblem(value, field, defaults, index) {
+    if (index?.addressHit)
+        return resolveEventReference(
+            value,
+            {
+                ...(field.ref ? { ref: field.ref } : {}),
+                ...(field.accepts ? { accepts: field.accepts } : {}),
+                anchors: field.anchors,
+                ...(field.single ? { single: true } : {}),
+            },
+            index,
+        ).problem;
+    const written = writtenForm(value);
+    if (typeof written !== "string") return "should be an Address";
+    const { address, anchor } = splitAnchor(written);
+    if (anchor !== undefined && !isAddressSegment(anchor))
+        return `names the anchor \`${anchor}\`, which is not an address segment`;
+    return matchesKind(address, "address", defaults) ? undefined : "should be an Address";
+}
+
 /**
  * Validate typed entries and resolve declared non-art Address targets.
  * @param {object} note - The authored note.
@@ -631,7 +649,11 @@ function checkDataReferences(note, field, value, segments, context, index) {
         )
             continue;
         let reason;
-        if (!matchesKind(check.value, check.kind, defaults))
+        if (check.kind === "address" && field.anchors && (field.single || anchored(check.value)))
+            reason = eventReferenceProblem(check.value, field, defaults, index);
+        else if (check.kind === "address" && hasAnchor(check.value) && !field.anchors)
+            reason = NO_ANCHOR;
+        else if (!matchesKind(check.value, check.kind, defaults))
             reason = `should be ${check.kind === "address" ? "an Address" : "a Shortcode"}`;
         else if (check.kind === "address") {
             const tuple = parseAddress(check.value, defaults, { declared: true });
@@ -650,7 +672,11 @@ function checkDataReferences(note, field, value, segments, context, index) {
             file: note.file,
             ...positionOfFrontmatterPath(note.raw ?? "", path, { key: check.key || check.atKey }),
             severity: "error",
-            message: `\`${path.join(".")}\` ${reason}, but reads ${JSON.stringify(check.value)}`,
+            // The value as the file states it: the note's own Addresses are
+            // already canonical, and a key is quoted as the key it is.
+            message: `\`${path.join(".")}\` ${reason}, but reads ${JSON.stringify(
+                (!check.key && frontmatterValueAt(note.raw, path)) || writtenForm(check.value),
+            )}`,
         });
     }
     return findings;
@@ -981,10 +1007,10 @@ function checkTags(note, { type }) {
  *
  * {@link module:engine/art-fields.ART_SLOTS} is the declaration; this is that
  * list in the shape the checks below read, so the linter states no art key of
- * its own and a slot added there is checked here with no second edit. All four
- * are authored under `data:`, which is what `inData` records.
+ * its own and a slot added there is checked here with no second edit. Every
+ * slot is authored under `data:`, which is what `inData` records.
  *
- * `document` separates the three that reach a compiled document from `banner`,
+ * `document` separates the slots that reach a compiled document from `banner`,
  * which reaches none by design. The inert-art check reads it: a key that is
  * *meant* to reach no document is not an inert key, and reporting every note
  * that names a hero image would bury the finding that matters.

package/engine/frontmatter.mjs

@@ -31,6 +31,7 @@
 // enum cannot drift apart — a value absent from the list is a build
 // error, never a silent ship.
 import { AddressEntries } from "./address-values.mjs";
+import { renderAddress } from "./address-render.mjs";
 import { AFFILIATION_STANDINGS } from "../sohl/affiliation-standings.mjs";
 
 /**
@@ -287,9 +288,13 @@ export function resolveRelation(fm, ctx = "item") {
     for (const [code, value] of entries) {
         const standing = String(value);
         if (!AFFILIATION_STANDINGS.includes(standing)) {
-            throw new Error(
-                `${ctx}: ${key}["${code}"] must be one of ${AFFILIATION_STANDINGS.join(", ")}, got "${value}"`,
+            const error = new Error(
+                `${ctx}: ${key}["${typeof code === "string" ? code : renderAddress(code)}"] must be one of ${AFFILIATION_STANDINGS.join(", ")}, got "${value}"`,
             );
+            // Where the compiler reports it: the authored key's value where the
+            // key is still its written text, else the map itself.
+            error.keyPath = ["data", key, ...(typeof code === "string" ? [code] : [])];
+            throw error;
         }
         if (typed) typedEntries.push({ target: code, value: standing, sourceKey: "" });
         else out[code] = standing;

package/engine/generate.mjs

@@ -40,6 +40,7 @@
  */
 
 import { noteAddressContext } from "./note-addresses.mjs";
+import { GENERATED_DRAWING_DIR } from "./generated-sections.mjs";
 import fs from "fs";
 import path from "path";
 import log from "loglevel";
@@ -678,6 +679,56 @@ export function emptyPassErrors(passes) {
         );
 }
 
+/**
+ * Where the module ships the drawings its generated sections name, below the
+ * staged package root: `assets/generated/`, so a section's
+ * `generated/from-<shortcode>.svg` resolves inside the install as every other
+ * own-package pathname does — `modules/<id>/assets/generated/…`.
+ *
+ * The staged package root is the directory holding the compiled packs, which
+ * the manifest addresses as `packs/<name>`.
+ *
+ * @param {object} config - The resolved configuration.
+ * @returns {string} The directory, absolute.
+ */
+function stagedDrawingDir(config) {
+    return path.join(path.dirname(config.paths.stage), "assets", GENERATED_DRAWING_DIR);
+}
+
+/**
+ * Draw the map from each place given a **From here** section and stage it
+ * into the module, where the section's image resolves. Drawn under
+ * `build/map/foundry/` and copied, so the `.dot` each drawing is made from
+ * stays out of the module.
+ *
+ * @param {object[]} records - The corpus this compile derived.
+ * @param {object} config - The resolved configuration.
+ * @returns {Promise<object[]>} What drawing found, as diagnostics.
+ */
+async function stageGeneratedDrawings(records, config) {
+    // Imported here: the derivation reads the map world, which reaches the
+    // content index, and a static import from this module would close a cycle
+    // through the compilers.
+    const { drawMapsFrom } = await import("./derived-sections.mjs");
+    let foreignIndex = new Map();
+    try {
+        const { loadForeignIndexes } = await import("./metadata-index.mjs");
+        foreignIndex = loadForeignIndexes(config, [config.contentPackage]).index;
+    } catch {
+        foreignIndex = new Map();
+    }
+    const staged = stagedDrawingDir(config);
+    fs.rmSync(staged, { recursive: true, force: true });
+    const { maps, findings } = drawMapsFrom(records, {
+        outDir: path.join(config.rootDir, "build", "map", "foundry"),
+        foreignIndex,
+        config,
+    });
+    if (maps.size) fs.mkdirSync(staged, { recursive: true });
+    for (const [name, file] of maps) fs.copyFileSync(file, path.join(staged, name));
+    return findings;
+}
+
 /**
  * Generate the build-only JSON for every pack (or one, when `only` is given).
  *
@@ -744,6 +795,8 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
         problems: corpusProblems,
     });
     for (const problem of corpusProblems) emitDiagnostic(problem);
+    for (const finding of await stageGeneratedDrawings(corpus.records, config))
+        emitDiagnostic(finding);
 
     // A note whose `type:` no configured pack claims compiles into nothing, and
     // used to say nothing — no pass got far enough to reject it, so the