@heroiclands/package-build 23.12.5 → 23.12.7

package/engine/run-words.mjs

@@ -0,0 +1,266 @@
+/*
+ * 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 mapped run's words are words of its language.** In a run marked with
+ * `lang=`, whose language's `note` names its language note, and with `map=`,
+ * 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 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 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
+ * `’` reads as `'`. A word with no letter is not checked.
+ *
+ * Nothing here requires a word to take a particular form: a lexicon word
+ * stated with its own plural, and the plural the rule gives, both pass.
+ *
+ * @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 { WORD } from "./word-pattern.mjs";
+
+/** Whether a value is a plain map. */
+const isMap = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** A list value, or an empty one. */
+const listOf = (value) => (Array.isArray(value) ? value : []);
+
+/** The characters a compound is split at. */
+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`.
+ *
+ * @param {Record<string, any>|undefined} data - The language note's `data`.
+ * @returns {Set<string>} The words, folded.
+ */
+export function registeredNameWords(data) {
+    const words = new Set();
+    for (const row of listOf(data?.register)) {
+        if (!isMap(row) || typeof row.name !== "string") continue;
+        if (row.tongue === RESERVED_TONGUE) continue;
+        addWords(words, row.name);
+    }
+    return words;
+}
+
+/**
+ * What a mapped run's words are checked against, for one language.
+ *
+ * @typedef {object} WordBook
+ * @property {string} language - The language's configured name, as `lang=`
+ *   writes it.
+ * @property {(word: string) => boolean} accepts - Whether a folded word is
+ *   one of the language's.
+ */
+
+/**
+ * Each configured language's word book: one per language whose `note` names a
+ * language note.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string}} config -
+ *   The resolved configuration.
+ * @returns {Map<string, WordBook>} The books by language name.
+ */
+export function wordBooksFromRecords(records, config = {}) {
+    const list = [...(records ?? [])];
+    const books = new Map();
+    const languages = languageRecordsByName(list, config);
+    if (!languages.size) return books;
+    for (const [name, record] of languages) {
+        const own = lexiconWords(record.data);
+        const names = registeredNameWords(record.data);
+        books.set(
+            name,
+            Object.freeze({
+                language: name,
+                accepts: (word) => own.has(word) || names.has(word),
+            }),
+        );
+    }
+    return books;
+}
+
+/**
+ * The words of a text its book does not accept, each once, at the offset of
+ * its first character: a compound not accepted whole gives each part that is
+ * not.
+ *
+ * @param {string} text - The text, with no escapes.
+ * @param {WordBook} book - The language's book.
+ * @param {Set<string>} [said] - The folded words already reported in this
+ *   run, which are not reported again; updated.
+ * @returns {Array<{offset: number, word: string}>} The words, in order.
+ */
+export function unknownWords(text, book, said = new Set()) {
+    const out = [];
+    const check = (word, offset) => {
+        if (!LETTER.test(word)) return;
+        const folded = foldWord(word);
+        if (book.accepts(folded) || said.has(folded)) return;
+        said.add(folded);
+        out.push({ offset, word });
+    };
+    for (const match of text.matchAll(WORD)) {
+        const word = match[0];
+        const offset = /** @type {number} */ (match.index);
+        if (book.accepts(foldWord(word))) continue;
+        if (!JOINS.test(word)) {
+            check(word, offset);
+            continue;
+        }
+        let at = 0;
+        for (const part of word.split(JOINS)) {
+            check(part, offset + at);
+            at += part.length + 1;
+        }
+    }
+    return out;
+}
+
+/**
+ * The finding for a word of a mapped run that is not a word of its language.
+ *
+ * @param {string} word - The word as written.
+ * @param {string} language - The language as `lang=` names it.
+ * @returns {string} The message.
+ */
+export function unknownWordMessage(word, language) {
+    return (
+        `\`${word}\` is not a word of the \`${language}\` lexicon, a registered name, or a regular ` +
+        "form of one; coin it in the lexicon (or register the name) first"
+    );
+}

package/engine/scenes.mjs

@@ -176,6 +176,7 @@ export class Scenes extends BasePackCompiler {
                     markdown,
                     leadName: name,
                     resolveRole,
+                    runs: this.corpus?.runs,
                     // As in the journals pass: an address resolves in the pack
                     // that emits it, which is what makes the folder
                     // materialise there too.

package/engine/script-font-delivery.mjs

@@ -0,0 +1,321 @@
+/*
+ * 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
+ */
+
+/**
+ * **Delivering the installed faces to each target.** A consumer that installs
+ * `@heroiclands/fonts` and sets text in one of its faces with `font=` gets the
+ * fonts on the site, in the Foundry module and in its books; without both,
+ * nothing ships and nothing links to it.
+ *
+ * - **Site and Foundry** receive `fonts.css`, listing only the WOFF2 sources,
+ *   the WOFF2 files and `LICENSE`.
+ * - **Books** search the package's `fonts/` directory, which holds the TTFs.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { baseStyleLayer } from "./base-styles.mjs";
+import { scanRuns } from "./content-scripts.mjs";
+import { FONTS_MANIFEST, resolveScriptFonts } from "./script-fonts.mjs";
+
+/**
+ * Where the files land in the staged Foundry module, relative to its root.
+ *
+ * @type {string}
+ */
+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.
+ *
+ * @type {string}
+ */
+export const SITE_FONTS_DIR = "fonts/heroiclands";
+
+/** The stylesheet the fonts package publishes at its root. */
+const STYLESHEET = "fonts.css";
+
+/** The licence the fonts package publishes at its root. */
+const LICENSE = "LICENSE";
+
+/**
+ * The part of a resolved configuration delivery reads.
+ *
+ * @typedef {object} DeliveryConfig
+ * @property {string} [rootDir] - The consuming package's root.
+ * @property {{content?: string}} [paths] - Where its notes are; relative to
+ *   `rootDir` unless absolute.
+ * @property {Readonly<Record<string, {tag: string}>>} [languages] - Its languages.
+ */
+
+/** The faces each configuration's notes set text in, found once. */
+const usedFaces = new WeakMap();
+
+/**
+ * The faces the package's notes set text in with `font=`, read from the
+ * notes themselves: every Markdown file under the content tree that writes
+ * `font=` is scanned for its runs.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @returns {ReadonlySet<string>} The slugs of the faces used.
+ */
+export function facesUsed(config, installed) {
+    const known = usedFaces.get(config);
+    if (known) return known;
+    const used = new Set();
+    const content =
+        config.paths?.content && config.rootDir ?
+            path.resolve(config.rootDir, config.paths.content)
+        :   undefined;
+    /** @param {string} dir */
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith(".")) continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) walk(full);
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                const source = fs.readFileSync(full, "utf8");
+                if (!/\bfont=/.test(source)) continue;
+                const body = source.replace(
+                    /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,
+                    (frontmatter) => frontmatter.replace(/[^\r\n]/g, " "),
+                );
+                const ctx = { languages: config.languages ?? {}, faces: installed.faces };
+                for (const run of scanRuns(body, ctx).runs)
+                    if (run.font !== undefined && installed.faces.has(run.font)) used.add(run.font);
+            }
+        }
+    };
+    if (content && fs.existsSync(content)) walk(content);
+    usedFaces.set(config, used);
+    return used;
+}
+
+/**
+ * The installed package, when this consumer is to ship it.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {import("./script-fonts.mjs").ScriptFonts|undefined} The package, or
+ *   `undefined` without a root, an install, a manifest, or a note that sets
+ *   text in one of its faces.
+ */
+function delivered(config) {
+    if (!config?.rootDir) return undefined;
+    const installed = resolveScriptFonts(config.rootDir);
+    if (!installed?.manifest) return undefined;
+    return facesUsed(config, installed).size ? installed : undefined;
+}
+
+/**
+ * The files a target receives, as paths relative to the fonts package root.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {string[]} formats - The font formats the target uses: `woff2`, `ttf`.
+ * @returns {{root: string, version: string, files: string[]}|undefined} The
+ *   files, sorted: `fonts.css`, `LICENSE` and every file in `fonts/` of a
+ *   listed format. `undefined` when the consumer ships none.
+ */
+export function scriptFontFiles(config, formats) {
+    const installed = delivered(config);
+    if (!installed) return undefined;
+    const fontsDir = path.join(installed.root, "fonts");
+    const fonts =
+        fs.existsSync(fontsDir) ?
+            fs
+                .readdirSync(fontsDir)
+                .filter((name) => formats.some((format) => name.endsWith(`.${format}`)))
+                .map((name) => `fonts/${name}`)
+        :   [];
+    const files = [STYLESHEET, LICENSE, ...fonts].filter((file) =>
+        fs.existsSync(path.join(installed.root, file)),
+    );
+    return { root: installed.root, version: installed.version, files: files.sort() };
+}
+
+/**
+ * The source list of a `src` declaration, split at its top-level commas.
+ *
+ * @param {string} list - The value, without `src:` and the closing `;`.
+ * @returns {string[]} The sources, each with its leading whitespace.
+ */
+function splitSources(list) {
+    const out = [];
+    let depth = 0;
+    let quote = "";
+    let start = 0;
+    for (let i = 0; i < list.length; i++) {
+        const char = list[i];
+        if (quote) {
+            if (char === "\\") i++;
+            else if (char === quote) quote = "";
+        } else if (char === '"' || char === "'") quote = char;
+        else if (char === "(") depth++;
+        else if (char === ")") depth--;
+        else if (char === "," && depth === 0) {
+            out.push(list.slice(start, i));
+            start = i + 1;
+        }
+    }
+    out.push(list.slice(start));
+    return out;
+}
+
+/** A source's `url(…)` address, unquoted, or `undefined` for a `local(…)`. */
+const sourceUrl = (source) => {
+    const match = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^)\s]*))\s*\)/u.exec(source);
+    return match ? (match[1] ?? match[2] ?? match[3]).replace(/^\.\//u, "") : undefined;
+};
+
+/**
+ * The fonts package's stylesheet as a target stages it: each `@font-face`
+ * `src` lists only the files staged beside it, so no browser asks for a
+ * format the target does not carry. A `local(…)` source stays, and a face
+ * left with no source is dropped.
+ *
+ * @param {string} css - The stylesheet as the package publishes it.
+ * @param {ReadonlySet<string>} staged - The staged files, relative to the
+ *   stylesheet: `fonts/SemaronKuriale-Regular.woff2`.
+ * @returns {string} The stylesheet to stage.
+ */
+export function stagedStylesheet(css, staged) {
+    return css.replace(/@font-face\s*\{[^}]*\}(?:[ \t]*\r?\n)?/gu, (face) => {
+        let empty = false;
+        const kept = face.replace(/(\bsrc\s*:)([^;}]*)(;?)/u, (_all, key, list, end) => {
+            const sources = splitSources(list).filter((source) => {
+                const url = sourceUrl(source);
+                return url === undefined ? source.trim() !== "" : staged.has(url);
+            });
+            if (!sources.length) empty = true;
+            return `${key} ${sources.map((source) => source.trim()).join(", ")}${end}`;
+        });
+        return empty ? "" : kept;
+    });
+}
+
+/**
+ * Copy the delivered files into a directory, keeping their relative layout so
+ * the stylesheet's `url("fonts/…")` resolves from where it lands. The
+ * stylesheet is rewritten by {@link stagedStylesheet} to name only the files
+ * copied with it.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {string} dest - The directory to fill; created when there is
+ *   something to put in it.
+ * @param {string[]} formats - The font formats the target uses.
+ * @returns {number} How many files were written; 0 when the consumer ships none.
+ */
+export function copyScriptFonts(config, dest, formats) {
+    const found = scriptFontFiles(config, formats);
+    if (!found) return 0;
+    const staged = new Set(found.files);
+    for (const file of found.files) {
+        const to = path.join(dest, file);
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        if (file === STYLESHEET)
+            fs.writeFileSync(
+                to,
+                stagedStylesheet(fs.readFileSync(path.join(found.root, file), "utf8"), staged),
+            );
+        else fs.copyFileSync(path.join(found.root, file), to);
+    }
+    return found.files.length;
+}
+
+/**
+ * Whether the package ships what its manifest and stylesheet promise: the
+ * stylesheet, the licence and every file the manifest lists.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {{file: string, severity: "error", message: string}[]} One finding
+ *   per missing file, located at the manifest; empty when the consumer ships none.
+ */
+export function checkScriptFonts(config) {
+    const installed = delivered(config);
+    if (!installed) return [];
+    const manifest = path.join(installed.root, FONTS_MANIFEST);
+    const wanted = new Set([STYLESHEET, LICENSE]);
+    for (const entry of installed.manifest?.families ?? []) {
+        for (const format of ["woff2", "ttf"]) {
+            const file = entry.files?.[format];
+            if (file) wanted.add(file);
+        }
+    }
+    return [...wanted]
+        .filter((file) => !fs.existsSync(path.join(installed.root, file)))
+        .map((file) => ({
+            file: manifest,
+            severity: /** @type {const} */ ("error"),
+            message:
+                `@heroiclands/fonts ${installed.version} does not ship \`${file}\`, ` +
+                "which the package's fonts depend on",
+        }));
+}
+
+/**
+ * The site param naming the stylesheet, relative to the site root.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {string|undefined} The versioned address, or `undefined` when the
+ *   site ships no fonts.
+ */
+export function siteFontsParam(config) {
+    const found = scriptFontFiles(config, ["woff2"]);
+    return found ? `${SITE_FONTS_DIR}/${found.version}/${STYLESHEET}` : undefined;
+}
+
+/**
+ * The directory under the Hugo 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`.
+ */
+export function siteFontsDestination(version) {
+    return `${SITE_FONTS_DIR}/${version}`;
+}
+
+/**
+ * The manifest `styles`, with the fonts' stylesheet named after the base sheet.
+ *
+ * @param {object} options
+ * @param {unknown} options.styles - The `styles` so far, base sheet included.
+ * @param {"system"|"module"} options.artifact - Which artifact is shipped.
+ * @param {boolean} options.delivered - Whether the module carries the fonts.
+ * @returns {unknown} The `styles` to emit.
+ */
+export function withScriptFontStyle({ styles, artifact, delivered: carried }) {
+    if (!carried) return styles;
+    const list = Array.isArray(styles) ? styles : [];
+    const src = `${STAGED_FONTS_DIR}/${STYLESHEET}`;
+    const names = (entry) => (typeof entry === "string" ? entry : entry?.src);
+    if (list.some((entry) => names(entry) === src)) return list;
+    const entry = { src, layer: baseStyleLayer(artifact) };
+    const baseAt = list.findIndex((item) => names(item) === "styles/package-build-base.css");
+    return [...list.slice(0, baseAt + 1), entry, ...list.slice(baseAt + 1)];
+}
+
+/**
+ * The directory of TTFs a book's compiler searches.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {string|undefined} The package's `fonts/` directory, or `undefined`
+ *   when the consumer ships no fonts.
+ */
+export function typstScriptFontPath(config) {
+    const installed = delivered(config);
+    return installed ? path.join(installed.root, "fonts") : undefined;
+}