@heroiclands/package-build 0.6.0 → 3.0.0

package/engine/content-tree.mjs

@@ -0,0 +1,56 @@
+/*
+ * 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
+ */
+
+/**
+ * Is there any content to compile?
+ *
+ * The pack build's worst failure is not an error but a **success on nothing**: a
+ * content tree that is absent or empty compiles zero documents, reports no
+ * error, and ships compendiums that are simply empty. Nothing downstream
+ * notices — the LevelDB packs are written, the deploy mirrors them, and the
+ * defect surfaces as "my compendiums are blank" long after the build went green.
+ *
+ * `assets/content/` is this repository's own source (#1445), but an empty or
+ * partial tree is still possible — a bad checkout, or a sparse clone. This
+ * counts what is actually there so the build can refuse.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Count the Markdown notes below a content tree.
+ *
+ * Only notes count. The per-pack folder manifests are not content, so a tree
+ * holding nothing but manifests counts zero — which is correct, because it
+ * compiles zero documents. Dot directories are skipped so stale editor caches
+ * cannot make an empty tree look populated.
+ *
+ * @param {string} root - Absolute path to the content tree.
+ * @returns {number} The number of `.md` notes, or 0 when the tree is absent.
+ */
+export function countContentNotes(root) {
+    if (!fs.existsSync(root)) return 0;
+
+    let count = 0;
+    /** @param {string} dir */
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith(".")) continue;
+            if (entry.isDirectory()) walk(path.join(dir, entry.name));
+            else if (entry.isFile() && entry.name.endsWith(".md")) count += 1;
+        }
+    };
+    walk(root);
+    return count;
+}

package/engine/diagnostics.mjs

@@ -0,0 +1,270 @@
+/*
+ * 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
+ */
+
+/**
+ * Build diagnostics that name the file, line and column they are about.
+ *
+ * A build that reports a problem by the **note's name** — `Unresolved wikilink
+ * in "The Capital Nome"` — has told the author what is wrong and not where it
+ * is. A name is not an address: finding it means searching the tree for a note
+ * whose `name.full` matches and then searching that file for the link, and
+ * four identical warnings on one note are indistinguishable from one another
+ * (#17).
+ *
+ * So every diagnostic about a note is emitted in the form every C-family
+ * compiler, `tsc` and ESLint already use:
+ *
+ * ```text
+ * assets/content/Nomes/Capital.md:42:17: warning: unresolved wikilink [[Kenbet_Pat]] (unknown)
+ * ```
+ *
+ * `file:line:column: severity: message`. Nothing here is invented, which is
+ * the point: an editor, a CI annotator or a `grep` already parses it, with no
+ * knowledge of this build and nothing extra for it to emit.
+ *
+ * **Two rules keep the form parseable.**
+ *
+ * - _The locator starts the line._ Diagnostics deliberately bypass `loglevel`,
+ *   whose `[timestamp] [WARN]:` prefix occupies exactly the position a parser
+ *   reads the path from — a greedy path pattern swallows the prefix and yields
+ *   a filename no editor can open.
+ * - _A field is dropped, never guessed._ A position that cannot be established
+ *   honestly is omitted (`file: warning: …`) rather than defaulted to `1:1`,
+ *   which would send a reader to the frontmatter every time.
+ */
+
+import path from "node:path";
+
+/**
+ * The `file:line:column` locator, with whatever is known.
+ *
+ * The path is relativized against the working directory — during a build that
+ * is the consuming repository's root, so the result is both shorter to read
+ * and what an editor resolves a relative diagnostic against. A path outside
+ * the tree stays absolute, since a `../../..` locator helps nobody.
+ *
+ * @param {object} at
+ * @param {string} [at.file] - Absolute or relative path to the source file.
+ * @param {number} [at.line] - 1-based line.
+ * @param {number} [at.column] - 1-based column. Ignored without a line.
+ * @returns {string} The locator, or `""` when not even a file is known.
+ */
+export function formatLocator({ file, line, column } = {}) {
+    if (!file) return "";
+    let shown = file;
+    if (path.isAbsolute(file)) {
+        const rel = path.relative(process.cwd(), file);
+        // `..` means the file sits outside the working directory; an absolute
+        // path is the more useful of the two there.
+        if (rel && !rel.startsWith("..")) shown = rel;
+    }
+    if (!Number.isFinite(line)) return shown;
+    if (!Number.isFinite(column)) return `${shown}:${line}`;
+    return `${shown}:${line}:${column}`;
+}
+
+/**
+ * One diagnostic, as a parseable line.
+ *
+ * @param {object} d
+ * @param {string} [d.file] - Source file the diagnostic is about.
+ * @param {number} [d.line] - 1-based line.
+ * @param {number} [d.column] - 1-based column.
+ * @param {"warning"|"error"} d.severity - Which of the two levels this is.
+ * @param {string} d.message - What is wrong, in one sentence.
+ * @returns {string} `file:line:column: severity: message`, with any unknown
+ *   leading field omitted.
+ */
+export function formatDiagnostic({ file, line, column, severity, message }) {
+    const locator = formatLocator({ file, line, column });
+    return `${locator ? `${locator}: ` : ""}${severity}: ${message}`;
+}
+
+/**
+ * Prints one diagnostic on the console, unprefixed.
+ *
+ * **Both severities go to stderr**, which is what keeps findings clear of the
+ * progress and summary prose a build writes to stdout. That is Node's doing,
+ * not a choice made here: `console.warn` is an alias for `console.error` and
+ * writes to `process.stderr`, so the two branches below differ only in which
+ * severity word the line carries, never in the stream.
+ *
+ * Saying otherwise has already cost something — an earlier version of this
+ * comment claimed warnings went to stdout, and a consumer wrote a whole
+ * local wrapper to obtain the stderr routing it already had. Anything relying
+ * on the separation should split on the `severity` field, not on the stream.
+ *
+ * This deliberately sidesteps `loglevel`, for the reason given in the module
+ * docs.
+ *
+ * @param {object} d - As {@link formatDiagnostic}.
+ * @returns {void}
+ */
+export function emitDiagnostic(d) {
+    const line = formatDiagnostic(d);
+    if (d.severity === "error") console.error(line);
+    else console.warn(line);
+}
+
+/**
+ * Where a character offset within a note's **body** falls in its **file**.
+ *
+ * Three corrections separate the two, and each is applied only where it is
+ * true:
+ *
+ * 1. _The frontmatter._ A body offset is not a file line until the lines
+ *    before the body are added — `bodyLine`.
+ * 2. _The trimmed first line._ `parseMarkdownFile` trims the body, so its
+ *    first line may have lost indentation the file still has. `bodyColumn`
+ *    restores it, and only on that line.
+ * 3. _Generated text._ A body is scanned **after** its content tables expand,
+ *    so an offset may fall in text no one authored. `lineMap` maps each
+ *    scanned line back to the line it came from; a generated line reports the
+ *    directive that produced it and **no column**, since there is no authored
+ *    character to point at.
+ *
+ * @param {string} body - The text the offset indexes into.
+ * @param {number} offset - 0-based character offset within `body`.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - 1-based file line of the body's line 0.
+ * @param {number} [opts.bodyColumn=1] - 1-based file column of the body's
+ *   first character.
+ * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - Per
+ *   scanned line, the 0-based body line it came from. From
+ *   {@link expandContentTables}.
+ * @returns {{line: number, column: number|undefined, generated: boolean}}
+ */
+export function positionInBody(
+    body,
+    offset,
+    { bodyLine = 1, bodyColumn = 1, lineMap } = {},
+) {
+    const upTo = String(body ?? "").slice(0, Math.max(0, offset));
+    const nl = upTo.lastIndexOf("\n");
+    const scannedLine = upTo.length === 0 ? 0 : upTo.split("\n").length - 1;
+    const column = upTo.length - nl; // 1-based: offset - (nl + 1) + 1
+
+    const mapped = lineMap?.[scannedLine];
+    const sourceLine = mapped ? mapped.line : scannedLine;
+    const generated = mapped ? mapped.generated : false;
+
+    return {
+        line: bodyLine + sourceLine,
+        // A generated line has no authored column, and the first line's
+        // column is the only one the trim can have moved.
+        column:
+            generated ? undefined
+            : sourceLine === 0 ? bodyColumn + column - 1
+            : column,
+        generated,
+    };
+}
+
+/**
+ * Where a **frontmatter key** is declared in a note's file.
+ *
+ * {@link positionInBody} answers the same question for the body, and the two
+ * are separate because the body is what the compilers scan while frontmatter is
+ * what the linters read — a key sits *before* the body, so a body offset can
+ * never reach it.
+ *
+ * The search is deliberately scoped to the frontmatter block rather than run
+ * over the whole file. A bare search for the key would match the first place
+ * the word appears anywhere, which for a key like `name` or `type` is routinely
+ * a line of prose — sending the reader to a position that is not the problem,
+ * which is the one thing the located form exists to prevent.
+ *
+ * @param {string} raw - The file's full contents, frontmatter included.
+ * @param {string} key - The top-level frontmatter key.
+ * @param {string} [value] - When given, prefer the occurrence whose line also
+ *   carries this text. A list-valued key (`aliases`) is reported at the entry
+ *   that is wrong, not at the key that introduces it.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when the key cannot be located — dropped rather than guessed, as
+ *   {@link formatDiagnostic} requires.
+ */
+export function positionInFrontmatter(raw, key, value = undefined) {
+    if (typeof raw !== "string" || !key) return {};
+    const fence = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!fence) return {};
+    const block = fence[1];
+    const lines = block.split("\n");
+
+    // A value locates the exact entry; the key alone locates its declaration.
+    const wanted = value == null ? undefined : String(value);
+    let keyLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (wanted != null && lines[i].includes(wanted)) {
+            keyLine = i;
+            break;
+        }
+        if (
+            keyLine === -1 &&
+            new RegExp(`^\\s*${escape(key)}\\s*:`).test(lines[i])
+        ) {
+            keyLine = i;
+            if (wanted == null) break;
+        }
+    }
+    if (keyLine === -1) return {};
+
+    const needle = wanted != null ? wanted : key;
+    const column = lines[keyLine].indexOf(needle);
+    return {
+        // +2: the file's line 1 is the opening `---`, so the block's line 0 is
+        // the file's line 2.
+        line: keyLine + 2,
+        ...(column === -1 ? {} : { column: column + 1 }),
+    };
+}
+
+/** Escape a literal for use inside a `RegExp`. */
+function escape(literal) {
+    return String(literal).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Where a literal sits in a text, so a finding about it can be opened.
+ *
+ * {@link positionInBody} maps an offset within a parsed note body, and
+ * {@link positionInFrontmatter} finds a key in the fence. This is the plainer
+ * case: a finding about a string the reader can see in a file that is neither —
+ * a manifest, a lockfile, a config.
+ *
+ * `@heroiclands/package-build` carries the same arithmetic for the files *it*
+ * reads. That is a duplicate worth naming: unlike the diagnostic *format* or a
+ * validation *rule*, "which line and column is this substring on" has exactly
+ * one correct answer and cannot drift into disagreement. The tidier arrangement
+ * is for that package to re-export this one — the dependency runs that way — and
+ * it should, next time either is touched.
+ *
+ * @param {string} text - The file's contents.
+ * @param {string} needle - The literal to locate.
+ * @param {number} [occurrence] - Which occurrence, 1-based. Repeats of one
+ *   literal are otherwise indistinguishable.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when the literal is not there — dropped rather than guessed.
+ */
+export function positionOfLiteral(text, needle, occurrence = 1) {
+    if (typeof text !== "string" || !needle) return {};
+    let at = -1;
+    for (let n = 0; n < occurrence; n++) {
+        at = text.indexOf(needle, at + 1);
+        if (at === -1) return {};
+    }
+    const before = text.slice(0, at);
+    return {
+        line: before.split("\n").length,
+        column: at - before.lastIndexOf("\n"),
+    };
+}

package/engine/field-reference.mjs

@@ -0,0 +1,242 @@
+/*
+ * 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
+ */
+
+/**
+ * The authoring reference, generated from the declared item fields.
+ *
+ * **Generated because a hand-written one would be wrong within a release.** The
+ * overwhelming majority of a content repository's compiled documents are items
+ * — 1,230 of SoHL's 1,362 when this was written — and a table spanning a dozen
+ * types, each with a shape, a default and a requiredness, is exactly the kind of
+ * prose that drifts silently from the code it describes. The declarations
+ * (`fields` on each `itemBuilders` entry) already *are* that table, so the page
+ * is rendered from them rather than transcribed (#22).
+ *
+ * **It ships here, not in the consumer.** Any repository can define an item
+ * type of its own, so "what frontmatter does this type accept?" is a question
+ * every consuming repository has. Rendering from the resolved configuration
+ * means each one documents *its own* registry with the same command, rather
+ * than SoHL owning a generator the others cannot run.
+ *
+ * Package-agnostic: it knows the declaration vocabulary, and nothing about any
+ * particular type. The types themselves come from configuration.
+ *
+ * @module
+ */
+
+import { authoredFields } from "./field-spec.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+
+/**
+ * Render a value the way an author would write it in YAML frontmatter.
+ *
+ * @param {any} value - The default a field declares.
+ * @returns {string} An inline-code cell, or an em dash when there is no
+ *   default to show.
+ */
+function renderDefault(value) {
+    if (value === undefined) return "—";
+    if (value === null) return "`null`";
+    if (typeof value === "string")
+        return value === "" ? '`""`' : `\`${value}\``;
+    if (Array.isArray(value))
+        return value.length === 0 ? "`[]`" : `\`${JSON.stringify(value)}\``;
+    if (typeof value === "object") {
+        const json = JSON.stringify(value);
+        return json === "{}" ? "`{}`" : `\`${json}\``;
+    }
+    return `\`${String(value)}\``;
+}
+
+/** Escape the pipe that would otherwise end a markdown table cell. */
+function cell(text) {
+    return String(text).replace(/\|/g, "\\|");
+}
+
+/**
+ * A markdown table with every column padded to its widest cell.
+ *
+ * **Padded so the generated page is stable under Prettier.** A consumer commits
+ * this page and formats its repository; Prettier aligns markdown table columns,
+ * so an unpadded table is rewritten the moment the formatter runs — and the
+ * `--check` guard then reports the page stale on every clean checkout, with the
+ * formatter and the generator each undoing the other.
+ *
+ * Plain `.length` rather than a display-width measure, because that is what
+ * Prettier's alignment comes to for this content: every cell is Latin text,
+ * backticks and the odd em dash, each of which counts one. A cell holding a
+ * wide character would need the measure Prettier uses; there are none, and
+ * `tests/field-reference.test.ts` fails if the rendered page ever stops
+ * agreeing with Prettier.
+ *
+ * @param {string[][]} rows - The header row, then the body.
+ * @returns {string[]} Markdown lines.
+ */
+function padTable(rows) {
+    const widths = rows[0].map((_, column) =>
+        Math.max(...rows.map((row) => row[column].length)),
+    );
+    const line = (cells) =>
+        `| ${cells.map((c, i) => c.padEnd(widths[i])).join(" | ")} |`;
+    const [header, ...body] = rows;
+    return [
+        line(header),
+        `| ${widths.map((w) => "-".repeat(w)).join(" | ")} |`,
+        ...body.map(line),
+    ];
+}
+
+/**
+ * The field table for one type.
+ *
+ * @param {readonly object[]} fields - The type's declaration.
+ * @returns {string[]} Markdown lines.
+ */
+function fieldTable(fields) {
+    const authored = authoredFields(fields);
+    if (!authored.length) {
+        return ["This type reads no `sohl:` fields of its own."];
+    }
+    const rows = [
+        ["Field", "Shape", "Required", "Default", "Description"],
+        ...authored.map((field) => [
+            `\`${field.name}\``,
+            cell(field.shape ?? "as authored"),
+            field.required ? "**yes**" : "no",
+            field.required ? "—" : renderDefault(field.default),
+            cell(field.describe ?? ""),
+        ]),
+    ];
+    return padTable(rows);
+}
+
+/**
+ * A minimal note for one type: the frontmatter envelope every note carries,
+ * plus exactly the `sohl:` fields the type requires.
+ *
+ * Minimal is the point — an example carrying every optional field would teach
+ * that they are expected, and would itself need maintaining. What is shown is
+ * the smallest note that compiles.
+ *
+ * @param {string} type - The item type.
+ * @param {readonly object[]} fields - Its declaration.
+ * @returns {string[]} Markdown lines, a fenced YAML block.
+ */
+function workedExample(type, fields) {
+    const required = authoredFields(fields).filter((field) => field.required);
+    const lines = [
+        // `markdown`, not `yaml`: the block is a whole note — frontmatter *and*
+        // the prose beneath it — so labelling it YAML was wrong about the
+        // content. It also made the page unstable, because Prettier formats a
+        // fenced block in the language it declares, and reformatting this one as
+        // YAML dropped the blank line after the frontmatter.
+        "```markdown",
+        "---",
+        "name:",
+        `  full: An Example ${type}`,
+        `type: ${type}`,
+        "shortcode: xmpl",
+        "package: <your content package>",
+        "id: <16-character id>",
+        "sohl:",
+        "  archetype: null",
+    ];
+    for (const field of required) {
+        lines.push(`  ${field.name}: <${field.shape ?? "value"}>`);
+    }
+    lines.push(
+        "---",
+        "",
+        "The prose here compiles into the item's documentation.",
+        "```",
+    );
+    return lines;
+}
+
+/**
+ * Render the per-type item frontmatter reference.
+ *
+ * @param {object} [options] - Rendering options.
+ * @param {string} [options.title] - The page's H1.
+ * @param {string[]} [options.preamble] - Lines placed after the H1, before the
+ *   first type. Written by the consumer, since only it knows what its page
+ *   should link to.
+ * @param {string} [options.generatedBy] - What a reader should re-run to
+ *   regenerate the page, named in the do-not-edit banner.
+ * @param {object} [options.config] - Resolved configuration. Defaults to the
+ *   consumer's own.
+ * @returns {string} The complete markdown page.
+ */
+export function renderItemFieldReference({
+    title = "Item Note Frontmatter",
+    preamble = [],
+    generatedBy = "the content-build field reference generator",
+    config = loadPackConfig(),
+} = {}) {
+    const declared = config.itemFields ?? {};
+    const types = [...config.itemTypes].sort();
+    const documented = types.filter((type) => declared[type]?.length);
+    const undocumented = types.filter((type) => !declared[type]?.length);
+
+    const lines = [
+        `# ${title}`,
+        "",
+        `<!-- AUTO-GENERATED FILE — do not edit by hand.`,
+        `     Generated by ${generatedBy}.`,
+        `     Every field comes from the \`fields\` declaration on that type's`,
+        `     \`itemBuilders\` entry, which is also what builds the document. -->`,
+        "",
+        ...preamble,
+    ];
+    if (preamble.length) lines.push("");
+
+    lines.push(
+        `${documented.length} of the ${types.length} item types this ` +
+            `repository compiles declare their frontmatter below. Every field ` +
+            `is written under a note's \`sohl:\` block; a dotted name such as ` +
+            `\`impact.die\` is a nested key. A field a note does not carry ` +
+            `takes the default shown, and a **required** field has none — ` +
+            `omitting it fails the build rather than guessing.`,
+        "",
+    );
+
+    for (const type of documented) {
+        lines.push(
+            `## ${type}`,
+            "",
+            ...fieldTable(declared[type]),
+            "",
+            ...workedExample(type, declared[type]),
+            "",
+        );
+    }
+
+    if (undocumented.length) {
+        lines.push(
+            "## Types that declare no fields",
+            "",
+            "These compile, but their `itemBuilders` entry declares no " +
+                "`fields`, so nothing here can say what they accept:",
+            "",
+            ...undocumented.map((type) => `- \`${type}\``),
+            "",
+        );
+    }
+
+    // Trailing blank lines trimmed, so a caller adding its own newline gets
+    // exactly one. Sections push a separating "" after themselves, which leaves
+    // one at the end; Prettier strips it, and a page that disagrees with the
+    // formatter by one character is rewritten on the consumer's next format run
+    // and then reported stale by `--check` forever after.
+    return lines.join("\n").replace(/\n+$/, "");
+}