@heroiclands/package-build 23.12.5 → 23.12.7

package/engine/language-data.mjs

@@ -34,6 +34,9 @@
  *   type;
  * - every language a cognate's `forms` names is a language note;
  * - a register row states a `tongue` or a `kind`;
+ * - a register row tagged `other:<tongue>` or `exonym:<tongue>` names a name
+ *   the tongue's own language note registers under that tongue, case folded
+ *   and NFC (see {@link foreignRowFindings});
  * - a sound-change set's name stands once in the note, a step's label once
  *   in its set, and its `from` and `to` name language notes;
  * - a frame's classes are bases of the master word classes;
@@ -52,7 +55,7 @@
 
 import { pathLabel as label } from "./data-keys.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
-import { addressKeyOf } from "./culture-reach.mjs";
+import { addressKeyOf, isLanguageNote } from "./culture-reach.mjs";
 import { AddressEntries } from "./address-values.mjs";
 import { isAddressTuple, renderAddress } from "./address.mjs";
 import {
@@ -111,6 +114,119 @@ export function tongueDeclared(tag, declared) {
         :   declared.has(`${match[1]}:${TONGUE_PLACEHOLDER}`);
 }
 
+/** The tag families whose rows name a name of another tongue's register. */
+const FOREIGN_FAMILIES = new Set(["other", "exonym"]);
+
+/** How a foreign row that its tongue's register does not bear out is reported. */
+export const FOREIGN_ROW_SEVERITY = "warning";
+
+/** A name as a foreign row is compared: NFC and lowercase. */
+const foldName = (name) => name.normalize("NFC").toLowerCase();
+
+/**
+ * Each tag a language note of the index declares with a `language`, to the
+ * canonical Addresses of the language notes it names, keyed once per index.
+ *
+ * @type {WeakMap<object, Map<string, Set<string>>>}
+ */
+const tongueLanguagesByIndex = new WeakMap();
+
+/**
+ * The language notes each tag names: every `data.tongues` entry of the index's
+ * own language notes whose `tag` is a plain tag and that states a `language`.
+ *
+ * @param {object} index - The link index.
+ * @returns {Map<string, Set<string>>} Canonical Addresses by tag.
+ */
+function tongueLanguages(index) {
+    const known = tongueLanguagesByIndex.get(index);
+    if (known) return known;
+    const out = new Map();
+    for (const note of index.notes ?? []) {
+        if (!isLanguageNote(note.fm)) continue;
+        for (const tongue of listOf(note.fm?.data?.tongues)) {
+            if (!isMap(tongue) || typeof tongue.tag !== "string" || tongue.tag.includes(":"))
+                continue;
+            const key = addressKeyOf(tongue.language, index, "skill");
+            if (!key) continue;
+            if (!out.has(tongue.tag)) out.set(tongue.tag, new Set());
+            out.get(tongue.tag).add(key);
+        }
+    }
+    tongueLanguagesByIndex.set(index, out);
+    return out;
+}
+
+/**
+ * The findings on a register's rows tagged `other:<tongue>` or
+ * `exonym:<tongue>`, each checked against the register of the tongue's own
+ * language note.
+ *
+ * A tongue names the language note a `data.tongues` entry of one of the
+ * index's language notes tags it with, through its `language`: `other:helonic`
+ * reads the note that `{tag: helonic, language: skill-helonclng}` names. The
+ * row passes when that note's `data.register` holds a row of the same name
+ * whose `tongue` is `helonic`. A tongue no entry links to a language note, or
+ * one linked to two, is a finding at the row's `tongue`; a language note of
+ * another package is not read, since its register does not reach this index.
+ * Bare `other`, and every other tag, are not checked.
+ *
+ * @param {Array<{row: object, i: number}>} rows - The register rows whose tag
+ *   `data.tongues` declares.
+ * @param {object|undefined} index - The link index.
+ * @param {(path: Array<string|number>, severity: string, message: string) => object} finding -
+ *   Builds a finding at a frontmatter path.
+ * @returns {object[]} The findings.
+ */
+function foreignRowFindings(rows, index, finding) {
+    if (!index?.addressHit) return [];
+    const findings = [];
+    for (const { row, i } of rows) {
+        const match = USED_TAG_PATTERN.exec(row.tongue);
+        if (!match || match[2] === undefined || !FOREIGN_FAMILIES.has(match[1])) continue;
+        const tongue = match[2];
+        const languages = [...(tongueLanguages(index).get(tongue) ?? [])];
+        if (languages.length !== 1) {
+            findings.push(
+                finding(
+                    ["data", "register", i, "tongue"],
+                    FOREIGN_ROW_SEVERITY,
+                    languages.length ?
+                        `the tongue \`${tongue}\` in \`${row.tongue}\` names ${languages.length} ` +
+                            `language notes, ${languages.join(" and ")}; the \`data.tongues\` entries ` +
+                            `tagged \`${tongue}\` name one`
+                    :   `the tongue \`${tongue}\` in \`${row.tongue}\` names no language note: no ` +
+                            `language note's \`data.tongues\` tags \`${tongue}\` with a \`language\``,
+                ),
+            );
+            continue;
+        }
+        const target = index.addressHit(languages[0]);
+        const fm = target?.fm;
+        if (!fm || !isLanguageNote(fm)) continue;
+        const name = foldName(row.name);
+        const listed = listOf(fm.data?.register).some(
+            (other) =>
+                isMap(other) &&
+                other.tongue === tongue &&
+                typeof other.name === "string" &&
+                foldName(other.name) === name,
+        );
+        if (listed) continue;
+        const title = typeof fm.name?.full === "string" ? fm.name.full : fm.name;
+        findings.push(
+            finding(
+                ["data", "register", i, "name"],
+                FOREIGN_ROW_SEVERITY,
+                `\`${row.name}\` is registered as \`${row.tongue}\`, but the register of ` +
+                    `${title} (${fm.type}-${fm.shortcode}) lists no \`${tongue}\` name ` +
+                    `\`${row.name}\`; correct the spelling, or register the name there first`,
+            ),
+        );
+    }
+    return findings;
+}
+
 /**
  * The entries of a cognate's `forms`, whatever form it reached the check in:
  * `[written key, value, Address]`.
@@ -192,6 +308,22 @@ export function checkLanguageData(note, { index, types } = {}) {
                     "`data.grammar.verbs` must state exactly one of `invariant: true` or `persons`",
                 ),
             );
+        else if (invariant && Object.hasOwn(verbs, "replaces"))
+            findings.push(
+                finding(
+                    ["data", "grammar", "verbs", "replaces"],
+                    "error",
+                    "`data.grammar.verbs.replaces` states what a `persons` ending replaces, and an invariant pattern has none",
+                ),
+            );
+        else if (typeof verbs.replaces === "string" && !verbs.replaces.trim())
+            findings.push(
+                finding(
+                    ["data", "grammar", "verbs", "replaces"],
+                    "error",
+                    "`data.grammar.verbs.replaces` must name the letters an ending replaces; leave it out where endings are added",
+                ),
+            );
         else if (invariant && (verbs.invariant == null || verbs.invariant === false))
             findings.push(
                 finding(
@@ -319,6 +451,7 @@ export function checkLanguageData(note, { index, types } = {}) {
             );
         });
     };
+    const foreignRows = [];
     listOf(data.register).forEach((row, i) => {
         if (!isMap(row)) return;
         if (row.tongue == null && row.kind == null)
@@ -331,7 +464,10 @@ export function checkLanguageData(note, { index, types } = {}) {
             );
         if (typeof row.tongue !== "string") return;
         undeclared([row.tongue], () => ["data", "register", i, "tongue"]);
+        if (typeof row.name === "string" && tongueDeclared(row.tongue, declared))
+            foreignRows.push({ row, i });
     });
+    findings.push(...foreignRowFindings(foreignRows, index, finding));
 
     // ── Sounds ───────────────────────────────────────────────────────────────
     const sounds = isMap(data.sounds) ? data.sounds : {};

package/engine/language-tag.mjs

@@ -0,0 +1,103 @@
+/*
+ * 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
+ */
+
+/**
+ * **BCP 47 language tags** (RFC 5646), checked without the IANA registry.
+ *
+ * A tag is accepted when it is well-formed by the RFC's grammar and meets the
+ * two validity rules that need no registry: no variant subtag appears twice,
+ * and no extension singleton appears twice. Matching is case-insensitive, as
+ * the RFC requires. Whether each subtag is registered is not checked.
+ *
+ * A constructed language takes `art-x-<name>`: `art` is the registered
+ * collective code for artificial languages, and the private-use part names
+ * which one.
+ *
+ * @module
+ */
+
+const ALPHANUM = "[a-z0-9]";
+
+/** What separates a tag's subtags: RFC 5646's own separator, not an Address's. */
+const SUBTAG_SEPARATOR = "-";
+
+/** `langtag`, with each part captured so the validity rules can read them. */
+const LANGTAG = new RegExp(
+    "^" +
+        // language: 2–3 letters with up to three extlangs, 4 letters, or 5–8 letters
+        "(?:[a-z]{2,3}(?:-[a-z]{3}){0,3}|[a-z]{4}|[a-z]{5,8})" +
+        // script
+        "(?:-[a-z]{4})?" +
+        // region
+        "(?:-(?:[a-z]{2}|[0-9]{3}))?" +
+        // variants
+        `((?:-(?:${ALPHANUM}{5,8}|[0-9]${ALPHANUM}{3}))*)` +
+        // extensions: a singleton other than x, then subtags of 2–8
+        `((?:-[0-9a-wy-z](?:-${ALPHANUM}{2,8})+)*)` +
+        // private use
+        `(?:-x(?:-${ALPHANUM}{1,8})+)?` +
+        "$",
+    "i",
+);
+
+/** A tag that is private use alone. */
+const PRIVATE_USE = new RegExp(`^x(?:-${ALPHANUM}{1,8})+$`, "i");
+
+/** RFC 5646's grandfathered tags, which the grammar does not otherwise admit. */
+const GRANDFATHERED = new Set([
+    "en-gb-oed",
+    "i-ami",
+    "i-bnn",
+    "i-default",
+    "i-enochian",
+    "i-hak",
+    "i-klingon",
+    "i-lux",
+    "i-mingo",
+    "i-navajo",
+    "i-pwn",
+    "i-tao",
+    "i-tay",
+    "i-tsu",
+    "sgn-be-fr",
+    "sgn-be-nl",
+    "sgn-ch-de",
+    "art-lojban",
+    "cel-gaulish",
+    "no-bok",
+    "no-nyn",
+    "zh-guoyu",
+    "zh-hakka",
+    "zh-min",
+    "zh-min-nan",
+    "zh-xiang",
+]);
+
+/**
+ * Whether a value is a BCP 47 language tag.
+ *
+ * @param {unknown} value - The value to test.
+ * @returns {boolean} Whether it is a well-formed tag with no repeated variant
+ *   or extension singleton.
+ */
+export function isLanguageTag(value) {
+    if (typeof value !== "string" || value === "") return false;
+    const tag = value.toLowerCase();
+    if (GRANDFATHERED.has(tag) || PRIVATE_USE.test(tag)) return true;
+    const match = LANGTAG.exec(tag);
+    if (!match) return false;
+    const variants = match[1].split(SUBTAG_SEPARATOR).filter(Boolean);
+    if (new Set(variants).size !== variants.length) return false;
+    const singletons = match[2].split(SUBTAG_SEPARATOR).filter((part) => part.length === 1);
+    return new Set(singletons).size === singletons.length;
+}

package/engine/language-terms.mjs

@@ -1597,7 +1597,8 @@ function listOfMaps(name, fields, describe) {
 
 /**
  * The six present persons of the one optional regular verb pattern, in
- * presentation order. Empty endings leave the citation form unchanged.
+ * presentation order. Each ending is added to the citation form, or takes the
+ * place of its closing `replaces`; an empty ending adds nothing.
  *
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
  */
@@ -1617,7 +1618,7 @@ export const VERB_PERSON_FIELDS = Object.freeze(
             required: true,
             allowEmpty: true,
             shape: "an ending string, empty for unchanged",
-            describe: `The ending added to the citation form for ${label}.`,
+            describe: `The ending for ${label}, added to the citation form or in place of its closing \`replaces\`.`,
         }),
     ),
 );
@@ -1635,7 +1636,18 @@ const VERB_PATTERN_FIELDS = Object.freeze([
         kind: "map",
         shape: "a map — `{ I, you, heShe, we, youAll, they }` of ending strings",
         fields: VERB_PERSON_FIELDS,
-        describe: "All six present endings, each added to the citation form; excludes `invariant`.",
+        describe:
+            "All six present endings, each added to the citation form or in place of its " +
+            "closing `replaces`; excludes `invariant`.",
+    }),
+    Object.freeze({
+        name: "replaces",
+        kind: "string",
+        shape: "the closing letters every ending takes the place of",
+        describe:
+            "Letters a citation form closes on, swapped for each `persons` ending: with `then`, " +
+            "`lokathen` and `zor` give `lokazor`. A citation form closing otherwise takes the " +
+            "ending whole. With `persons` only.",
     }),
 ]);
 
@@ -1664,7 +1676,7 @@ const GRAMMAR_FIELDS = Object.freeze([
     Object.freeze({
         name: "verbs",
         kind: "map",
-        shape: "a map — `{ invariant: true }` or `{ persons: { I, you, heShe, we, youAll, they } }`",
+        shape: "a map — `{ invariant: true }` or `{ persons: { I, you, heShe, we, youAll, they }, replaces? }`",
         fields: VERB_PATTERN_FIELDS,
         describe: "One optional regular present pattern, printed once at the dictionary head.",
     }),