@heroiclands/package-build 23.12.8 → 24.0.0

package/engine/run-words.mjs

@@ -17,20 +17,14 @@
  * each word (see {@link module:engine/word-pattern.WORD}) is accepted when,
  * case folded, it is:
  *
- * - a `data.words[].form` of the language, or a word of one;
+ * - a `data.words[].form` of the language, or a word of one, or a declared
+ *   `variants` entry of a word;
  * - a word of a name in the language note's own `data.register` whose `tongue`
  *   is not `translation`, so a foreign name the run uses is listed there first,
  *   as `other:<tongue>` or under another tag the note declares;
- * - a form one rule the language states derives from a lexicon form:
- *   - the noun plural `data.grammar.plural` gives, or the word's own `plural`;
- *   - a verb's citation form with one ending of `data.grammar.verbs.persons`,
- *     which takes the place of a closing `data.grammar.verbs.replaces` where
- *     the pattern states one (see {@link module:engine/verb-pattern.verbForm});
- *   - a suffix of `data.affixes` that states `replaces`, or its `front` form:
- *     `vowel` takes the place of a closing vowel (a letter whose base is `a`,
- *     `e`, `i`, `o` or `u`), letters take the place of those letters, and a
- *     stem closing otherwise takes the suffix whole. An affix that states no
- *     `replaces` derives nothing.
+ * - a form one rule the language states derives from a lexicon form: a noun
+ *   plural, a verb's present form, a replacing suffix, an agreeing form or a
+ *   participle, of a lexicon form or of one of its variants (see {@link module:engine/word-forms.derivedForms}).
  *
  * A word not accepted whole is split at its hyphens and en dashes, and each
  * part is checked. An apostrophe joins a word, so `k'aralzon` is one word, and
@@ -42,11 +36,9 @@
  * @module
  */
 
-import { pluralOf } from "./dictionary-rows.mjs";
 import { languageRecordsByName } from "./map-lexicon.mjs";
 import { RESERVED_TONGUE } from "./language-terms.mjs";
-import { replaceClosing, verbForm, verbPattern } from "./verb-pattern.mjs";
-import { parseWordClass } from "./word-classes.mjs";
+import { addWords, foldWord, lexiconWords } from "./word-forms.mjs";
 import { WORD } from "./word-pattern.mjs";
 
 /** Whether a value is a plain map. */
@@ -61,104 +53,6 @@ const JOINS = /[–-]/u;
 /** A letter, which a checked word holds at least one of. */
 const LETTER = /\p{L}/u;
 
-/**
- * A word as it is compared: NFC, lowercase, `’` read as `'`.
- *
- * @param {string} word - The word.
- * @returns {string} Its folded form.
- */
-export function foldWord(word) {
-    return word.normalize("NFC").toLowerCase().replace(/’/gu, "'");
-}
-
-/** Whether a character is a vowel: its base letter is a, e, i, o or u. */
-const isVowel = (char) => /^[aeiou]/iu.test(char.normalize("NFD"));
-
-/**
- * Add a text's words to a set, each whole and each part of a compound.
- *
- * @param {Set<string>} set - The set.
- * @param {string} text - A form or a name.
- */
-function addWords(set, text) {
-    for (const [word] of text.matchAll(WORD)) {
-        const folded = foldWord(word);
-        set.add(folded);
-        for (const part of folded.split(JOINS)) if (part) set.add(part);
-    }
-}
-
-/**
- * The form a suffix stating `replaces` makes of a stem.
- *
- * @param {string} stem - The stem, folded.
- * @param {string} suffix - The suffix, folded, with no hyphen.
- * @param {string} replaces - The affix's `replaces`.
- * @returns {string} The derived form.
- */
-function attach(stem, suffix, replaces) {
-    if (replaces === "vowel") {
-        const last = Array.from(stem).at(-1);
-        return last !== undefined && isVowel(last) ?
-                stem.slice(0, -last.length) + suffix
-            :   stem + suffix;
-    }
-    return replaceClosing(stem, suffix, foldWord(replaces));
-}
-
-/**
- * The suffixes a language's affixes state `replaces` for: each `form`, and
- * its `front` form, written `-x`.
- *
- * @param {Record<string, any>} data - The language note's `data`.
- * @returns {Array<{suffix: string, replaces: string}>} The suffixes, folded.
- */
-function replacingSuffixes(data) {
-    const out = [];
-    for (const affix of listOf(data.affixes)) {
-        if (!isMap(affix) || typeof affix.replaces !== "string") continue;
-        for (const written of [affix.form, affix.front]) {
-            if (typeof written !== "string") continue;
-            const form = foldWord(written.trim());
-            if (!/^[-–]/u.test(form) || /[-–]$/u.test(form)) continue;
-            const suffix = form.replace(/^[-–]+/u, "");
-            if (suffix) out.push({ suffix, replaces: affix.replaces });
-        }
-    }
-    return out;
-}
-
-/**
- * The words a language note accepts of its own: its forms, and what its
- * plural rows, verb pattern and replacing suffixes derive from them.
- *
- * @param {Record<string, any>} data - The language note's `data`.
- * @returns {Set<string>} The words, folded.
- */
-export function lexiconWords(data) {
-    const accepted = new Set();
-    const grammar = isMap(data?.grammar) ? data.grammar : undefined;
-    const verbs = verbPattern(grammar?.verbs);
-    const replaces = verbs?.replaces === undefined ? undefined : foldWord(verbs.replaces);
-    const suffixes = replacingSuffixes(data ?? {});
-    for (const word of listOf(data?.words)) {
-        if (!isMap(word) || typeof word.form !== "string") continue;
-        addWords(accepted, word.form);
-        const plural = pluralOf(word, grammar);
-        if (plural) addWords(accepted, plural);
-        if (verbs && parseWordClass(word.class).base === "v")
-            for (const { ending } of verbs.endings)
-                addWords(accepted, verbForm(foldWord(word.form), foldWord(ending), replaces));
-        if (suffixes.length)
-            for (const [stem] of word.form.matchAll(WORD)) {
-                const folded = foldWord(stem);
-                for (const { suffix, replaces } of suffixes)
-                    accepted.add(attach(folded, suffix, replaces));
-            }
-    }
-    return accepted;
-}
-
 /**
  * The words of every name a language note registers under a tongue other than
  * `translation`.

package/engine/script-emphasis-terms.mjs

@@ -0,0 +1,38 @@
+/*
+ * 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 words a script note and a language note state emphasis by.** Read by
+ * the vocabulary as it is declared, so this module imports nothing; the
+ * checks and the conventions' use are in {@link module:engine/script-emphasis}.
+ *
+ * @module
+ */
+
+/** The conventions a script states its emphasis by. */
+export const EMPHASIS_CONVENTIONS = Object.freeze(["rubric", "overline"]);
+
+/** The class each convention gives an `<em>` or a `<strong>`. */
+export const EMPHASIS_CLASSES = Object.freeze({
+    rubric: "emph-rubric",
+    overline: "emph-overline",
+});
+
+/**
+ * The conventions a language note states, which override its script's.
+ * `words` marks emphasis with a word, so a mark in its text is a finding.
+ */
+export const LANGUAGE_EMPHASES = Object.freeze(["words", ...EMPHASIS_CONVENTIONS]);
+
+/** The `subType` of a script note. */
+export const SCRIPT_SUBTYPE = "script";

package/engine/script-emphasis.mjs

@@ -0,0 +1,295 @@
+/*
+ * 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
+ */
+
+/**
+ * **How a script marks emphasis.** A script note — a `skill` of
+ * `subType: script` — names the faces it is written in and its scribal
+ * convention for a stressed word:
+ *
+ * ```yaml
+ * data:
+ *   script:
+ *     fonts: [semaron-kuriale]
+ *     emphasis: rubric
+ *     strongEmphasis: overline
+ * ```
+ *
+ * - **`fonts`** lists installed faces by the slug `font=` names them by. A
+ *   face belongs to one script.
+ * - **`emphasis`** is `rubric` (red text) or `overline` (a line above the
+ *   word), and sets both `*…*` and `**…**`.
+ * - **`strongEmphasis`**, where stated, sets `**…**` alone.
+ *
+ * Inside a run in one of those faces, `*…*` and `**…**` stay an `<em>` and a
+ * `<strong>` on the site and in Foundry, carrying {@link module:engine/script-emphasis-terms.EMPHASIS_CLASSES}'s
+ * class, and the book sets them in its rubric ink or under an overline. A face
+ * no script note lists sets its emphasis plain: the element with no class, in
+ * the face's Regular. See {@link module:engine/content-scripts.renderRuns}.
+ *
+ * @module
+ */
+
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { nearest } from "./near-miss.mjs";
+import { FONTS_PACKAGE } from "./script-fonts.mjs";
+import {
+    EMPHASIS_CONVENTIONS,
+    LANGUAGE_EMPHASES,
+    SCRIPT_SUBTYPE,
+} from "./script-emphasis-terms.mjs";
+import { GENERIC_FAMILIES } from "./text-maps.mjs";
+import { LANGUAGE_SUBTYPE } from "./word-terms.mjs";
+
+export {
+    EMPHASIS_CLASSES,
+    EMPHASIS_CONVENTIONS,
+    LANGUAGE_EMPHASES,
+} from "./script-emphasis-terms.mjs";
+
+/**
+ * One face's conventions, one for each level of emphasis.
+ *
+ * @typedef {object} Emphasis
+ * @property {"rubric"|"overline"} em - What `*…*` is set by.
+ * @property {"rubric"|"overline"} strong - What `**…**` is set by.
+ */
+
+/**
+ * A convention a language note states.
+ *
+ * @typedef {"words"|"rubric"|"overline"} LanguageEmphasis
+ */
+
+/** Whether a value is a plain map. */
+const isMap = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/** Whether a value is one of the conventions. */
+const isConvention = (value) => EMPHASIS_CONVENTIONS.includes(value);
+
+/**
+ * Each face's conventions, from the script notes among the index records. The
+ * first note to list a face keeps it; a second is the lint's to report, and a
+ * note whose convention is unknown gives none.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @returns {Map<string, Emphasis>} The conventions, by face slug.
+ */
+export function emphasesFromRecords(records) {
+    const out = new Map();
+    for (const record of records ?? []) {
+        if (!record || !isNoteRecord(record)) continue;
+        if (
+            record.type !== "skill" ||
+            String(record.subType ?? "").toLowerCase() !== SCRIPT_SUBTYPE
+        )
+            continue;
+        const script = record.data?.script;
+        if (!isMap(script) || !Array.isArray(script.fonts) || !isConvention(script.emphasis))
+            continue;
+        const strong =
+            script.strongEmphasis === undefined || script.strongEmphasis === null ?
+                script.emphasis
+            :   script.strongEmphasis;
+        if (!isConvention(strong)) continue;
+        const emphasis = Object.freeze({ em: script.emphasis, strong });
+        for (const slug of script.fonts)
+            if (typeof slug === "string" && !out.has(slug)) out.set(slug, emphasis);
+    }
+    return out;
+}
+
+/**
+ * The convention each language's note states.
+ *
+ * @param {ReadonlyMap<string, Record<string, any>>} byName - Each configured
+ *   language's note record, by language name, from
+ *   {@link module:engine/map-lexicon.languageRecordsByName}.
+ * @returns {Map<string, LanguageEmphasis>} The conventions, by language name;
+ *   a language whose note states none, or one the build does not know, is
+ *   absent.
+ */
+export function languageEmphasesOf(byName) {
+    const out = new Map();
+    for (const [name, record] of byName ?? [])
+        if (LANGUAGE_EMPHASES.includes(record?.data?.emphasis)) out.set(name, record.data.emphasis);
+    return out;
+}
+
+/**
+ * Refuse `data.emphasis` on a skill that is not a language, at its key.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageEmphasis(note) {
+    const value = note?.fm?.data?.emphasis;
+    if (value === undefined || value === null) return [];
+    if (String(note.fm?.subType ?? "").toLowerCase() === LANGUAGE_SUBTYPE) return [];
+    return [
+        {
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", ["data", "emphasis"], { key: true }),
+            severity: "error",
+            message:
+                "`data.emphasis` states how a language marks emphasis, and this note's " +
+                `\`subType\` is not \`${LANGUAGE_SUBTYPE}\``,
+        },
+    ];
+}
+
+/** The notes listing each face, read once per lint index. */
+const listedFaces = new WeakMap();
+
+/**
+ * Each face the index's script notes list, and the notes listing it.
+ *
+ * @param {{notes?: Iterable<{file: string, fm?: Record<string, any>}>}} index - The lint index.
+ * @returns {Map<string, string[]>} Slug → the files that list it.
+ */
+function facesIn(index) {
+    const known = listedFaces.get(index);
+    if (known) return known;
+    const faces = new Map();
+    for (const note of index.notes ?? []) {
+        const fm = note?.fm;
+        if (fm?.type !== "skill" || String(fm.subType ?? "").toLowerCase() !== SCRIPT_SUBTYPE)
+            continue;
+        const fonts = fm.data?.script?.fonts;
+        if (!Array.isArray(fonts)) continue;
+        for (const slug of new Set(fonts.filter((value) => typeof value === "string"))) {
+            if (!faces.has(slug)) faces.set(slug, []);
+            faces.get(slug).push(note.file);
+        }
+    }
+    listedFaces.set(index, faces);
+    return faces;
+}
+
+/**
+ * Check a note's `data.script`: that the note is a script, and that its
+ * `fonts` is not empty, names no generic family, lists no face twice, and
+ * lists no face another script note lists. The data-key check owns every key,
+ * its kind and the conventions; whether a face is installed is
+ * {@link checkScriptNoteFonts}'s.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{index?: {notes?: Iterable<object>}}} [context] - The lint index.
+ * @returns {object[]} The findings, each at its key or entry.
+ */
+export function checkScriptField(note, { index } = {}) {
+    const value = note?.fm?.data?.script;
+    if (value === undefined || value === null) return [];
+    const raw = note.raw ?? "";
+    /**
+     * @param {Array<string|number>} keyPath - Where the fault is.
+     * @param {string} message - What is wrong.
+     * @param {boolean} [key] - Locate the key rather than its value.
+     */
+    const finding = (keyPath, message, key = false) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(raw, ["data", "script", ...keyPath], { key }),
+        severity: "error",
+        message,
+    });
+    if (String(note.fm?.subType ?? "").toLowerCase() !== SCRIPT_SUBTYPE)
+        return [
+            finding(
+                [],
+                "`data.script` states a script's faces and emphasis, and this note's " +
+                    `\`subType\` is not \`${SCRIPT_SUBTYPE}\``,
+                true,
+            ),
+        ];
+    if (!isMap(value) || !Array.isArray(value.fonts)) return [];
+    const { fonts } = value;
+    if (!fonts.length)
+        return [
+            finding(
+                ["fonts"],
+                "`data.script.fonts` is empty; a script lists each face it is written in",
+            ),
+        ];
+    const findings = [];
+    const first = new Map();
+    fonts.forEach((slug, at) => {
+        if (typeof slug !== "string") return;
+        if (GENERIC_FAMILIES.includes(slug)) {
+            findings.push(
+                finding(
+                    ["fonts", at],
+                    `\`data.script.fonts[${at}]\` is \`${slug}\`, a generic family; a script lists the faces it is written in`,
+                ),
+            );
+            return;
+        }
+        if (first.has(slug)) {
+            findings.push(
+                finding(
+                    ["fonts", at],
+                    `\`data.script.fonts[${at}]\` lists the font \`${slug}\` a second time; the first is ` +
+                        `\`data.script.fonts[${first.get(slug)}]\``,
+                ),
+            );
+            return;
+        }
+        first.set(slug, at);
+        if (!index) return;
+        const others = (facesIn(index).get(slug) ?? []).filter((file) => file !== note.file);
+        if (others.length)
+            findings.push(
+                finding(
+                    ["fonts", at],
+                    `\`data.script.fonts[${at}]\` is \`${slug}\`, which ${others.join(", ")} also lists; a face belongs to one script`,
+                ),
+            );
+    });
+    return findings;
+}
+
+/**
+ * Each face a script note lists that is not installed, at its entry.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{faces?: ReadonlyMap<string, unknown>}} [ctx] - The installed faces,
+ *   from {@link module:engine/content-scripts.runContext}.
+ * @returns {object[]} The findings.
+ */
+export function checkScriptNoteFonts(note, ctx) {
+    const fm = note?.fm;
+    if (String(fm?.subType ?? "").toLowerCase() !== SCRIPT_SUBTYPE) return [];
+    const fonts = fm?.data?.script?.fonts;
+    if (!Array.isArray(fonts)) return [];
+    const faces = ctx?.faces ?? new Map();
+    const raw = note.raw ?? "";
+    const findings = [];
+    const seen = new Set();
+    fonts.forEach((slug, at) => {
+        if (typeof slug !== "string" || seen.has(slug)) return;
+        seen.add(slug);
+        if (GENERIC_FAMILIES.includes(slug) || faces.has(slug)) return;
+        const near = nearest(slug, [...faces.keys()]);
+        findings.push({
+            file: note.file,
+            ...positionOfFrontmatterPath(raw, ["data", "script", "fonts", at]),
+            severity: "error",
+            message:
+                `\`${slug}\` is not a font: \`data.script.fonts[${at}]\` names ` +
+                (faces.size ? "an installed face" : (
+                    `a face of ${FONTS_PACKAGE}, which this package has not installed`
+                )) +
+                (near ? `; did you mean \`${near}\`?` : ""),
+        });
+    });
+    return findings;
+}

package/engine/script-font-delivery.mjs

@@ -39,8 +39,8 @@ import { FONTS_MANIFEST, resolveScriptFonts } from "./script-fonts.mjs";
 export const STAGED_FONTS_DIR = "fonts/heroiclands";
 
 /**
- * Where the files land in the Hugo static tree, relative to `build/hugo/static`,
- * beneath a directory per version.
+ * Where the files land in the site's static tree, beneath a directory per
+ * version.
  *
  * @type {string}
  */
@@ -279,10 +279,10 @@ export function siteFontsParam(config) {
 }
 
 /**
- * The directory under the Hugo static tree that holds this version's fonts.
+ * The directory under the site's static tree that holds this version's fonts.
  *
  * @param {string} version - The fonts package's version.
- * @returns {string} The POSIX path, relative to `build/hugo/static`.
+ * @returns {string} The POSIX path, relative to the static tree.
  */
 export function siteFontsDestination(version) {
     return `${SITE_FONTS_DIR}/${version}`;