@heroiclands/package-build 25.1.2 → 25.2.0

package/engine/metadata-index.mjs

@@ -62,6 +62,7 @@ import {
 } from "./content-address.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { isGmNote } from "./note-vocabulary.mjs";
+import { nameFormLists } from "./name-forms.mjs";
 
 /**
  * Written once a fetch completes, so a half-finished cache is never used.
@@ -448,7 +449,13 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 ...(typeof record.name?.sort === "string" && record.name.sort ?
                     { nameSort: record.name.sort }
                 :   {}),
-                aliases: record.name?.aliases,
+                // Every form the note's name lists, by language, and the
+                // language the publishing package derived for the note.
+                forms:
+                    nameFormLists(record.name).length ?
+                        Object.fromEntries(nameFormLists(record.name))
+                    :   undefined,
+                lang: typeof record.lang === "string" ? record.lang : undefined,
                 // Absent where the package publishes no page for it. A consumer
                 // must tolerate that rather than invent an href, exactly as it
                 // already tolerates an entry with no `uuid`.
@@ -489,15 +496,15 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 // walking that parent's own chain.
                 culture: record.data?.culture ?? undefined,
                 ...(parts.type === "lore" && record.subType === "culture" ?
-                    {
-                        data: {
-                            language: record.data?.language,
-                            appearanceProfile: record.data?.appearanceProfile,
-                        },
-                    }
+                    { data: { appearanceProfile: record.data?.appearanceProfile } }
                 :   {}),
                 ...(parts.type === "skill" && record.subType === "language" ?
-                    { data: { names: record.data?.names } }
+                    {
+                        data: { names: record.data?.names },
+                        ...(typeof record.languageCode === "string" ?
+                            { languageCode: record.languageCode }
+                        :   {}),
+                    }
                 :   {}),
                 population: record.data?.population ?? undefined,
                 ...(Object.hasOwn(record.data ?? {}, "government") ?

package/engine/name-forms.mjs

@@ -0,0 +1,99 @@
+/*
+ * 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
+ */
+
+/**
+ * A note's names, by language.
+ *
+ * `name` is `{full, <code>: [forms]}`. `full` is the English name a page,
+ * a compendium entry and an index print. Every other name the subject goes by
+ * is listed under the code of its language: a code `languages:` declares, or
+ * `en`, which needs no declaration. The first form of a list is that
+ * language's standard form, and `full` counts as an English form.
+ *
+ * `sort`, and a character's `given` and `clan`, are single strings and no
+ * language's forms, so a configured language may not take one of those names.
+ *
+ * A leaf module, importing nothing.
+ *
+ * @module
+ */
+
+/**
+ * A whole visible label as names are matched: NFC, straight apostrophes,
+ * single spaces, trimmed, and case folded. Matching ignores case; a name is
+ * displayed as it was written, never in this form.
+ *
+ * @param {string} text - A visible name, `full` or a form.
+ * @returns {string} Its matching key.
+ */
+export function normalizeName(text) {
+    return displayName(text).toLowerCase();
+}
+
+/**
+ * A whole visible label as it is displayed: NFC, straight apostrophes, single
+ * spaces and trimmed, its case as written.
+ *
+ * @param {string} text - A visible name, `full` or a form.
+ * @returns {string} The label for display.
+ */
+export function displayName(text) {
+    return text.normalize("NFC").replaceAll("’", "'").replace(/\s+/g, " ").trim();
+}
+
+/** The language every note falls back to, and a code no configuration need declare. */
+export const FALLBACK_LANGUAGE = "en";
+
+/** The single-string name keys every note accepts, in display order. */
+export const NOTE_NAME_KEYS = Object.freeze(["full", "sort"]);
+
+/** Additional name components accepted by an individual character. */
+export const CHARACTER_NAME_KEYS = Object.freeze(["given", "clan"]);
+
+/** Every `name` key that is not a language's list of forms. */
+export const NAME_STRING_KEYS = Object.freeze([...NOTE_NAME_KEYS, ...CHARACTER_NAME_KEYS]);
+
+const STRING_KEYS = new Set(NAME_STRING_KEYS);
+
+/**
+ * A note's form lists, in authored order: each key of `name` that is not one
+ * of {@link NAME_STRING_KEYS} and holds a list, with its string forms.
+ *
+ * Read without the configuration, so a reader of an index gets every list a
+ * note states; which codes a note may state is the frontmatter lint's
+ * question, not a reader's.
+ *
+ * @param {unknown} name - A note's `name`.
+ * @returns {Array<[string, string[]]>} `[code, forms]` pairs; a form that is
+ *   not a nonempty string is left out, and so is a list left empty by that.
+ */
+export function nameFormLists(name) {
+    if (!name || typeof name !== "object" || Array.isArray(name)) return [];
+    const out = [];
+    for (const [code, value] of Object.entries(name)) {
+        if (STRING_KEYS.has(code) || !Array.isArray(value)) continue;
+        const forms = value.filter((form) => typeof form === "string" && form.trim() !== "");
+        if (forms.length) out.push([code, forms]);
+    }
+    return out;
+}
+
+/**
+ * Every form a note's name lists, in authored order, without `full`.
+ *
+ * @param {unknown} name - A note's `name`.
+ * @returns {string[]} The forms; empty where it lists none.
+ */
+export function nameFormsOf(name) {
+    return nameFormLists(name).flatMap(([, forms]) => forms);
+}

package/engine/name-refs.mjs

@@ -0,0 +1,143 @@
+/*
+ * 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
+ */
+
+/**
+ * The `ref=` attribute of a `.name` span: the note a spelling belongs to, or a
+ * page-local key for a subject with no note. Shape findings need no catalog;
+ * resolution findings take the prepared name catalog.
+ * @module
+ */
+
+import { rebaseNameSpans } from "./name-markup.mjs";
+import { scanSpans } from "./content-spans.mjs";
+
+/** A page-local key: `#` then a word of letters, digits, `_` and `-`. */
+const LOCAL_KEY = /^#[\p{L}\p{N}][\p{L}\p{N}_-]*$/u;
+
+const isName = (span) =>
+    span.attrs.some(([key, value]) => key === "class" && value.split(/\s+/).includes("name"));
+
+/**
+ * Whether a `ref` value is a page-local key rather than a note address.
+ * @param {string} ref - The attribute value as written.
+ * @returns {boolean} True for a value beginning with `#`.
+ */
+export const isLocalRef = (ref) => ref.startsWith("#");
+
+/**
+ * The `ref` a span states.
+ * @param {{attrs: ReadonlyArray<readonly [string, string]>}} span - A parsed span.
+ * @returns {string|null} The value as written, or null when the span has none.
+ */
+export function readNameRef(span) {
+    return span.attrs.find(([key]) => key === "ref")?.[1] ?? null;
+}
+
+/** A finding at a named attribute part, with the position left out when unknown. */
+function at(span, key, part, file, message) {
+    const site = span.attributePositions?.[key]?.[part];
+    return {
+        ...(file === undefined ? {} : { file }),
+        ...(Number.isFinite(site?.line) ? { line: site.line } : {}),
+        ...(Number.isFinite(site?.column) ? { column: site.column } : {}),
+        severity: "error",
+        message,
+    };
+}
+
+/**
+ * The `ref=` findings that depend on the span alone.
+ * @param {ReadonlyArray<import("./names.mjs").ParsedNameSpan>} spans - Every parsed span, at file coordinates.
+ * @param {{file?: string}} [options] - Authored source file.
+ * @returns {Array<{file?: string, line?: number, column?: number, severity: "error", message: string}>} One error per defect.
+ */
+export function nameRefFindings(spans, { file } = {}) {
+    const findings = [];
+    for (const span of spans) {
+        const ref = readNameRef(span);
+        if (ref === null) continue;
+        if (!isName(span)) {
+            findings.push(
+                at(
+                    span,
+                    "ref",
+                    "key",
+                    file,
+                    "ref= belongs on a .name span; a wikilink never takes ref",
+                ),
+            );
+            continue;
+        }
+        if (span.attrs.some(([key]) => key === "data-type"))
+            findings.push(
+                at(
+                    span,
+                    "data-type",
+                    "key",
+                    file,
+                    "data-type is for a name with no note; the ref states the type",
+                ),
+            );
+        if (isLocalRef(ref) && !LOCAL_KEY.test(ref))
+            findings.push(
+                at(
+                    span,
+                    "ref",
+                    "value",
+                    file,
+                    `ref ${JSON.stringify(ref)} must be a note address or a page-local key such as #jane`,
+                ),
+            );
+    }
+    return findings;
+}
+
+/**
+ * Create the check that every note `ref=` of a note names a note.
+ * @param {object} options - The lint's prepared inputs.
+ * @param {import("./names.mjs").NameCatalog} options.catalog - Resolves an address to its note.
+ * @param {Map<string, {raw: string, body: string, bodyLine?: number, bodyColumn?: number}>} [options.parsed] - Captured authored bodies.
+ * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Exact-text scanner projections.
+ * @returns {(note: {file: string, raw: string}) => Array<{file: string, line?: number, column?: number, severity: "error", message: string}>} One error per unresolved address.
+ */
+export function createNameRefChecker({ catalog, parsed, syntax }) {
+    return ({ file, raw }) => {
+        const authored = parsed?.get(file);
+        const spans =
+            authored?.raw === raw && Number.isInteger(authored.bodyLine) ?
+                rebaseNameSpans(
+                    (syntax ? syntax(authored.body).spans : scanSpans(authored.body)).names,
+                    {
+                        raw,
+                        bodyLine: authored.bodyLine,
+                        bodyColumn: authored.bodyColumn,
+                    },
+                )
+            :   scanSpans(raw).names;
+        const findings = [];
+        for (const span of spans) {
+            const ref = readNameRef(span);
+            if (ref === null || isLocalRef(ref) || catalog.resolve(ref)) continue;
+            findings.push(
+                at(
+                    span,
+                    "ref",
+                    "value",
+                    file,
+                    `ref ${JSON.stringify(ref)} names no note in this package or its declared dependencies`,
+                ),
+            );
+        }
+        return findings;
+    };
+}

package/engine/name-rows.mjs

@@ -22,7 +22,15 @@ import { encodeAddresses } from "./address-values.mjs";
 import { isNoteRecord } from "./index-records.mjs";
 
 /** Every column of the `names` relation, in order. */
-export const NAME_COLUMNS = Object.freeze(["owner", "name", "type", "subType", "line", "column"]);
+export const NAME_COLUMNS = Object.freeze([
+    "owner",
+    "name",
+    "type",
+    "subType",
+    "ref",
+    "line",
+    "column",
+]);
 
 /**
  * @typedef {object} NameRow
@@ -30,6 +38,7 @@ export const NAME_COLUMNS = Object.freeze(["owner", "name", "type", "subType", "
  * @property {string} name - Rendered visible text of the occurrence.
  * @property {string|null} type - Supplied note type, or null.
  * @property {string|null} subType - Supplied subtype, or null.
+ * @property {string|null} ref - The `ref=` as written, a note address or a page-local `#key`, or null.
  * @property {number} line - Original 1-based source line at the opening bracket.
  * @property {number} column - Original 1-based UTF-16 source column at that bracket.
  */
@@ -61,6 +70,7 @@ export function namesRows(records) {
                 name: entry.name,
                 type: entry.type ?? null,
                 subType: entry.subType ?? null,
+                ref: entry.ref ?? null,
                 line: entry.line,
                 column: entry.column,
             });

package/engine/names.mjs

@@ -19,7 +19,9 @@ import { formatLocator } from "./diagnostics.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { isNoteRecord } from "./index-records.mjs";
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { readNameRef } from "./name-refs.mjs";
 import { WORD } from "./word-pattern.mjs";
+import { displayName, nameFormsOf, normalizeName } from "./name-forms.mjs";
 
 const compare = (a, b) =>
     a < b ? -1
@@ -32,7 +34,7 @@ const compare = (a, b) =>
  * @property {string} key - Canonical page identity, or the ambiguous label identity.
  * @property {string} full - Declared full name.
  * @property {true} indexed - The identity belongs to the indexed catalog.
- * @property {boolean} [fullUse] - The label is a full-name form rather than an alias.
+ * @property {boolean} [fullUse] - The label is a form of the full name rather than a listed form.
  * @property {string} [type] - The note's type, absent on an ambiguous label identity.
  * @property {string|null} [subType] - The note's subtype, or null.
  * @property {NameMatch[]} [candidates] - Indexed identities sharing the label.
@@ -40,7 +42,7 @@ const compare = (a, b) =>
  */
 
 /**
- * The prepared name and declared-alias lookup.
+ * The prepared lookup of full names and listed forms.
  * @typedef {object} NameCatalog
  * @property {(label: string, preferred?: {key: string}, kind?: NameKind) => NameMatch|undefined} recognize - Match a whole visible label, among notes of `kind` when it supplies a type.
  * @property {(target: string) => NameMatch|undefined} resolve - Resolve an Address target without its anchor to its indexed identity.
@@ -60,6 +62,7 @@ const compare = (a, b) =>
  * @property {string} name - Rendered visible text.
  * @property {string|null} type - Supplied valid type, or null.
  * @property {string|null} subType - Supplied valid subtype, or null.
+ * @property {string|null} ref - The `ref=` as written, a note address or a `#key`, or null.
  * @property {number} line - Original 1-based file line.
  * @property {number} column - Original 1-based UTF-16 file column.
  */
@@ -116,19 +119,14 @@ const compare = (a, b) =>
  * @property {NameConflict[]} conflicts - Labels with incompatible supplied kinds.
  */
 
-/**
- * Normalize a whole visible label without folding its case.
- * @param {string} text - Visible name or declared alias.
- * @returns {string} NFC text with straight apostrophes and single spaces.
- */
-export function normalizeName(text) {
-    return text.normalize("NFC").replaceAll("’", "'").replace(/\s+/g, " ").trim();
-}
+// A label's matching key folds case; its display form keeps it.
+export { displayName, normalizeName } from "./name-forms.mjs";
 
 /**
- * Whole-label possessives and regular plurals; other forms are declared aliases.
- * @param {string} text - Full name or declared alias.
- * @returns {string[]} Supported whole-label forms.
+ * Whole-label possessives and regular plurals, as matching keys; any other
+ * form is one a note's name lists.
+ * @param {string} text - Full name or a listed form.
+ * @returns {string[]} Supported whole-label forms, case folded.
  */
 export function nameForms(text) {
     const value = normalizeName(text);
@@ -150,7 +148,7 @@ function identity(record) {
 }
 
 /**
- * Prepare full names, declared aliases and link identities from captured records.
+ * Prepare full names, every listed form and link identities from captured records.
  * @param {object} options - The invocation's existing corpus and link index.
  * @param {readonly object[]} options.records - Captured local records.
  * @param {ReturnType<typeof import("./content-links.mjs").buildLinkIndex>} options.index - Captured address space.
@@ -160,7 +158,7 @@ export function createNameCatalog({ records, index }) {
     const names = new Map(),
         byFile = new Map(),
         entries = new Map();
-    const addName = (key, full, aliases, type, subType) => {
+    const addName = (key, full, forms, type, subType) => {
         const entry = entries.get(key) ?? {
             key,
             full,
@@ -169,7 +167,7 @@ export function createNameCatalog({ records, index }) {
             subType: typeof subType === "string" && subType ? subType : null,
         };
         entries.set(key, entry);
-        for (const text of [full, ...(aliases ?? [])]) {
+        for (const text of [full, ...(forms ?? [])]) {
             if (typeof text !== "string" || !text.trim()) continue;
             for (const spelling of nameForms(text)) {
                 if (!names.has(spelling)) names.set(spelling, new Map());
@@ -192,7 +190,7 @@ export function createNameCatalog({ records, index }) {
         const entry = addName(
             index.resolve(page) ? page : canonical,
             full,
-            record.name.aliases,
+            nameFormsOf(record.name),
             parts.type,
             record.subType,
         );
@@ -211,7 +209,10 @@ export function createNameCatalog({ records, index }) {
             continue;
         const page = canonicalKey(parts.package, "note", parts.type, parts.shortcode);
         const key = index.foreign.index.has(page) ? page : canonical;
-        entries.set(canonical, addName(key, hit.name, hit.aliases, parts.type, hit.subType));
+        entries.set(
+            canonical,
+            addName(key, hit.name, nameFormsOf(hit.forms), parts.type, hit.subType),
+        );
     }
     return {
         recognize(label, preferred, kind) {
@@ -302,8 +303,9 @@ export function collectUnwrittenNames({ records, catalog }) {
             if (!kinds.has(kind)) kinds.set(kind, { type, subType, names: new Map() });
             const names = kinds.get(kind).names,
                 name = normalizeName(occurrence.name);
-            if (!names.has(name)) names.set(name, []);
-            names.get(name).push(nameUse(record, occurrence));
+            if (!names.has(name))
+                names.set(name, { display: displayName(occurrence.name), uses: [] });
+            names.get(name).uses.push(nameUse(record, occurrence));
         }
     }
     const groups = [...kinds.values()]
@@ -316,7 +318,7 @@ export function collectUnwrittenNames({ records, catalog }) {
             subType,
             names: [...names]
                 .sort(([a], [b]) => compare(a, b))
-                .map(([name, uses]) => ({ name, uses: uses.sort(compareUses) })),
+                .map(([, { display, uses }]) => ({ name: display, uses: uses.sort(compareUses) })),
         }));
     const firstUse = firstNameUse(
         groups.flatMap((group) => group.names.flatMap((name) => name.uses)),
@@ -383,6 +385,7 @@ export function analyzeNameSpans(spans, { file, vocabulary = NOTE_VOCABULARY, ty
             name: span.visible,
             type: kind.type,
             subType: kind.subType,
+            ref: readNameRef(span),
             line: span.line,
             column: span.column,
         });
@@ -401,11 +404,13 @@ export function analyzeNameSpans(spans, { file, vocabulary = NOTE_VOCABULARY, ty
  */
 export function createNamesReport({ package: contentPackage, records, catalog }) {
     const names = new Map();
+    const displays = new Map();
     for (const record of records.filter(isNoteRecord))
         for (const occurrence of record.names ?? []) {
             if (occurrence.type === null) continue;
             const name = normalizeName(occurrence.name);
             if (!names.has(name)) names.set(name, new Map());
+            if (!displays.has(name)) displays.set(name, displayName(occurrence.name));
             const kinds = names.get(name),
                 key = JSON.stringify([occurrence.type, occurrence.subType]);
             if (!kinds.has(key))
@@ -421,7 +426,7 @@ export function createNamesReport({ package: contentPackage, records, catalog })
         }
         if (parents.size < 2 && ![...parents.values()].some((values) => values.size > 1)) continue;
         conflicts.push({
-            name,
+            name: displays.get(name),
             kinds: [...kinds.values()]
                 .sort(
                     (a, b) => compare(a.type, b.type) || compare(a.subType ?? "", b.subType ?? ""),

package/engine/note-addresses.mjs

@@ -159,9 +159,6 @@ export function addressPositions(fm, context = {}) {
                 ...(ASSET_TYPE_NAMES.has(field.ref) || field.ref === "folder" ?
                     { system: "none" }
                 :   {}),
-                ...(field.name === "language" && field.ref === "skill" ?
-                    { system: NOTE_SYSTEM, noteOnly: true }
-                :   {}),
             });
     }
     out.push(...STRUCTURED_ADDRESSES.filter((p) => !p.noteType || p.noteType === fm.type));

package/engine/note-frontmatter.mjs

@@ -21,11 +21,9 @@ export {
     NOTE_TOP_LEVEL_KEY_SET,
 } from "./note-vocabulary.mjs";
 
-/** The name properties every note accepts, in display order. */
-export const NOTE_NAME_KEYS = Object.freeze(["full", "aliases", "sort"]);
-
-/** Additional name components accepted by an individual character. */
-export const CHARACTER_NAME_KEYS = Object.freeze(["given", "clan"]);
+// The single-string name keys, beside the language form lists they are told
+// apart from.
+export { CHARACTER_NAME_KEYS, NOTE_NAME_KEYS } from "./name-forms.mjs";
 
 /** Return authored keys from an opening YAML frontmatter map. */
 export function authoredNoteKeys(markdown) {