@heroiclands/package-build 22.26.0 → 22.28.0

package/engine/content-poetry.mjs

@@ -59,3 +59,144 @@ export function poetryMarkdown(body) {
         )
         .join("\n\n");
 }
+
+import { slugify } from "./content-slug.mjs";
+import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+
+/** Read poetry code fences; start/end are inclusive zero-based source lines.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanPoetry(source) {
+    const lines = String(source ?? "").split("\n"),
+        blocks = [],
+        errors = [];
+    let opening = null;
+    for (let i = 0; i < lines.length; i++) {
+        const match = /^ *(`{3,}|~{3,})(.*)$/.exec(lines[i]);
+        if (opening) {
+            if (
+                match &&
+                match[1][0] === opening.fence[0] &&
+                match[1].length >= opening.fence.length &&
+                !match[2].trim()
+            ) {
+                if (opening.name === "poetry") {
+                    const body = lines.slice(opening.start + 1, i).join("\n");
+                    if (!body.trim())
+                        errors.push({
+                            line: opening.start + 1,
+                            column: 1,
+                            message: "poetry block is empty",
+                        });
+                    for (let n = opening.start + 1; n < i; n++) {
+                        const col = lines[n].indexOf("\t");
+                        if (col >= 0)
+                            errors.push({
+                                line: n + 1,
+                                column: col + 1,
+                                message: "tabs are not allowed in poetry",
+                            });
+                    }
+                    if (
+                        opening.attributes.syllables &&
+                        opening.attributes.syllables.split(",").length !== verseLines(body).length
+                    )
+                        errors.push({
+                            line: opening.start + 1,
+                            column: 1,
+                            message: `poetry syllables= gives ${opening.attributes.syllables.split(",").length} counts for ${verseLines(body).length} verse lines`,
+                        });
+                    blocks.push({ ...opening, end: i, body });
+                }
+                opening = null;
+            }
+            continue;
+        }
+        if (!match) continue;
+        const info = match[2].trim();
+        opening = {
+            start: i,
+            fence: match[1],
+            name: info.split(/\s/)[0],
+            attributes: {},
+            id: "",
+            classes: [],
+            indent: /^ */.exec(lines[i])[0],
+        };
+        if (opening.name !== "poetry") continue;
+        const raw = info.slice(6).trim();
+        const at = { line: i + 1, column: 1 };
+        if (raw && !/^\{[^}\n]*\}$/.test(raw)) {
+            errors.push({ ...at, message: "poetry attributes need {…} braces" });
+            continue;
+        }
+        const parsed = parseExtensionAttributes(raw ? raw.slice(1, -1) : "");
+        opening.id = parsed.id;
+        opening.classes = parsed.classes;
+        opening.attributes = parsed.values;
+        for (const message of [...parsed.problems, ...refusedAttributes(parsed.values)])
+            errors.push({ ...at, message });
+        for (const [key, value] of Object.entries(parsed.values)) {
+            if (!["form", "meter", "rhyme", "syllables", "lang"].includes(key))
+                errors.push({ ...at, message: `${key}= is not a poetry attribute` });
+            else if (key === "syllables" && !/^[1-9]\d*(?:,[1-9]\d*)*$/.test(value))
+                errors.push({
+                    ...at,
+                    message: "poetry syllables= needs positive comma-separated counts",
+                });
+            else if (key === "lang" && !/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(value))
+                errors.push({ ...at, message: "poetry lang= needs a language tag" });
+        }
+    }
+    if (opening?.name === "poetry")
+        errors.push({
+            line: opening.start + 1,
+            column: 1,
+            message: "poetry block needs a closing code fence",
+        });
+    return { blocks, errors };
+}
+
+/** Replace verse fences with HTML wrappers whose body remains inline Markdown.
+ * @param {string} source - Authored Markdown.
+ */
+export function renderPoetry(source) {
+    const { blocks, errors } = scanPoetry(source),
+        lines = String(source ?? "").split("\n"),
+        output = [];
+    let cursor = 0;
+    const escape = (value) =>
+        String(value)
+            .replace(/&/g, "&amp;")
+            .replace(/"/g, "&quot;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;");
+    for (const block of blocks) {
+        output.push(...lines.slice(cursor, block.start));
+        const attrs = [`class="${escape(["poetry", ...block.classes].join(" "))}"`];
+        if (block.id) attrs.push(`id="${escape(slugify(block.id))}"`);
+        for (const [key, value] of Object.entries(block.attributes))
+            if (!refusedAttributes({ [key]: value }).length)
+                attrs.push(`${key === "lang" ? key : `data-${key}`}="${escape(value)}"`);
+        let indent = block.indent;
+        if (
+            indent.length >= 4 &&
+            !lines.slice(0, block.start).some((line) => /^ *(?:[-+*]|\d+[.)]) +/.test(line))
+        )
+            indent = "";
+        output.push(
+            "",
+            `${indent}<div ${attrs.join(" ")}>`,
+            "",
+            ...poetryMarkdown(block.body)
+                .split("\n")
+                .map((line) => (line ? indent + line : line)),
+            "",
+            `${indent}</div>`,
+            "",
+        );
+        cursor = block.end + 1;
+    }
+    output.push(...lines.slice(cursor));
+    return { markdown: output.join("\n"), errors };
+}

package/engine/content-spans.mjs

@@ -0,0 +1,177 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+import MarkdownIt from "markdown-it";
+import { alertMarkdownPlugin } from "./content-alerts.mjs";
+import { slugify } from "./content-slug.mjs";
+import { scanPoetry } from "./content-poetry.mjs";
+import footnotePlugin from "markdown-it-footnote";
+import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+
+/** Add bracket spans after recognized Markdown links and footnotes.
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function spanMarkdownPlugin(md) {
+    md.inline.ruler.after("link", "bracket_span", (state, silent) => {
+        const start = state.pos;
+        if (
+            state.src[start] !== "[" ||
+            /@[A-Za-z]+$/.test(state.src.slice(0, start)) ||
+            state.src[start + 1] === "[" ||
+            state.src[start + 1] === "^" ||
+            state.src[start + 1] === "!" ||
+            ["!", "[", "]"].includes(state.src[start - 1])
+        )
+            return false;
+        const end = state.md.helpers.parseLinkLabel(state, start, false);
+        if (end < 0 || ["(", "["].includes(state.src[end + 1])) return false;
+        let finish = end + 1;
+        let parsed = { id: "", classes: [], values: {}, problems: [] };
+        if (state.src[finish] === "{") {
+            let quote = false,
+                escape = false,
+                close = finish + 1;
+            for (; close < state.posMax; close++) {
+                const char = state.src[close];
+                if (escape) {
+                    escape = false;
+                    continue;
+                }
+                if (char === "\\") {
+                    escape = true;
+                    continue;
+                }
+                if (char === '"') quote = !quote;
+                if (char === "}" && !quote) break;
+            }
+            if (close === state.posMax)
+                parsed.problems.push("span attributes need closing {…} braces");
+            else {
+                parsed = parseExtensionAttributes(state.src.slice(finish + 1, close));
+                finish = close + 1;
+            }
+        }
+        const problems = [...parsed.problems, ...refusedAttributes(parsed.values)];
+        if (silent) {
+            state.pos = finish;
+            return true;
+        }
+        const token = state.push("span_open", "span", 1);
+        token.meta = {
+            span: true,
+            start,
+            end: finish,
+            text: state.src.slice(start + 1, end),
+            problems,
+        };
+        if (parsed.id) token.attrSet("id", slugify(parsed.id));
+        if (parsed.classes.length) token.attrSet("class", parsed.classes.join(" "));
+        for (const [key, value] of Object.entries(parsed.values))
+            if (!refusedAttributes({ [key]: value }).length) token.attrSet(key, value);
+        const nested = [];
+        state.md.inline.parse(state.src.slice(start + 1, end), state.md, state.env, nested);
+        for (const child of nested)
+            if (child.meta?.span) {
+                child.meta.start += start + 1;
+                child.meta.end += start + 1;
+            }
+        state.tokens.push(...nested);
+        state.push("span_close", "span", -1);
+        state.pos = finish;
+        return true;
+    });
+}
+
+const parser = new MarkdownIt({ html: true })
+    .use(footnotePlugin)
+    .use(alertMarkdownPlugin)
+    .use(spanMarkdownPlugin);
+/** Read span anchors and located attribute diagnostics outside literal code.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanSpans(source) {
+    const text = String(source ?? ""),
+        env = {},
+        tokens = parser.parse(text, env),
+        spans = [],
+        errors = [];
+    const lines = text.split("\n"),
+        starts = [];
+    let offset = 0;
+    for (const line of lines) {
+        starts.push(offset);
+        offset += line.length + 1;
+    }
+    const collect = (children, position) => {
+        for (const child of children ?? []) {
+            if (!child.meta?.span) continue;
+            const start = position(child.meta.start),
+                end = position(child.meta.end);
+            const prefix = text.slice(0, start),
+                line = prefix.split("\n").length,
+                column = start - prefix.lastIndexOf("\n");
+            spans.push({
+                id: child.attrGet("id") ?? "",
+                line,
+                column,
+                start,
+                end,
+                text: child.meta.text,
+                attrs: child.attrs ?? [],
+            });
+            for (const message of child.meta.problems) errors.push({ line, column, message });
+        }
+    };
+    for (const token of tokens) {
+        if (token.type !== "inline" || !token.map) continue;
+        const contentLines = token.content.split("\n"),
+            positions = [];
+        let local = 0;
+        for (let n = 0; n < contentLines.length; n++) {
+            const sourceLine = token.map[0] + n;
+            const column = lines[sourceLine]?.indexOf(contentLines[n]) ?? -1;
+            positions.push({ local, absolute: starts[sourceLine] + Math.max(0, column) });
+            local += contentLines[n].length + 1;
+        }
+        collect(token.children, (pos) => {
+            const mapping = positions.findLast((mapping) => mapping.local <= pos) ?? positions[0];
+            return mapping.absolute + pos - mapping.local;
+        });
+    }
+    // Verse fences preserve inline Markdown even though the block parser
+    // normally treats every code fence as literal text.
+    for (const poem of scanPoetry(text).blocks) {
+        for (let line = poem.start + 1; line < poem.end; line++) {
+            const children = [];
+            parser.inline.parse(lines[line], parser, env, children);
+            collect(children, (pos) => starts[line] + pos);
+        }
+    }
+    spans.sort((a, b) => a.start - b.start);
+    errors.sort((a, b) => a.line - b.line || a.column - b.column);
+    return { spans, errors };
+}
+
+/** Emit span tags while leaving their inline content as Markdown for Hugo.
+ * @param {string} source - Authored Markdown.
+ */
+export function renderSpans(source) {
+    const { spans, errors } = scanSpans(source);
+    let markdown = String(source ?? "");
+    const escape = (value) =>
+        String(value)
+            .replace(/&/g, "&amp;")
+            .replace(/"/g, "&quot;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;");
+    for (const span of spans
+        .filter(
+            (span) => !spans.some((parent) => parent.start < span.start && parent.end >= span.end),
+        )
+        .sort((a, b) => b.start - a.start)) {
+        const attrs = span.attrs.map(([key, value]) => ` ${key}="${escape(value)}"`).join("");
+        markdown =
+            markdown.slice(0, span.start) +
+            `<span${attrs}>${renderSpans(span.text).markdown}</span>` +
+            markdown.slice(span.end);
+    }
+    return { markdown, errors };
+}

package/engine/folder-notes.mjs

@@ -42,9 +42,8 @@
  * because a `Folder` is a core Foundry document like a `JournalEntry` or a
  * `Scene`, not a system's.
  *
- * **A folder note carries no prose.** It is structure, not content, so it wants
- * no documentation journal and takes no part in `docEntryTypes` — the one
- * open decision, settled the way it recommended.
+ * **A folder note requires a body** under author validation. That body creates
+ * no documentation journal and takes no part in `docEntryTypes`.
  *
  * @module
  */

package/engine/foundry-entries.mjs

@@ -85,6 +85,7 @@ import {
     assertNoSectionField,
     assertNoTraitsField,
 } from "./retired-fields.mjs";
+import { collectAnchors } from "./anchors.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
@@ -121,6 +122,7 @@ export function anchorsOf(entryUuid, entryId, body, name) {
         const uuid = pageUuid(entryUuid, journalPageId(entryId, page));
         if (index === 0) anchors[LEAD_ANCHOR] = uuid;
         if (page.anchorSlug) anchors[page.anchorSlug] = uuid;
+        for (const anchor of collectAnchors(page.markdown)) anchors[anchor.slug] = uuid;
     });
     return anchors;
 }

package/engine/frontmatter-lint.mjs

@@ -88,6 +88,7 @@ import { DEFAULT_PARENT } from "./folder-notes.mjs";
 import {
     BEING_ARCHETYPES,
     dataFields,
+    isLegacyDataField,
     declaredTags,
     subTypeCharsetMessage,
     typeCharsetMessage,
@@ -502,7 +503,7 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
     }
 
     for (const key of Object.keys(entries)) {
-        if (declared.has(key)) continue;
+        if (declared.has(key) || isLegacyDataField(type, key)) continue;
         const current = renamed.get(key);
         if (current) {
             findings.push({

package/engine/heading-attributes.mjs

@@ -12,7 +12,7 @@
  * an id a surface publishes as an anchor, classes a surface may honour, and
  * attributes an HTML surface writes onto the element. This is where that
  * reading lives, so there is one grammar — the same one a `:::` block and a
- * `:::figure` are written in.
+ * captions and divs are written in.
  *
  * **A leaf, deliberately.** `anchors.mjs` is shared by the compilers, the index
  * and the link checker and cannot import any of them; the figure pass is

package/engine/helpers.mjs

@@ -25,6 +25,7 @@
  * journals.mjs, actors.mjs).
  */
 
+import { renderAlerts } from "./content-alerts.mjs";
 import { buildReferenceTargets } from "./reference-targets.mjs";
 import { standingsDigest } from "./standings.mjs";
 
@@ -72,6 +73,7 @@ import { linkFindingMessage } from "./wikilink-syntax.mjs";
 import { isDraftNote } from "./note-vocabulary.mjs";
 import { DERIVED_PACKED_TYPES, NEVER_PACKED_TYPES } from "./note-claims.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { spanMarkdownPlugin } from "./content-spans.mjs";
 import { renderBlocks } from "./content-blocks.mjs";
 import { headingAttributesPlugin } from "./heading-attributes.mjs";
 import { renderFigureBlocks, scanFigures } from "./content-figures.mjs";
@@ -105,6 +107,7 @@ let localAssetImageInfoCache;
 export const md = markdownit({ html: true })
     .use(footnotePlugin)
     .use(deflistPlugin)
+    .use(spanMarkdownPlugin)
     // A heading's attribute block, written onto the heading element rather than
     // typeset into it — the reading the website's renderer does for itself.
     .use(headingAttributesPlugin)
@@ -220,11 +223,11 @@ md.renderer.rules.footnote_open = (tokens, idx, options, env, renderer) => {
  * @returns {string} The rendered HTML.
  */
 export function renderFoundryMarkdown(body, figures, footnoteNumbers, docId, resolveRole) {
-    const blocks = renderBlocks(body, "foundry");
-    const figured = renderFigureBlocks(blocks.markdown, (block) => md.render(block), figures, {
+    const figured = renderFigureBlocks(body, (block) => md.render(block), figures, {
         resolveRole,
     });
-    return md.render(figured.markdown, { footnoteNumbers, docId });
+    const blocks = renderBlocks(figured.markdown, "foundry");
+    return md.render(renderAlerts(blocks.markdown, "foundry").markdown, { footnoteNumbers, docId });
 }
 
 /**
@@ -918,6 +921,8 @@ export function buildContentLinkIndex(
             // Read from the record rather than from a second reading of the
             // note's headings — the one-anchor-reader rule.
             anchors: new Set((record.anchors ?? []).map((anchor) => anchor.slug)),
+            anchorUuids: record.foundry?.note?.anchors,
+            docAnchorUuids: documentation?.foundry?.note?.anchors,
         });
     }
     // Packages this build links *into* but does not publish. Each publishes