@heroiclands/package-build 22.15.1 → 22.17.0

package/engine/code-fences.mjs

@@ -46,110 +46,36 @@
  * prevent.
  */
 
+import { parseExtensionAttributes } from "./extension-attributes.mjs";
+
 /** A fence line, capturing its indent, its marker, and its info string. */
 export const FENCE_LINE = /^([ \t]*)(`{3,}|~{3,})[ \t]*([^\r\n]*)$/;
 
 /**
- * A fence's info string, read as **org-babel header arguments**.
- *
- * A directive fence carries statements *about the directive* that are no part of
- * the query it holds — whether an empty result is intended, what heading level a
- * section takes, later a caption. Those started as an ad-hoc bare word
- * (`allow-empty`) and a `key=value` (`section-level=3`), each matched by its own
- * regex: a grammar only in the sense that two regexes are one, and with no room
- * to add a third property without adding a third spelling.
- *
- * Org-mode settled this long ago. A babel source block writes them after the
- * language as `:key value`, which is a real grammar with a specification, a
- * parser, and an editor that already completes it.
- *
- * ```text
- * ```sql :section-level 3 :allow-empty
- * ```
- *
- * **The language word stays first and stays plain.** `sql` is what GitHub,
- * Prettier and every other markdown reader match on to syntax-highlight the
- * block, so it leads and the header args follow; a reader that does not know
- * them sees an ordinary SQL block.
- *
- * The grammar, matching org's:
- *
- * - a key is `:name` **starting a word** — a colon inside or ending a word is
- *   text, so `:caption Gear: the tables` is one argument;
- * - a value runs to the next key or the end of the string, spaces included, and
- *   is trimmed;
- * - a key with no value is `true`, which is what a statement like
- *   `:allow-empty` is;
- * - a value may be `"quoted"` to hold a word that would otherwise read as a
- *   key — the one ambiguity org has too;
- * - a repeated key takes its last value.
- *
- * @param {string} info - The text after the fence marker.
- * @returns {{language: string, args: Record<string, string|true>}} The language,
- *   lowercased, and the header arguments in written order.
+ * Read a language name and optional braced attributes from a code fence.
+ * @param {string} info - Text after the fence marker.
+ * @returns {{language: string, args: Record<string, string>, problems: string[]}}
+ *   Parsed values and syntax findings.
  */
 export function parseHeaderArgs(info) {
     const text = String(info ?? "").trim();
-    if (!text) return { language: "", args: {} };
-
-    // The language is the first word; everything after it is header arguments.
-    const firstKey = text.search(/(?:^|\s):[A-Za-z][\w-]*/);
-    const head = (firstKey === -1 ? text : text.slice(0, firstKey)).trim();
-    const language = head.split(/\s+/)[0]?.toLowerCase() ?? "";
-    if (firstKey === -1) return { language, args: {} };
-
-    const args = {};
-    const rest = text.slice(firstKey);
-    // Split before each key: a colon that starts a word. A colon inside or at
-    // the end of a word is ordinary text, which is what keeps `Gear:` a value.
-    const quoted = quotedSpans(rest);
-    const re = /(?:^|\s):([A-Za-z][\w-]*)/g;
-    const keys = [];
-    let m;
-    while ((m = re.exec(rest)) !== null) {
-        // A key-like word inside a quoted value is part of the value — that is
-        // the whole reason quoting exists here.
-        if (quoted.some(([from, to]) => m.index >= from && m.index < to)) continue;
-        keys.push({ name: m[1], at: m.index, end: re.lastIndex });
-    }
-    for (let i = 0; i < keys.length; i += 1) {
-        const from = keys[i].end;
-        const to = i + 1 < keys.length ? keys[i + 1].at : rest.length;
-        const raw = rest.slice(from, to).trim();
-        args[keys[i].name] = raw === "" ? true : unquote(raw);
-    }
-    return { language, args };
-}
-
-/**
- * The `"…"` and `'…'` spans in a header-argument string, as [start, end) offsets.
- *
- * Scanned once before the keys are, so a key-like word inside a value is never
- * read as the next key.
- *
- * @param {string} text - The header-argument text.
- * @returns {Array<[number, number]>} The quoted spans.
- */
-function quotedSpans(text) {
-    const spans = [];
-    const re = /"[^"]*"|'[^']*'/g;
-    let m;
-    while ((m = re.exec(text)) !== null) spans.push([m.index, m.index + m[0].length]);
-    return spans;
-}
-
-/**
- * A header-argument value with its surrounding quotes removed.
- *
- * Quoting is how a value holds a word that would otherwise read as the next key
- * — the same escape hatch org offers, and the only one needed.
- *
- * @param {string} value - The raw value.
- * @returns {string} The value, unquoted.
- */
-function unquote(value) {
-    const m = /^"([^"]*)"$|^'([^']*)'$/.exec(value);
-    return m ? (m[1] ?? m[2]) : value;
+    if (!text) return { language: "", args: {}, problems: [] };
+    const match = /^([^\s{}]+)(?:\s+(.*))?$/.exec(text);
+    const language = match?.[1]?.toLowerCase() ?? "";
+    const rest = match?.[2]?.trim() ?? "";
+    if (!rest) return { language, args: {}, problems: [] };
+    if (!/^\{[\s\S]*\}$/.test(rest))
+        return { language, args: {}, problems: ["fence attributes need {key=value} syntax"] };
+    const parsed = parseExtensionAttributes(rest.slice(1, -1));
+    return {
+        language,
+        args: parsed.values,
+        problems: [
+            ...parsed.problems,
+            ...(parsed.id ? ["a code fence does not accept an id"] : []),
+            ...(parsed.classes.length ? ["a code fence does not accept classes"] : []),
+        ],
+    };
 }
 
 /** A list item's opening line, capturing the indent and the marker itself. */

package/engine/compile-corpus.mjs

@@ -39,7 +39,7 @@
  */
 
 import { indexRecordsFor } from "./content-index.mjs";
-import { buildContentLinkIndex, collectContentDocs } from "./helpers.mjs";
+import { buildContentLinkIndex } from "./helpers.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { prepareTreeSqlTables } from "./sql-tables.mjs";
 
@@ -60,8 +60,7 @@ import { prepareTreeSqlTables } from "./sql-tables.mjs";
  *   created when none is passed, and returned on the corpus either way — a note
  *   the index refuses is a note the compile must still *report*, exactly as the
  *   compile loop reported it when the loop was the first to see it.
- * @returns {Promise<{records: object[], linkIndex: object, contentDocs: object[],
- *   sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
+ * @returns {Promise<{records: object[], linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
 export async function buildCompileCorpus({
@@ -81,12 +80,12 @@ export async function buildCompileCorpus({
         skipDirectories,
         problems: collected,
     });
-    const scope = { skipDirectories, config: resolved, records };
+    const corpusOptions = { config: resolved, records };
+    const sqlOptions = { ...corpusOptions, skipDirectories };
     return {
         records,
         problems: collected,
-        linkIndex: buildContentLinkIndex(contentBase, router, scope),
-        contentDocs: collectContentDocs(contentBase, scope),
-        sqlTables: await prepareTreeSqlTables(contentBase, scope),
+        linkIndex: buildContentLinkIndex(contentBase, router, corpusOptions),
+        sqlTables: await prepareTreeSqlTables(contentBase, sqlOptions),
     };
 }

package/engine/content-admonitions.mjs

@@ -0,0 +1,114 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+import MarkdownIt from "markdown-it";
+import footnotePlugin from "markdown-it-footnote";
+import deflistPlugin from "markdown-it-deflist";
+import { parseExtensionAttributes } from "./extension-attributes.mjs";
+
+const parser = new MarkdownIt({ html: true }).use(footnotePlugin).use(deflistPlugin);
+const OPEN = /^:::(info|warn)(?:\s+(.*))?\s*$/;
+const CLOSE = /^:::\s*$/;
+const STYLES = Object.freeze({
+    info: { label: "Info", icon: "ℹ", color: "#2f6f9f", background: "#eef6fb" },
+    warn: { label: "Warning", icon: "⚠", color: "#9a6700", background: "#fff5db" },
+});
+
+/** Find inline info and warning blocks without interpreting code examples. */
+export function scanAdmonitions(source) {
+    const lines = String(source ?? "").split("\n");
+    const blocks = [];
+    const errors = [];
+    let opening = null;
+    let codeFence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length)
+                codeFence = null;
+            continue;
+        }
+        if (fence) {
+            codeFence = fence[1];
+            continue;
+        }
+        const open = OPEN.exec(line);
+        if (open) {
+            if (opening) {
+                errors.push({
+                    line: i + 1,
+                    column: 1,
+                    message: "nested info and warning blocks are not supported",
+                });
+                continue;
+            }
+            const raw = open[2]?.trim() ?? "";
+            let id = "";
+            if (raw) {
+                if (!/^\{[^}\n]*\}$/.test(raw))
+                    errors.push({
+                        line: i + 1,
+                        column: 1,
+                        message: "block attributes need {#id} syntax",
+                    });
+                else {
+                    const attrs = parseExtensionAttributes(raw.slice(1, -1));
+                    id = attrs.id;
+                    for (const message of attrs.problems)
+                        errors.push({ line: i + 1, column: 1, message });
+                    if (attrs.classes.length || Object.keys(attrs.values).length)
+                        errors.push({
+                            line: i + 1,
+                            column: 1,
+                            message: "info and warn accept only an id",
+                        });
+                }
+            }
+            opening = { start: i, kind: open[1], id };
+            continue;
+        }
+        if (CLOSE.test(line) && opening) {
+            const body = lines
+                .slice(opening.start + 1, i)
+                .join("\n")
+                .trim();
+            if (!body)
+                errors.push({
+                    line: opening.start + 1,
+                    column: 1,
+                    message: `${opening.kind} block is empty`,
+                });
+            blocks.push({ ...opening, end: i, body });
+            opening = null;
+        }
+    }
+    if (opening)
+        errors.push({
+            line: opening.start + 1,
+            column: 1,
+            message: `${opening.kind} block needs a closing ::: line`,
+        });
+    return { blocks, errors };
+}
+
+/** Render info and warning blocks as styled, labelled HTML. */
+export function renderAdmonitions(source, renderMarkdown = parser.render.bind(parser)) {
+    const { blocks, errors } = scanAdmonitions(source);
+    if (errors.length) return { markdown: source, errors };
+    const lines = String(source ?? "").split("\n");
+    const output = [];
+    let cursor = 0;
+    for (const block of blocks) {
+        const style = STYLES[block.kind];
+        output.push(...lines.slice(cursor, block.start));
+        output.push(
+            `<aside${block.id ? ` id="${block.id}"` : ""} class="sohl-admonition sohl-admonition-${block.kind}" style="border-left: 3px solid ${style.color}; background: ${style.background}; padding: 0.5em 0.8em; margin: 0.75em 0;">`,
+            `<p><strong><span aria-hidden="true">${style.icon}</span> ${style.label}</strong></p>`,
+            renderMarkdown(block.body).trim(),
+            "</aside>",
+        );
+        cursor = block.end + 1;
+    }
+    output.push(...lines.slice(cursor));
+    return { markdown: output.join("\n"), errors: [] };
+}

package/engine/content-captions.mjs

@@ -0,0 +1,181 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import MarkdownIt from "markdown-it";
+import footnotePlugin from "markdown-it-footnote";
+import deflistPlugin from "markdown-it-deflist";
+
+import { slugify } from "./content-slug.mjs";
+import { parseExtensionAttributes } from "./extension-attributes.mjs";
+
+const parser = new MarkdownIt({ html: true }).use(footnotePlugin).use(deflistPlugin);
+const OPEN = /^:::caption\s+(\{[^}\n]*\})\s*$/;
+const CAPTION_LINE = /^:::caption\b/;
+const CLOSE = /^:::\s*$/;
+
+/** A caption's automatically determined kind. */
+export const CAPTION_NAMES = Object.freeze({
+    code: "Code",
+    table: "Table",
+    figure: "Figure",
+    prose: "Prose",
+});
+
+/** Number a sequence of captions with counters shared across documents. */
+export function numberCaptions(captions, counts) {
+    return captions.map((caption) => {
+        const number = (counts[caption.kind] ?? 0) + 1;
+        counts[caption.kind] = number;
+        return { ...caption, number, label: `${CAPTION_NAMES[caption.kind]} ${number}` };
+    });
+}
+
+/**
+ * Read caption directives and the Markdown block immediately after each one.
+ * SQL fences are expanded before this pass, so their output is a table.
+ *
+ * @param {string} source - A note body with expanded tables.
+ * @returns {{captions: Array<{id: string, text: string, kind: string, number: number,
+ *   label: string, line: number, blockStart: number, blockEnd: number,
+ *   directiveEnd: number}>, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanCaptions(source) {
+    const lines = String(source ?? "").split("\n");
+    const captions = [];
+    const errors = [];
+    const counts = { code: 0, table: 0, figure: 0, prose: 0 };
+    const ids = new Set();
+    const headingIds = [];
+    let codeFence = null;
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length)
+                codeFence = null;
+            continue;
+        }
+        if (fence) {
+            codeFence = fence[1];
+            continue;
+        }
+        const heading = /^\s*#{1,6}\s+.+?\{#([^}]+)\}\s*$/.exec(line);
+        if (heading) headingIds.push({ id: slugify(heading[1].trim()), line: i + 1 });
+        if (!CAPTION_LINE.test(line)) continue;
+        const open = OPEN.exec(line);
+        if (!open) {
+            errors.push({ line: i + 1, column: 1, message: "caption needs {#anchor} attributes" });
+            continue;
+        }
+        const attributes = parseExtensionAttributes(open[1].slice(1, -1));
+        if (
+            attributes.problems.length ||
+            !attributes.id ||
+            attributes.classes.length ||
+            Object.keys(attributes.values).length
+        ) {
+            errors.push({
+                line: i + 1,
+                column: 1,
+                message: attributes.problems[0] ?? "caption accepts only {#anchor}",
+            });
+            continue;
+        }
+        const id = attributes.id;
+        const start = i;
+        let close = i + 1;
+        while (close < lines.length && !CLOSE.test(lines[close])) close++;
+        if (close === lines.length) {
+            errors.push({ line: start + 1, column: 1, message: "caption needs a closing :::" });
+            continue;
+        }
+        const caption = lines
+            .slice(i + 1, close)
+            .join("\n")
+            .trim();
+        if (!caption) errors.push({ line: start + 1, column: 1, message: "caption text is empty" });
+        if (ids.has(slugify(id)))
+            errors.push({ line: start + 1, column: 1, message: `duplicate caption id "${id}"` });
+        ids.add(slugify(id));
+
+        let next = close + 1;
+        while (next < lines.length && !lines[next].trim()) next++;
+        if (next === lines.length || CAPTION_LINE.test(lines[next])) {
+            errors.push({ line: start + 1, column: 1, message: "caption needs a following block" });
+            i = close;
+            continue;
+        }
+        const tokens = parser.parse(lines.slice(next).join("\n"), {});
+        const first = tokens.find((token) => token.level === 0 && token.map);
+        if (!first) {
+            errors.push({ line: start + 1, column: 1, message: "caption needs a following block" });
+            i = close;
+            continue;
+        }
+        const blockEnd = next + first.map[1];
+        const block = lines.slice(next, blockEnd).join("\n");
+        const kind =
+            first.type === "table_open" ? "table"
+            : first.type === "fence" && /^\s*sql\b/i.test(first.info ?? "") ? "table"
+            : first.type === "fence" || first.type === "code_block" ? "code"
+            : /^(?:!\[|!\[\[|<figure\b|<img\b)/.test(block.trim()) ? "figure"
+            : "prose";
+        const number = ++counts[kind];
+        captions.push({
+            id,
+            text: caption,
+            kind,
+            number,
+            label: `${CAPTION_NAMES[kind]} ${number}`,
+            line: start + 1,
+            blockStart: next,
+            blockEnd,
+            directiveEnd: close + 1,
+        });
+        i = close;
+    }
+    for (const heading of headingIds) {
+        if (ids.has(heading.id))
+            errors.push({
+                line: heading.line,
+                column: 1,
+                message: `heading and caption declare the same anchor "${heading.id}"`,
+            });
+    }
+    return { captions, errors };
+}
+
+/** Render captioned blocks as HTML, leaving other Markdown untouched. */
+export function renderCaptionBlocks(source, renderMarkdown = parser.render.bind(parser), numbers) {
+    const { captions, errors } = scanCaptions(source);
+    if (errors.length) return { markdown: source, errors };
+    const byId = numbers ? new Map(numbers.map((entry) => [entry.id, entry])) : new Map();
+    const lines = String(source ?? "").split("\n");
+    const output = [];
+    let cursor = 0;
+    const escape = (value) =>
+        String(value)
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;");
+    for (const caption of captions) {
+        output.push(...lines.slice(cursor, caption.line - 1));
+        const numbered = byId.get(caption.id) ?? caption;
+        let html = renderMarkdown(lines.slice(caption.blockStart, caption.blockEnd).join("\n"));
+        if (caption.kind === "figure")
+            html = html.replace(/<figcaption\b[^>]*>[\s\S]*?<\/figcaption>/i, "");
+        const captionHtml = parser.renderInline(caption.text);
+        output.push(
+            `<div id="${escape(slugify(caption.id))}" class="content-caption content-caption-${caption.kind}">`,
+            html.trim(),
+            `<p class="content-caption-label">${escape(numbered.label)}: ${captionHtml}</p>`,
+            "</div>",
+        );
+        cursor = caption.blockEnd;
+    }
+    output.push(...lines.slice(cursor));
+    return { markdown: output.join("\n"), errors: [] };
+}

package/engine/content-embeds.mjs

@@ -23,8 +23,8 @@
  *
  * ## An embed resolves to an ordinary image, and that is the whole design
  *
- * `![[thorn|Thorn]]{float: top-left}` becomes
- * `![Thorn](thalorna/assets/images/beings/thorn.webp){float: top-left}` in the
+ * `![[thorn|Thorn]]{float=top-left}` becomes
+ * `![Thorn](thalorna/assets/images/beings/thorn.webp){float=top-left}` in the
  * source text, before any surface renders it. Everything downstream is machinery
  * that already exists: {@link module:engine/content-images.imagePlugin} draws the
  * figure for a Foundry journal and for the book's Typst walk,

package/engine/content-footnotes.mjs

@@ -0,0 +1,34 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+/**
+ * Separate top-level footnote definitions from prose while retaining line numbers.
+ * Definitions belong to the note and can be used by any rendered page.
+ * @param {string} source - Authored Markdown.
+ * @returns {{markdown: string, definitions: string}} Body with blanked definitions and their source.
+ */
+export function separateFootnotes(source) {
+    const lines = String(source ?? "").split("\n");
+    const body = [...lines];
+    const definitions = [];
+    let fence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
+        if (fence) {
+            if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length)
+                fence = null;
+            continue;
+        }
+        if (marker) {
+            fence = marker[1];
+            continue;
+        }
+        if (!/^\[\^[^\]\s]+\]:/.test(lines[i])) continue;
+        const start = i;
+        i++;
+        while (i < lines.length && (!lines[i].trim() || /^(?: {4}|\t)/.test(lines[i]))) i++;
+        definitions.push(lines.slice(start, i).join("\n").trimEnd());
+        for (let at = start; at < i; at++) body[at] = "";
+        i--;
+    }
+    return { markdown: body.join("\n"), definitions: definitions.join("\n\n") };
+}

package/engine/content-format-check.mjs

@@ -141,7 +141,7 @@ export function declaredPaths(artifact) {
  * mappings" instead of "on a `weapongear`". Reading `on a \`the shared
  * mappings\`` would be the alternative, and a diagnostic is prose.
  *
- * @param {object} finding - `{system, systemVersion, noteType, source, target, shared}`.
+ * @param {{system: string, systemVersion: string, noteType: string, source: string, target: string, shared: boolean}} finding - The unresolved mapping.
  * @returns {string} The message.
  */
 export function undeclaredTargetMessage({
@@ -468,7 +468,7 @@ function under(path, prefix) {
 /**
  * What an author is told when the specification and the declaration disagree.
  *
- * @param {object} finding - `{noteType, source, target, name, to}`.
+ * @param {{noteType: string, source: string, target: string, name: string, to: string}} finding - The differing mapping.
  * @returns {string} The message.
  */
 export function fieldDriftMessage({ noteType, source, target, name, to }) {