@heroiclands/package-build 24.1.1 → 25.1.0

package/engine/written-in.mjs

@@ -1,204 +0,0 @@
-/*
- * 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 script a language is written in.** A language note — a `skill` of
- * `subType: language` — names the map and the face its text is written in:
- *
- * ```yaml
- * data:
- *   writtenIn: { map: semaron, font: semaron-kuriale }
- * ```
- *
- * These are native-presentation defaults, not an effect of identifying a
- * language. A rendering run requests them with its own `.nativefont` class
- * and explicit `lang=`; plain `[Zaron tholmeza]{lang=vyl}` stays Roman.
- * The renderer fills the map and font independently, honoring explicit
- * overrides and reporting an incompatible pair rather than silently omitting
- * a default. A nested marked run makes its own presentation choice.
- *
- * The low-level `fromWrittenIn` helper also serves explicit conversion
- * commands. It returns compatible default suggestions to those callers;
- * rendering opt-in and its required-font diagnostics belong to the run reader.
- *
- * @module
- */
-
-import { positionOfFrontmatterPath } from "./diagnostics.mjs";
-import { nearest } from "./near-miss.mjs";
-import { compileMap } from "./text-maps.mjs";
-import { LANGUAGE_SUBTYPE } from "./word-terms.mjs";
-
-/** The `data` key a language note names its script in. */
-export const WRITTEN_IN_KEY = "writtenIn";
-
-/**
- * A language's script.
- *
- * @typedef {object} WrittenIn
- * @property {string} map - The `data.map.name` of the mapping note.
- * @property {string} font - The slug of the face, one the map is drawn in.
- */
-
-/** Whether a value is a plain map. */
-const isMap = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
-
-/**
- * Whether a map is drawn in a face: it lists the face, or lists none.
- *
- * @param {import("./text-maps.mjs").TextMap} map - The map.
- * @param {string} font - The face's slug.
- * @returns {boolean} Whether the map may set text in it.
- */
-export function drawnIn(map, font) {
-    return !map.fonts.size || map.fonts.has(font);
-}
-
-/** A list of names as prose: `a`, `a` and `b`, `a`, `b` and `c`. */
-function said(names) {
-    const quoted = names.map((name) => `\`${name}\``);
-    return quoted.length < 2 ?
-            quoted.join("")
-        :   `${quoted.slice(0, -1).join(", ")} and ${quoted.at(-1)}`;
-}
-
-/**
- * The script each configured language's note names, where the map is known
- * and is drawn in the face. A default that names an unknown map or a face its
- * map is not drawn in is the note's finding, and fills no run.
- *
- * @param {ReadonlyMap<string, Record<string, any>>} byName - Each configured
- *   language's note record, by language name, from
- *   {@link module:engine/map-lexicon.languageRecordsByName}.
- * @param {ReadonlyMap<string, import("./text-maps.mjs").TextMap>} maps - The
- *   maps by name.
- * @returns {Map<string, WrittenIn>} The scripts, by language name.
- */
-export function writtenInOf(byName, maps) {
-    const out = new Map();
-    for (const [name, record] of byName ?? []) {
-        const value = record?.data?.[WRITTEN_IN_KEY];
-        if (!isMap(value) || typeof value.map !== "string" || typeof value.font !== "string")
-            continue;
-        const map = maps?.get(value.map);
-        if (!map || !drawnIn(map, value.font)) continue;
-        out.set(name, Object.freeze({ map: value.map, font: value.font }));
-    }
-    return out;
-}
-
-/**
- * The keys a run takes from its language's script: each of `map` and `font`
- * the run does not state, where it agrees with the one the run does.
- *
- * @param {{lang?: string, map?: string, font?: string}} keys - The run's keys,
- *   its own and those it inherits.
- * @param {ReadonlyMap<string, WrittenIn>|undefined} scripts - Each language's
- *   script, from {@link writtenInOf}.
- * @param {ReadonlyMap<string, import("./text-maps.mjs").TextMap>|undefined} maps -
- *   The maps by name.
- * @returns {{map?: string, font?: string}} What the run takes; empty when it
- *   takes nothing.
- */
-export function fromWrittenIn(keys, scripts, maps) {
-    if (keys.lang === undefined || (keys.map !== undefined && keys.font !== undefined)) return {};
-    const script = scripts?.get(keys.lang);
-    if (!script) return {};
-    if (keys.map === undefined && keys.font === undefined) return { ...script };
-    if (keys.map === undefined) {
-        const map = maps?.get(script.map);
-        return map && drawnIn(map, /** @type {string} */ (keys.font)) ? { map: script.map } : {};
-    }
-    const map = maps?.get(keys.map);
-    return map && drawnIn(map, script.font) ? { font: script.font } : {};
-}
-
-/** The maps each lint index's notes declare, read once. */
-const declaredMaps = new WeakMap();
-
-/**
- * Each map the index's notes declare, by name; the first note to declare a
- * name keeps it.
- *
- * @param {{notes?: Iterable<{fm?: Record<string, any>}>}} index - The lint index.
- * @returns {Map<string, import("./text-maps.mjs").TextMap>} The maps.
- */
-function mapsIn(index) {
-    const known = declaredMaps.get(index);
-    if (known) return known;
-    const maps = new Map();
-    for (const note of index.notes ?? []) {
-        const map = compileMap(note?.fm?.data?.map);
-        if (map && !maps.has(map.name)) maps.set(map.name, map);
-    }
-    declaredMaps.set(index, maps);
-    return maps;
-}
-
-/**
- * Check a note's `data.writtenIn`: that the note is a language, that `map`
- * names a map a mapping note declares, and that the map is drawn in `font`.
- * The data-key check owns the keys and their kinds.
- *
- * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
- * @param {{index?: {notes?: Iterable<object>}}} [context] - The lint index;
- *   without one, only the note's `subType` is checked.
- * @returns {object[]} The findings, each at its key or value.
- */
-export function checkWrittenIn(note, { index } = {}) {
-    const value = note?.fm?.data?.[WRITTEN_IN_KEY];
-    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", WRITTEN_IN_KEY, ...keyPath], { key }),
-        severity: "error",
-        message,
-    });
-    if (String(note.fm?.subType ?? "").toLowerCase() !== LANGUAGE_SUBTYPE)
-        return [
-            finding(
-                [],
-                `\`data.${WRITTEN_IN_KEY}\` names the script a language is written in, and this ` +
-                    `note's \`subType\` is not \`${LANGUAGE_SUBTYPE}\``,
-                true,
-            ),
-        ];
-    if (!index || !isMap(value) || typeof value.map !== "string") return [];
-    const maps = mapsIn(index);
-    const map = maps.get(value.map);
-    if (!map) {
-        const near = nearest(value.map, [...maps.keys()]);
-        return [
-            finding(
-                ["map"],
-                `\`data.${WRITTEN_IN_KEY}.map\` is \`${value.map}\`, which no mapping note's ` +
-                    "`data.map.name` declares" +
-                    (near ? `; did you mean \`${near}\`?` : ""),
-            ),
-        ];
-    }
-    if (typeof value.font !== "string" || drawnIn(map, value.font)) return [];
-    return [
-        finding(
-            ["font"],
-            `\`data.${WRITTEN_IN_KEY}.font\` is \`${value.font}\`, which the map \`${map.name}\` ` +
-                `is not drawn in; it is drawn in ${said([...map.fonts.keys()])}`,
-        ),
-    ];
-}

package/types/engine/map-lexicon.d.mts

@@ -1,330 +0,0 @@
-/**
- * Each configured language's lexicon, read from the language note its `note`
- * names and its family chain. The nearest exact NFC form supplies the whole
- * word; grammar, registers and other settings remain the daughter's own.
- * A language with no `note`, or one naming no language note, has none.
- *
- * @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, Lexicon>} The lexicons by language name.
- */
-export function lexiconsFromRecords(records: Iterable<Record<string, any>> | undefined, config?: {
-    languages?: Readonly<Record<string, {
-        tag: string;
-        note?: string;
-    }>>;
-    contentPackage?: string;
-}): Map<string, Lexicon>;
-/**
- * The language note each configured language's `note` names, by language
- * name. A language with no `note`, or one naming no language note, is absent.
- *
- * @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, Record<string, any>>} The records.
- */
-export function languageRecordsByName(records: Iterable<Record<string, any>> | undefined, { languages, contentPackage }?: {
-    languages?: Readonly<Record<string, {
-        tag: string;
-        note?: string;
-    }>>;
-    contentPackage?: string;
-}): Map<string, Record<string, any>>;
-/**
- * Each `languages.<name>.note` that names no language note, at its key.
- *
- * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string, configFile?: string, configText?: string}} config -
- *   The resolved configuration, and where it was read from.
- * @param {Iterable<Record<string, any>>} records - Index records.
- * @returns {object[]} The findings.
- */
-export function languageNoteFindings(config: {
-    languages?: Readonly<Record<string, {
-        tag: string;
-        note?: string;
-    }>>;
-    contentPackage?: string;
-    configFile?: string;
-    configText?: string;
-}, records: Iterable<Record<string, any>>): object[];
-/**
- * A lookup of a word's native form under one map in one face: the form stated
- * for the face, else the one stated for no face.
- *
- * @param {Lexicon|undefined} lexicon - The lexicon.
- * @param {string} map - The map's name.
- * @param {string|undefined} font - The face.
- * @returns {((word: string) => string|undefined)|undefined} The lookup, or
- *   `undefined` with no lexicon.
- */
-export function nativeLookup(lexicon: Lexicon | undefined, map: string, font: string | undefined): ((word: string) => string | undefined) | undefined;
-/**
- * What a run, a passage or a listing is mapped by.
- *
- * @typedef {object} Mapping
- * @property {import("./text-maps.mjs").TextMap} map - The map.
- * @property {string|undefined} font - The face, whose own rows come first.
- * @property {((word: string) => string|undefined)|undefined} native - The
- *   language's native forms under the map in the face, for a map that spells
- *   by its rows.
- * @property {((word: string) => import("./logographic.mjs").Writing)|undefined} writing -
- *   Each word's writing, for a logographic map.
- */
-/**
- * The one path from a map, a face and a language to what rewrites the text.
- *
- * @param {{maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>, lexicons?: ReadonlyMap<string, Lexicon>}} ctx -
- *   The run context.
- * @param {{map: string, font?: string, lang?: string}} keys - The map, the face
- *   and the language.
- * @returns {Mapping|undefined} The mapping, or `undefined` for an unknown map.
- */
-export function mappingFor(ctx: {
-    maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>;
-    lexicons?: ReadonlyMap<string, Lexicon>;
-}, { map, font, lang }: {
-    map: string;
-    font?: string;
-    lang?: string;
-}): Mapping | undefined;
-/**
- * Why a face is not one a map is for, or `undefined` where it is.
- *
- * @param {import("./text-maps.mjs").TextMap} map - The map.
- * @param {string} font - The face's slug.
- * @returns {string|undefined} The problem.
- */
-export function fontProblem(map: import("./text-maps.mjs").TextMap, font: string): string | undefined;
-/**
- * What is wrong with a capitalised word whose native form the rows cannot
- * capitalise.
- *
- * @param {string} word - The word as written.
- * @param {string} lower - The lowercase form the lexicon states.
- * @param {string|undefined} lang - The language.
- * @param {string} map - The map's name.
- * @returns {string} The message.
- */
-export function uncapitalisedMessage(word: string, lower: string, lang: string | undefined, map: string): string;
-/**
- * What is wrong with a word a logographic map gives no writing.
- *
- * @param {string} word - The word as written.
- * @param {object} unwritten - Why it has none, as
- *   {@link module:engine/logographic.writingsOf} says.
- * @param {string|undefined} lang - The run's language.
- * @param {string} map - The map's name.
- * @returns {string} The message.
- */
-export function unwrittenMessage(word: string, unwritten: object, lang: string | undefined, map: string): string;
-/**
- * Map a passage exactly as the build maps a run with the same keys.
- *
- * @param {object} ctx - The run context.
- * @param {{map: string, font?: string, lang?: string}} keys - The map, the face
- *   and the language.
- * @param {string} text - The passage, with no escapes.
- * @returns {{text: string}|{problem: string, about: string}} The mapped text, or the problem.
- */
-export function transliterate(ctx: object, keys: {
-    map: string;
-    font?: string;
-    lang?: string;
-}, text: string): {
-    text: string;
-} | {
-    problem: string;
-    about: string;
-};
-/**
- * Every word of a language's lexicon with its native form under a map: the
- * stated exception, else the rows' spelling, each exactly as the build gives
- * it. With `derived`, the forms the language's rules derive follow the words,
- * each case folded and naming the word it comes from in `from`, so the list
- * is what the mapped-run word check accepts of the lexicon.
- *
- * Under a logographic map an entry carries `source` in place of `exception`:
- * `own` for a writing it states, `parts` for one its parts give, and `none`,
- * with an empty `native`, where it has none. A word whose form a run cannot
- * write, because the form stands for entries written differently, or a part
- * does, also carries `ambiguous: true`; its `native` is still its own
- * writing, the signs a run writes directly for that sense.
- *
- * @param {object} ctx - The run context.
- * @param {{lang: string, map?: string, font?: string, derived?: boolean}} keys -
- *   The language, the map, the face, and whether to list derived forms. A map
- *   or a face left out is the one the language's `data.writtenIn` names.
- * @returns {{entries: Array<{form: string, native: string, exception?: boolean, source?: "own"|"parts"|"none", ambiguous?: true, class: string|null, gloss: string|null, from?: string}>}|{problem: string, about: string}}
- *   The words in `data.words` order, then any derived forms, or the problem.
- */
-export function lexiconEntries(ctx: object, { lang, map, font, derived }: {
-    lang: string;
-    map?: string;
-    font?: string;
-    derived?: boolean;
-}): {
-    entries: Array<{
-        form: string;
-        native: string;
-        exception?: boolean;
-        source?: "own" | "parts" | "none";
-        ambiguous?: true;
-        class: string | null;
-        gloss: string | null;
-        from?: string;
-    }>;
-} | {
-    problem: string;
-    about: string;
-};
-/**
- * Check a mapping note's `fonts` against the installed faces: an unknown face
- * and a face listed twice, at the entry, and each code point a listed face
- * lacks, at the row that writes it.
- *
- * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
- * @param {{faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>, maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>}} ctx -
- *   The run context.
- * @returns {object[]} The findings.
- */
-export function checkMapFonts(note: {
-    file: string;
-    raw?: string;
-    fm?: Record<string, any>;
-}, ctx: {
-    faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>;
-    maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>;
-}): object[];
-/**
- * Check a language note's native forms against the maps and faces: a word's
- * `native`, an affix's, and the endings' in `data.grammar.native`. Each is
- * checked for an unknown map, a face the map is not for, a second form for one
- * map and face (and one ending), and a code point a face it applies in does
- * not draw. A word's form under a map that spells by its rows is also checked
- * for stating what the rows already give; under a logographic map the rows
- * spell no word, so that check does not apply. An affix's and an ending's
- * writings mean something only under a logographic map, and an ending of a
- * person is written only where `data.grammar.verbs` states `persons`. The
- * shape of each entry is the data-key check's.
- *
- * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
- * @param {{faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>, maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>}} ctx -
- *   The run context.
- * @returns {object[]} The findings.
- */
-export function checkLexiconNatives(note: {
-    file: string;
-    raw?: string;
-    fm?: Record<string, any>;
-}, ctx: {
-    faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>;
-    maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>;
-}): object[];
-/**
- * One row per native form of a language note's word, for the `natives`
- * relation: a text is a value of a row, never a struct key, so forms that
- * differ only in case stay apart.
- *
- * @param {Iterable<Record<string, any>>} records - Index records.
- * @returns {Array<Record<string, string|number|null>>} The rows; `word` is the
- *   word's 0-based place in `data.words`, `native` the form's in its `native`.
- */
-export function nativeRows(records: Iterable<Record<string, any>>): Array<Record<string, string | number | null>>;
-/** Every column of the `natives` relation, in order. */
-export const NATIVE_COLUMNS: readonly string[];
-/**
- * One native form, read.
- */
-export type NativeForm = {
-    /**
-     * - The map it is written for.
-     */
-    map: string;
-    /**
-     * - The one face it is for.
-     */
-    font: string | undefined;
-    /**
-     * - The word in the script.
-     */
-    text: string;
-};
-/**
- * One word of a lexicon.
- */
-export type LexiconWord = {
-    /**
-     * - The word as cited.
-     */
-    form: string;
-    /**
-     * - Its class.
-     */
-    class: string | null;
-    /**
-     * - Its senses, joined by `; `.
-     */
-    gloss: string | null;
-    /**
-     * - Its native forms.
-     */
-    natives: readonly NativeForm[];
-};
-/**
- * A language's lexicon.
- */
-export type Lexicon = {
-    /**
-     * - The language's configured name.
-     */
-    language: string;
-    /**
-     * - Its words, in `data.words` order.
-     */
-    words: readonly LexiconWord[];
-    /**
-     * - The native
-     * forms by the word's form, NFC; the first word of a form keeps it.
-     */
-    byForm: ReadonlyMap<string, readonly NativeForm[]>;
-    /**
-     * - The
-     * forms the language's rules derive from its words, folded, as the mapped-run
-     * word check accepts them (see {@link module :engine/word-forms.derivedForms}).
-     */
-    derived: ReadonlyArray<{
-        form: string;
-        from: LexiconWord;
-    }>;
-    /**
-     * - The language note's `data`, which a
-     * logographic map writes words from.
-     */
-    data: Record<string, any>;
-};
-/**
- * What a run, a passage or a listing is mapped by.
- */
-export type Mapping = {
-    /**
-     * - The map.
-     */
-    map: import("./text-maps.mjs").TextMap;
-    /**
-     * - The face, whose own rows come first.
-     */
-    font: string | undefined;
-    /**
-     * - The
-     * language's native forms under the map in the face, for a map that spells
-     * by its rows.
-     */
-    native: ((word: string) => string | undefined) | undefined;
-    /**
-     * -
-     * Each word's writing, for a logographic map.
-     */
-    writing: ((word: string) => import("./logographic.mjs").Writing) | undefined;
-};