@heroiclands/package-build 23.13.0 → 24.0.0

package/engine/verse-metre.mjs

@@ -0,0 +1,357 @@
+/*
+ * 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 verse fence declares its metre, and the build counts its beats.** A
+ * metre is declared once, as an entry of a `doc` note's `data.metres`:
+ *
+ * ```yaml
+ * data:
+ *   metres:
+ *     - { name: hexameter, beats: 6, kind: accentual }
+ * ```
+ *
+ * A fence that states `scan=` with the `name` and `lang=` with a language
+ * whose note states `data.sounds.stress` is counted line by line, and a line
+ * that cannot have the metre's beats is a warning at that line. No `scan=`
+ * means no check.
+ *
+ * **Syllables** are vowel groups: a vowel is a letter whose base is `a`, `e`,
+ * `i`, `o` or `u`, and a pair of vowels the language lists in
+ * `data.sounds.syllables.vowelPairs` is one syllable. **The stressed
+ * syllable** follows `data.sounds.stress`: `two` for a word of two, `longer`
+ * for a word of three or more, and a vowel carrying the rule's `mark` is
+ * stressed wherever it sits.
+ *
+ * **Beats** follow the accentual convention:
+ *
+ * - a word of two or more syllables has one beat, on its stressed syllable;
+ * - a one-syllable noun, verb, adjective, numeral or proper name has a beat;
+ *   a one-syllable particle, preposition, conjunction, adverb or pronoun has
+ *   none, by the `class` of the lexicon entry the word is, or is derived
+ *   from; a word whose entries differ is a beat that may be left out;
+ * - a one-syllable word the lexicon does not hold is a content word;
+ * - a word of four or more syllables whose stress is not on its first may take
+ *   a second, lighter beat on its first syllable, and a line scans when its
+ *   count can be the metre's, choosing second beats as it needs;
+ * - the caesura is not written.
+ *
+ * @module
+ */
+
+import { nearest } from "./near-miss.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { METRE_KINDS, METRE_NAME } from "./metre-declaration.mjs";
+import { languageRecordsByName } from "./map-lexicon.mjs";
+import { STRESS_LONGER, STRESS_MARKS, STRESS_TWO } from "./language-terms.mjs";
+import { parseWordClass } from "./word-classes.mjs";
+import { derivedForms, foldWord } from "./word-forms.mjs";
+import { WORD } from "./word-pattern.mjs";
+
+export { METRE_KINDS, METRE_NAME, checkMetresField } from "./metre-declaration.mjs";
+
+/** The bases whose one-syllable words carry a beat. */
+export const BEAT_BASES = Object.freeze(["n", "v", "adj", "num", "name"]);
+
+/** The characters a compound is split at. */
+const JOINS = /[–-]/u;
+
+/** A letter, which a counted word holds at least one of. */
+const LETTER = /\p{L}/u;
+
+/** Whether a value is a plain map. */
+const isMap = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** A list value, or an empty one. */
+const listOf = (value) => (Array.isArray(value) ? value : []);
+
+/** A character's base letter, lowercase. */
+const baseOf = (char) => char.normalize("NFD")[0].toLowerCase();
+
+/** Whether a character is a vowel: its base letter is a, e, i, o or u. */
+const isVowel = (char) => "aeiou".includes(baseOf(char));
+
+/**
+ * The syllables of a word, each as the vowel group that makes it.
+ *
+ * @param {string} word - The word.
+ * @param {Iterable<string>} pairs - The vowel pairs that are one syllable.
+ * @returns {string[]} The nuclei, in order; none for a word with no vowel.
+ */
+export function nucleiOf(word, pairs) {
+    const chars = Array.from(String(word).normalize("NFC"));
+    const known = new Set(pairs);
+    const longest = Math.max(1, ...Array.from(known, (pair) => Array.from(pair).length));
+    const nuclei = [];
+    for (let at = 0; at < chars.length; at++) {
+        if (!isVowel(chars[at])) continue;
+        let taken = 1;
+        for (let size = Math.min(longest, chars.length - at); size > 1; size--) {
+            const group = chars.slice(at, at + size);
+            if (!group.every(isVowel)) continue;
+            if (known.has(group.join("")) || known.has(group.map(baseOf).join(""))) {
+                taken = size;
+                break;
+            }
+        }
+        nuclei.push(chars.slice(at, at + taken).join(""));
+        at += taken - 1;
+    }
+    return nuclei;
+}
+
+/**
+ * The index of the stressed syllable of a word.
+ *
+ * @param {string} word - The word.
+ * @param {{two: string, longer: string, mark?: string}} rule - The language's
+ *   `data.sounds.stress`.
+ * @param {Iterable<string>} pairs - The vowel pairs that are one syllable.
+ * @returns {number} The 0-based syllable; 0 for a word of one syllable or none.
+ */
+export function stressIndex(word, rule, pairs) {
+    const nuclei = nucleiOf(word, pairs);
+    const mark = rule.mark === undefined ? undefined : STRESS_MARKS[rule.mark];
+    if (mark) {
+        const marked = nuclei.findIndex((nucleus) => nucleus.normalize("NFD").includes(mark));
+        if (marked >= 0) return marked;
+    }
+    const count = nuclei.length;
+    if (count <= 1) return 0;
+    if (count === 2) return rule.two === "last" ? 1 : 0;
+    if (rule.longer === "antepenultimate") return count - 3;
+    if (rule.longer === "final") return count - 1;
+    return count - 2;
+}
+
+/**
+ * What a language's lines are counted by.
+ *
+ * @typedef {object} MetreBook
+ * @property {string} language - The language's configured name.
+ * @property {{two: string, longer: string, mark?: string}} rule - Its stress rule.
+ * @property {ReadonlySet<string>} pairs - Its vowel pairs.
+ * @property {ReadonlyMap<string, ReadonlySet<string>>} classes - Each lexicon
+ *   form, and each form its rules derive, folded, with the class bases of its
+ *   entries.
+ */
+
+/** Whether a stress value is a complete rule. */
+const isRule = (stress) =>
+    isMap(stress) && STRESS_TWO.includes(stress.two) && STRESS_LONGER.includes(stress.longer);
+
+/**
+ * Each configured language's metre book: one per language whose `note` names a
+ * language note stating a complete `data.sounds.stress`.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string}} config -
+ *   The resolved configuration.
+ * @returns {Map<string, MetreBook>} The books by language name.
+ */
+export function metreBooksFromRecords(records, config = {}) {
+    const books = new Map();
+    for (const [language, record] of languageRecordsByName([...(records ?? [])], config)) {
+        const data = isMap(record.data) ? record.data : {};
+        const sounds = isMap(data.sounds) ? data.sounds : {};
+        if (!isRule(sounds.stress)) continue;
+        const syllables = isMap(sounds.syllables) ? sounds.syllables : {};
+        const classes = new Map();
+        const add = (form, word) => {
+            const base = parseWordClass(word.class).base;
+            if (base === undefined) return;
+            const folded = foldWord(form);
+            if (!classes.has(folded)) classes.set(folded, new Set());
+            classes.get(folded).add(base);
+        };
+        for (const word of listOf(data.words))
+            if (isMap(word) && typeof word.form === "string") add(word.form, word);
+        for (const { form, word } of derivedForms(data)) add(form, word);
+        books.set(
+            language,
+            Object.freeze({
+                language,
+                rule: Object.freeze({ ...sounds.stress }),
+                pairs: new Set(listOf(syllables.vowelPairs).filter((p) => typeof p === "string")),
+                classes,
+            }),
+        );
+    }
+    return books;
+}
+
+/**
+ * Every metre the index's `doc` notes declare, by name. The first note to
+ * declare a name keeps it.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @returns {Map<string, import("./metre-declaration.mjs").Metre>} The metres.
+ */
+export function metresFromRecords(records) {
+    const metres = new Map();
+    for (const record of records ?? []) {
+        if (!record || !isNoteRecord(record)) continue;
+        for (const entry of listOf(record.data?.metres)) {
+            if (
+                !isMap(entry) ||
+                typeof entry.name !== "string" ||
+                !METRE_NAME.test(entry.name) ||
+                !Number.isInteger(Number(entry.beats)) ||
+                Number(entry.beats) < 1 ||
+                !METRE_KINDS.includes(entry.kind) ||
+                metres.has(entry.name)
+            )
+                continue;
+            metres.set(
+                entry.name,
+                Object.freeze({ name: entry.name, beats: Number(entry.beats), kind: entry.kind }),
+            );
+        }
+    }
+    return metres;
+}
+
+/**
+ * The beats a word can carry.
+ *
+ * @param {string} word - The word as written.
+ * @param {MetreBook} book - The language's book.
+ * @returns {{min: number, max: number}} The fewest and the most.
+ */
+function wordBeats(word, book) {
+    const folded = foldWord(word);
+    const count = nucleiOf(folded, book.pairs).length;
+    if (count === 0) return { min: 0, max: 0 };
+    if (count > 1) {
+        const first = stressIndex(folded, book.rule, book.pairs) === 0;
+        return { min: 1, max: count >= 4 && !first ? 2 : 1 };
+    }
+    const bases = book.classes.get(folded);
+    if (!bases) return { min: 1, max: 1 };
+    const carrying = [...bases].filter((base) => BEAT_BASES.includes(base)).length;
+    if (carrying === bases.size) return { min: 1, max: 1 };
+    return { min: 0, max: carrying ? 1 : 0 };
+}
+
+/**
+ * The beats a line of verse can have.
+ *
+ * @param {string} text - The line.
+ * @param {MetreBook} book - The line's language's book.
+ * @returns {{min: number, max: number}} The beats without the second beats a
+ *   long word may take, and with all of them.
+ */
+export function lineBeats(text, book) {
+    let min = 0;
+    let max = 0;
+    for (const [whole] of String(text).matchAll(WORD)) {
+        const parts = book.classes.has(foldWord(whole)) ? [whole] : whole.split(JOINS);
+        for (const part of parts) {
+            if (!LETTER.test(part)) continue;
+            const beats = wordBeats(part, book);
+            min += beats.min;
+            max += beats.max;
+        }
+    }
+    return { min, max };
+}
+
+/**
+ * The warning for a line that cannot have its metre's beats.
+ *
+ * @param {{min: number, max: number}} beats - The line's beats.
+ * @param {import("./metre-declaration.mjs").Metre} metre - The fence's metre.
+ * @returns {string} The message.
+ */
+export function metreMessage({ min, max }, metre) {
+    const has = max === min ? `${min} beats` : `${min} beats (${max} with secondary beats)`;
+    return `this line has ${has}; the metre \`${metre.name}\` has ${metre.beats}`;
+}
+
+/**
+ * Check the verse fences that state `scan=`.
+ *
+ * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
+ *   The fences, from {@link module:engine/content-verse.scanVerse}.
+ * @param {string[]} lines - The source's lines.
+ * @param {{metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, columnsClass: string, columnKeys: readonly string[], attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
+ *   The metres and books, and how the fence says its columns and where its
+ *   keys sit.
+ * @returns {{errors: object[], warnings: object[]}} The findings at 1-based
+ *   positions.
+ */
+export function metreFindings(blocks, lines, ctx) {
+    const errors = [];
+    const warnings = [];
+    const metres = ctx.metres ?? new Map();
+    for (const block of blocks) {
+        const name = block.attributes.scan;
+        if (name === undefined) continue;
+        const opening = lines[block.start];
+        const at = (key, part) => ({
+            line: block.start + 1,
+            column: ctx.attributeColumns(opening, key)[part],
+        });
+        const error = (position, message) => errors.push({ ...position, message });
+        if (
+            block.classes.includes(ctx.columnsClass) ||
+            ctx.columnKeys.some((key) => block.attributes[key] !== undefined)
+        ) {
+            error(
+                at("scan", "key"),
+                "`scan=` counts the beats of one language's lines; a verse in columns sets a line in each of two",
+            );
+            continue;
+        }
+        const metre = metres.get(name);
+        if (!metre) {
+            const near = nearest(name, [...metres.keys()]);
+            error(
+                at("scan", "value"),
+                `\`${name}\` is not a declared metre: \`scan=\` names the \`name\` of a \`data.metres\` entry of a \`doc\` note` +
+                    (near ? `; did you mean \`${near}\`?` : ""),
+            );
+            continue;
+        }
+        const lang = block.attributes.lang;
+        if (lang === undefined) {
+            error(
+                at("scan", "key"),
+                "`scan=` counts beats by a language's stress rule: the fence needs a `lang=`",
+            );
+            continue;
+        }
+        const book = ctx.metreBooks?.get(lang);
+        if (!book) {
+            error(
+                at("lang", "value"),
+                ctx.lexicons?.has(lang) ?
+                    `the language \`${lang}\` states no \`data.sounds.stress\`, which \`scan=\` counts beats by`
+                :   `the language \`${lang}\` is not a configured language with a \`note\`, so it has no stress rule for \`scan=\` to count beats by`,
+            );
+            continue;
+        }
+        for (let line = block.start + 1; line < block.end; line++) {
+            const text = lines[line];
+            if (!text.trim()) continue;
+            const beats = lineBeats(text, book);
+            if (metre.beats >= beats.min && metre.beats <= beats.max) continue;
+            warnings.push({
+                line: line + 1,
+                column: /^\s*/.exec(text)[0].length + 1,
+                message: metreMessage(beats, metre),
+            });
+        }
+    }
+    return { errors, warnings };
+}

package/engine/wikilink-syntax.mjs

@@ -19,36 +19,23 @@ import { parseAddress, isAddressTuple, splitAnchor } from "./address.mjs";
 /**
  * What a `[[…]]` **is**, before anything decides where it points.
  *
- * One authored link compiles to two different addresses — a Foundry `@UUID`
- * enricher for the packs, a URL for the web — and those two destinations are the
- * *only* thing that legitimately differs. The syntax is the author's, and it is
- * the same syntax whichever build is reading it.
+ * One authored link is written three ways — a Foundry `@UUID` content link for
+ * the packs, a URL for the web, a cross-reference for the book — and those
+ * forms are the *only* thing that legitimately differs. The syntax is the
+ * author's, and it is the same syntax whichever build is reading it.
  *
- * It was written twice, and the two copies had already drifted:
+ * So the parse lives here, once, and two readers take it: the link checker
+ * (`content-links.mjs`) and the resolver (`wikilinks.mjs`). Each receives the
+ * parts and decides only what it is for: which document the address names.
  *
- * | Body | `foundry` side | `web` side |
- * | --- | --- | --- |
- * | `[[weapongear-bsw` ⏎ `]]` in a table cell | not a link | a link whose target ends in a newline |
- * | a stray `[[`, a real link two paragraphs later | finds the real link | swallows both paragraphs as one target |
- *
- * The web side's pattern omitted `\n` from the excluded set, so an unclosed
- * bracket consumed everything up to the next `]]` anywhere in the document —
- * the same shape of corruption a hand-rolled code-fence regex caused on the one
- * page whose subject is link syntax. It was also internally
- * inconsistent: its *frontmatter* scan excluded newlines while its body scan did
- * not.
- *
- * So the parse lives here, once. A resolver receives the parts and decides only
- * what it is actually for: which document the address names.
- *
- * The one rule about a link's *shape* that both resolvers share also lives here
- * — **a link carries a label** ({@link unlabelledLinkMessage}) — because the
- * two state it through one message and the author reads the same words
- * whichever ran first.
+ * The one rule about a link's *shape* also lives here — **a link carries a
+ * label** ({@link unlabelledLinkMessage}) — because every build states it
+ * through one message and the author reads the same words whichever ran
+ * first.
  *
  * For the same reason, so does the **vocabulary of link findings**
  * ({@link LINK_FINDING_REASONS}) and the message each one reports through
- * ({@link linkFindingMessage}). Three builds read one authored link; an author
+ * ({@link linkFindingMessage}). Every build reads one authored link; an author
  * meets whichever ran first, and a consumer switching on a `reason` should not
  * be switching on which build produced it.
  *
@@ -66,8 +53,8 @@ import { parseAddress, isAddressTuple, splitAnchor } from "./address.mjs";
  * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
  * keeps every reader from seeing one as the other. Stated here rather than in
  * each reader for the reason the rest of this module exists: the checker, the
- * pack compilers and the web resolver all match on this pattern, and three
- * copies of the exclusion is three places for it to be forgotten. An embed's
+ * resolver and the embed reader all match on this pattern, and a copy of the
+ * exclusion in each is a place for it to be forgotten. An embed's
  * own grammar is {@link module:engine/content-embeds}.
  */
 export const WIKILINK = /(?<!!)\[\[([^\]\n]+)\]\](?:\{(?:[^{}"\n]|"(?:\\.|[^"\\\n])*")*\})?/g;
@@ -138,12 +125,8 @@ export function parseWikilink(rawInner, literal = "") {
  * `[[x|]]` is labelled and `[[x]]` is not, and only the first addresses
  * anything.
  *
- * Stated here because the two resolvers had already drawn the line in two
- * places and drawn it differently: the packs tested falsiness and were right,
- * the web tested `??` — which falls through on `null` only — and emitted
- * `[](/url/)`, a link with no clickable text, through every build. That
- * is the same drift this module exists to prevent, in the case its own
- * {@link ParsedWikilink} docstring calls out. One reading, one place.
+ * Read with `??`, which falls through on `null` only, an empty label would
+ * emit `[](/url/)`: a link with no clickable text. One reading, one place.
  *
  * @param {{display: string|null}} parsed - A parsed wikilink, or anything
  *   carrying its `display`.
@@ -156,7 +139,7 @@ export function authoredLabel({ display }) {
 /**
  * What an author writing an unlabelled link is told, in one place.
  *
- * Shared by the link checker, the pack compilers and the web resolver, because
+ * Shared by the link checker and the resolver, on every target, because
  * an author meets whichever runs first and they should read the same. It names
  * the form to write rather than a value to correct: there is no value that
  * makes an unlabelled link resolve.
@@ -180,14 +163,12 @@ export function unlabelledLinkMessage(target) {
 }
 
 /**
- * Every way a link can fail, named once for all three resolvers.
+ * Every way a link can fail, named once for every reader of a link.
  *
- * A link is read in three places — the checker (`content-links.mjs`), the pack
- * compilers (`wikilinks.mjs`) and the web resolver (`web-wikilinks.mjs`) — and
- * each would otherwise name the failures in its own words. `unknown` in one is
- * `unresolved` in another and `broken type/shortcode` in the third, so a
- * consumer switching on a `reason` was switching on which build had produced
- * it. The set is closed and lives here, beside the syntax the three share.
+ * A link is read by the checker (`content-links.mjs`) and by the resolver
+ * (`wikilinks.mjs`) for every target, and each names a failure by one of these
+ * reasons, so a consumer switching on a `reason` never switches on which build
+ * produced it. The set is closed and lives here, beside the syntax they share.
  *
  * - `unlabelled` — no `|`, so the link addresses nothing.
  * - `not-an-address` — labelled, but the target does not parse as an address.
@@ -256,7 +237,7 @@ export function isEventAnchor(hit, anchor) {
  *
  * An address naming no note is a typo or an omission: the intent of a
  * placeholder for a note nobody has written yet is spelled as a `draft`-tagged
- * note that exists, resolves and renders marked. Both want fixing, and all three builds say so.
+ * note that exists, resolves and renders marked. Both want fixing, and every build says so.
  *
  * @param {string} target - The address as authored, named in the message.
  * @returns {string} The message, unpunctuated at the end as a finding is.
@@ -322,9 +303,9 @@ export function ambiguousAddressMessage(target, packages = []) {
 /**
  * The message for one link finding, whichever resolver found it.
  *
- * The single table the checker, the pack compilers and the web resolver all
- * report through, so one authored link cannot get three different explanations
- * of the same mistake depending on which build the author ran first. Callers
+ * The single table the checker and the resolver report through, on every
+ * target, so one authored link cannot get different explanations of the same
+ * mistake depending on which build the author ran first. Callers
  * add their own context around it — the note's name, the file it sits in — and
  * never their own wording for the defect.
  *
@@ -423,8 +404,9 @@ export function linkFindingMessage({
 /**
  * Whether a parsed link addresses a section of the page it is written on.
  *
- * `[[#some-heading]]` — no target, only an anchor. Both resolvers special-case
- * it before consulting any index, because there is nothing to look up.
+ * `[[#some-heading]]` — no target, only an anchor. The resolver and the checker
+ * special-case it before consulting any index, because there is nothing to look
+ * up.
  *
  * @param {ParsedWikilink} parsed - A parsed wikilink.
  * @returns {boolean} True when the link is same-page.