@heroiclands/package-build 23.12.8 → 24.0.0

package/engine/metre-declaration.mjs

@@ -0,0 +1,134 @@
+/*
+ * 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 metre is declared once, as an entry of a `doc` note's `data.metres`**:
+ * its `name`, the `beats` of a line and the `kind` of count. This module holds
+ * the declaration and its field check, and imports nothing that reads the note
+ * vocabulary, which declares the field with them; reading the metres of an
+ * index and counting a verse against them is {@link module:engine/verse-metre}.
+ *
+ * @module
+ */
+
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/** 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 : []);
+
+/** What a metre's `kind` may be. */
+export const METRE_KINDS = Object.freeze(["accentual"]);
+
+/** What a metre's `name` may be. */
+export const METRE_NAME = /^[a-z0-9-]+$/;
+
+/**
+ * One declared metre.
+ *
+ * @typedef {object} Metre
+ * @property {string} name - What `scan=` names it by.
+ * @property {number} beats - The beats of a line.
+ * @property {string} kind - How they are counted: `accentual`.
+ */
+
+/** The notes declaring each metre name, read once per lint index. */
+const declaredNames = new WeakMap();
+
+/**
+ * Each metre name the index's notes declare, and the notes declaring it.
+ *
+ * @param {{notes?: Iterable<{file: string, fm?: Record<string, any>}>}} index - The lint index.
+ * @returns {Map<string, string[]>} Name → the files that declare it.
+ */
+function namesIn(index) {
+    const known = declaredNames.get(index);
+    if (known) return known;
+    const names = new Map();
+    for (const note of index.notes ?? [])
+        for (const entry of listOf(note?.fm?.data?.metres)) {
+            if (!isMap(entry) || typeof entry.name !== "string") continue;
+            if (!names.has(entry.name)) names.set(entry.name, new Set());
+            names.get(entry.name).add(note.file);
+        }
+    const out = new Map([...names].map(([name, files]) => [name, [...files]]));
+    declaredNames.set(index, out);
+    return out;
+}
+
+/**
+ * Check a note's `data.metres`: each name's form, that no other entry declares
+ * it, and that a beat count is a whole number above zero. The data-key check
+ * owns every key, its kind and the closed `kind` list.
+ *
+ * @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 checkMetresField(note, { index } = {}) {
+    const list = note?.fm?.data?.metres;
+    if (!Array.isArray(list)) return [];
+    const raw = note.raw ?? "";
+    const finding = (keyPath, message) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(raw, ["data", "metres", ...keyPath]),
+        severity: "error",
+        message,
+    });
+    const findings = [];
+    const seen = new Set();
+    list.forEach((entry, at) => {
+        if (!isMap(entry)) return;
+        const { name, beats } = entry;
+        if (typeof name === "string") {
+            const label = `data.metres[${at}].name`;
+            if (!METRE_NAME.test(name))
+                findings.push(
+                    finding(
+                        [at, "name"],
+                        `\`${label}\` is \`${name}\`; a metre's name is lowercase letters, digits and \`-\``,
+                    ),
+                );
+            else if (seen.has(name))
+                findings.push(
+                    finding(
+                        [at, "name"],
+                        `\`${label}\` is \`${name}\`, which this note declares twice; a metre's name is unique`,
+                    ),
+                );
+            else {
+                const others = (index ? (namesIn(index).get(name) ?? []) : []).filter(
+                    (file) => file !== note.file,
+                );
+                if (others.length)
+                    findings.push(
+                        finding(
+                            [at, "name"],
+                            `\`${label}\` is \`${name}\`, which ${others.join(", ")} also declares; a metre's name is unique`,
+                        ),
+                    );
+            }
+            seen.add(name);
+        }
+        if (beats !== undefined && Number.isFinite(Number(beats)) && !(Number(beats) >= 1))
+            findings.push(
+                finding(
+                    [at, "beats"],
+                    `\`data.metres[${at}].beats\` is \`${String(beats)}\`; a metre has one or more beats`,
+                ),
+            );
+    });
+    return findings;
+}

package/engine/names.mjs

@@ -33,6 +33,8 @@ const compare = (a, b) =>
  * @property {string} full - Declared full name.
  * @property {true} indexed - The identity belongs to the indexed catalog.
  * @property {boolean} [fullUse] - The label is a full-name form rather than an alias.
+ * @property {string} [type] - The note's type, absent on an ambiguous label identity.
+ * @property {string|null} [subType] - The note's subtype, or null.
  * @property {NameMatch[]} [candidates] - Indexed identities sharing the label.
  * @property {string} [destination] - Canonical Address used by a resolved link.
  */
@@ -40,10 +42,18 @@ const compare = (a, b) =>
 /**
  * The prepared name and declared-alias lookup.
  * @typedef {object} NameCatalog
- * @property {(label: string, preferred?: {key: string}) => NameMatch|undefined} recognize - Match a whole visible label.
+ * @property {(label: string, preferred?: {key: string}, kind?: NameKind) => NameMatch|undefined} recognize - Match a whole visible label, among notes of `kind` when it supplies a type.
  * @property {(target: string) => NameMatch|undefined} resolve - Resolve an Address target without its anchor to its indexed identity.
  */
 
+/**
+ * What a typed `.name` span says the named thing is. A null type matches any note;
+ * a type matches only notes of that type, and a subtype only notes of that subtype.
+ * @typedef {object} NameKind
+ * @property {string|null} type - Supplied type, or null.
+ * @property {string|null} subType - Supplied subtype, or null.
+ */
+
 /**
  * One captured marked-name occurrence.
  * @typedef {object} MarkedName
@@ -150,10 +160,16 @@ export function createNameCatalog({ records, index }) {
     const names = new Map(),
         byFile = new Map(),
         entries = new Map();
-    const addName = (key, full, aliases = []) => {
-        const entry = entries.get(key) ?? { key, full, indexed: true };
+    const addName = (key, full, aliases, type, subType) => {
+        const entry = entries.get(key) ?? {
+            key,
+            full,
+            indexed: true,
+            type,
+            subType: typeof subType === "string" && subType ? subType : null,
+        };
         entries.set(key, entry);
-        for (const text of [full, ...aliases]) {
+        for (const text of [full, ...(aliases ?? [])]) {
             if (typeof text !== "string" || !text.trim()) continue;
             for (const spelling of nameForms(text)) {
                 if (!names.has(spelling)) names.set(spelling, new Map());
@@ -173,7 +189,13 @@ export function createNameCatalog({ records, index }) {
         const full = record.name?.full;
         if (!parts || parts.type === FOLDER_TYPE || typeof full !== "string") continue;
         const page = canonicalKey(parts.package, "note", parts.type, parts.shortcode);
-        const entry = addName(index.resolve(page) ? page : canonical, full, record.name.aliases);
+        const entry = addName(
+            index.resolve(page) ? page : canonical,
+            full,
+            record.name.aliases,
+            parts.type,
+            record.subType,
+        );
         entries.set(canonical, entry);
         if (index.resolve(page)) entries.set(page, entry);
         if (record.file?.path) byFile.set(record.file.path, entry);
@@ -189,11 +211,16 @@ export function createNameCatalog({ records, index }) {
             continue;
         const page = canonicalKey(parts.package, "note", parts.type, parts.shortcode);
         const key = index.foreign.index.has(page) ? page : canonical;
-        entries.set(canonical, addName(key, hit.name, hit.aliases));
+        entries.set(canonical, addName(key, hit.name, hit.aliases, parts.type, hit.subType));
     }
     return {
-        recognize(label, preferred) {
-            const candidates = [...(names.get(normalizeName(label))?.values() ?? [])];
+        recognize(label, preferred, kind) {
+            const candidates = [...(names.get(normalizeName(label))?.values() ?? [])].filter(
+                (entry) =>
+                    !kind?.type ||
+                    (entry.type === kind.type &&
+                        (kind.subType == null || entry.subType === kind.subType)),
+            );
             const target =
                 candidates.find((entry) => entry.key === preferred?.key) ??
                 (candidates.length === 1 ? candidates[0] : undefined);
@@ -268,7 +295,7 @@ export function collectUnwrittenNames({ records, catalog }) {
     const kinds = new Map();
     for (const record of records.filter(isNoteRecord)) {
         for (const occurrence of record.names ?? []) {
-            if (catalog.recognize(occurrence.name)) continue;
+            if (catalog.recognize(occurrence.name, undefined, occurrence)) continue;
             const type = occurrence.type,
                 subType = occurrence.subType,
                 kind = JSON.stringify([type, subType]);

package/engine/note-matter.mjs

@@ -0,0 +1,66 @@
+/*
+ * 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 page's frontmatter, read and written.** Reading splits and parses a note
+ * exactly as the content index does ({@link splitFrontmatter} and `yaml`), so a
+ * value reads the same on the site and in the preview as in a compendium pack.
+ * Writing serializes with `js-yaml`, which quotes every string a YAML 1.1
+ * reader would take for a boolean, a number or a timestamp, so each
+ * value reads back as the string or number it was.
+ *
+ * @module
+ */
+
+import YAML from "yaml";
+import { dump } from "js-yaml";
+import { splitFrontmatter } from "./diagnostics.mjs";
+
+/**
+ * A page split at its frontmatter.
+ *
+ * @typedef {object} NoteMatter
+ * @property {unknown} data - The parsed frontmatter; an empty map where the
+ *   page has none or the block is empty.
+ * @property {string} content - The body after the closing fence and its line
+ *   break, or the whole text where there is no frontmatter.
+ * @property {string} matter - The YAML source between the fences; empty where
+ *   there is no frontmatter.
+ */
+
+/**
+ * Split a page's frontmatter from its body and parse it.
+ *
+ * @param {string} source - The complete Markdown source.
+ * @returns {NoteMatter} The parsed frontmatter, the body and the YAML source.
+ * @throws {Error} The `yaml` parse error, where the frontmatter is not YAML.
+ */
+export function readMatter(source) {
+    const fence = splitFrontmatter(source);
+    if (!fence) return { data: {}, content: source, matter: "" };
+    return { data: YAML.parse(fence.yaml) ?? {}, content: fence.body, matter: fence.yaml };
+}
+
+/**
+ * A page with `data` as its frontmatter above `content`.
+ *
+ * @param {string} content - The body.
+ * @param {Record<string, unknown>} data - The frontmatter.
+ * @returns {string} The fenced YAML, then the body closed on a line break; the
+ *   body alone where `data` serializes to an empty map.
+ */
+export function writeMatter(content, data) {
+    const yaml = dump(data).trim();
+    const body = content.endsWith("\n") ? content : `${content}\n`;
+    return yaml === "{}" ? body : `---\n${yaml}\n---\n${body}`;
+}

package/engine/note-vocabulary.mjs

@@ -112,6 +112,12 @@ import { checkNoteEvents } from "./note-events.mjs";
 import { AFFILIATION_STANDINGS } from "../sohl/affiliation-standings.mjs";
 import { EVENT_ENTRY } from "./note-event-terms.mjs";
 import { CULTURE_FIELD, checkCultureSubType } from "./culture-choice.mjs";
+import {
+    POST_AUTHOR_FIELD,
+    POST_DATE_FIELD,
+    POST_SUBTYPE,
+    checkPostFields,
+} from "./post-fields.mjs";
 import { checkCultureParents } from "./culture-parents.mjs";
 import {
     checkAppearanceProfile,
@@ -154,6 +160,10 @@ import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkSettlementTables } from "./settlement-tables.mjs";
 import { checkMapField } from "./text-maps.mjs";
+import { checkConceptList, checkCoreFlag } from "./core-vocabulary.mjs";
+import { METRE_KINDS, checkMetresField } from "./metre-declaration.mjs";
+import { checkLanguageEmphasis, checkScriptField } from "./script-emphasis.mjs";
+import { EMPHASIS_CONVENTIONS, LANGUAGE_EMPHASES } from "./script-emphasis-terms.mjs";
 
 /**
  * One `data:` key a note type may carry.
@@ -655,6 +665,67 @@ const ABBREVIATION_FIELD = Object.freeze({
         "note only. See [a language's words](format-details.md#a-languages-words).",
 });
 
+/**
+ * A language's `data.core`: whether it must cover the core vocabulary.
+ * {@link checkCoreFlag} checks where it sits.
+ *
+ * @type {DataFieldSpec}
+ */
+const CORE_FIELD = Object.freeze({
+    name: "core",
+    kind: "boolean",
+    shape: "`true` or `false`",
+    check: checkCoreFlag,
+    describe:
+        "Whether the language must cover the core vocabulary: `true` lists it in the " +
+        "`package-build core` report. A language skill note only. See " +
+        "[the core vocabulary](format-details.md#the-core-vocabulary).",
+});
+
+/**
+ * A `doc` note's `data.concepts`: the core vocabulary's concept list.
+ * {@link checkConceptList} checks what an entry means.
+ *
+ * @type {DataFieldSpec}
+ */
+const CONCEPTS_FIELD = Object.freeze({
+    name: "concepts",
+    kind: "list",
+    shape: "list of `{ id, gloss, group }`",
+    check: checkConceptList,
+    entries: Object.freeze({
+        kind: "map",
+        shape: "a map — `{ id, gloss, group }`",
+        fields: Object.freeze([
+            Object.freeze({
+                name: "id",
+                kind: "string",
+                required: true,
+                shape: "lowercase letters, digits and `-`",
+                describe:
+                    "The concept's id, which a word's `concept` names. Unique in the package.",
+            }),
+            Object.freeze({
+                name: "gloss",
+                kind: "string",
+                required: true,
+                shape: "a short gloss, such as `a smell; a scent`",
+                describe: "What the concept means, in brief.",
+            }),
+            Object.freeze({
+                name: "group",
+                kind: "string",
+                required: true,
+                shape: "a group name, such as `senses`",
+                describe: "The group the report lists the concept under.",
+            }),
+        ]),
+    }),
+    describe:
+        "The concepts of a core vocabulary, in the order the report lists them. See " +
+        "[the core vocabulary](format-details.md#the-core-vocabulary).",
+});
+
 /**
  * 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.
@@ -2096,8 +2167,64 @@ export const NOTE_VOCABULARY = Object.freeze({
             NAMES_FIELD,
             FAMILY_FIELD,
             ABBREVIATION_FIELD,
+            CORE_FIELD,
             ...WORD_DATA_FIELDS,
             ...LANGUAGE_DATA_FIELDS,
+            {
+                name: "emphasis",
+                kind: "string",
+                shape: "`words`, `rubric` or `overline`",
+                allowed: LANGUAGE_EMPHASES,
+                check: checkLanguageEmphasis,
+                describe:
+                    "How the language marks a stressed word, over its script's `emphasis`: " +
+                    "`rubric` or `overline` sets `*…*` and `**…**` so in a run of the language, " +
+                    "and `words` marks it with a word, so either is a finding. Only a skill of " +
+                    "`subType: language` states it.",
+            },
+            {
+                name: "script",
+                kind: "map",
+                shape: "a map — `{ fonts, emphasis, strongEmphasis? }`",
+                check: checkScriptField,
+                fields: Object.freeze([
+                    {
+                        name: "fonts",
+                        kind: "list",
+                        shape: "list of installed faces' slugs",
+                        required: true,
+                        entries: Object.freeze({
+                            kind: "string",
+                            shape: "an installed face's slug",
+                        }),
+                        describe:
+                            "The faces the script is written in, by the slug `font=` names them by. " +
+                            "A face belongs to one script.",
+                    },
+                    {
+                        name: "emphasis",
+                        kind: "string",
+                        shape: "`rubric` or `overline`",
+                        allowed: EMPHASIS_CONVENTIONS,
+                        required: true,
+                        describe:
+                            "How the script marks a stressed word: `rubric` sets it in red, " +
+                            "`overline` draws a line above it. It sets `*…*` and `**…**` inside a " +
+                            "run in one of its faces, unless the run's language states its own " +
+                            "`emphasis`.",
+                    },
+                    {
+                        name: "strongEmphasis",
+                        kind: "string",
+                        shape: "`rubric` or `overline`",
+                        allowed: EMPHASIS_CONVENTIONS,
+                        describe: "The convention `**…**` takes instead of `emphasis`'s.",
+                    },
+                ]),
+                describe:
+                    "A script note's faces and how it marks emphasis. Only a skill of " +
+                    "`subType: script` states it.",
+            },
         ]),
     }),
 
@@ -2176,14 +2303,20 @@ export const NOTE_VOCABULARY = Object.freeze({
             "howto",
             "concept",
             "settingguide",
+            POST_SUBTYPE,
         ]),
-        // A setting guide introduces one culture and names it; no other genre
-        // states one.
+        // A setting guide introduces one culture and names it, and a post
+        // states the day it was published and who wrote it; no other genre
+        // states either.
         check: (note, context) => [
             ...checkCitedPopulations(note, context),
             ...checkCultureSubType(note, context),
+            ...checkPostFields(note),
         ],
         data: Object.freeze([
+            CONCEPTS_FIELD,
+            POST_DATE_FIELD,
+            POST_AUTHOR_FIELD,
             {
                 ...CULTURE_FIELD,
                 describe:
@@ -2193,7 +2326,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "map",
                 kind: "map",
-                shape: "a map — `{ name, vowels?, fonts, rows }`",
+                shape: "a map — `{ name, logographic?, vowels?, fonts, rows }`",
                 check: checkMapField,
                 fields: Object.freeze([
                     {
@@ -2204,6 +2337,15 @@ export const NOTE_VOCABULARY = Object.freeze({
                             "What `map=` names the map by: lowercase letters, digits and `-`, " +
                             "unique in the package.",
                     },
+                    {
+                        name: "logographic",
+                        kind: "boolean",
+                        shape: "`true`",
+                        describe:
+                            "The script writes meanings: a mapped run's words are written by " +
+                            "the language's lexicon alone, and the rows write only the text " +
+                            "between them.",
+                    },
                     {
                         name: "vowels",
                         ...TEXT,
@@ -2261,6 +2403,48 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "before it is set. See " +
                     "[mapping notes](format-details.md#mapping-notes).",
             },
+            {
+                name: "metres",
+                kind: "list",
+                shape: "list of `{ name, beats, kind }`",
+                check: checkMetresField,
+                entries: Object.freeze({
+                    kind: "map",
+                    shape: "a map — `{ name, beats, kind }`",
+                    fields: Object.freeze([
+                        {
+                            name: "name",
+                            ...TEXT,
+                            required: true,
+                            describe:
+                                "What a verse fence's `scan=` names the metre by: lowercase " +
+                                "letters, digits and `-`, unique in the package.",
+                        },
+                        {
+                            name: "beats",
+                            kind: "integer",
+                            shape: "a whole number above zero",
+                            required: true,
+                            describe: "The beats of one line.",
+                        },
+                        {
+                            name: "kind",
+                            kind: "string",
+                            allowed: METRE_KINDS,
+                            shape: `one of ${METRE_KINDS.join(", ")}`,
+                            required: true,
+                            describe:
+                                "How the beats are counted: `accentual`, one beat for each " +
+                                "stressed syllable the language's stress rule and the beat " +
+                                "convention give.",
+                        },
+                    ]),
+                }),
+                describe:
+                    "The metres a verse fence's `scan=` names. A fence that states one is " +
+                    "warned at each line that cannot have its beats. See " +
+                    "[metres](../authoring/links-and-markup.md#metre).",
+            },
         ]),
     }),