@heroiclands/package-build 22.15.0 → 22.16.0

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 }) {

package/engine/content-format.mjs

@@ -12,68 +12,12 @@
  */
 
 /**
- * Reading `docs/content-format.md` as data.
+ * Reads the structured note-format contract shipped with this package.
  *
- * The content format — three frontmatter regions, a note vocabulary with its
- * own `type` and `subType`, and a declared map from each note type onto each
- * system's document fields — is prose, because that is the only form in which
- * the *reasons* survive. But two of the things it states are checkable, and
- * were checked by throwaway scripts while it was being drafted:
- *
- * - **every `system.*` target it names** must exist in the naming system's
- *   published `schema.json`, or the specification and the system disagree; and
- * - **every authored note** should carry only the keys the format declares for
- *   its type, which during the migration is a progress bar as much as a
- *   check.
- *
- * Both need the document as data, and this is the module that supplies it.
- *
- * **It reads the document's own tables rather than a transcription of them.**
- * A hardcoded list of targets and per-type vocabularies would be a second copy
- * of the specification, free to drift from the first the moment either is
- * edited — which is exactly the failure the checks exist to prevent, moved one
- * level up. So the parser knows the *shape* of the tables the document uses and
- * nothing about their contents: no type name, no field name and no system name
- * is written here. Editing the document changes what the checks assert.
- *
- * **Three table shapes carry everything.**
- *
- * | table | recognised by its first header cell | yields |
- * | --- | --- | --- |
- * | the per-type vocabulary | `` `data` property `` | the keys that type's `data:` block may carry |
- * | the per-type mapping | `shared source` | one claim per `system.*` cell |
- * | a closed vocabulary | `` `<name>` value `` | the values `<name>` admits |
- *
- * A mapping table's remaining header cells name the systems (`→ sohl`,
- * `→ hm3`), so the system vocabulary comes from the document too.
- *
- * **A closed vocabulary is a table because it is a list with consequences.**
- * Where the format admits a fixed set of names and refuses the rest, each name
- * takes a row beside what it means, which is the only place a reader can
- * compare them. The header names the vocabulary rather than the parser, so a
- * second one costs a table and nothing here.
- *
- * **The other half of a type's vocabulary is a bullet list, not a table.** A
- * type's `subType` values are stated as `**subType**:` followed by one bullet
- * per value, `- <value>` or `- <value>: <definition>`, and that is read here
- * for the same reason the tables are: so the specification and
- * `note-vocabulary.mjs` cannot disagree about which genres exist. The
- * one shape is enforced rather than guessed at — the document wrote them five
- * ways, and a reader that accepted every spelling would accept the sixth by
- * reading the section as declaring nothing, which is the drift it exists to
- * catch. An unrecognised shape throws.
- *
- * **A mapping table before the first `### type:` heading is the shared one.**
- * The document states the rows every type maps identically once, at the top,
- * and omits them from all sixteen per-type tables — so a parser that only ever
- * looked inside a type's section could not see them, and the eight rows they
- * cover were checked by nothing. Position is the whole distinction:
- * there is no marker to read and none is wanted, since the document's own
- * argument for stating them once is that they belong to no type in particular. A cell that
- * names no field — `NA`, `**see above**`, a `flags.*` path — is not a claim,
- * and is skipped rather than reported: the check is about `system.*` targets,
- * and a column reading NA is the document saying this type produces no document
- * there.
+ * Types, subtype values, field paths, system mappings, and closed vocabularies
+ * have located declarations. The guides can change their headings and tables
+ * without changing validation. A caller may supply a Markdown specification
+ * explicitly through `--spec`; the bundled contract is YAML.
  *
  * @module
  */
@@ -81,35 +25,34 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import YAML from "yaml";
 
 /**
- * The specification this package ships.
+ * The structured format contract this package ships.
  *
  * Resolved from this module rather than from the working directory: a consumer
- * runs `content-build content-format` inside its own repository, and the
- * document it should be checked against is the one that came with the toolchain
+ * runs `package-build content-format` inside its own repository, and the
+ * contract it should be checked against is the one that came with the toolchain
  * version it resolved — the same rule `--version` follows.
  *
  * @type {string}
  */
 export const CONTENT_FORMAT_PATH = path.join(
     path.dirname(fileURLToPath(import.meta.url)),
-    "..",
-    "docs",
-    "content-format.md",
+    "content-format.yaml",
 );
 
 /**
  * What one note type's section declares.
  *
  * @typedef {object} TypeSpec
- * @property {string} name - The note type, as the `### type:` heading spells it.
- * @property {number} line - 1-based line of that heading.
+ * @property {string} name - The note type as declared in the contract.
+ * @property {number} line - 1-based line of that declaration.
  * @property {Set<string>} dataKeys - The head segment of each declared `data`
  *   property — what a note actually writes. `appearance.eye_color` is authored
  *   as `appearance`, so that is the key recorded.
  * @property {Set<string>} dataPaths - The declared paths, whole.
- * @property {string[]} subTypes - The `subType` values the section enumerates,
+ * @property {string[]} subTypes - The declared `subType` values,
  *   in document order — empty when it states none, which is the ordinary case
  *   for a type that has no `subType` at all.
  */
@@ -426,11 +369,122 @@ export function parseContentFormat(text, { file = CONTENT_FORMAT_PATH } = {}) {
 }
 
 /**
- * Read and parse the specification from disk.
+ * Read and parse the bundled contract or a caller-supplied specification.
  *
- * @param {string} [file] - The document. Defaults to {@link CONTENT_FORMAT_PATH}.
+ * @param {string} [file] - The contract. Defaults to {@link CONTENT_FORMAT_PATH}.
  * @returns {ContentFormat} What it declares.
  */
 export function loadContentFormat(file = CONTENT_FORMAT_PATH) {
-    return parseContentFormat(fs.readFileSync(file, "utf8"), { file });
+    const source = fs.readFileSync(file, "utf8");
+    return file.endsWith(".md") ?
+            parseContentFormat(source, { file })
+        :   parseStructuredContentFormat(source, { file });
+}
+
+/**
+ * Read the machine contract without depending on the presentation of a guide.
+ * A Markdown file remains accepted by `--spec` for callers carrying a custom
+ * specification; the shipped contract is YAML.
+ *
+ * @param {string} text - YAML content.
+ * @param {object} [opts]
+ * @param {string} [opts.file] - Location reported in diagnostics.
+ * @returns {ContentFormat} Types, mappings, and closed vocabularies.
+ */
+export function parseStructuredContentFormat(text, { file = CONTENT_FORMAT_PATH } = {}) {
+    const lines = new YAML.LineCounter();
+    const document = YAML.parseDocument(text, { lineCounter: lines, uniqueKeys: true });
+    if (document.errors.length) {
+        const fault = document.errors[0];
+        const position = fault.pos?.[0] === undefined ? null : lines.linePos(fault.pos[0]);
+        throw new Error(
+            `${file}${position ? `:${position.line}:${position.col}` : ""}: error: ${fault.message}`,
+        );
+    }
+    const root = document.toJS();
+    const mapping = (value) => value && typeof value === "object" && !Array.isArray(value);
+    if (
+        root?.version !== 1 ||
+        !mapping(root.types) ||
+        !Array.isArray(root.claims) ||
+        !mapping(root.vocabularies)
+    ) {
+        throw new Error(
+            `${file}: error: expected format contract version 1 with types, claims, and vocabularies`,
+        );
+    }
+    const at = (node) => (node?.range?.[0] === undefined ? null : lines.linePos(node.range[0]));
+    const errorAt = (node, message) => {
+        const position = at(node);
+        return new Error(
+            `${file}${position ? `:${position.line}:${position.col}` : ""}: error: ${message}`,
+        );
+    };
+    const types = new Map();
+    for (const [name, spec] of Object.entries(root.types)) {
+        const node = document.getIn(["types", name], true);
+        if (!Array.isArray(spec.data) || !Array.isArray(spec.subTypes)) {
+            throw errorAt(node, `type ${name} needs data and subTypes lists`);
+        }
+        for (const [index, field] of spec.data.entries()) {
+            if (typeof field !== "string" || !field.trim()) {
+                throw errorAt(
+                    document.getIn(["types", name, "data", index], true),
+                    `type ${name} has an empty or non-string data field`,
+                );
+            }
+        }
+        for (const [index, subType] of spec.subTypes.entries()) {
+            if (typeof subType !== "string" || !subType.trim()) {
+                throw errorAt(
+                    document.getIn(["types", name, "subTypes", index], true),
+                    `type ${name} has an empty or non-string subType`,
+                );
+            }
+        }
+        types.set(name, {
+            name,
+            line: at(node)?.line,
+            dataKeys: new Set(spec.data.map((field) => field.split(".")[0])),
+            dataPaths: new Set(spec.data),
+            subTypes: spec.subTypes,
+        });
+    }
+    const claims = root.claims.map((claim, index) => {
+        const node = document.getIn(["claims", index], true);
+        const position = at(node);
+        if (
+            !mapping(claim) ||
+            ["noteType", "system", "source", "target"].some(
+                (key) => typeof claim[key] !== "string" || !claim[key].trim(),
+            )
+        ) {
+            throw errorAt(node, "a mapping needs noteType, system, source, and target");
+        }
+        return {
+            ...claim,
+            ...(position ? { line: position.line, column: position.col } : {}),
+        };
+    });
+    const vocabularies = new Map();
+    for (const [name, values] of Object.entries(root.vocabularies)) {
+        const node = document.getIn(["vocabularies", name], true);
+        if (!Array.isArray(values)) {
+            throw errorAt(node, `vocabulary ${name} needs a values list`);
+        }
+        for (const [index, value] of values.entries()) {
+            if (typeof value !== "string" || !value.trim()) {
+                throw errorAt(
+                    document.getIn(["vocabularies", name, index], true),
+                    `vocabulary ${name} has an empty or non-string value`,
+                );
+            }
+        }
+        vocabularies.set(name, {
+            name,
+            line: at(node)?.line,
+            values,
+        });
+    }
+    return { file, types, claims, vocabularies };
 }