@heroiclands/package-build 23.3.0 → 23.3.2

package/engine/content-index.mjs

@@ -86,6 +86,7 @@
  */
 
 import { isAddressSegment } from "./address-charset.mjs";
+import { cultureInheritance, reportCultureParents } from "./culture-parents.mjs";
 import {
     formatDiagnostic,
     locateFrontmatterKey,
@@ -1178,6 +1179,27 @@ export function collectContentIndex(
     // is found by its canonical address. Before the sort, which reads nothing
     // the pass writes.
     resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems });
+    const cultureNotes = records
+        .filter((record) => isNoteRecord(record) && record.type === "lore")
+        .map((record) => ({
+            fm: record,
+            file: noteFile(contentBase, record),
+            raw: fs.readFileSync(noteFile(contentBase, record), "utf8"),
+        }));
+    const cultureByKey = new Map(
+        cultureNotes.map((note) => [
+            canonicalKey(contentPackage, "note", "lore", note.fm.shortcode),
+            note,
+        ]),
+    );
+    const inheritance = cultureInheritance({
+        contentPackage,
+        notes: cultureNotes,
+        addressHit: (key) => cultureByKey.get(key) ?? foreignRecord?.(key),
+    });
+    reportCultureParents(inheritance.findings, problems);
+    for (const [note, inherited] of inheritance.values)
+        if (Object.keys(inherited).length) note.fm.data = { ...note.fm.data, ...inherited };
 
     // Sorted at every depth like a note's record, and for the same reason: the
     // declaration order of the `asset` fields is a fact about the emitter, not

package/engine/content-links.mjs

@@ -55,6 +55,7 @@
 import { readWikilink } from "./wikilink-syntax.mjs";
 import { encodeAddresses } from "./address-values.mjs";
 import fs from "node:fs";
+import { cultureRecordProblems, cultureInheritedFields } from "./culture-parents.mjs";
 import path from "node:path";
 
 import { matchAllOutsideCode } from "./code-fences.mjs";
@@ -224,6 +225,14 @@ export function buildLinkIndex(
         const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, "");
         const type = record.type.toLowerCase();
         const note = { file: absPath, rel, fm, body, raw, type };
+        const hierarchyProblems = cultureRecordProblems(record);
+        note.inheritedCultureFields = cultureInheritedFields(record);
+        if (hierarchyProblems)
+            note.reportedCultureParents = new Set(
+                hierarchyProblems
+                    .filter((problem) => problem.file === absPath)
+                    .map((problem) => problem.parentIndex),
+            );
 
         for (const hit of frontmatterWikilinks(fm)) {
             frontmatterLinks.push({ note, ...hit });

package/engine/culture-parents.mjs

@@ -0,0 +1,301 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { isDeepStrictEqual } from "node:util";
+import { canonicalKey, parseAddress, renderAddress } from "./address.mjs";
+import { positionOfFrontmatterPath, formatDiagnostic } from "./diagnostics.mjs";
+
+const fields = ["language", "appearanceProfile"];
+const payload = (note) => note.fm ?? note;
+const dataOf = (note) => payload(note).data ?? payload(note);
+const culture = (note) => payload(note).type === "lore" && payload(note).subType === "culture";
+const parentsOf = (note) => (Array.isArray(dataOf(note).parents) ? dataOf(note).parents : []);
+
+/** Read a culture parent against the field's Address defaults. */
+function address(value, index) {
+    const tuple = parseAddress(value, {
+        package: index.contentPackage,
+        system: "note",
+        type: "lore",
+        types: index.types,
+        packages: index.packages,
+    });
+    return tuple.reason ? undefined : tuple;
+}
+
+/** The authored edge graph, with every cyclic edge identified. */
+function graph(index) {
+    const out = new Map();
+    const queue = [...(index.notes ?? [])].filter(culture);
+    while (queue.length) {
+        const note = queue.pop();
+        if (out.has(note)) continue;
+        const edges = [];
+        out.set(note, edges);
+        parentsOf(note).forEach((value, position) => {
+            const tuple = address(value, index);
+            if (!tuple || tuple.type !== "lore") return;
+            const target = index.addressHit?.(renderAddress(tuple));
+            if (!target || !culture(target)) return;
+            edges.push({ target, position });
+            queue.push(target);
+        });
+    }
+    const reaches = (start, end) => {
+        const seen = new Set();
+        const queue = [start];
+        while (queue.length) {
+            const current = queue.pop();
+            if (current === end) return true;
+            if (seen.has(current)) continue;
+            seen.add(current);
+            queue.push(...(out.get(current) ?? []).map((edge) => edge.target));
+        }
+        return false;
+    };
+    const cyclic = new Map();
+    for (const [note, edges] of out)
+        cyclic.set(
+            note,
+            new Set(
+                edges.filter((edge) => reaches(edge.target, note)).map((edge) => edge.position),
+            ),
+        );
+    return { out, cyclic };
+}
+
+/** A located hierarchy finding with the Address of the culture it concerns. */
+function finding(note, index, path, message) {
+    const fm = payload(note);
+    return {
+        file: note.file,
+        ...positionOfFrontmatterPath(note.raw ?? "", ["data", "parents", ...path]),
+        severity: "error",
+        code: "culture-parents",
+        cultureAddress: canonicalKey(index.contentPackage, "note", "lore", fm.shortcode),
+        parentIndex: path[0],
+        message,
+    };
+}
+
+/** Validate subtype scope and culture targets; unresolved targets use the ordinary reference check. */
+function parentFindings(note, index, analysis, unresolved) {
+    const data = dataOf(note);
+    if (data.parents === undefined || data.parents === null) return [];
+    if (!culture(note))
+        return [finding(note, index, [], "data.parents is stated by only culture lore notes")];
+    const findings = [];
+    parentsOf(note).forEach((value, position) => {
+        const tuple = address(value, index);
+        if (!tuple) return;
+        const key = renderAddress(tuple);
+        const target = tuple.type === "lore" ? index.addressHit?.(key) : undefined;
+        if (tuple.type !== "lore") {
+            if (unresolved)
+                findings.push(
+                    finding(
+                        note,
+                        index,
+                        [position],
+                        `data.parents.${position} accepts lore, not ${tuple.type}`,
+                    ),
+                );
+        } else if (!target) {
+            if (unresolved)
+                findings.push(
+                    finding(
+                        note,
+                        index,
+                        [position],
+                        `data.parents.${position} names ${key}, which does not resolve in this package or its declared dependencies`,
+                    ),
+                );
+        } else if (!culture(target))
+            findings.push(
+                finding(
+                    note,
+                    index,
+                    [position],
+                    `data.parents.${position} names ${key}, whose subType is not culture`,
+                ),
+            );
+        else if (analysis.cyclic.get(note)?.has(position))
+            findings.push(
+                finding(
+                    note,
+                    index,
+                    [position],
+                    `data.parents.${position} forms a culture parent cycle; a culture is never its own ancestor`,
+                ),
+            );
+    });
+    return findings;
+}
+
+const graphs = new WeakMap();
+const hierarchyProblems = new WeakMap();
+const inheritedFields = new WeakMap();
+const inheritedSources = new WeakMap();
+
+/** The authored source of one inherited field, retained outside the published record. */
+export function cultureFieldSource(records, key, field) {
+    const record = records.find(
+        (entry) =>
+            entry.type === "lore" &&
+            entry.subType === "culture" &&
+            canonicalKey(entry.package, "note", "lore", entry.shortcode) === key,
+    );
+    return record && inheritedSources.get(record)?.get(field);
+}
+
+/** Fields supplied by an ancestor rather than authored on this record. */
+export function cultureInheritedFields(record) {
+    return inheritedFields.get(record);
+}
+
+/** Read the hierarchy findings retained beside a resolved index record. */
+export function cultureRecordProblems(record) {
+    return hierarchyProblems.get(record);
+}
+
+/** Read hierarchy findings attached to one culture's resolved index record. */
+export function cultureHierarchyProblems(records, key) {
+    return records.flatMap((record) =>
+        (
+            record.type === "lore" &&
+            record.subType === "culture" &&
+            canonicalKey(record.package, "note", "lore", record.shortcode) === key
+        ) ?
+            (hierarchyProblems.get(record) ?? [])
+        :   [],
+    );
+}
+
+/**
+ * Check the declared culture-parent field in the normal frontmatter lint.
+ * @param {object} note - The note's frontmatter and source location.
+ * @param {{index?: object}} [options] - The corpus and its Address lookup.
+ * @returns {object[]} Located findings.
+ */
+export function checkCultureParents(note, { index } = {}) {
+    if (note.reportedCultureParents) return [];
+    const context = index ?? { contentPackage: undefined, notes: [note] };
+    let analysis = graphs.get(context);
+    if (!analysis) {
+        analysis = graph(context);
+        graphs.set(context, analysis);
+    }
+    return parentFindings(note, context, analysis, false);
+}
+
+/**
+ * Resolve each omitted culture field independently, searching parents in listed depth-first order.
+ * Same-depth disagreement withholds the inherited field and produces a finding.
+ * @param {object} index - The authored culture nodes and Address lookup.
+ * @returns {{values: Map<object, object>, findings: object[]}}
+ */
+export function cultureInheritance(index) {
+    const analysis = graph(index);
+    const findings = [];
+    const values = new Map();
+    for (const note of index.notes ?? []) {
+        if (!culture(note)) continue;
+        findings.push(...parentFindings(note, index, analysis, true));
+        const inherited = {};
+        const sources = new Map();
+        for (const field of fields) {
+            if (dataOf(note)[field] !== undefined) continue;
+            const candidates = [];
+            const work = [{ node: note, depth: 0 }];
+            const seen = new Map();
+            while (work.length) {
+                const { node, depth, via } = work.pop();
+                if (analysis.cyclic.get(node)?.size) continue;
+                if (seen.has(node) && seen.get(node) <= depth) continue;
+                seen.set(node, depth);
+                const value = dataOf(node)[field];
+                if (depth && value !== undefined) {
+                    candidates.push({ value, depth, via, node });
+                    continue;
+                }
+                const edges = analysis.out.get(node) ?? [];
+                for (let i = edges.length - 1; i >= 0; i--) {
+                    const edge = edges[i];
+                    if (!analysis.cyclic.get(node)?.has(edge.position))
+                        work.push({
+                            node: edge.target,
+                            depth: depth + 1,
+                            via: depth ? via : edge.position,
+                        });
+                }
+            }
+            const atDepth = new Map();
+            let conflicting;
+            for (const candidate of candidates) {
+                if (
+                    atDepth.has(candidate.depth) &&
+                    !isDeepStrictEqual(atDepth.get(candidate.depth), candidate.value)
+                )
+                    conflicting = candidate;
+                else atDepth.set(candidate.depth, candidate.value);
+            }
+            if (conflicting)
+                findings.push(
+                    finding(
+                        note,
+                        index,
+                        [conflicting.via],
+                        `culture parents at the same depth disagree on data.${field}; state the field on this culture`,
+                    ),
+                );
+            else if (candidates.length) {
+                inherited[field] = candidates[0].value;
+                const source = candidates[0].node;
+                sources.set(field, { file: source.file, raw: source.raw, fm: payload(source) });
+            }
+        }
+        inheritedSources.set(payload(note), sources);
+        values.set(note, inherited);
+    }
+    for (const note of index.notes ?? []) {
+        if (!culture(note)) continue;
+        inheritedFields.set(payload(note), new Set(Object.keys(values.get(note) ?? {})));
+        const relevant = new Set();
+        const work = [note];
+        while (work.length) {
+            const current = work.pop();
+            if (relevant.has(current)) continue;
+            relevant.add(current);
+            work.push(...(analysis.out.get(current) ?? []).map((edge) => edge.target));
+        }
+        const addresses = new Set(
+            [...relevant].map((entry) =>
+                canonicalKey(index.contentPackage, "note", "lore", payload(entry).shortcode),
+            ),
+        );
+        hierarchyProblems.set(
+            payload(note),
+            findings.filter((problem) => addresses.has(problem.cultureAddress)),
+        );
+    }
+    return { values, findings };
+}
+
+/** Emit or collect all findings from culture inheritance. */
+export function reportCultureParents(findings, problems) {
+    if (problems) problems.push(...findings);
+    else if (findings.length)
+        throw Object.assign(new Error(findings.map(formatDiagnostic).join("\n")), {
+            located: true,
+        });
+}

package/engine/data-keys.mjs

@@ -33,6 +33,11 @@
  *   Shortcode, a pack, a name), and this describes the value under each key.
  *   The keys themselves are checked as the field's `keyKind` says.
  *
+ * A map declaring both `fields` and `values` holds its declared keys, each
+ * checked by its own declaration, beside keys named by the author, each
+ * checked by `values`. A language's `data.names` is one: `pattern` and
+ * `given` beside the lists the language names for itself.
+ *
  * Dotted field names (`appearance.eye_color`) declare a container's keys by
  * their segments, and the container is closed to them just the same.
  *
@@ -57,7 +62,7 @@ import { nearest } from "./near-miss.mjs";
  * @property {string} name - The key as an author writes it.
  * @property {string} [kind] - Its value's shape: `string`, `date`, `number`,
  *   `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
- *   or `string-or-list` — see {@link fitsKind}. Absent, the check
+ *   `string-or-list`, or `string-list-or-map` — see {@link fitsKind}. Absent, the check
  *   makes no claim about the value.
  * @property {readonly string[]} [allowed] - The closed set a present value is
  *   one of, where the key takes a fixed word.
@@ -145,6 +150,10 @@ export function fitsKind(value, kind) {
             return isScalar(value) || fitsKind(value, "map");
         case "string-or-list":
             return isScalar(value) || Array.isArray(value);
+        // One value, a list of them described by `entries`, or a map of them
+        // described by `values`.
+        case "string-list-or-map":
+            return fitsKind(value, "string-or-list") || fitsKind(value, "map");
         default:
             return true;
     }
@@ -258,7 +267,7 @@ export function checkDataKeys(note, fields) {
      */
     const walk = (spec, value, path) => {
         if (spec.fields && isPlainMap(value)) {
-            closeMap(spec.fields, value, path);
+            closeMap(spec.fields, value, path, spec.values);
             return;
         }
         if (Array.isArray(value)) {
@@ -308,11 +317,18 @@ export function checkDataKeys(note, fields) {
         return false;
     };
 
-    /** Close one map to its declared keys, and walk each that is present. */
-    const closeMap = (inner, value, path) => {
+    /**
+     * Close one map to its declared keys, and walk each that is present. With
+     * `rest`, a key it does not declare is walked against `rest` instead.
+     */
+    const closeMap = (inner, value, path, rest) => {
         const names = inner.map((spec) => spec.name);
         for (const key of Object.keys(value)) {
             if (names.includes(key)) continue;
+            if (rest) {
+                visit(rest, value[key], [...path, key]);
+                continue;
+            }
             const guess = nearest(key, names);
             findings.push(
                 finding(

package/engine/frontmatter-lint.mjs

@@ -412,6 +412,7 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
     }
 
     for (const field of fields) {
+        if (note.inheritedCultureFields?.has(field.name)) continue;
         if (!field.kind) continue;
         const segments = field.name.split(".");
         let value = entries;
@@ -457,7 +458,12 @@ 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));
+    findings.push(
+        ...checkDataKeys(
+            note,
+            fields.filter((field) => !note.inheritedCultureFields?.has(field.name)),
+        ),
+    );
 
     return findings;
 }
@@ -600,6 +606,13 @@ function checkDataReferences(note, field, value, segments, context, index) {
                     :   `; write \`${slot.declines}\` to decline the image on purpose`);
         }
         if (!reason) continue;
+        if (
+            note.fm?.type === "lore" &&
+            note.fm?.subType === "culture" &&
+            field.name === "parents" &&
+            note.reportedCultureParents?.has(check.path[0])
+        )
+            continue;
         const path = ["data", ...segments, ...check.path];
         findings.push({
             file: note.file,
@@ -1526,6 +1539,7 @@ export function lintNote(
         // way a wikilink would. The linter names no such field itself; the
         // vocabulary does, beside the field.
         for (const field of fields) {
+            if (note.inheritedCultureFields?.has(field.name)) continue;
             if (typeof field.check !== "function") continue;
             findings.push(...field.check(note, { index }));
         }