@heroiclands/package-build 23.13.0 → 24.0.0

package/engine/core-vocabulary.mjs

@@ -0,0 +1,208 @@
+/*
+ * 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
+ */
+
+/**
+ * A setting's core vocabulary: the concept list a `doc` note states in
+ * `data.concepts`, the `data.core` flag that says a language must cover it, and
+ * the `concept` a word of a language serves.
+ *
+ * This check owns what the values mean, each finding located at the key at
+ * fault:
+ *
+ * - a concept's `id` is lowercase letters, digits and `-`;
+ * - an `id` is stated once in a list, and by one note in the package;
+ * - a concept's `gloss` and `group` are not blank;
+ * - `data.core` is stated on a language only;
+ * - a word's `concept` names entries of the concept list, each once.
+ *
+ * @module
+ */
+
+import { pathLabel as label } from "./data-keys.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { nearest } from "./near-miss.mjs";
+import { LANGUAGE_SUBTYPE } from "./word-terms.mjs";
+
+/** What a concept's `id` is made of. */
+export const CONCEPT_ID = /^[a-z0-9-]+$/;
+
+/** Whether a value is a plain map. */
+const isMap = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/** A list value, or an empty one. */
+const listOf = (value) => (Array.isArray(value) ? value : []);
+
+/**
+ * The notes of an index that state a concept list, read once per index.
+ *
+ * @type {WeakMap<object, Array<{file: string, ids: Map<string, number>}>>}
+ */
+const stated = new WeakMap();
+
+/**
+ * Each note of the index that states `data.concepts`, with the ids it states
+ * and where each first stands.
+ *
+ * @param {{notes?: Iterable<{file: string, fm?: Record<string, any>}>}} index - The lint index.
+ * @returns {Array<{file: string, ids: Map<string, number>}>} The notes.
+ */
+function listsIn(index) {
+    const known = stated.get(index);
+    if (known) return known;
+    const lists = [];
+    for (const note of index.notes ?? []) {
+        const concepts = note?.fm?.data?.concepts;
+        if (!Array.isArray(concepts)) continue;
+        const ids = new Map();
+        concepts.forEach((entry, at) => {
+            if (isMap(entry) && typeof entry.id === "string" && !ids.has(entry.id))
+                ids.set(entry.id, at);
+        });
+        lists.push({ file: note.file, ids });
+    }
+    stated.set(index, lists);
+    return lists;
+}
+
+/**
+ * Every concept id the index's notes state.
+ *
+ * @param {{notes?: Iterable<object>}|undefined} index - The lint index.
+ * @returns {Set<string>|undefined} The ids, or `undefined` without an index.
+ */
+export function conceptIdsIn(index) {
+    if (!index?.notes) return undefined;
+    return new Set(listsIn(index).flatMap((list) => [...list.ids.keys()]));
+}
+
+/**
+ * Check a `doc` note's `data.concepts`: each id's spelling, an id stated twice,
+ * an id another note states, and a blank `gloss` or `group`.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{index?: {notes?: Iterable<object>}}} [context] - The lint index.
+ * @returns {object[]} The findings, each at its key.
+ */
+export function checkConceptList(note, { index } = {}) {
+    const concepts = note?.fm?.data?.concepts;
+    if (!Array.isArray(concepts)) return [];
+    const raw = note.raw ?? "";
+    const finding = (path, message) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(raw, path),
+        severity: "error",
+        message,
+    });
+    const others = index ? listsIn(index).filter((list) => list.file !== note.file) : [];
+    const findings = [];
+    const seen = new Set();
+    concepts.forEach((entry, at) => {
+        if (!isMap(entry)) return;
+        const where = (key) => ["data", "concepts", at, key];
+        if (typeof entry.id === "string") {
+            if (!CONCEPT_ID.test(entry.id))
+                findings.push(
+                    finding(
+                        where("id"),
+                        `\`${label(where("id"))}\` is \`${entry.id}\`; a concept's id is lowercase letters, digits and \`-\``,
+                    ),
+                );
+            else if (seen.has(entry.id))
+                findings.push(
+                    finding(
+                        where("id"),
+                        `\`${entry.id}\` is stated twice in this list; a concept's id is unique`,
+                    ),
+                );
+            else {
+                const also = others.find((list) => list.ids.has(entry.id));
+                if (also)
+                    findings.push(
+                        finding(
+                            where("id"),
+                            `\`${entry.id}\` is also stated by ${also.file}; a concept's id is unique`,
+                        ),
+                    );
+            }
+            seen.add(entry.id);
+        }
+        for (const key of ["gloss", "group"])
+            if (typeof entry[key] === "string" && entry[key].trim() === "")
+                findings.push(
+                    finding(where(key), `\`${label(where(key))}\` is blank; state the ${key}`),
+                );
+    });
+    return findings;
+}
+
+/**
+ * Check a `skill` note's `data.core`: stated on a language only.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - A `skill` note.
+ * @returns {object[]} The findings.
+ */
+export function checkCoreFlag(note) {
+    const fm = note?.fm ?? {};
+    if (!isMap(fm.data) || fm.data.core === undefined || fm.data.core === null) return [];
+    if (String(fm.subType ?? "").toLowerCase() === LANGUAGE_SUBTYPE) return [];
+    return [
+        {
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", ["data", "core"], { key: true }),
+            severity: "error",
+            message:
+                "`data.core` says a language must cover the core vocabulary, and this note's " +
+                `\`subType\` is not \`${LANGUAGE_SUBTYPE}\``,
+        },
+    ];
+}
+
+/**
+ * What is wrong with a word's `concept`: an id the list does not declare, and
+ * an id stated twice.
+ *
+ * @param {unknown} value - The word's `concept`: an id, or a list of them.
+ * @param {Set<string>|undefined} known - The ids the index declares, or
+ *   `undefined` where there is no index to check against.
+ * @returns {Array<{entry: number|null, message: string}>} Each problem and the
+ *   list entry it sits at, `null` for a single id.
+ */
+export function conceptProblems(value, known) {
+    if (!known) return [];
+    const single = typeof value === "string";
+    const entries = single ? [value] : listOf(value);
+    const problems = [];
+    const seen = new Set();
+    entries.forEach((id, at) => {
+        if (typeof id !== "string") return;
+        const entry = single ? null : at;
+        if (seen.has(id)) {
+            problems.push({
+                entry,
+                message: `\`${id}\` is stated twice in this word's \`concept\``,
+            });
+            return;
+        }
+        seen.add(id);
+        if (known.has(id)) return;
+        const near = nearest(id, known);
+        problems.push({
+            entry,
+            message:
+                known.size ?
+                    `\`${id}\` is not a core concept${near ? `; did you mean \`${near}\`?` : ""}`
+                :   `\`${id}\` is not a core concept: no note states \`data.concepts\``,
+        });
+    });
+    return problems;
+}

package/engine/dictionary-html.mjs

@@ -0,0 +1,119 @@
+/*
+ * 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
+ */
+
+/**
+ * **Dictionary rows in finished HTML.** {@link groupDictionaryLists} gives a
+ * definition list written as HTML the rows and the `dictionary` class that
+ * {@link module:engine/definition-list.dictionaryListPlugin} gives one written
+ * in Markdown, so both read the same on a page.
+ *
+ * The page is read as tokens, and a stack of open elements gives each nested
+ * list its own rows. Comments, `script`, `style`, `pre` and `textarea` are
+ * opaque: a literal example inside one is left as written. A list that already
+ * has rows keeps them.
+ *
+ * @module
+ */
+
+/** One token: a comment, an opaque element, a declaration, a tag, text, or a bare `<`. */
+const TOKEN =
+    /<!--[^]*?-->|<script\b(?:[^"'<>]|"[^"]*"|'[^']*')*>[^]*?<\/script\s*>|<style\b(?:[^"'<>]|"[^"]*"|'[^']*')*>[^]*?<\/style\s*>|<pre\b(?:[^"'<>]|"[^"]*"|'[^']*')*>[^]*?<\/pre\s*>|<textarea\b(?:[^"'<>]|"[^"]*"|'[^']*')*>[^]*?<\/textarea\s*>|<![^>]*>|<\/?[a-z][a-z0-9:-]*(?:[^"'<>]|"[^"]*"|'[^']*')*>|[^<]+|</gi;
+
+/** Elements with no closing tag. */
+const VOID = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+]);
+
+/** Add the `dictionary` class to a `<dl …>` opening tag. */
+function withDictionaryClass(token) {
+    if (
+        /\sclass\s*=\s*["'](?:[^"']*\s)?dictionary(?:\s|["'])/i.test(token) ||
+        /\sclass\s*=\s*dictionary(?:\s|>)/i.test(token)
+    )
+        return token;
+    if (/\sclass\s*=\s*["']/i.test(token))
+        return token.replace(/(\sclass\s*=\s*["'])/i, "$1dictionary ");
+    if (/\sclass\s*=/i.test(token))
+        return token.replace(/(\sclass\s*=\s*)([^\s>]+)/i, '$1"dictionary $2"');
+    return token.replace(/^<dl/i, '<dl class="dictionary"');
+}
+
+/**
+ * Group each term of every definition list with its definitions.
+ *
+ * @param {string} html - A page's HTML.
+ * @returns {string} The HTML with a `dictionary` class on each `dl` and a `div`
+ *   around each term and the definitions that follow it.
+ */
+export function groupDictionaryLists(html) {
+    const source = String(html ?? "");
+    if (!/<dl(?:\s|>)/i.test(source)) return source;
+    const tokens = source.match(TOKEN) ?? [];
+    const parts = [];
+    const lists = [];
+    const elements = [];
+    tokens.forEach((original, i) => {
+        let token = original;
+        const previous = tokens[i - 1];
+        const next = tokens[i + 1];
+        // Whitespace between a term and its definition, and between a definition's
+        // opening and its first paragraph, would add a word space to a fixed gap.
+        if (
+            lists.length &&
+            i > 0 &&
+            next !== undefined &&
+            /^\s+$/.test(token) &&
+            ((/^<\/dt\s*>$/i.test(previous) && /^<dd(?:\s|>)/i.test(next)) ||
+                (/^<dd(?:\s[^>]*)?>$/i.test(previous) && /^<p(?:\s|>)/i.test(next)))
+        )
+            token = "";
+        const opaque = /^<(?:!--|script\b|style\b|pre\b|textarea\b)/i.test(token);
+        if (!opaque && /^<\/?[a-z]/i.test(token)) {
+            const tag = token.replace(/^<\/?([a-z][a-z0-9:-]*)[^]*$/i, "$1").toLowerCase();
+            const closing = token.startsWith("</");
+            if (tag === "dl" && !closing) {
+                lists.push({ row: false });
+                token = withDictionaryClass(token);
+            } else if (tag === "dt" && !closing && lists.length && elements.at(-1) === "dl") {
+                const list = lists.at(-1);
+                if (list.row) parts.push("</div>");
+                parts.push("<div>");
+                list.row = true;
+            } else if (tag === "dl" && closing && lists.length) {
+                const list = lists.at(-1);
+                if (list.row) parts.push("</div>");
+                lists.pop();
+            }
+            if (closing) {
+                if (elements.length) elements.pop();
+            } else if (!(/\/\s*>$/.test(token) || VOID.has(tag))) {
+                elements.push(tag);
+            }
+        }
+        parts.push(token);
+    });
+    return parts.join("");
+}

package/engine/field-reference.mjs

@@ -368,7 +368,7 @@ function deepMerge(base, overlay) {
  * The one question that decides whether `docs item-fields` writes a note
  * envelope: `assets/content/` walks every file under it for its `type:`, so a
  * generated page filed there needs one to publish at all, while a page filed
- * anywhere else — a repository's own `docs/` — is read by nobody but Hugo's
+ * anywhere else — a repository's own `docs/` — is read by nobody but the
  * `--check` guard and the reader following a link, neither of which wants
  * frontmatter.
  *

package/engine/frontmatter-lint.mjs

@@ -813,7 +813,7 @@ function checkKeyedMap(note, { field, segments, entries, raw, packs }) {
  * lands at — would mean checking the value against the sections that could
  * exist (every content type, plus whatever a repository configured) rather
  * than against the genres its type declares. Two vocabularies in one field is
- * the cause, and it is removed rather than the symptom: a section is a Hugo
+ * the cause, and it is removed rather than the symptom: a section is a
  * directory the note format does not
  * carry, and a page introducing a type is an ordinary note addressed
  * `doc-<type>`. So the closed list answers for every note, whatever it is

package/engine/heading-attributes.mjs

@@ -216,6 +216,95 @@ export function headingAttributesPlugin(md) {
     });
 }
 
+/**
+ * The id a heading's text gives it on the web: GitHub's form, lower case, each
+ * space or hyphen a hyphen, every character that is not a letter, a digit or
+ * an underscore dropped.
+ *
+ * @param {string} text - The heading's text, without its markup.
+ * @returns {string} The id, or `heading` when nothing is left of the text.
+ */
+export function headingId(text) {
+    let id = "";
+    for (const char of String(text ?? "").trim()) {
+        if (char === " " || char === "-") id += "-";
+        else if (char === "_" || /[\p{L}\p{Nd}]/u.test(char)) id += char.toLowerCase();
+    }
+    return id || "heading";
+}
+
+/** The tokens whose content is a heading's text. */
+const TEXT_TOKENS = new Set(["text", "code_inline", "typographic"]);
+
+/**
+ * The text a heading's id is made from.
+ *
+ * Its words, code and punctuation; a line break as a newline; no markup. An
+ * element inside the heading — emphasis, a link, an image — gives only its
+ * first piece of text, which ends at the first punctuation the page sets
+ * typographically, so `[Nkaru'thar](…)` gives `Nkaru`.
+ *
+ * @param {object[]} children - The heading's inline tokens.
+ * @returns {string} The text.
+ */
+function headingText(children) {
+    const list = children ?? [];
+    /** The first piece of text inside the element opening at `index`. */
+    const first = (index) => {
+        const token = list[index];
+        if (!token || token.nesting === -1) return "";
+        if (TEXT_TOKENS.has(token.type)) return token.content;
+        if (token.type === "image") return headingText(token.children?.slice(0, 1));
+        if (token.nesting === 1) return first(index + 1);
+        return "";
+    };
+    let text = "";
+    for (let i = 0; i < list.length; i++) {
+        const token = list[i];
+        if (TEXT_TOKENS.has(token.type)) text += token.content;
+        else if (token.type === "softbreak" || token.type === "hardbreak") text += "\n";
+        else if (token.type === "image") text += headingText(token.children?.slice(0, 1));
+        else if (token.nesting === 1) {
+            text += first(i + 1);
+            for (let depth = 1; depth > 0 && i + 1 < list.length;) {
+                i++;
+                depth += list[i].nesting;
+            }
+        }
+    }
+    return text;
+}
+
+/**
+ * Give every heading an id, so a page's contents list and a reader's link can
+ * name any section.
+ *
+ * An authored `{#id}` is kept, and every other heading takes {@link headingId}
+ * of its text. A repeated id takes `-1`, `-2` and so on, counted over every id
+ * on the page that came before it.
+ *
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function headingIdsPlugin(md) {
+    md.core.ruler.push("heading_ids", (state) => {
+        const taken = new Set();
+        const tokens = state.tokens;
+        for (let i = 0; i < tokens.length; i++) {
+            if (tokens[i].type !== "heading_open") continue;
+            const authored = tokens[i].attrGet("id");
+            if (authored) {
+                taken.add(authored);
+                continue;
+            }
+            const base = headingId(headingText(tokens[i + 1]?.children));
+            let id = base;
+            for (let n = 1; taken.has(id); n++) id = `${base}-${n}`;
+            taken.add(id);
+            tokens[i].attrSet("id", id);
+        }
+    });
+}
+
 /**
  * Parse one line as a heading, and say whether it starts a journal page.
  *