@heroiclands/package-build 23.5.1 → 23.6.0

package/engine/literature-notes.mjs

@@ -17,9 +17,10 @@
  * `data.culture`, is a field every lore note but a culture note may state,
  * declared in `culture-choice.mjs`.
  *
- * `data.language` is shared with the `culture` subType: a work names the
- * tongue it is composed in, and a culture names the tongue its people speak,
- * whose name lists `package-build npc new` draws from.
+ * `data.language` is shared beyond literature: a work names the tongue it is
+ * composed in, a culture the tongue its people speak, whose name lists
+ * `package-build npc new` draws from, and an affiliation the trade, temple or
+ * order tongue it keeps.
  *
  * `DataFieldSpec` declares the keys a type accepts, not the subType that may
  * write them, so {@link checkLiteratureNote} scopes these keys to the subTypes
@@ -74,8 +75,8 @@ export function checkLanguageChoice(note, { index } = {}) {
 }
 
 /**
- * `data.language`: the tongue a work is composed in, or the tongue a culture's
- * people speak. Optional on both.
+ * `data.language`: the tongue a work is composed in, the tongue a culture's
+ * people speak, or the tongue an affiliation keeps. Optional on all three.
  *
  * @type {object}
  */
@@ -87,9 +88,10 @@ export const LANGUAGE_FIELD = Object.freeze({
     accepts: Object.freeze(["skill"]),
     check: checkLanguageChoice,
     describe:
-        "The tongue the work is composed in, or on a culture note the tongue its people " +
-        "speak, as a language skill note. `package-build npc new` draws a culture's names " +
-        "from its language's `data.names`. A `literature` or `culture` note only.",
+        "The tongue the note is in, as a language skill note: the tongue a work is composed " +
+        "in, a culture's people speak, or an affiliation keeps as its trade, temple or order " +
+        "tongue. `package-build npc new` draws a culture's names from its language's " +
+        "`data.names`. A `literature` or `culture` lore note, or an affiliation, only.",
 });
 
 /**

package/engine/note-addresses.mjs

@@ -69,6 +69,31 @@ export const STRUCTURED_ADDRESSES = Object.freeze([
         type: "place",
         accepts: ["place"],
     },
+    // A language's word Addresses and a glossary entry's language, read
+    // leniently: a value that is no Address stays as written, for the words or
+    // glossary check to refuse at its own key.
+    {
+        noteType: "skill",
+        path: ["data", "words", "*", "attested"],
+        shape: "list",
+        lenient: true,
+    },
+    {
+        noteType: "skill",
+        path: ["data", "words", "*", "source", "language"],
+        shape: "value",
+        type: "skill",
+        accepts: ["skill"],
+        lenient: true,
+    },
+    ...["lore", "affiliation"].map((noteType) => ({
+        noteType,
+        path: ["data", "glossary", "*", "language"],
+        shape: "value",
+        type: "skill",
+        accepts: ["skill"],
+        lenient: true,
+    })),
 ]);
 
 /**

package/engine/note-vocabulary.mjs

@@ -119,6 +119,20 @@ import {
 } from "./appearance-profile.mjs";
 import { checkExtraFeatures } from "./appearance-features.mjs";
 import { LANGUAGE_FIELD, LITERATURE_FIELDS, checkLiteratureNote } from "./literature-notes.mjs";
+import {
+    AFFIX_FIELDS,
+    GLOSSARY_ENTRY_FIELDS,
+    WORD_FIELDS,
+    WORD_FIELD_FIELDS,
+} from "./word-terms.mjs";
+import { WORD_CLASS_MODIFIERS } from "./word-classes.mjs";
+import {
+    checkLanguageAbbreviation,
+    checkLanguageFamily,
+    checkLanguageWords,
+} from "./language-words.mjs";
+import { checkGlossary } from "./glossary-entries.mjs";
+import { checkAffiliationReach } from "./culture-reach.mjs";
 import { checkLanguageNames, requiredGivenGenders } from "./language-names.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
@@ -540,6 +554,126 @@ const APPEARANCE_PROFILE_FIELD = Object.freeze({
     ]),
 });
 
+/**
+ * A language's words and what they are read against: the class modifiers it
+ * uses, the fields its words are grouped under, and the affixes a word's
+ * pieces may name. A language skill note only; {@link checkLanguageWords}
+ * checks what the values mean.
+ *
+ * @type {ReadonlyArray<DataFieldSpec>}
+ */
+const WORD_DATA_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "classModifiers",
+        kind: "list",
+        shape: "list of word class modifiers",
+        entries: Object.freeze({
+            kind: "string",
+            allowed: Object.freeze(WORD_CLASS_MODIFIERS.map((item) => item.token)),
+            shape: "a word class modifier",
+        }),
+        describe:
+            "The class modifiers the language uses, from the master word classes. A word's " +
+            "class may carry only these. Empty when unstated. A language skill note only.",
+    }),
+    Object.freeze({
+        name: "fields",
+        kind: "list",
+        shape: "list of `{ name, holds }`",
+        entries: Object.freeze({
+            kind: "map",
+            shape: "a map — `{ name, holds }`",
+            fields: WORD_FIELD_FIELDS,
+        }),
+        describe: "The fields the language's words are grouped under. A language skill note only.",
+    }),
+    Object.freeze({
+        name: "words",
+        kind: "list",
+        shape: "list of `{ form, class, field, gloss, … }`",
+        entries: Object.freeze({
+            kind: "map",
+            shape: "a map — `{ form, class, field, gloss, … }`",
+            fields: WORD_FIELDS,
+        }),
+        describe:
+            "The language's words, one map each, in the order they print. A language skill " +
+            "note only. See [a language's words](format-details.md#a-languages-words).",
+    }),
+    Object.freeze({
+        name: "affixes",
+        kind: "list",
+        shape: "list of `{ form, gloss, attaches?, examples? }`",
+        entries: Object.freeze({
+            kind: "map",
+            shape: "a map — `{ form, gloss, attaches?, examples? }`",
+            fields: AFFIX_FIELDS,
+        }),
+        describe:
+            "The affixes a word's `built` pieces may name, each with its gloss. A language " +
+            "skill note only.",
+    }),
+]);
+
+/**
+ * A language's `data.family`: the parent language whose words it reads as its
+ * own. {@link checkLanguageFamily} checks it.
+ *
+ * @type {DataFieldSpec}
+ */
+const FAMILY_FIELD = Object.freeze({
+    name: "family",
+    kind: "address",
+    shape: "an Address",
+    ref: "skill",
+    accepts: Object.freeze(["skill"]),
+    check: checkLanguageFamily,
+    describe:
+        "The parent language, as a language skill note: this language reads the parent's " +
+        "words, and its parents' in turn, as its own. A language skill note only. See " +
+        "[a language's words](format-details.md#a-languages-words).",
+});
+
+/**
+ * A language's `data.abbreviation`: the tag a dictionary prints beside an
+ * entry's class. {@link checkLanguageAbbreviation} checks it.
+ *
+ * @type {DataFieldSpec}
+ */
+const ABBREVIATION_FIELD = Object.freeze({
+    name: "abbreviation",
+    kind: "string",
+    shape: "a string, such as `Prov.`",
+    check: checkLanguageAbbreviation,
+    describe:
+        "The tag a dictionary prints for the language, beside an entry's class and in an " +
+        "etymology, as `Prov.`; the language's full name where unstated. A language skill " +
+        "note only. See [a language's words](format-details.md#a-languages-words).",
+});
+
+/**
+ * A culture's or an affiliation's `data.glossary`: the terms that belong to
+ * its people or members rather than to a language's grammar.
+ * {@link checkGlossary} checks what an entry means.
+ *
+ * @type {DataFieldSpec}
+ */
+const GLOSSARY_FIELD = Object.freeze({
+    name: "glossary",
+    kind: "list",
+    shape: "list of `{ name, name_sort?, common?, definition?, pronunciation?, language? }`",
+    entries: Object.freeze({
+        kind: "map",
+        shape: "a map — `{ name, name_sort?, common?, definition?, pronunciation?, language? }`",
+        fields: GLOSSARY_ENTRY_FIELDS,
+    }),
+    describe:
+        "Its own glossary terms: euphemisms, idioms, terms of art and titles that are not " +
+        "ranks. An entry with a `definition` creates a term or replaces its senses; one " +
+        "without marks a term the note already has. Every entry resolves to a language. " +
+        "Empty when unstated. See [glossary terms](format-details.md#glossary-terms).",
+});
+
 /**
  * A language's `data.names`: the pattern its speakers' names are built by and
  * the lists each part is drawn from. Its keys beyond `pattern` and `given` are
@@ -1527,7 +1661,14 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     affiliation: Object.freeze({
         stubbable: true,
-        check: checkAffiliationRankFloor,
+        // A body's rank floor, whether it reaches a culture at all — a body
+        // reaching none puts its ranks, offices and language in no culture's
+        // glossary — and its own glossary.
+        check: (note, context) => [
+            ...checkAffiliationRankFloor(note, context),
+            ...checkAffiliationReach(note, context),
+            ...checkGlossary(note, context),
+        ],
         subTypes: Object.freeze([
             "guild",
             "order",
@@ -1645,6 +1786,14 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...CULTURE_FIELD,
                 describe: "The people this affiliation belongs to, as a culture lore note.",
             },
+            {
+                ...LANGUAGE_FIELD,
+                describe:
+                    "The trade, temple or order tongue the affiliation keeps, as a language " +
+                    "skill note. It reaches the affiliation's culture, and its words enter that " +
+                    "culture's glossary. A glossary entry that states no `language` is in it.",
+            },
+            GLOSSARY_FIELD,
             {
                 name: "relations",
                 kind: "map",
@@ -1839,6 +1988,9 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     skill: Object.freeze({
         stubbable: true,
+        // A language note's words, held to the master word classes and to what
+        // the note declares; no other skill states them.
+        check: checkLanguageWords,
         subTypes: Object.freeze([
             "social",
             "nature",
@@ -1862,6 +2014,9 @@ export const NOTE_VOCABULARY = Object.freeze({
                 describe: "The skill this one specialises.",
             },
             NAMES_FIELD,
+            FAMILY_FIELD,
+            ABBREVIATION_FIELD,
+            ...WORD_DATA_FIELDS,
         ]),
     }),
 
@@ -2045,6 +2200,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             ...checkCalendarNote(note, context),
             ...checkLiteratureNote(note),
             ...checkCultureSubType(note, context),
+            ...checkGlossary(note, context),
         ],
         data: Object.freeze([
             ...CALENDAR_FIELDS,
@@ -2068,6 +2224,10 @@ export const NOTE_VOCABULARY = Object.freeze({
             LANGUAGE_FIELD,
             EVENTS_FIELD,
             APPEARANCE_PROFILE_FIELD,
+            {
+                ...GLOSSARY_FIELD,
+                describe: `\`culture\` only: ${GLOSSARY_FIELD.describe}`,
+            },
         ]),
     }),
 

package/engine/path-charset.mjs

@@ -0,0 +1,120 @@
+/*
+ * 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 characters a content or picture path may hold.
+ *
+ * Every character of a path is printable 7-bit ASCII, U+0020 to U+007E. A note's
+ * identity comes from its `shortcode` and a picture's from its basename, so a
+ * path's spelling changes no address; what a non-ASCII path does change is how
+ * the file travels. Filesystems disagree on Unicode normalisation, shells and
+ * `git ls-files` quote the bytes, and archive tools and CDN keys each encode
+ * the name their own way.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { DEPLOYED_ASSET_TYPES } from "./asset-types.mjs";
+
+/**
+ * The distinct characters of a string outside U+0020 to U+007E, in order of
+ * first appearance.
+ *
+ * @param {string} text - A path, or one component of one.
+ * @returns {string[]} The offending characters; empty when the text is clean.
+ */
+export function offendingPathCharacters(text) {
+    const found = [];
+    for (const ch of text) {
+        const point = ch.codePointAt(0) ?? 0;
+        if ((point < 0x20 || point > 0x7e) && !found.includes(ch)) found.push(ch);
+    }
+    return found;
+}
+
+/**
+ * The message for a path holding characters outside printable ASCII.
+ *
+ * @param {string[]} characters - The offending characters.
+ * @returns {string} The finding's message.
+ */
+function pathMessage(characters) {
+    const named = characters.map((ch) => {
+        const point = ch.codePointAt(0) ?? 0;
+        const code = `U+${point.toString(16).toUpperCase().padStart(4, "0")}`;
+        return point < 0x20 || point === 0x7f ? code : `${code} (${ch})`;
+    });
+    return (
+        `the path holds ${named.join(", ")}, outside printable ASCII; ` +
+        "rename the file using ASCII only"
+    );
+}
+
+/**
+ * Walk the content tree and the package's picture roots, reporting each entry
+ * whose name holds a character outside printable ASCII.
+ *
+ * An entry is checked by its own name as the walk reaches it, so a directory
+ * with a bad name is reported once and not again for every file beneath it.
+ * Dot-entries and `skipDirectories` are skipped, as in the other content walks.
+ * A finding names its file relative to the working directory, with no line or
+ * column.
+ *
+ * @param {object} opts - Options.
+ * @param {string} opts.contentBase - Root of the content tree.
+ * @param {string} opts.assetsBase - The package's asset directory, whose
+ *   picture roots are walked.
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
+ * @returns {{findings: Array<{file: string, severity: "error", message: string}>,
+ *   files: number}} The findings, and how many paths were checked.
+ */
+export function lintPathCharset({ contentBase, assetsBase, skipDirectories = [] }) {
+    const skip = new Set(skipDirectories);
+    const findings = [];
+    let files = 0;
+
+    /** @param {string} dir - Directory to descend into. */
+    const walk = (dir) => {
+        /** @type {import("node:fs").Dirent[]} */
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || skip.has(entry.name)) continue;
+            const full = path.join(dir, entry.name);
+            files += 1;
+            const bad = offendingPathCharacters(entry.name);
+            if (bad.length) {
+                findings.push({
+                    file: path.relative(process.cwd(), full),
+                    severity: /** @type {const} */ ("error"),
+                    message: pathMessage(bad),
+                });
+            }
+            if (entry.isDirectory()) walk(full);
+        }
+    };
+
+    const roots = new Set([
+        path.resolve(contentBase),
+        ...DEPLOYED_ASSET_TYPES.map((entry) => path.resolve(assetsBase, entry.root)),
+    ]);
+    for (const root of roots) walk(root);
+    return { findings, files };
+}