@heroiclands/package-build 23.13.0 → 24.0.1

package/engine/content-styles.mjs

@@ -0,0 +1,91 @@
+/*
+ * 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 shared rules of the content stylesheet**, rescoped for a surface that
+ * is not Foundry.
+ *
+ * `assets/styles/content-base.css` styles what the renderer emits, scoped to
+ * the roots a Foundry journal and its editors use. Two other surfaces reuse its
+ * rules without a second copy: the editor preview takes the stretches marked
+ * `preview:shared`, and a site takes the highlighted-code rules. Both read the
+ * one file and replace the scope, so a colour changed there changes everywhere.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+
+import { baseStylesheetSource } from "./base-styles.mjs";
+
+/** The roots the shipped content stylesheet scopes its rules to. */
+export const CONTENT_ROOTS =
+    ":is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)";
+
+/** The stretches of the shipped content stylesheet other surfaces share. */
+const SHARED_RULES = /\/\* preview:shared [^]*?\*\/([^]*?)\/\* \/preview:shared \*\//g;
+
+/**
+ * The rules the Foundry content stylesheet shares with other surfaces, scoped
+ * to a selector.
+ *
+ * @param {string} scope - The selector that replaces the Foundry roots.
+ * @returns {string} The rules.
+ * @throws {Error} When the stylesheet marks no shared rules.
+ */
+export function sharedContentRules(scope) {
+    const css = fs.readFileSync(baseStylesheetSource(), "utf8");
+    const shared = [...css.matchAll(SHARED_RULES)].map((match) => match[1]);
+    if (!shared.length) throw new Error("the content stylesheet marks no rules for the preview");
+    return shared.join("").replaceAll(CONTENT_ROOTS, scope);
+}
+
+/**
+ * The rules that colour highlighted code, scoped to a selector.
+ *
+ * A rule belongs to the set when one of its selectors names a `hljs-` token
+ * class. The rules are taken from the shared stretches, so the colours, their
+ * custom properties and their `light-dark()` pairs are the stylesheet's own.
+ *
+ * @param {string} scope - The selector that replaces the Foundry roots.
+ * @returns {string} The token rules, one per block.
+ */
+export function highlightRules(scope) {
+    const shared = sharedContentRules(scope)
+        .replace(/\/\*[^]*?\*\//g, "")
+        .replace(/\s*\n\s+(?=\.hljs-)/g, " ");
+    return (
+        shared
+            .split("}")
+            .map((rule) => rule.trim())
+            .filter(
+                (rule) => rule.includes("{") && /\.hljs-/.test(rule.slice(0, rule.indexOf("{"))),
+            )
+            .map((rule) => `${rule}\n}`)
+            .join("\n\n") + "\n"
+    );
+}
+
+/**
+ * The stylesheet a site links for highlighted code.
+ *
+ * A site sets no colour scheme, and the token colours are `light-dark()` pairs
+ * that read the scheme in force, so code is given the dark one its pages are
+ * drawn in.
+ *
+ * @param {string} [scope] - The element the page body sits in.
+ * @returns {string} The stylesheet.
+ */
+export function siteCodeStylesheet(scope = ".single-body") {
+    return `${scope} :is(pre, code) {\n    color-scheme: dark;\n}\n\n${highlightRules(scope)}`;
+}

package/engine/content-symbols.mjs

@@ -0,0 +1,186 @@
+/*
+ * 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 glyph and cartouche spans of a note, read in one place for the stages
+ * that need their pictures: the renderer that draws them and the book that
+ * stages their files.
+ *
+ * @module
+ */
+
+import {
+    glyphHtml,
+    glyphPathname,
+    cartoucheHtml,
+    cartouchePathname,
+    cartoucheProblems,
+    glyphProblems,
+} from "./content-glyphs.mjs";
+import { scanSpans } from "./content-spans.mjs";
+
+/**
+ * A span's attributes as the construct's checker reads them.
+ * @param {Array<[string, string]>} attrs - The span's attribute pairs.
+ * @returns {{id: string, classes: string[], values: Record<string, string>}} Parsed form.
+ */
+function parsedAttributes(attrs) {
+    const find = (name) => attrs.find(([key]) => key === name)?.[1] ?? "";
+    return {
+        id: find("id"),
+        classes: find("class").split(/\s+/).filter(Boolean),
+        values: Object.fromEntries(attrs.filter(([key]) => !["id", "class"].includes(key))),
+    };
+}
+
+/**
+ * The well-formed glyph and cartouche spans of a note, outermost only, outside
+ * code.
+ * @param {string} source - Authored Markdown.
+ * @returns {Array<{kind: "glyph"|"cartouche", start: number, end: number, slug: string, alt: string, frame?: string, size?: string, align?: string, height?: string, caption?: string}>}
+ *   One entry per sign, in source order. A sign with a finding is left out: it
+ *   is reported and draws as an ordinary span.
+ */
+function symbolSpans(source) {
+    if (!/\.(glyph|cartouche)\b/.test(source)) return [];
+    const { spans } = scanSpans(source);
+    const signs = spans
+        .map((span) => ({ span, parsed: parsedAttributes(span.attrs) }))
+        .flatMap(({ span, parsed }) => {
+            const kind = ["glyph", "cartouche"].find((name) => parsed.classes.includes(name));
+            const problems = { glyph: glyphProblems, cartouche: cartoucheProblems }[kind];
+            if (!problems || problems(parsed).length) return [];
+            const { slug, frame, size, align, height, caption } = parsed.values;
+            return [
+                {
+                    kind,
+                    start: span.start,
+                    end: span.end,
+                    slug,
+                    alt: span.visible.trim(),
+                    ...(frame ? { frame } : {}),
+                    ...(size ? { size } : {}),
+                    ...(align ? { align } : {}),
+                    ...(height ? { height } : {}),
+                    ...(caption ? { caption } : {}),
+                },
+            ];
+        });
+    return signs.filter(
+        (sign) => !signs.some((outer) => outer.start < sign.start && outer.end >= sign.end),
+    );
+}
+
+const OPEN = "\uE000",
+    CLOSE = "\uE001";
+const PLACEHOLDER = new RegExp(`${OPEN}([0-9a-f]+)${CLOSE}`, "g");
+
+/**
+ * A cartouche as the inert text a Markdown parser passes through untouched.
+ * A figure written as HTML at the start of a line would open a CommonMark HTML
+ * block and leave the rest of its paragraph unparsed, so the figure is written
+ * as inline HTML by {@link cartoucheFigures} after the paragraph is parsed.
+ * @param {object} cartouche - The figure's attributes, with `src` the address of its picture.
+ * @returns {string} Private-use delimiters around the hex of the attributes' JSON.
+ */
+function cartouchePlaceholder(cartouche) {
+    const hex = [...new TextEncoder().encode(JSON.stringify(cartouche))]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+    return `${OPEN}${hex}${CLOSE}`;
+}
+
+/**
+ * Markdown-it plugin: write each cartouche placeholder as the inline HTML of
+ * its figure, in whatever paragraph, cell or title it stands.
+ * @param {import("markdown-it")} md - Parser to extend.
+ */
+export function cartoucheFigures(md) {
+    md.core.ruler.after("inline", "cartouche_figures", (state) => {
+        for (const token of state.tokens) {
+            if (token.type !== "inline" || !token.children) continue;
+            token.children = token.children.flatMap((child) => {
+                if (child.type !== "text" || !child.content.includes(OPEN)) return [child];
+                const pieces = [];
+                let last = 0;
+                const piece = (type, content) => {
+                    const made = new state.Token(type, "", 0);
+                    made.content = content;
+                    made.level = child.level;
+                    pieces.push(made);
+                };
+                for (const match of child.content.matchAll(PLACEHOLDER)) {
+                    if (match.index > last) piece("text", child.content.slice(last, match.index));
+                    const { src, ...cartouche } = JSON.parse(
+                        new TextDecoder().decode(
+                            Uint8Array.from(match[1].match(/../g), (pair) => parseInt(pair, 16)),
+                        ),
+                    );
+                    piece("html_inline", cartoucheHtml(cartouche, src));
+                    last = match.index + match[0].length;
+                }
+                if (last < child.content.length) piece("text", child.content.slice(last));
+                return pieces;
+            });
+        }
+    });
+}
+
+/**
+ * Write each glyph and cartouche span as the HTML that draws its picture. A
+ * cartouche is written as a placeholder that {@link cartoucheFigures} turns
+ * into its figure.
+ *
+ * @param {string} source - Markdown that may contain glyph and cartouche spans.
+ * @param {(src: string) => string} [resolveSrc] - From a sign's authored
+ *   pathname to the address the target serves; omitted, the pathname.
+ * @param {object} [options]
+ * @param {boolean} [options.glyphs] - Write glyph spans; `false` leaves them
+ *   as the source they were written in. Default `true`.
+ * @returns {string} The Markdown with each well-formed sign written as HTML or a placeholder.
+ */
+export function renderSymbolSpans(source, resolveSrc, { glyphs = true } = {}) {
+    let markdown = String(source ?? "");
+    for (const sign of symbolSpans(markdown).sort((a, b) => b.start - a.start)) {
+        if (sign.kind === "glyph" && !glyphs) continue;
+        const picture = (sign.kind === "glyph" ? glyphPathname : cartouchePathname)(sign.slug);
+        const src = resolveSrc?.(picture) ?? picture;
+        const html =
+            sign.kind === "glyph" ?
+                glyphHtml(sign, src)
+            :   cartouchePlaceholder({ ...sign, alt: sign.alt || undefined, src });
+        markdown = markdown.slice(0, sign.start) + html + markdown.slice(sign.end);
+    }
+    return markdown;
+}
+
+/**
+ * Every picture the glyphs and cartouches of a body name, for a stage that has
+ * to place the files before a compiler reads them.
+ *
+ * @param {string} body - The note's Markdown.
+ * @returns {Array<{src: string, locate: string}>} The authored pathname of each
+ *   picture and the slug that locates it in the note's text, in document order
+ *   within glyphs and then cartouches.
+ */
+export function symbolImagesIn(body) {
+    const signs = symbolSpans(String(body ?? ""));
+    return ["glyph", "cartouche"].flatMap((kind) =>
+        signs
+            .filter((sign) => sign.kind === kind)
+            .map(({ slug }) => ({
+                src: (kind === "glyph" ? glyphPathname : cartouchePathname)(slug),
+                locate: slug,
+            })),
+    );
+}

package/engine/content-verse.mjs

@@ -164,9 +164,7 @@ export const COLUMNS_CLASS = "verse-columns";
  */
 export const VERSE_KEYS = Object.freeze([
     "form",
-    "meter",
-    "rhyme",
-    "syllables",
+    "scan",
     "lang",
     "font",
     "map",
@@ -222,15 +220,6 @@ export function scanVerse(source) {
                         columned ?
                             verseGroups(block, lines).filter((group) => !group.stanzaBreak).length
                         :   verseLines(body).length;
-                    if (
-                        opening.attributes.syllables &&
-                        opening.attributes.syllables.split(",").length !== count
-                    )
-                        errors.push({
-                            line: opening.start + 1,
-                            column: 1,
-                            message: `verse syllables= gives ${opening.attributes.syllables.split(",").length} counts for ${count} verse lines`,
-                        });
                     if (columned) errors.push(...columnFindings(block, lines));
                     blocks.push(block);
                 }
@@ -270,17 +259,16 @@ export function scanVerse(source) {
                     message: `\`${key}=\` is not a column: a verse has at most two, \`col1=\` and \`col2=\``,
                 });
             else if (!VERSE_KEYS.includes(key))
-                errors.push({ ...at, message: `${key}= is not a verse attribute` });
-            else if (key === "numstep" && !/^\d+$/.test(value))
                 errors.push({
                     line: i + 1,
                     column: keyColumn(lines[i], key),
-                    message: "verse numstep= numbers every Nth line: a whole number, 0 for none",
+                    message: `${key}= is not a verse attribute`,
                 });
-            else if (key === "syllables" && !/^[1-9]\d*(?:,[1-9]\d*)*$/.test(value))
+            else if (key === "numstep" && !/^\d+$/.test(value))
                 errors.push({
-                    ...at,
-                    message: "verse syllables= needs positive comma-separated counts",
+                    line: i + 1,
+                    column: keyColumn(lines[i], key),
+                    message: "verse numstep= numbers every Nth line: a whole number, 0 for none",
                 });
         }
     }

package/engine/core-report.mjs

@@ -0,0 +1,169 @@
+/*
+ * 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 core report: for each language that must cover the core vocabulary, the
+ * concepts of the list it has no word for.
+ *
+ * The list is the `data.concepts` of the package's `doc` notes. A language
+ * must cover it where it states `data.core: true`. A word covers every
+ * concept its `concept` names, and a language reads the words of its
+ * `data.family` chain as its own. A missing concept is a fact to work through,
+ * never a finding.
+ *
+ * @module
+ */
+
+import { encodeAddresses } from "./address-values.mjs";
+import { isLanguageRecord, languageLineages, noteAddressOf } from "./word-rows.mjs";
+
+/** Whether a value is a plain map. */
+const isMap = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/** The slug a record is written by in a reference, such as `skill-vylari`. */
+const slugOf = (record) => record.address?.slug ?? record.shortcode;
+
+/** The name a language is reported by. */
+const nameOf = (record) =>
+    typeof record.name?.full === "string" && record.name.full ? record.name.full : record.shortcode;
+
+/**
+ * The concept list the records state, in record then authored order. An id
+ * another list repeats keeps its first place.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records.
+ * @returns {Array<{id: string, gloss: string, group: string}>} The concepts.
+ */
+function conceptsOf(records) {
+    const out = [];
+    const seen = new Set();
+    for (const record of records) {
+        const list = record?.data?.concepts;
+        if (!Array.isArray(list)) continue;
+        for (const entry of list) {
+            if (
+                !isMap(entry) ||
+                typeof entry.id !== "string" ||
+                typeof entry.gloss !== "string" ||
+                typeof entry.group !== "string" ||
+                seen.has(entry.id)
+            )
+                continue;
+            seen.add(entry.id);
+            out.push({ id: entry.id, gloss: entry.gloss, group: entry.group });
+        }
+    }
+    return out;
+}
+
+/** The concept ids a word serves. */
+function idsOf(word) {
+    const value = isMap(word) ? word.concept : undefined;
+    return (Array.isArray(value) ? value : [value]).filter((id) => typeof id === "string");
+}
+
+/**
+ * The core report of a set of index records.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records.
+ * @param {{language?: string}} [options] - A language to report alone, by its
+ *   name, shortcode or reference slug whether or not it states `data.core`.
+ * @returns {{concepts: number, languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
+ *   The report, or the problem when there is no concept list or the language
+ *   asked for is none.
+ */
+export function coreReport(records, { language } = {}) {
+    const all = [...records].map((record) => encodeAddresses(record));
+    const concepts = conceptsOf(all);
+    if (!concepts.length)
+        return {
+            about: "concepts",
+            problem: "no note states `data.concepts`, so there is no core vocabulary to cover",
+        };
+    const languages = all.filter(isLanguageRecord);
+    let chosen;
+    if (language === undefined) chosen = languages.filter((record) => record.data?.core === true);
+    else {
+        const want = language.toLowerCase();
+        chosen = languages.filter((record) =>
+            [nameOf(record), record.shortcode, slugOf(record)].some(
+                (key) => String(key).toLowerCase() === want,
+            ),
+        );
+        if (!chosen.length)
+            return {
+                about: "language",
+                problem: `\`${language}\` is no language note: name one by its name, its shortcode or its reference`,
+            };
+    }
+    chosen.sort((a, b) => nameOf(a).localeCompare(nameOf(b)));
+
+    const { languages: byKey, chain } = languageLineages(all);
+    const groups = [...new Set(concepts.map((concept) => concept.group))];
+    return {
+        concepts: concepts.length,
+        languages: chosen.map((record) => {
+            const have = new Set();
+            for (const key of chain(noteAddressOf(record) ?? ""))
+                for (const word of byKey.get(key)?.data?.words ?? [])
+                    for (const id of idsOf(word)) have.add(id);
+            const missing = [];
+            for (const group of groups) {
+                const members = concepts.filter((concept) => concept.group === group);
+                const lacking = members.filter((concept) => !have.has(concept.id));
+                if (lacking.length)
+                    missing.push({
+                        group,
+                        count: lacking.length,
+                        total: members.length,
+                        concepts: lacking.map(({ id, gloss }) => ({ id, gloss })),
+                    });
+            }
+            const lacking = missing.reduce((sum, group) => sum + group.count, 0);
+            return {
+                name: nameOf(record),
+                language: slugOf(record),
+                core: record.data?.core === true,
+                total: concepts.length,
+                covered: concepts.length - lacking,
+                missing,
+            };
+        }),
+    };
+}
+
+/**
+ * A core report as text: one block per language, its missing concepts under
+ * their groups with counts, each concept's id and gloss tab-separated.
+ *
+ * @param {{concepts: number, languages: Array<object>}} report - A report from {@link coreReport}.
+ * @returns {string} The text, ending in a newline.
+ */
+export function coreReportText(report) {
+    if (!report.languages.length) return "No language states `data.core: true`.\n";
+    return report.languages
+        .map((one) => {
+            if (!one.missing.length)
+                return `${one.name} (${one.language}): all ${one.total} core concepts have a word\n`;
+            const lines = [
+                `${one.name} (${one.language}): ${one.total - one.covered} of ${one.total} core concepts have no word`,
+            ];
+            for (const group of one.missing) {
+                lines.push(`  ${group.group}: ${group.count} of ${group.total}`);
+                for (const concept of group.concepts)
+                    lines.push(`    ${concept.id}\t${concept.gloss}`);
+            }
+            return `${lines.join("\n")}\n`;
+        })
+        .join("\n");
+}