@heroiclands/package-build 23.8.0 → 23.10.0

package/engine/lexical-sections.mjs

@@ -0,0 +1,247 @@
+/*
+ * 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
+ */
+
+/**
+ * Automatic dictionaries and glossaries, derived synchronously from the same
+ * rows their SQL layouts read. An existing anchored section receives its list
+ * after its authored text; otherwise the note receives a new final section.
+ * The insertion and the publisher read the same Markdown, on every surface.
+ *
+ * @module
+ */
+
+import { renderAddress } from "./address.mjs";
+import { encodeAddresses } from "./address-values.mjs";
+import { scanBlocks } from "./content-blocks.mjs";
+import { renderDictionary, renderGlossary } from "./dictionary-layout.mjs";
+import { DICTIONARY_COLUMNS, TERM_COLUMNS, dictionaryAndTermRows } from "./dictionary-rows.mjs";
+import { glossaryLanguage } from "./glossary-language.mjs";
+import { scanHeadingAttributes } from "./heading-attributes.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+
+/** The automatic lexical sections and the authored anchors each may reuse. */
+export const LEXICAL_SECTIONS = Object.freeze(
+    [
+        {
+            slug: "dictionary",
+            heading: "Dictionary",
+            aliases: ["dictionary", "lexicon"],
+            dataKey: "words",
+            types: [{ type: "skill", subType: "language" }],
+        },
+        {
+            slug: "glossary",
+            heading: "Glossary",
+            aliases: ["glossary"],
+            dataKey: "glossary",
+            types: [{ type: "lore", subType: "culture" }, { type: "affiliation" }],
+        },
+    ].map((section) =>
+        Object.freeze({
+            ...section,
+            aliases: Object.freeze(section.aliases),
+            types: Object.freeze(section.types.map((kind) => Object.freeze(kind))),
+        }),
+    ),
+);
+
+/** The lexical section this note's own nonempty frontmatter requests. */
+function sectionFor(record) {
+    return LEXICAL_SECTIONS.find(
+        (section) =>
+            section.types.some(
+                (kind) =>
+                    record?.type === kind.type &&
+                    (!kind.subType || record.subType === kind.subType),
+            ) &&
+            Array.isArray(record.data?.[section.dataKey]) &&
+            record.data[section.dataKey].length > 0,
+    );
+}
+
+/**
+ * Whether frontmatter supplies an automatic lexical section, including on a
+ * note with no authored prose. Such a note has content and is not a stub.
+ *
+ * @param {object|null|undefined} frontmatter - A note or its index record.
+ * @returns {boolean} Whether its own nonempty words or glossary qualify.
+ */
+export function hasLexicalEntries(frontmatter) {
+    return Boolean(sectionFor(frontmatter));
+}
+
+/** A note's canonical identity, including a data-only note that was a stub. */
+const keyOf = (record) =>
+    record?.package && record.type && record.shortcode ?
+        renderAddress({
+            package: record.package,
+            system: "note",
+            type: record.type,
+            shortcode: record.shortcode,
+        })
+    :   undefined;
+
+/**
+ * One automatic section, whose rows are rendered at its containing heading's
+ * level when inserted.
+ *
+ * @typedef {object} LexicalSection
+ * @property {string} slug - The canonical section anchor and layout name.
+ * @property {string} heading - The heading used when none is authored.
+ * @property {readonly string[]} aliases - Authored heading anchors to reuse.
+ * @property {{columns: string[], rows: object[]}} result - The selected rows.
+ * @property {import("./dictionary-layout.mjs").LayoutOptions} options - Labels,
+ *   linkability and the page's language, shared by every surface.
+ */
+
+/**
+ * Automatic lexical sections by owning note's canonical Address. Only
+ * nonempty own `words` or `glossary` arrays qualify. A glossary selects only
+ * explicitly declared owner entries, including a rank only when named there.
+ *
+ * @param {object[]} records - The audience's visible index records.
+ * @param {object[]} [all=records] - Complete records for lineage traversal.
+ * @returns {Map<string, LexicalSection[]>} Sections by owning Address.
+ */
+export function lexicalSectionsFor(records, all = records) {
+    const visible = encodeAddresses(records).filter(isNoteRecord);
+    const complete = encodeAddresses(all).filter(isNoteRecord);
+    const byKey = new Map(visible.map((record) => [keyOf(record), record]));
+    const addressContext = {
+        types: new Set(complete.map((record) => record.type)),
+        packages: new Set(complete.map((record) => record.package)),
+        system: "note",
+    };
+    const { dictionary, terms } = dictionaryAndTermRows(visible, complete);
+    const sections = new Map();
+    for (const [key, record] of byKey) {
+        if (!key) continue;
+        const spec = sectionFor(record);
+        if (!spec) continue;
+        const language = spec.slug === "dictionary";
+        const rows =
+            language ?
+                dictionary.filter((row) => row.language === key)
+            :   terms.filter((row) => row.owner === key && row.origins.includes("glossary"));
+        const pageLanguage = glossaryLanguage(undefined, record, {
+            self: key,
+            keyOf: (value) => (typeof value === "string" ? value : undefined),
+            lookup: (address) => byKey.get(address),
+        });
+        sections.set(key, [
+            {
+                slug: spec.slug,
+                heading: spec.heading,
+                aliases: spec.aliases,
+                result: { columns: [...(language ? DICTIONARY_COLUMNS : TERM_COLUMNS)], rows },
+                options: {
+                    addressContext: { ...addressContext, package: record.package },
+                    pageLanguage,
+                    pageOwner: key,
+                    ...(language ? { verbs: record.data?.grammar?.verbs } : {}),
+                    labelOf: (address) => byKey.get(address)?.name?.full,
+                    linkable: (ref) => {
+                        const target = byKey.get(renderAddress({ ...ref, system: "note" }));
+                        return Boolean(target && (target.address || hasLexicalEntries(target)));
+                    },
+                },
+            },
+        ]);
+    }
+    return sections;
+}
+
+/** Authored section headings outside literal content and named containers. */
+function headings(markdown, syntax) {
+    const containers = (syntax ? syntax(markdown).blocks : scanBlocks(markdown)).blocks;
+    return scanHeadingAttributes(markdown)
+        .headings.filter(
+            (heading) =>
+                !containers.some(
+                    (block) => heading.line - 1 >= block.start && heading.line - 1 <= block.end,
+                ),
+        )
+        .map((heading) => ({ line: heading.line - 1, level: heading.level, slug: heading.id }));
+}
+
+/**
+ * Insert lists at the end of their authored anchored sections, or append a
+ * new H1 section when no heading names one. Source lines after an insertion
+ * retain their original positions; inserted lines point to their heading.
+ *
+ * @param {string} markdown - The body with authored directives expanded.
+ * @param {LexicalSection[]} [sections=[]] - From {@link lexicalSectionsFor}.
+ * @param {{authored?: string, lineMap?: object[], generatedFrom?: number, syntax?: import("./content-session.mjs").ContentSyntax}} [context] -
+ *   The original authored body, source mappings and the start of appended
+ *   nonlexical generated sections. Without `authored`, `markdown` is the source.
+ * @returns {{markdown: string, lineMap: object[], generatedFrom?: number}}
+ */
+export function insertLexicalSections(
+    markdown,
+    sections = [],
+    { authored = markdown, lineMap, generatedFrom, syntax } = {},
+) {
+    const lines = String(markdown ?? "").split("\n");
+    const locations = lineMap ? [...lineMap] : lines.map((_, line) => ({ line, generated: false }));
+    if (!sections.length)
+        return {
+            markdown: lines.join("\n"),
+            lineMap: locations,
+            ...(generatedFrom === undefined ? {} : { generatedFrom }),
+        };
+    const edits = [];
+    const realHeadings = headings(String(authored ?? ""), syntax)
+        .map((heading) => ({
+            ...heading,
+            sourceLine: heading.line,
+            line: locations.findIndex(
+                (location, at) =>
+                    location.line === heading.line &&
+                    !location.generated &&
+                    (generatedFrom === undefined || at < generatedFrom),
+            ),
+        }))
+        .filter((heading) => heading.line >= 0);
+    for (const section of sections) {
+        const own = realHeadings.find((heading) => section.aliases.includes(heading.slug));
+        const next =
+            own &&
+            realHeadings.find((heading) => heading.line > own.line && heading.level <= own.level);
+        const at = next?.line ?? (own ? (generatedFrom ?? lines.length) : lines.length);
+        const level = own?.level ?? 1;
+        const render = section.slug === "dictionary" ? renderDictionary : renderGlossary;
+        const list = render(section.result, {
+            ...section.options,
+            sectionLevel: Math.min(6, level + 1),
+        });
+        if (!list && own) continue;
+        const text = `${own ? "" : `# ${section.heading} {#${section.slug}}\n\n`}${list}`;
+        edits.push({
+            at,
+            source: own?.sourceLine ?? Math.max(0, String(authored ?? "").split("\n").length - 1),
+            lines: ["", ...text.split("\n"), ""],
+        });
+    }
+    for (const edit of edits.sort((a, b) => b.at - a.at)) {
+        const location = { line: edit.source, generated: true };
+        lines.splice(edit.at, 0, ...edit.lines);
+        locations.splice(edit.at, 0, ...edit.lines.map(() => ({ ...location })));
+        if (generatedFrom !== undefined && edit.at <= generatedFrom)
+            generatedFrom += edit.lines.length;
+    }
+    return {
+        markdown: lines.join("\n"),
+        lineMap: locations,
+        ...(generatedFrom === undefined ? {} : { generatedFrom }),
+    };
+}

package/engine/markup-validation.mjs

@@ -19,14 +19,19 @@ import { scanAlerts } from "./content-alerts.mjs";
  * Frontmatter is masked so literal YAML values cannot become body markup.
  * @param {string} source - Complete Markdown source, optionally with frontmatter.
  * @param {string} file - Diagnostic filename.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
  * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
  */
-export function markupFindings(source, file) {
+export function markupFindings(source, file, syntax) {
     const body = String(source ?? "").replace(
         /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,
         (frontmatter) => frontmatter.replace(/[^\r\n]/g, " "),
     );
-    return [...scanBlocks(body).errors, ...scanAlerts(body).errors].map((error) => ({
+    const scanned = syntax?.(body);
+    return [
+        ...(scanned?.blocks ?? scanBlocks(body)).errors,
+        ...(scanned?.alerts ?? scanAlerts(body)).errors,
+    ].map((error) => ({
         file,
         ...error,
         severity: "error",

package/engine/metadata-index.mjs

@@ -445,6 +445,7 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
             const foundry = record.foundry?.[parts.system];
             index.set(key, {
                 name: record.name?.full ?? record.name,
+                aliases: record.name?.aliases,
                 // Absent where the package publishes no page for it. A consumer
                 // must tolerate that rather than invent an href, exactly as it
                 // already tolerates an entry with no `uuid`.

package/engine/name-markup.mjs

@@ -0,0 +1,114 @@
+/*
+ * 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
+ */
+
+/** Pure projections of parsed inline text and original marked-name positions. */
+
+/**
+ * An original source range with its opening file position.
+ * @typedef {object} SpanSourceSite
+ * @property {number} start - Inclusive UTF-16 source offset.
+ * @property {number} end - Exclusive UTF-16 source offset.
+ * @property {number} line - Original 1-based source line.
+ * @property {number} column - Original 1-based UTF-16 source column.
+ */
+
+/**
+ * The retained attribute key and value at their authored positions.
+ * @typedef {object} SpanAttributePosition
+ * @property {SpanSourceSite} key - Attribute name, without surrounding whitespace.
+ * @property {SpanSourceSite} value - Authored value, without its surrounding quotes.
+ */
+
+/**
+ * One actual bracketed span and its renderer-derived visible text.
+ * @typedef {object} ContentSpan
+ * @property {string} id - Normalized anchor, or an empty string.
+ * @property {number} start - Inclusive UTF-16 offset of the opening bracket.
+ * @property {number} end - Exclusive UTF-16 offset after the complete span.
+ * @property {number} line - Original 1-based line of the opening bracket.
+ * @property {number} column - Original 1-based UTF-16 column of the bracket.
+ * @property {string} text - Inline label source passed to the existing parser.
+ * @property {number} contentEnd - Original UTF-16 offset of the closing label bracket.
+ * @property {string} visible - Visible text from the actual parsed children.
+ * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted HTML attributes.
+ * @property {Record<string, SpanAttributePosition>} attributePositions - Authored key/value sites by retained attribute name.
+ */
+
+/**
+ * One located span-grammar or refused-attribute finding.
+ * @typedef {object} SpanFinding
+ * @property {number} line - Original 1-based source line.
+ * @property {number} column - Original 1-based UTF-16 source column.
+ * @property {string} message - The existing grammar or attribute diagnostic.
+ */
+
+/**
+ * A captured authored span inventory.
+ * @typedef {object} SpanScan
+ * @property {ContentSpan[]} spans - All actual parsed bracketed spans in source order.
+ * @property {ContentSpan[]} names - The same span objects carrying the exact name class.
+ * @property {SpanFinding[]} errors - Located diagnostics in source order.
+ */
+
+/**
+ * Visible name text from the renderer's actual parsed children. Footnote
+ * markers and images supply no name text; references have already resolved.
+ * @param {readonly object[]} tokens - Parsed inline tokens.
+ * @returns {string} Text without inline formatting or annotation markers.
+ */
+export function inlineText(tokens) {
+    return tokens
+        .map((token) => {
+            if (token.children && token.type !== "image") return inlineText(token.children);
+            if (token.type === "text" || token.type === "code_inline") return token.content;
+            if (token.type === "softbreak" || token.type === "hardbreak") return " ";
+            return "";
+        })
+        .join("");
+}
+
+/**
+ * Rebase an authored body's captured names to its original raw file.
+ * The inventory is read only; no source parsing or second marker scan occurs.
+ * @template {ContentSpan} Span
+ * @param {readonly Span[]} spans - The captured body's name spans.
+ * @param {{raw: string, bodyLine?: number, bodyColumn?: number}} source - Original body origin.
+ * @returns {Span[]} Copies retaining the span metadata with raw offsets and file coordinates.
+ */
+export function rebaseNameSpans(spans, { raw, bodyLine = 1, bodyColumn = 1 }) {
+    let origin = 0;
+    for (let line = 1; line < bodyLine; line++) origin = raw.indexOf("\n", origin) + 1;
+    origin += bodyColumn - 1;
+    /**
+     * @template {SpanSourceSite} Site
+     * @param {Site} position - Captured relative range and opening position.
+     * @returns {Site} The same metadata at original file coordinates.
+     */
+    const rebase = (position) => ({
+        ...position,
+        start: position.start + origin,
+        end: position.end + origin,
+        line: bodyLine + position.line - 1,
+        column: position.column + (position.line === 1 ? bodyColumn - 1 : 0),
+    });
+    return spans.map((span) => ({
+        ...rebase(span),
+        contentEnd: span.contentEnd + origin,
+        attributePositions: Object.fromEntries(
+            Object.entries(span.attributePositions ?? {}).map(([key, positions]) => [
+                key,
+                { key: rebase(positions.key), value: rebase(positions.value) },
+            ]),
+        ),
+    }));
+}

package/engine/name-rows.mjs

@@ -0,0 +1,70 @@
+/*
+ * 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
+ */
+
+/**
+ * Authored `.name` occurrences projected from own-note index records into the
+ * SQL `names` relation. Documentation records and assets contribute no rows.
+ * @module
+ */
+
+import { canonicalKey, readCanonicalKey } from "./address.mjs";
+import { encodeAddresses } from "./address-values.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+
+/** Every column of the `names` relation, in order. */
+export const NAME_COLUMNS = Object.freeze(["owner", "name", "type", "subType", "line", "column"]);
+
+/**
+ * @typedef {object} NameRow
+ * @property {string|null} owner - Containing authored page's canonical NOTE Address.
+ * @property {string} name - Rendered visible text of the occurrence.
+ * @property {string|null} type - Supplied note type, or null.
+ * @property {string|null} subType - Supplied subtype, or null.
+ * @property {number} line - Original 1-based source line at the opening bracket.
+ * @property {number} column - Original 1-based UTF-16 source column at that bracket.
+ */
+
+/**
+ * The containing page's NOTE identity, including for a native Item source.
+ * @param {Record<string, any>} record - An own-note index record.
+ * @returns {string|null} The page Address, or null for an unaddressable record.
+ */
+function ownerOf(record) {
+    const parts = readCanonicalKey(encodeAddresses(record.address?.canonical));
+    return parts ? canonicalKey(parts.package, "note", parts.type, parts.shortcode) : null;
+}
+
+/**
+ * Project captured occurrences without reading sources or changing records.
+ * @param {Iterable<Record<string, any>>} records - Index records, already narrowed
+ *   to the audience; canonical Addresses may be typed or encoded strings.
+ * @returns {NameRow[]} One row per occurrence, in record then source order.
+ */
+export function namesRows(records) {
+    const rows = [];
+    for (const record of records) {
+        if (!record || !isNoteRecord(record) || !Array.isArray(record.names)) continue;
+        const owner = ownerOf(record);
+        for (const entry of record.names) {
+            rows.push({
+                owner,
+                name: entry.name,
+                type: entry.type ?? null,
+                subType: entry.subType ?? null,
+                line: entry.line,
+                column: entry.column,
+            });
+        }
+    }
+    return rows;
+}