@heroiclands/package-build 23.9.0 → 23.11.0

package/engine/changelog-group.mjs

@@ -46,33 +46,37 @@ import {
 const CHANGES_HEADING_RE = /^### (?:Major|Minor|Patch) Changes$/gm;
 
 /**
- * A labelled block's own `**Label**` line, split from everything after it.
+ * A label, its complete opening paragraph and its remaining items.
  *
  * @param {string} blockText - One block, as {@link topLevelBlocks} collects
  *   it — its first line is the label line for a labelled block.
- * @returns {{labelLine: string, rest: string, hadBlankLine: boolean}} `rest`
- *   has its leading blank line dropped; a block with nothing but the label
- *   line yields `""`. `hadBlankLine` says whether the label line was
- *   followed by a blank line in `blockText` — false for a bold sentence a
- *   hard-wrapped paragraph continues directly beneath, with no blank line
- *   of its own.
+ * @returns {{labelLine: string, introduction: string, rest: string}} The
+ *   introduction retains hard wrapping and stops before a bullet or code.
  */
-function splitLabelLine(blockText) {
-    const nl = blockText.indexOf("\n");
-    if (nl === -1) return { labelLine: blockText, rest: "", hadBlankLine: false };
-    const after = blockText.slice(nl + 1);
+function splitLabelBlock(blockText) {
+    const lines = blockText.replace(/\s+$/, "").split("\n");
+    const labelLine = /^\*\*[^*]+\*\*/.exec(lines[0])[0];
+    const inline = lines[0].slice(labelLine.length).trimStart();
+    const introduction = inline ? [inline] : [];
+    const codeLines = codeLineSet(blockText);
+    let cursor = 1;
+    while (
+        cursor < lines.length &&
+        lines[cursor].trim() !== "" &&
+        !/^-\s/.test(lines[cursor]) &&
+        !codeLines.has(cursor + 1)
+    )
+        introduction.push(lines[cursor++]);
     return {
-        labelLine: blockText.slice(0, nl),
-        rest: after.replace(/^\n+/, ""),
-        hadBlankLine: after.startsWith("\n"),
+        labelLine,
+        introduction: introduction.join("\n"),
+        rest: lines.slice(cursor).join("\n").replace(/^\n+/, ""),
     };
 }
 
 /**
- * A block's top-level items: its bullets, or — when it carries none — the
- * whole thing as one paragraph item. This is what merging concatenates and
- * deduplicates, so a bulleted `**Compendiums**` block and a prose one merge
- * on the same footing.
+ * A block's top-level bullets and the prose or code between them, in source
+ * order. A bullet retains its indented continuation and nested items.
  *
  * @param {string} text - A block's content, label line already stripped (or
  *   a lead block's whole text).
@@ -83,7 +87,26 @@ function itemsOf(text) {
     if (!trimmed) return [];
     const bullets = topLevelBullets(trimmed, codeLineSet(trimmed));
     if (bullets.length === 0) return [trimmed];
-    return bullets.map((bullet) => bullet.text.replace(/\s+$/, ""));
+    const starts = [];
+    let offset = 0;
+    for (const line of trimmed.split("\n")) {
+        starts.push(offset);
+        offset += line.length + 1;
+    }
+    const items = [];
+    const append = (part) => {
+        const item = part.replace(/^(?:[ \t]*\n)+/, "").replace(/\s+$/, "");
+        if (item) items.push(item);
+    };
+    let cursor = 0;
+    for (const bullet of bullets) {
+        const start = starts[bullet.startLine - 1];
+        append(trimmed.slice(cursor, start));
+        append(bullet.text);
+        cursor = start + bullet.text.length;
+    }
+    append(trimmed.slice(cursor));
+    return items;
 }
 
 /**
@@ -124,13 +147,9 @@ function joinItems(items) {
  * One label's blocks (or every unlabelled one), folded into the single
  * block `group` writes for it.
  *
- * A single, unmerged block — the common case, one changeset writing one
- * label once — keeps its own label-to-body separator rather than forcing a
- * blank line: a bold sentence a hard-wrapped paragraph continues directly
- * beneath must round-trip unchanged, not gain a blank line it never had.
- * Merging two or more blocks, or a label whose lone block carries several
- * items (bullets), still separates the label from its body with a blank
- * line — the convention every existing multi-item block already uses.
+ * A single block with no duplicate items retains its own spacing. Merged
+ * opening paragraphs form one hard-wrapped introduction before the items,
+ * so paragraph boundaries cannot turn labelled text into unlabelled lead.
  *
  * @param {Array<{label: string|null, text: string}>} blocks - Every block
  *   sharing one label, in file order. All carry the same `label`.
@@ -140,13 +159,15 @@ function mergeGroup(blocks) {
     if (blocks[0].label === null) {
         return joinItems(dedupeItems(blocks.flatMap((block) => itemsOf(block.text))));
     }
-    const { labelLine, hadBlankLine } = splitLabelLine(blocks[0].text);
-    const items = dedupeItems(blocks.flatMap((block) => itemsOf(splitLabelLine(block.text).rest)));
-    if (items.length === 0) return labelLine;
-    if (blocks.length === 1 && items.length === 1) {
-        return `${labelLine}${hadBlankLine ? "\n\n" : "\n"}${items[0]}`;
-    }
-    return `${labelLine}\n\n${joinItems(items)}`;
+    const parts = blocks.map((block) => splitLabelBlock(block.text));
+    const introductions = dedupeItems(parts.map((part) => part.introduction).filter(Boolean));
+    const originalItems = parts.flatMap((part) => itemsOf(part.rest));
+    const items = dedupeItems(originalItems);
+    if (blocks.length === 1 && items.length === originalItems.length)
+        return blocks[0].text.replace(/\s+$/, "");
+    const heading =
+        parts[0].labelLine + (introductions.length ? ` ${introductions.join("\n")}` : "");
+    return heading + (items.length ? `\n\n${joinItems(items)}` : "");
 }
 
 /**
@@ -245,7 +266,10 @@ export function groupChangelogText(text, { labels = null } = {}) {
     if (!range) return { text, findings: [] };
 
     const section = text.slice(range.start, range.end);
-    const headings = [...section.matchAll(CHANGES_HEADING_RE)];
+    const codeLines = codeLineSet(section);
+    const headings = [...section.matchAll(CHANGES_HEADING_RE)].filter(
+        (heading) => !codeLines.has(lineColOf(section, heading.index).line),
+    );
     if (headings.length === 0) return { text, findings: [] };
 
     let rebuilt = section.slice(0, headings[0].index);

package/engine/changelog-lint.mjs

@@ -277,7 +277,8 @@ export function topLevelBlocks(text, codeLines, scaffoldLines = new Set()) {
         const raw = lines[i];
 
         if (codeLines.has(lineNo)) {
-            if (current) current.parts.push(raw);
+            current ??= { startLine: lineNo, label: null, parts: [] };
+            current.parts.push(raw);
             afterBlank = raw.trim() === "";
             continue;
         }
@@ -800,7 +801,10 @@ export function lintReleaseText(text, { labels = null } = {}) {
  *   of the file.
  */
 export function releaseSectionRange(text) {
-    const matches = [...text.matchAll(/^## /gm)];
+    const codeLines = codeLineSet(text);
+    const matches = [...text.matchAll(/^## /gm)].filter(
+        (heading) => !codeLines.has(lineColOf(text, heading.index).line),
+    );
     if (matches.length === 0) return null;
     const start = matches[0].index;
     const end = matches.length > 1 ? matches[1].index : text.length;

package/engine/compendiums.mjs

@@ -70,6 +70,8 @@ import { loadPackConfig } from "./pack-config.mjs";
  * @param {string} [opts.stageDest]      Directory the LevelDB packs are built
  *     into, one subdirectory per pack. Defaults to the configured stage.
  * @param {string} [opts.packName]       Restrict the run to a single pack.
+ * @param {import("./content-session.mjs").ContentSession} [opts.session] - Captured context shared with other operations.
+ * @param {boolean} [opts.reportPreparation=true] - Emit shared preparation findings unless the caller already reported them.
  * @throws {Error} If pack JSON generation reported any error. Packs compiled
  *     from incomplete or empty JSON ship blank or short compendiums, and the
  *     omission is invisible until a player looks for content that is not there
@@ -86,7 +88,14 @@ export async function compilePacks({
     sourcePacks = config.packDirectories,
     stageDest = config.paths.stage,
     packName,
+    session,
+    reportPreparation = true,
 } = {}) {
+    session?.assertContext({
+        config,
+        contentBase: config.paths.content,
+        skipDirectories: config.skipDirectories,
+    });
     const packNames = sourcePacks.filter((name) => !packName || name === packName);
 
     // A prebuilt pack's JSON is checked in rather than generated, so it is
@@ -105,7 +114,12 @@ export async function compilePacks({
     // content tree, and a package that ships only prebuilt packs has none at
     // all — so running it would fail the build over a tree nothing reads.
     if (needsGeneration) {
-        const errors = await generatePacksJson({ only: packName, config });
+        const errors = await generatePacksJson({
+            only: packName,
+            config,
+            session,
+            reportPreparation,
+        });
         if (errors > 0) {
             throw new Error(
                 `Pack JSON generation reported ${errors} error(s); refusing to ` +

package/engine/compile-corpus.mjs

@@ -60,7 +60,8 @@ 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[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
+ * @param {import("./content-session.mjs").ContentSession} [opts.session] - Captured context shared with other operations.
+ * @returns {Promise<{records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[], syntax?: import("./content-session.mjs").ContentSyntax}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
 export async function buildCompileCorpus({
@@ -70,8 +71,20 @@ export async function buildCompileCorpus({
     router,
     config,
     problems,
+    session,
 }) {
     const resolved = config ?? loadPackConfig();
+    if (session) {
+        session.assertContext({
+            config: resolved,
+            contentBase,
+            assetsBase,
+            skipDirectories,
+            router,
+        });
+        if (problems && problems !== session.problems) problems.push(...session.problems);
+        return session.compileCorpus();
+    }
     const collected = problems ?? [];
     const parsed = new Map();
     const records = indexRecordsFor({

package/engine/content-charset.mjs

@@ -85,6 +85,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { capturedSources } from "./content-sources.mjs";
 
 /**
  * Tier 1 — the letters, and the two whitespace characters a file is made of.
@@ -407,16 +408,27 @@ export function checkText(text, file) {
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
  *   in addition to the dot-directories always skipped.
  * @param {readonly string[]} [opts.extensions] - File extensions to read.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} The findings, and how
  *   many files produced them.
  */
-export function lintContentCharset(contentBase, { skipDirectories = [], extensions } = {}) {
+export function lintContentCharset(
+    contentBase,
+    { skipDirectories = [], extensions, sources } = {},
+) {
     const exts = new Set(extensions ?? [".md", ".markdown", ".yaml", ".yml", ".json"]);
     const skip = new Set(skipDirectories);
     /** @type {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} */
     const findings = [];
     let files = 0;
+    if (sources) {
+        for (const [full, text] of capturedSources(contentBase, sources, skipDirectories, exts)) {
+            files++;
+            findings.push(...checkText(text, path.relative(process.cwd(), full)));
+        }
+        return { findings, files };
+    }
 
     /** @param {string} dir - Directory to descend into. */
     const walk = (dir) => {

package/engine/content-html.mjs

@@ -52,9 +52,10 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { capturedSources } from "./content-sources.mjs";
 
 import { matchAllOutsideCode } from "./code-fences.mjs";
-import { positionInBody } from "./diagnostics.mjs";
+import { positionInBody, splitFrontmatter } from "./diagnostics.mjs";
 
 /**
  * A raw HTML tag, opening, closing or self-closing.
@@ -133,15 +134,28 @@ export function checkHtml(body, file, { bodyLine = 1, bodyColumn = 1 } = {}) {
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
  *   in addition to the dot-directories always skipped.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} The findings, and
  *   how many files were read.
  */
-export function lintContentHtml(contentBase, { skipDirectories = [] } = {}) {
+export function lintContentHtml(contentBase, { skipDirectories = [], sources } = {}) {
     const skip = new Set(skipDirectories);
     /** @type {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} */
     const findings = [];
     let files = 0;
+    if (sources) {
+        for (const [full, content] of capturedSources(
+            contentBase,
+            sources,
+            skipDirectories,
+            new Set([".md", ".markdown"]),
+        )) {
+            files++;
+            findings.push(...checkHtml(...bodyOf(content, path.relative(process.cwd(), full))));
+        }
+        return { findings, files };
+    }
 
     /** @param {string} dir - Directory to descend into. */
     const walk = (dir) => {
@@ -188,10 +202,10 @@ export function lintContentHtml(contentBase, { skipDirectories = [] } = {}) {
  *   arguments {@link checkHtml} takes.
  */
 function bodyOf(content, file) {
-    const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    const match = splitFrontmatter(content);
     if (!match) return [content, file, { bodyLine: 1, bodyColumn: 1 }];
 
-    const raw = match[2];
+    const raw = match.body;
     const body = raw.trim();
     const bodyStart = content.length - raw.length + (raw.length - raw.trimStart().length);
     const before = content.slice(0, bodyStart);

package/engine/content-icons.mjs

@@ -27,6 +27,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { capturedSources } from "./content-sources.mjs";
 import { parseExtensionAttributes } from "./extension-attributes.mjs";
 
 /**
@@ -524,13 +525,26 @@ export function checkIconRegistry(registry, where = "icons") {
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
  * @param {IconRegistry} [opts.registry] - The package's registry.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} What it found.
  */
-export function lintContentIcons(contentBase, { skipDirectories = [], registry } = {}) {
+export function lintContentIcons(contentBase, { skipDirectories = [], registry, sources } = {}) {
     const skip = new Set(skipDirectories);
     const findings = [];
     let files = 0;
+    if (sources) {
+        for (const [full, text] of capturedSources(
+            contentBase,
+            sources,
+            skipDirectories,
+            new Set([".md", ".markdown"]),
+        )) {
+            files++;
+            findings.push(...lintIcons(text, path.relative(process.cwd(), full), registry));
+        }
+        return { findings, files };
+    }
 
     /** @param {string} dir - Directory to descend into. */
     const walk = (dir) => {

package/engine/content-images.mjs

@@ -80,10 +80,11 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { capturedSources } from "./content-sources.mjs";
 
 import { matchAllOutsideCode } from "./code-fences.mjs";
 import { parseExtensionAttributes } from "./extension-attributes.mjs";
-import { positionInBody } from "./diagnostics.mjs";
+import { positionInBody, splitFrontmatter } from "./diagnostics.mjs";
 import { FOOTNOTE_REFERENCE } from "./content-footnotes.mjs";
 import { foundryAddressProblem, pathnameProblem, servesFoundry } from "./pathnames.mjs";
 import { ASSET_ROLES } from "./asset-index.mjs";
@@ -431,16 +432,20 @@ export function standsAlone(text, start, end) {
     const lineEnd = src.indexOf("\n", end);
     const afterMatch = src.slice(end, lineEnd === -1 ? src.length : lineEnd);
     const reference = TRAILING_FOOTNOTE_REFERENCE.exec(afterMatch);
-    if (!/^[ \t]*$/.test(reference ? afterMatch.slice(reference[0].length) : afterMatch))
+    if (!/^[ \t]*\r?$/.test(reference ? afterMatch.slice(reference[0].length) : afterMatch))
         return false;
 
     const before = src.slice(0, lineStart);
-    const previous = before.replace(/\n$/, "").split("\n").pop() ?? "";
-    if (before.trim() && !/\n[ \t]*\n[ \t]*$/.test(before) && !DELIMITER.test(previous))
+    const previous =
+        before
+            .replace(/\r?\n$/, "")
+            .split(/\r?\n/)
+            .pop() ?? "";
+    if (before.trim() && !/\n[ \t]*\r?\n[ \t]*$/.test(before) && !DELIMITER.test(previous))
         return false;
     const after = lineEnd === -1 ? "" : src.slice(lineEnd);
-    const next = after.replace(/^\n/, "").split("\n")[0] ?? "";
-    if (after.trim() && !/^\n[ \t]*\n/.test(after) && !DELIMITER.test(next)) return false;
+    const next = after.replace(/^\n/, "").split(/\r?\n/)[0] ?? "";
+    if (after.trim() && !/^\n[ \t]*\r?\n/.test(after) && !DELIMITER.test(next)) return false;
     return true;
 }
 
@@ -586,10 +591,10 @@ export function checkImages(
  *   arguments {@link checkImages} takes.
  */
 function bodyOf(content, file) {
-    const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    const match = splitFrontmatter(content);
     if (!match) return [content, file, { bodyLine: 1, bodyColumn: 1 }];
 
-    const raw = match[2];
+    const raw = match.body;
     const body = raw.trim();
     const bodyStart = content.length - raw.length + (raw.length - raw.trimStart().length);
     const before = content.slice(0, bodyStart);
@@ -619,15 +624,29 @@ function bodyOf(content, file) {
  *   in addition to the dot-directories always skipped.
  * @param {object} [opts.config] - The resolved build configuration, passed to
  *   {@link checkImages} so an address is held to the Foundry surface too.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number|undefined,
  *   severity: "error", message: string}>, files: number}} The findings, and how
  *   many files were read.
  */
-export function lintContentImages(contentBase, { skipDirectories = [], config } = {}) {
+export function lintContentImages(contentBase, { skipDirectories = [], config, sources } = {}) {
     const skip = new Set(skipDirectories);
     /** @type {Array<{file: string, line: number, column: number|undefined, severity: "error", message: string}>} */
     const findings = [];
     let files = 0;
+    if (sources) {
+        for (const [full, content] of capturedSources(
+            contentBase,
+            sources,
+            skipDirectories,
+            new Set([".md", ".markdown"]),
+        )) {
+            files++;
+            const [body, rel, at] = bodyOf(content, path.relative(process.cwd(), full));
+            findings.push(...checkImages(body, rel, { ...at, config }));
+        }
+        return { findings, files };
+    }
 
     /** @param {string} dir - Directory to descend into. */
     const walk = (dir) => {