@heroiclands/package-build 25.1.1 → 25.1.3

package/engine/language-writings.mjs

@@ -80,8 +80,13 @@ function oneOf(form, candidates) {
     return { ambiguous: { form, glosses: candidates.map(({ gloss }) => gloss) } };
 }
 
+/** Each language data's writings, by encoding and face. */
+const writingsFound = new WeakMap();
+
 /**
- * The writings of a language's words under one encoding in one face.
+ * The writings of a language's words under one encoding in one face. One
+ * `data` yields one set of writings per encoding and face, and each word's
+ * writing is found once, so `data` must not be modified once it is read here.
  *
  * @param {Record<string, any>|undefined} data - The language note's `data`.
  * @param {string} enc - The encoding's name.
@@ -90,6 +95,34 @@ function oneOf(form, candidates) {
  *   The writing of a run's word, and of the `data.words` entry at an index.
  */
 export function writingsOf(data, enc, font) {
+    if (!isMap(data)) return findWritings(data, enc, font);
+    if (!writingsFound.has(data)) writingsFound.set(data, new Map());
+    const byFace = writingsFound.get(data);
+    const key = JSON.stringify([enc, font ?? null]);
+    if (!byFace.has(key)) {
+        const found = findWritings(data, enc, font);
+        const words = new Map();
+        byFace.set(key, {
+            word: (written) => {
+                if (!words.has(written)) words.set(written, found.word(written));
+                return words.get(written);
+            },
+            entry: found.entry,
+        });
+    }
+    return byFace.get(key);
+}
+
+/**
+ * The writings of a language's words under one encoding in one face, found
+ * afresh; see {@link writingsOf}.
+ *
+ * @param {Record<string, any>|undefined} data - The language note's `data`.
+ * @param {string} enc - The encoding's name.
+ * @param {string|undefined} font - The face.
+ * @returns {{word: (word: string) => Writing, entry: (index: number) => Writing}}
+ */
+function findWritings(data, enc, font) {
     const words = listOf(data?.words);
     const affixes = listOf(data?.affixes).filter(isMap);
     const grammar = isMap(data?.grammar) ? data.grammar : undefined;

package/engine/markdown-blocks.mjs

@@ -0,0 +1,58 @@
+/*
+ * 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 block structure of a Markdown source, in the renderer's grammar.
+ *
+ * Several scanners ask only where a source's fences, code blocks, raw HTML and
+ * quotes lie, each reading block tokens' `type`, `map` and `level` and nothing
+ * else. Inline parsing fills only an `inline` token's `children`, so this
+ * parser skips it, and the block tokens it yields are the ones a full parse
+ * yields. The scanners commonly ask about the same source in turn, so the most
+ * recent sources' tokens are kept.
+ *
+ * @module
+ */
+
+import MarkdownIt from "markdown-it";
+
+/** The renderer's block grammar, with inline parsing and its passes switched off. */
+const parser = new MarkdownIt({ html: true });
+parser.core.ruler.disable(["inline", "linkify", "replacements", "smartquotes", "text_join"]);
+
+/** How many recent sources keep their tokens. */
+const RECENT = 16;
+
+/** @type {Map<string, import("markdown-it").Token[]>} */
+const recent = new Map();
+
+/**
+ * The block tokens of a Markdown source. The array is shared between callers
+ * and must not be modified; an `inline` token carries no `children`.
+ *
+ * @param {unknown} source - Markdown.
+ * @returns {readonly import("markdown-it").Token[]} The block tokens, in order.
+ */
+export function blockTokens(source) {
+    const text = String(source ?? "");
+    const hit = recent.get(text);
+    if (hit) {
+        recent.delete(text);
+        recent.set(text, hit);
+        return hit;
+    }
+    const tokens = parser.parse(text, {});
+    recent.set(text, tokens);
+    if (recent.size > RECENT) recent.delete(recent.keys().next().value);
+    return tokens;
+}

package/engine/note-vocabulary.mjs

@@ -773,7 +773,8 @@ const NAMES_FIELD = Object.freeze({
         'builds a name from placeholders such as "{given} {clan}" and literal text, `given` ' +
         "maps a gender to a list of given names, " +
         `${wordList([...requiredGivenGenders()]).replace(" or ", " and ")} required, and ` +
-        "every other key is a list of names a placeholder of the same name draws from. A " +
+        "`en` holds groups of English names, and every other key is a list of names a " +
+        "placeholder of the same name draws from. A " +
         "language skill note only. See [name lists](format-details.md#name-lists).",
     fields: Object.freeze([
         Object.freeze({
@@ -783,7 +784,8 @@ const NAMES_FIELD = Object.freeze({
             shape: 'a pattern such as "{given} {clan}", a list of them, or a map of genders to either',
             describe:
                 "How a name is built: each `{list}` placeholder is filled from the list of " +
-                "that name, `{given.<gender>}` from that gender's given names, and the text " +
+                "that name, `{given.<gender>}` from that gender's given names, `{en.<list>}` from a " +
+                "list of English names, and the text " +
                 "around them is written as it stands. A list states every form a name may " +
                 "take; a map keyed by gender states each gender's forms, and a gender with " +
                 "none takes every pattern stated.",
@@ -822,6 +824,24 @@ const NAMES_FIELD = Object.freeze({
                 }),
             }),
         }),
+        Object.freeze({
+            name: "en",
+            kind: "map",
+            shape: "a map of list names to lists of English names",
+            describe:
+                "English names, never encoded in the tongue's script. A pattern draws from one " +
+                "list as `{en.<list>}`, as `{en.epithet}` does.",
+            values: Object.freeze({
+                kind: "list",
+                shape: "a list of English names",
+                describe: "A list of English names a placeholder draws from.",
+                entries: Object.freeze({
+                    kind: "string",
+                    shape: "a name",
+                    describe: "One English name, as written.",
+                }),
+            }),
+        }),
     ]),
     values: Object.freeze({
         kind: "list",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "25.1.1",
+    "version": "25.1.3",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/content-index.d.mts

@@ -225,10 +225,12 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @param {Map<string, {raw: string}>} [options.sources] - Selected captured source strings.
  * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Session scanner projections.
  * @param {Iterable<string>} [options.nameTypes] - Additional bare name kinds from configured type declarations.
+ * @param {ReturnType<typeof import("./content-timings.mjs").createContentTimings>} [options.timings] -
+ *   Invocation stage accounting, which records each phase of the derivation.
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, rootDir, languages, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
+export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, rootDir, languages, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, timings, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
@@ -257,6 +259,17 @@ export function collectContentIndex(contentBase: string, { contentPackage, curre
     }> | undefined;
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
     nameTypes?: Iterable<string> | undefined;
+    timings?: {
+        sync<T>(name: string, work: () => T): T;
+        measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        start(name: string): () => void;
+        hit(name: string): void;
+        snapshot(): {
+            totalMs: number;
+            stages: any;
+            hits: any;
+        };
+    } | undefined;
 }): Array<Record<string, any>>;
 /**
  * Serialize records as JSON Lines.
@@ -301,9 +314,11 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  * @param {import("./content-session.mjs").ContentSyntax} [opts.syntax] - Session scanner projections.
  * @param {Iterable<string>} [opts.nameTypes] - Bare name kinds, defaulting to configured item types.
  * @param {Map<string, object>} [opts.foreignIndex] - Captured dependency address view.
+ * @param {ReturnType<typeof import("./content-timings.mjs").createContentTimings>} [opts.timings] -
+ *   Invocation stage accounting.
  * @returns {object[]} One record per note, plus one per documentation entry.
  */
-export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, sources, syntax, nameTypes, foreignIndex, }?: {
+export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, sources, syntax, nameTypes, foreignIndex, timings, }?: {
     contentBase?: string | undefined;
     assetsBase?: string | undefined;
     config?: object | undefined;
@@ -322,6 +337,17 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
     nameTypes?: Iterable<string> | undefined;
     foreignIndex?: Map<string, object> | undefined;
+    timings?: {
+        sync<T>(name: string, work: () => T): T;
+        measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        start(name: string): () => void;
+        hit(name: string): void;
+        snapshot(): {
+            totalMs: number;
+            stages: any;
+            hits: any;
+        };
+    } | undefined;
 }): object[];
 /**
  * Prepare the complete bodies a content-index publication describes.

package/types/engine/content-session.d.mts

@@ -27,6 +27,7 @@ export function createContentSession({ config, contentBase, assetsBase, skipDire
     timings?: {
         sync<T>(name: string, work: () => T): T;
         measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        start(name: string): () => void;
         hit(name: string): void;
         snapshot(): {
             totalMs: number;

package/types/engine/content-timings.d.mts

@@ -4,6 +4,13 @@ export function createContentTimings(): {
     sync<T>(name: string, work: () => T): T;
     /** @template T @param {string} name @param {() => Promise<T>|T} work @returns {Promise<T>} */
     measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+    /**
+     * Open a stage that runs until the returned function is called, or
+     * until the stage it was opened in ends.
+     * @param {string} name
+     * @returns {() => void}
+     */
+    start(name: string): () => void;
     /** @param {string} name */
     hit(name: string): void;
     snapshot(): {

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

@@ -59,24 +59,11 @@ export function languageNoteFindings(config: {
  *   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>>;
-/** Project only conversion-readable language data to a JSON-safe object. */
-export function serializeLexicon(lexicon: any): {
-    language: any;
-    data: {
-        grammar?: {
-            [k: string]: any;
-        } | undefined;
-        words: {
-            [k: string]: any;
-        }[];
-        affixes: {
-            [k: string]: any;
-        }[];
-        register: {
-            [k: string]: any;
-        }[];
-    };
-} | undefined;
+/**
+ * Project only conversion-readable language data to a JSON-safe object. The
+ * projection of one lexicon is made once and shared, so it must not be modified.
+ */
+export function serializeLexicon(lexicon: any): any;
 /**
  * Resolve encoding, face and optional language input without loading files.
  *
@@ -129,23 +116,7 @@ export function encodingFor(ctx: import("./content-scripts.mjs").RunContext, { e
         };
     }>;
     font: any;
-    lexicon: {
-        language: any;
-        data: {
-            grammar?: {
-                [k: string]: any;
-            } | undefined;
-            words: {
-                [k: string]: any;
-            }[];
-            affixes: {
-                [k: string]: any;
-            }[];
-            register: {
-                [k: string]: any;
-            }[];
-        };
-    } | undefined;
+    lexicon: any;
 } | undefined;
 /** Why a face is incompatible with the selected encoding. */
 export function fontProblem(encoding: any, font: any): string | undefined;

package/types/engine/language-names.d.mts

@@ -104,6 +104,8 @@ export function drawName(names: object, gender: string, next: () => number): str
 export function nameMisfit(full: string, names: object, gender: string): string | undefined;
 /** The `skill` subType whose notes may carry name lists. */
 export const NAMES_SUBTYPE: "language";
+/** The key whose groups of lists hold English names. */
+export const ENGLISH_GROUP: "en";
 /** The placeholder that draws from the given-name list for a gender. */
 export const GIVEN_LIST: "given";
 /**
@@ -115,6 +117,7 @@ export type PatternPart = {
 } | {
     list: string;
     gender?: string;
+    sub?: string;
 };
 /**
  * One thing wrong with a language's name lists.

package/types/engine/language-writings.d.mts

@@ -16,7 +16,9 @@
  */
 export function nativeText(natives: unknown, enc: string, font: string | undefined): string | undefined;
 /**
- * The writings of a language's words under one encoding in one face.
+ * The writings of a language's words under one encoding in one face. One
+ * `data` yields one set of writings per encoding and face, and each word's
+ * writing is found once, so `data` must not be modified once it is read here.
  *
  * @param {Record<string, any>|undefined} data - The language note's `data`.
  * @param {string} enc - The encoding's name.

package/types/engine/markdown-blocks.d.mts

@@ -0,0 +1,8 @@
+/**
+ * The block tokens of a Markdown source. The array is shared between callers
+ * and must not be modified; an `inline` token carries no `children`.
+ *
+ * @param {unknown} source - Markdown.
+ * @returns {readonly import("markdown-it").Token[]} The block tokens, in order.
+ */
+export function blockTokens(source: unknown): readonly import("markdown-it").Token[];