@heroiclands/package-build 23.5.1 → 23.6.0

package/engine/word-rows.mjs

@@ -0,0 +1,233 @@
+/*
+ * 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 rows of the SQL `words` and `glossary` relations, read from index
+ * records whose Addresses are already strings.
+ *
+ * `words` is one row per `data.words` entry of every language note, keyed by
+ * that note, and `glossary` one row per `data.glossary` entry of every culture
+ * and affiliation, with the language the entry resolves to
+ * ({@link module:engine/glossary-language}). **Every row has every column**:
+ * the keys come from {@link module:engine/word-terms}, so a key no entry in a
+ * corpus writes is still a column, `NULL` in every row, and a fence naming it
+ * binds.
+ *
+ * A word row holds the words its own note states, and nothing is copied for a
+ * daughter language. `language_lineage` is one row per language and each of
+ * its ancestors through `data.family`, itself included at depth `0`, so a
+ * language's words with its inherited ones are a join of the two.
+ *
+ * @module
+ */
+
+import { renderAddress } from "./address.mjs";
+import { glossaryLanguage } from "./glossary-language.mjs";
+import { GLOSSARY_ENTRY_KEYS, LANGUAGE_SUBTYPE, WORD_KEYS } from "./word-terms.mjs";
+
+/** The columns a word row carries before the word's own keys. */
+const WORD_IDENTITY_COLUMNS = Object.freeze(["language", "position"]);
+
+/** The columns a word row derives after the word's own keys. */
+const WORD_DERIVED_COLUMNS = Object.freeze(["built_text", "built_parts"]);
+
+/** Every column of the `words` relation, in order. */
+export const WORD_COLUMNS = Object.freeze([
+    ...WORD_IDENTITY_COLUMNS,
+    ...WORD_KEYS,
+    ...WORD_DERIVED_COLUMNS,
+]);
+
+/** Every column of the `glossary` relation, in order. */
+export const GLOSSARY_COLUMNS = Object.freeze(["note", "position", ...GLOSSARY_ENTRY_KEYS]);
+
+/** Every column of the `language_lineage` relation, in order. */
+export const LINEAGE_COLUMNS = Object.freeze(["language", "ancestor", "depth"]);
+
+/** The columns of any of these relations that hold a whole number. */
+export const ROW_INTEGER_COLUMNS = Object.freeze(["position", "depth"]);
+
+/** Whether a value is a plain map. */
+const isMap = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/** A piece's form with its joining hyphens taken off, for a second match. */
+const bare = (form) => String(form).replace(/^-+|-+$/g, "");
+
+/**
+ * A lookup from a built piece to its gloss, over one language's words (stems
+ * included) and affixes.
+ *
+ * A piece matches a word or an affix written exactly as it is, and failing
+ * that one written with the same letters and different joining hyphens, so
+ * `wulf-` finds the word `wulf`. A word's own gloss wins over an affix's.
+ *
+ * @param {object} data - The language note's `data`.
+ * @returns {(piece: string) => string|null} The gloss, or `null` where none resolves.
+ */
+export function pieceGlosses(data) {
+    const exact = new Map();
+    const loose = new Map();
+    const take = (entries) => {
+        for (const entry of Array.isArray(entries) ? entries : []) {
+            if (!isMap(entry) || typeof entry.form !== "string" || typeof entry.gloss !== "string")
+                continue;
+            if (!exact.has(entry.form)) exact.set(entry.form, entry.gloss);
+            if (!loose.has(bare(entry.form))) loose.set(bare(entry.form), entry.gloss);
+        }
+    };
+    take(data?.words);
+    take(data?.affixes);
+    return (piece) => exact.get(piece) ?? loose.get(bare(piece)) ?? null;
+}
+
+/**
+ * Whether a record is a language note's.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {boolean}
+ */
+export function isLanguageRecord(record) {
+    return record?.type === "skill" && record?.subType === LANGUAGE_SUBTYPE;
+}
+
+/**
+ * A record's Address as a reference to it is written: in the `note` system,
+ * so it compares equal to the Addresses other notes state.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {string|null} The Address, or `null` for a record naming no note.
+ */
+function noteAddressOf(record) {
+    if (!record?.package || !record.type || !record.shortcode) return null;
+    return renderAddress({
+        package: String(record.package),
+        system: "note",
+        type: String(record.type),
+        shortcode: String(record.shortcode),
+    });
+}
+
+/**
+ * The `words` rows of a set of index records.
+ *
+ * A row's `language` is the note that states it.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @returns {object[]} One row per word, in record then entry order.
+ */
+export function wordRows(records) {
+    const rows = [];
+    for (const record of records) {
+        if (!isLanguageRecord(record)) continue;
+        const words = record.data?.words;
+        if (!Array.isArray(words) || !words.length) continue;
+        const language = noteAddressOf(record);
+        if (!language) continue;
+        const glossOf = pieceGlosses(record.data);
+        words.forEach((entry, position) => {
+            if (!isMap(entry)) return;
+            const row = { language, position };
+            for (const key of WORD_KEYS) row[key] = entry[key] ?? null;
+            if (row.name_sort === null) row.name_sort = row.form;
+            const built = Array.isArray(entry.built) ? entry.built.map(String) : [];
+            row.built_text = built.length ? built.join(" + ") : null;
+            row.built_parts =
+                built.length ? built.map((form) => ({ form, gloss: glossOf(form) })) : null;
+            rows.push(row);
+        });
+    }
+    return rows;
+}
+
+/**
+ * The `glossary` rows of a set of index records: one per entry of a culture's
+ * or an affiliation's `data.glossary`, with `name_sort` the name and `common`
+ * `false` where the entry leaves them unstated, and `language` the language
+ * the entry resolves to, or `NULL` where it resolves to none.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @param {Iterable<Record<string, any>>} [all] - Every record of the package,
+ *   for resolving a language through a note the audience does not see.
+ * @returns {object[]} One row per entry, in record then entry order.
+ */
+export function glossaryRows(records, all = records) {
+    const byAddress = new Map();
+    for (const record of all) {
+        const key = noteAddressOf(record);
+        if (key && !byAddress.has(key)) byAddress.set(key, record);
+    }
+    const reader = {
+        keyOf: (value) => (typeof value === "string" && value ? value : undefined),
+        lookup: (key) => byAddress.get(key),
+    };
+    const rows = [];
+    for (const record of records) {
+        const owner =
+            record?.type === "affiliation" ||
+            (record?.type === "lore" && record?.subType === "culture");
+        if (!owner) continue;
+        const entries = record.data?.glossary;
+        if (!Array.isArray(entries) || !entries.length) continue;
+        const note = noteAddressOf(record);
+        if (!note) continue;
+        entries.forEach((entry, position) => {
+            if (!isMap(entry) || typeof entry.name !== "string") return;
+            const row = { note, position };
+            for (const key of GLOSSARY_ENTRY_KEYS) row[key] = entry[key] ?? null;
+            if (row.name_sort === null) row.name_sort = row.name;
+            if (row.common === null) row.common = false;
+            row.language = glossaryLanguage(entry, record, { ...reader, self: note }) ?? null;
+            rows.push(row);
+        });
+    }
+    return rows;
+}
+
+/**
+ * The `language_lineage` rows of a set of index records: for each language
+ * note, itself at depth `0`, its `data.family` at depth `1`, and so on up the
+ * chain. The chain stops at a parent that is no language note of the package,
+ * and before a language it has already reached, so a cycle the lint refuses
+ * still yields finite rows.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @param {Iterable<Record<string, any>>} [all] - Every record of the package,
+ *   for following a chain through a note the audience does not see.
+ * @returns {object[]} One row per language and ancestor, in record then depth order.
+ */
+export function lineageRows(records, all = records) {
+    const languages = new Map();
+    for (const record of all)
+        if (isLanguageRecord(record)) {
+            const key = noteAddressOf(record);
+            if (key && !languages.has(key)) languages.set(key, record);
+        }
+    const rows = [];
+    for (const record of records) {
+        if (!isLanguageRecord(record)) continue;
+        const language = noteAddressOf(record);
+        if (!language) continue;
+        const seen = new Set();
+        let current = language;
+        for (let depth = 0; current && languages.has(current) && !seen.has(current); depth++) {
+            seen.add(current);
+            rows.push({ language, ancestor: current, depth });
+            const family = languages.get(current).data?.family;
+            current = typeof family === "string" && family ? family : undefined;
+        }
+    }
+    return rows;
+}

package/engine/word-terms.mjs

@@ -0,0 +1,306 @@
+/*
+ * 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 inner keys of a language note's words, fields and affixes, and of a
+ * culture's or an affiliation's glossary entries, as inner-key declarations.
+ *
+ * A leaf module, importing nothing: the note vocabulary reads these
+ * declarations as it loads, and the checks that judge what the values mean —
+ * a class against the master word classes, a field against the note's own
+ * fields — live in `language-words.mjs` and `glossary-entries.mjs`.
+ *
+ * @module
+ */
+
+/** The `skill` subType whose notes are languages, and the only one with words. */
+export const LANGUAGE_SUBTYPE = "language";
+
+/** The `data` keys a language note states its words in, beside `names`. */
+export const WORD_DATA_KEYS = Object.freeze(["classModifiers", "fields", "words", "affixes"]);
+
+/**
+ * Where a word comes from. `borrowed` names the tongue it was taken from;
+ * `inherited`, `kept` and `worn` name the ancient form where the note gives
+ * one; `coined`, `substrate` and `island` name no form.
+ */
+export const WORD_SOURCE_KINDS = Object.freeze([
+    "inherited",
+    "borrowed",
+    "kept",
+    "worn",
+    "coined",
+    "substrate",
+    "island",
+]);
+
+/** The source kind that requires `language`. */
+export const BORROWED_SOURCE_KIND = "borrowed";
+
+/**
+ * The keys of a word's `source`.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const WORD_SOURCE_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "kind",
+        kind: "string",
+        required: true,
+        allowed: WORD_SOURCE_KINDS,
+        shape: `one of ${WORD_SOURCE_KINDS.join(", ")}`,
+        describe: "How the word came into the tongue.",
+    }),
+    Object.freeze({
+        name: "language",
+        kind: "address",
+        shape: "a language skill Address",
+        describe: "The tongue the word was borrowed from; required for `borrowed`.",
+    }),
+    Object.freeze({
+        name: "form",
+        kind: "string",
+        shape: "a string",
+        describe: "The form the word had in its source, bare.",
+    }),
+]);
+
+/**
+ * The keys one word of a language note's `data.words` carries.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const WORD_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "form",
+        kind: "string",
+        required: true,
+        shape: "the word as cited, bare",
+        describe: "The word as cited, with no backticks.",
+    }),
+    Object.freeze({
+        name: "name_sort",
+        kind: "string",
+        shape: "a string",
+        describe: "The sort key; the form when unstated.",
+    }),
+    Object.freeze({
+        name: "class",
+        kind: "string",
+        required: true,
+        shape: "a word class, base first, such as `n I f`",
+        describe:
+            "A class from the master word classes: a base, then the modifiers the language " +
+            "declares in `classModifiers`.",
+    }),
+    Object.freeze({
+        name: "field",
+        kind: "string",
+        required: true,
+        shape: "one of the language's `fields` names",
+        describe: "The field the word is grouped under, named in the language's `fields`.",
+    }),
+    Object.freeze({
+        name: "gloss",
+        kind: "string",
+        required: true,
+        shape: "a string",
+        describe: "The meaning, in brief.",
+    }),
+    Object.freeze({
+        name: "source",
+        kind: "map",
+        shape: "a map — `{ kind, language?, form? }`",
+        fields: WORD_SOURCE_FIELDS,
+        describe: "Where the word comes from.",
+    }),
+    Object.freeze({
+        name: "built",
+        kind: "list",
+        shape: "a list of pieces",
+        entries: Object.freeze({ kind: "string", shape: "a string" }),
+        describe:
+            "The pieces the word is built from, in order, as the language's words and affixes " +
+            "write them; absent for a root word.",
+    }),
+    Object.freeze({
+        name: "attested",
+        kind: "list",
+        shape: "a list of Addresses",
+        entries: Object.freeze({ kind: "address", shape: "an Address" }),
+        describe: "The notes the word is cited from.",
+    }),
+    Object.freeze({
+        name: "pronunciation",
+        kind: "string",
+        shape: "a respelling such as `sol-MEH-reh`",
+        describe:
+            "A respelling in hyphen-separated syllables, the stressed one in capitals: letters, " +
+            "apostrophes and hyphens only, and at most one capitalised syllable.",
+    }),
+    Object.freeze({
+        name: "tones",
+        kind: "string",
+        shape: "a string",
+        describe: "A tone pattern, such as `LHL`.",
+    }),
+    Object.freeze({
+        name: "root",
+        kind: "string",
+        shape: "a string",
+        describe: "A consonantal skeleton, such as `d-l-k`.",
+    }),
+    Object.freeze({
+        name: "frame",
+        kind: "string",
+        shape: "a string",
+        describe: "The frame a root is set in.",
+    }),
+]);
+
+/** The keys of {@link WORD_FIELDS}, in declared order. */
+export const WORD_KEYS = Object.freeze(WORD_FIELDS.map((field) => field.name));
+
+/**
+ * The keys one entry of a language note's `data.fields` carries.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const WORD_FIELD_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "name",
+        kind: "string",
+        required: true,
+        shape: "a string",
+        describe: "The field's name, which a word's `field` names.",
+    }),
+    Object.freeze({
+        name: "holds",
+        kind: "string",
+        required: true,
+        shape: "a string",
+        describe: "What the field holds.",
+    }),
+]);
+
+/**
+ * The keys one entry of a language note's `data.affixes` carries.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const AFFIX_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "form",
+        kind: "string",
+        required: true,
+        shape: "the affix as written, such as `-rith`",
+        describe: "The affix as a word's `built` names it.",
+    }),
+    Object.freeze({
+        name: "gloss",
+        kind: "string",
+        required: true,
+        shape: "a string",
+        describe: "What the affix means.",
+    }),
+    Object.freeze({
+        name: "attaches",
+        kind: "string",
+        shape: "a string",
+        describe: "How it attaches, such as `replaces a closing vowel`.",
+    }),
+    Object.freeze({
+        name: "examples",
+        kind: "list",
+        shape: "a list of strings",
+        entries: Object.freeze({ kind: "string", shape: "a string" }),
+        describe: "The names the affix is read from.",
+    }),
+]);
+
+/**
+ * The keys one entry of a culture's or an affiliation's `data.glossary`
+ * carries.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const GLOSSARY_ENTRY_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "name",
+        kind: "string",
+        required: true,
+        shape: "a string",
+        describe: "The headword.",
+    }),
+    Object.freeze({
+        name: "name_sort",
+        kind: "string",
+        shape: "a string",
+        describe: "Its sort key; the name when unstated.",
+    }),
+    Object.freeze({
+        name: "common",
+        kind: "boolean",
+        shape: "`true` or `false`",
+        describe: "A word a player is expected to know by heart; `false` when unstated.",
+    }),
+    Object.freeze({
+        name: "definition",
+        kind: "string",
+        shape: "a string",
+        describe:
+            "The sense text. Stated, it creates the entry or replaces every sense the " +
+            "entry's other sources give it.",
+    }),
+    Object.freeze({
+        name: "pronunciation",
+        kind: "string",
+        shape: "a respelling such as `sol-MEH-reh`",
+        describe: "A respelling, held to the same rule as a word's.",
+    }),
+    Object.freeze({
+        name: "language",
+        kind: "address",
+        shape: "a language skill Address",
+        describe:
+            "The language the term is in. Unstated, it is the affiliation's language, its " +
+            "parents', or its culture's, or the culture's own.",
+    }),
+]);
+
+/** The keys of {@link GLOSSARY_ENTRY_FIELDS}, in declared order. */
+export const GLOSSARY_ENTRY_KEYS = Object.freeze(GLOSSARY_ENTRY_FIELDS.map((field) => field.name));
+
+/**
+ * Why a pronunciation is not a respelling, or `undefined` when it is one.
+ *
+ * A respelling is letters and apostrophes in hyphen-separated syllables, with
+ * at most one syllable in capitals.
+ *
+ * @param {string} text
+ * @returns {string|undefined}
+ */
+export function pronunciationProblem(text) {
+    const value = String(text ?? "");
+    if (!/^[\p{L}\p{M}'’]+(?:-[\p{L}\p{M}'’]+)*$/u.test(value))
+        return "a respelling holds letters, apostrophes and hyphens only, as `sol-MEH-reh`";
+    const stressed = value
+        .split(/-/)
+        .filter(
+            (syllable) =>
+                syllable !== syllable.toLowerCase() && syllable === syllable.toUpperCase(),
+        );
+    if (stressed.length > 1)
+        return `a respelling stresses one syllable, and this capitalises ${stressed.length}`;
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.5.1",
+    "version": "23.6.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/content-index.d.mts

@@ -316,11 +316,13 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
  *   `paths.contentIndex`.
  * @param {object} [options.config] - A resolved configuration; loaded when omitted.
  * @returns {{file: string, notes: number, assets: number, records: number,
- *   bytes: number, full: number, draft: number, stub: number}} Where it was
- *   written, how many notes and how many assets it holds, how many records that
- *   is in all, its size, and the ladder those notes sit on — so the ratio of
- *   written to unwritten is visible on every build rather than discovered in a
- *   year.
+ *   bytes: number, full: number, draft: number, stub: number,
+ *   dictionary: {file: string, rows: number}, terms: {file: string, rows: number}}}
+ *   Where it was written, how many notes and how many assets it holds, how many
+ *   records that is in all, its size, and the ladder those notes sit on — so
+ *   the ratio of written to unwritten is visible on every build rather than
+ *   discovered in a year — and where the `dictionary` and `terms` datafiles
+ *   were written beside it, with their row counts.
  * @throws {Error} When the content tree is absent, or when it yields no note at
  *   all — an empty index is indistinguishable from a mis-pointed tree, and a
  *   reader would take it as the authoritative statement that this package has
@@ -339,6 +341,14 @@ export function emitContentIndex({ contentBase, outDir, config }?: {
     full: number;
     draft: number;
     stub: number;
+    dictionary: {
+        file: string;
+        rows: number;
+    };
+    terms: {
+        file: string;
+        rows: number;
+    };
 };
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";

package/types/engine/culture-reach.d.mts

@@ -0,0 +1,66 @@
+/**
+ * A value's canonical Address as a string, whether the note holds it parsed or
+ * as written, or `undefined` where it is no Address.
+ *
+ * @param {unknown} value - The value.
+ * @param {object|undefined} index - The index, for the package and the types.
+ * @param {string} type - The type a bare shortcode defaults to.
+ * @returns {string|undefined} The Address.
+ */
+export function addressKeyOf(value: unknown, index: object | undefined, type: string): string | undefined;
+/** A note's own Address, keyed as a reference to it is: in the `note` system. */
+export function ownKey(note: any, index: any): string | undefined;
+/**
+ * The language a glossary entry on a note resolves to.
+ *
+ * @param {object} index - The link index.
+ * @param {object} note - The culture or affiliation the entry is written on.
+ * @param {object|undefined} entry - The entry, or nothing for the note's own.
+ * @returns {string|undefined} The language's Address.
+ */
+export function entryLanguage(index: object, note: object, entry: object | undefined): string | undefined;
+/**
+ * The glossary corpus of an index.
+ *
+ * @param {object} index - The link index: `notes`, `contentPackage`, `types`.
+ * @returns {GlossaryCorpus}
+ */
+export function glossaryCorpus(index: object): GlossaryCorpus;
+/**
+ * A culture's or an affiliation's terms, by NFC name, each with the sense
+ * texts its sources give.
+ *
+ * @param {object} index - The link index.
+ * @param {object} note - The culture or affiliation note.
+ * @returns {Map<string, string[]>} The terms; empty for a note no source reaches.
+ */
+export function noteTerms(index: object, note: object): Map<string, string[]>;
+/**
+ * Warn of an affiliation that reaches no culture, its own or one it inherits,
+ * in a tree that describes peoples.
+ *
+ * @param {object} note - An `affiliation` note.
+ * @param {{index?: object}} [context]
+ * @returns {object[]} One warning, at the note's `type`, or none.
+ */
+export function checkAffiliationReach(note: object, { index }?: {
+    index?: object;
+}): object[];
+export function isCultureNote(note: any): boolean;
+export function isLanguageNote(note: any): boolean;
+export function glossaryName(name: any): string;
+/**
+ * What the index says about each culture's and affiliation's terms, read once.
+ */
+export type GlossaryCorpus = {
+    /**
+     * - The tree holds a culture note.
+     */
+    describesPeoples: boolean;
+    /**
+     * - Each culture's and
+     * affiliation's terms by NFC name, each with the sense texts its sources
+     * give it.
+     */
+    terms: Map<string, Map<string, string[]>>;
+};