@heroiclands/package-build 22.4.2 → 22.4.3

package/engine/changelog-group.mjs

@@ -0,0 +1,256 @@
+/*
+ * 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
+ */
+
+/**
+ * Fold a release's changeset blocks together by their bold label.
+ *
+ * `@heroiclands/package-build/changelog` (`changelog.cjs`) writes each
+ * changeset's summary into `CHANGELOG.md` as its own block, verbatim, under
+ * `### <Bump> Changes` — one per changeset, in whatever order Changesets
+ * happened to read the files. A repository that groups its release prose by
+ * subject (`**Compendiums**`, `**Website**`) ends up with the same label
+ * opening several scattered blocks instead of one, because nothing ever
+ * merges them: three pull requests touching compendium content each write
+ * their own `**Compendiums**` block, and the release reads as three
+ * unrelated entries rather than one.
+ *
+ * `groupChangelogText` merges same-label blocks into one, in the display
+ * order `changelog.labels` declares, with the unlabelled lead paragraph
+ * first and any label absent from that vocabulary last. It reuses
+ * {@link module:engine/changelog-lint.topLevelBlocks} — the same block
+ * model `changelog check` reads a block's label from — rather than parsing
+ * the markdown a second way.
+ *
+ * @module
+ */
+
+import {
+    codeLineSet,
+    lineColOf,
+    releaseSectionRange,
+    topLevelBlocks,
+    topLevelBullets,
+} from "./changelog-lint.mjs";
+
+/** A `### <Bump> Changes` heading — the generated scaffold, never authored. */
+const CHANGES_HEADING_RE = /^### (?:Major|Minor|Patch) Changes$/gm;
+
+/**
+ * A labelled block's own `**Label**` line, split from everything after it.
+ *
+ * @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}} `rest` has its leading blank
+ *   line dropped; a block with nothing but the label line yields `""`.
+ */
+function splitLabelLine(blockText) {
+    const nl = blockText.indexOf("\n");
+    if (nl === -1) return { labelLine: blockText, rest: "" };
+    return { labelLine: blockText.slice(0, nl), rest: blockText.slice(nl + 1).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.
+ *
+ * @param {string} text - A block's content, label line already stripped (or
+ *   a lead block's whole text).
+ * @returns {string[]}
+ */
+function itemsOf(text) {
+    const trimmed = text.replace(/\s+$/, "");
+    if (!trimmed) return [];
+    const bullets = topLevelBullets(trimmed, codeLineSet(trimmed));
+    if (bullets.length === 0) return [trimmed];
+    return bullets.map((bullet) => bullet.text.replace(/\s+$/, ""));
+}
+
+/**
+ * The first occurrence of each item, exact-duplicate text dropped, order
+ * preserved — the "an exact-duplicate bullet once" rule.
+ *
+ * @param {string[]} items
+ * @returns {string[]}
+ */
+function dedupeItems(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const key = item.trim();
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push(item);
+    }
+    return out;
+}
+
+/**
+ * Join a merged group's items the way its own shape calls for: bullets
+ * adjacent, one to a line; a paragraph or a mix of paragraphs separated by a
+ * blank line, the same spacing a changeset's own multi-paragraph summary
+ * already uses.
+ *
+ * @param {string[]} items
+ * @returns {string}
+ */
+function joinItems(items) {
+    if (items.length === 0) return "";
+    const allBullets = items.every((item) => /^-\s/.test(item));
+    return items.join(allBullets ? "\n" : "\n\n");
+}
+
+/**
+ * One label's blocks (or every unlabelled one), folded into the single
+ * block `group` writes for it.
+ *
+ * @param {Array<{label: string|null, text: string}>} blocks - Every block
+ *   sharing one label, in file order. All carry the same `label`.
+ * @returns {string}
+ */
+function mergeGroup(blocks) {
+    if (blocks[0].label === null) {
+        return joinItems(dedupeItems(blocks.flatMap((block) => itemsOf(block.text))));
+    }
+    const { labelLine } = splitLabelLine(blocks[0].text);
+    const items = dedupeItems(blocks.flatMap((block) => itemsOf(splitLabelLine(block.text).rest)));
+    return items.length ? `${labelLine}\n\n${joinItems(items)}` : labelLine;
+}
+
+/**
+ * Where a group sorts, relative to the others in its section.
+ *
+ * The unlabelled lead group always sorts first, whether or not
+ * `changelog.labels` is declared — it is the summary a changeset writes with
+ * no category, and reads like the section's own opening line. A declared
+ * vocabulary then orders everything else by its position in that list, with
+ * an undeclared label sorted after every declared one; with no vocabulary
+ * declared at all, every labelled group keeps the order its label first
+ * appeared in.
+ *
+ * @param {string|null} key - A group's label, or `null` for the lead group.
+ * @param {string[]} appearanceOrder - Every key, in the order its first
+ *   block appeared in the section.
+ * @param {readonly string[]|null} labels - `changelog.labels`, or `null`.
+ * @returns {[number, number]} `[tier, rank]`, compared tier first.
+ */
+function groupRank(key, appearanceOrder, labels) {
+    if (key === null) return [-1, 0];
+    if (labels) {
+        const configured = labels.indexOf(key);
+        return configured === -1 ? [1, appearanceOrder.indexOf(key)] : [0, configured];
+    }
+    return [0, appearanceOrder.indexOf(key)];
+}
+
+/**
+ * Fold one `### <Bump> Changes` section's blocks together by label.
+ *
+ * @param {string} bodyText - Everything after the heading, up to the next
+ *   one or the end of the release section.
+ * @param {readonly string[]|null} labels - `changelog.labels`, in display
+ *   order, or `null` when the repository declares none.
+ * @returns {{text: string, unknown: Array<{label: string, startLine: number}>}}
+ *   The regrouped body (no leading or trailing blank lines), and every label
+ *   it wrote that `labels` does not declare, each at its merged block's
+ *   first-occurring line within `bodyText` — empty when `labels` is `null`,
+ *   since nothing is "unknown" against no vocabulary.
+ */
+function groupSection(bodyText, labels) {
+    const codeLines = codeLineSet(bodyText);
+    const blocks = topLevelBlocks(bodyText, codeLines);
+    if (blocks.length === 0) return { text: "", unknown: [] };
+
+    /** @type {string[]} */
+    const appearanceOrder = [];
+    /** @type {Map<string|null, Array<{label: string|null, text: string}>>} */
+    const groups = new Map();
+    for (const block of blocks) {
+        if (!groups.has(block.label)) {
+            groups.set(block.label, []);
+            appearanceOrder.push(block.label);
+        }
+        groups.get(block.label).push(block);
+    }
+
+    const sortedKeys = [...appearanceOrder].sort((a, b) => {
+        const [aTier, aRank] = groupRank(a, appearanceOrder, labels);
+        const [bTier, bRank] = groupRank(b, appearanceOrder, labels);
+        return aTier - bTier || aRank - bRank;
+    });
+
+    const unknown =
+        labels === null ?
+            []
+        :   sortedKeys
+                .filter((key) => key !== null && !labels.includes(key))
+                .map((key) => ({ label: key, startLine: groups.get(key)[0].startLine }));
+
+    const text = sortedKeys.map((key) => mergeGroup(groups.get(key))).join("\n\n");
+    return { text, unknown };
+}
+
+/**
+ * `changelog group`: fold the newest release's changeset blocks together by
+ * their bold label, order them, and file an undeclared one last.
+ *
+ * Every earlier release section is untouched, byte for byte — only the
+ * first `## <version>` section's `### <Bump> Changes` bodies are rewritten,
+ * each independently (a label groups within its own bump level, never
+ * across one). Running this on its own output is a no-op: a release already
+ * in label order, with each label merged to one block, groups to itself.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order. `null`/absent orders every group by first appearance
+ *   instead, lead paragraph first, and files nothing as unknown.
+ * @returns {{text: string, findings: Array<{line: number,
+ *   severity: "warning", message: string}>}}
+ */
+export function groupChangelogText(text, { labels = null } = {}) {
+    const range = releaseSectionRange(text);
+    if (!range) return { text, findings: [] };
+
+    const section = text.slice(range.start, range.end);
+    const headings = [...section.matchAll(CHANGES_HEADING_RE)];
+    if (headings.length === 0) return { text, findings: [] };
+
+    let rebuilt = section.slice(0, headings[0].index);
+    /** @type {Array<{line: number, severity: "warning", message: string}>} */
+    const findings = [];
+
+    for (let i = 0; i < headings.length; i++) {
+        const heading = headings[i];
+        const bodyStart = heading.index + heading[0].length;
+        const bodyEnd = i + 1 < headings.length ? headings[i + 1].index : section.length;
+        const { text: grouped, unknown } = groupSection(section.slice(bodyStart, bodyEnd), labels);
+
+        const isVeryLast = i === headings.length - 1 && range.end === text.length;
+        rebuilt += heading[0] + (grouped ? `\n\n${grouped}` : "") + (isVeryLast ? "\n" : "\n\n");
+
+        const { line: bodyFirstLine } = lineColOf(text, range.start + bodyStart);
+        for (const { label, startLine } of unknown) {
+            findings.push({
+                line: bodyFirstLine + (startLine - 1),
+                severity: "warning",
+                message:
+                    `changelog-group/unknown-label "${label}" is not declared in ` +
+                    "`changelog.labels` — filed last, in order of first appearance",
+            });
+        }
+    }
+
+    return { text: text.slice(0, range.start) + rebuilt + text.slice(range.end), findings };
+}

package/engine/changelog-lint.mjs

@@ -49,6 +49,9 @@ const TOP_BULLET_RE = /^-\s+/;
 /** A list item indented under something else. */
 const NESTED_BULLET_RE = /^[ \t]+[-*+]\s+/;
 
+/** A bold label opening a block at column 0: `**Compendiums**`. */
+const LABEL_LINE_RE = /^\*\*([^*]+)\*\*/;
+
 /** A commit-hash prefix: `- abc1234: …`, or a bare hex token opening the bullet. */
 const COMMIT_HASH_RE = /^-\s+([0-9a-fA-F]{7,40})(?=[:\s]|$)/;
 
@@ -92,7 +95,7 @@ const MAX_SECTION_LINES = 60;
  * @param {number} index - 0-based character offset.
  * @returns {{line: number, column: number}}
  */
-function lineColOf(text, index) {
+export function lineColOf(text, index) {
     const before = text.slice(0, Math.max(0, index));
     const nl = before.lastIndexOf("\n");
     return { line: before.split("\n").length, column: index - nl };
@@ -108,7 +111,7 @@ function lineColOf(text, index) {
  * @param {string} text - The section text.
  * @returns {Set<number>} Lines that fall inside a fenced or indented block.
  */
-function codeLineSet(text) {
+export function codeLineSet(text) {
     const lines = new Set();
     for (const region of codeRegions(text, { spans: false })) {
         const from = lineColOf(text, region.start).line;
@@ -185,7 +188,7 @@ function checkCodeFences(text) {
  *   {@link codeLineSet}.
  * @returns {Array<{startLine: number, text: string}>}
  */
-function topLevelBullets(text, codeLines) {
+export function topLevelBullets(text, codeLines) {
     const lines = text.split("\n");
     /** @type {Array<{startLine: number, text: string}>} */
     const bullets = [];
@@ -211,13 +214,93 @@ function topLevelBullets(text, codeLines) {
             continue;
         }
         // Column 0, not a bullet: a bold subsection label or a scaffold
-        // heading closes whatever bullet was open.
+        // heading closes whatever bullet was open — pushed here, or it is
+        // lost rather than merely closed.
+        if (current) bullets.push({ startLine: current.startLine, text: current.parts.join("\n") });
         current = null;
     }
     if (current) bullets.push({ startLine: current.startLine, text: current.parts.join("\n") });
     return bullets;
 }
 
+/**
+ * Every top-level block of release prose — one rendered changeset entry, or
+ * one unlabelled paragraph standing in for one.
+ *
+ * `@heroiclands/package-build/changelog` (`changelog.cjs`) writes a
+ * changeset's whole summary as one block, verbatim, so a block here holds
+ * together the same way that summary is authored: a bold label opening a
+ * line at column 0 (`**Compendiums**`) starts a new block, and — unlike
+ * {@link topLevelBullets}, where a bullet marker *is* the top-level
+ * construct — a `-` bullet at column 0 belongs to whatever block is
+ * already open, since a label's bullets sit unindented directly under it.
+ * Any other column-0 line (plain prose with no label, a bullet with no
+ * block open yet) starts the one "lead" block (`label: null`) a changeset
+ * with no category writes — the case `changelog group` sorts first and
+ * `check` never flags. Nested detail — a wrapped line, a bullet's own
+ * continuation — stays indented and belongs to whatever it follows.
+ * `changelog group` folds same-label blocks together; `check` warns when a
+ * block's label is not in the declared vocabulary.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines - Lines inside a code region, from
+ *   {@link codeLineSet}.
+ * @param {Set<number>} [scaffoldLines] - Generated heading lines that close
+ *   whatever block is open without starting one, from
+ *   {@link scaffoldLineSet} — empty for a caller that already isolated one
+ *   `### <Bump> Changes` body, since no heading falls inside it.
+ * @returns {Array<{startLine: number, label: string|null, text: string}>}
+ */
+export function topLevelBlocks(text, codeLines, scaffoldLines = new Set()) {
+    const lines = text.split("\n");
+    /** @type {Array<{startLine: number, label: string|null, text: string}>} */
+    const blocks = [];
+    /** @type {{startLine: number, label: string|null, parts: string[]}|null} */
+    let current = null;
+    const close = () => {
+        if (current)
+            blocks.push({
+                startLine: current.startLine,
+                label: current.label,
+                text: current.parts.join("\n"),
+            });
+        current = null;
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        const raw = lines[i];
+
+        if (codeLines.has(lineNo)) {
+            if (current) current.parts.push(raw);
+            continue;
+        }
+        if (scaffoldLines.has(lineNo)) {
+            close();
+            continue;
+        }
+        const atColumnZero = raw.trim() !== "" && !/^[ \t]/.test(raw);
+        if (!atColumnZero) {
+            if (current) current.parts.push(raw);
+            continue;
+        }
+        const label = LABEL_LINE_RE.exec(raw)?.[1] ?? null;
+        if (label !== null) {
+            close();
+            current = { startLine: lineNo, label, parts: [raw] };
+            continue;
+        }
+        if (TOP_BULLET_RE.test(raw) && current) {
+            current.parts.push(raw);
+            continue;
+        }
+        close();
+        current = { startLine: lineNo, label: null, parts: [raw] };
+    }
+    close();
+    return blocks;
+}
+
 /**
  * A bullet's word count, the bullet marker and markdown decoration stripped.
  *
@@ -502,6 +585,41 @@ function checkCodeLikeTokens(text, maskedRegions) {
     return findings;
 }
 
+/**
+ * A block's bold label absent from the declared `changelog.labels`
+ * vocabulary — the drift `**Character data**` beside `**Characters**`
+ * produces, invisible until something reads the declared list against what a
+ * changeset actually wrote. A warning, not an error: an undeclared label
+ * still ships and still groups (`changelog group` files it last), so nothing
+ * here blocks a release — it only says the vocabulary and the prose have
+ * drifted apart.
+ *
+ * @param {Array<{startLine: number, label: string|null}>} blocks - From
+ *   {@link topLevelBlocks}.
+ * @param {readonly string[]|null|undefined} labels - `changelog.labels`, or
+ *   `null`/`undefined` when the repository declares none, in which case
+ *   nothing is checked — there is no vocabulary for a label to drift from.
+ * @returns {RelativeFinding[]}
+ */
+function checkUnknownLabels(blocks, labels) {
+    if (!labels) return [];
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (const block of blocks) {
+        if (block.label === null || labels.includes(block.label)) continue;
+        findings.push({
+            line: block.startLine,
+            column: 3, // right after the opening `**`
+            severity: "warning",
+            message:
+                `changelog-check/unknown-label "${block.label}" is not declared in ` +
+                "`changelog.labels` (declared: " +
+                `${labels.join(", ")}) — add it there, or correct the label`,
+        });
+    }
+    return findings;
+}
+
 /**
  * The 1-based lines a caller drops from the heading rule because they are the
  * generated scaffold, never authored prose: the section's own `## <version>`
@@ -524,13 +642,17 @@ function scaffoldLineSet(text) {
  * Run every rule over one section of release prose.
  *
  * @param {string} text - The section, already isolated by the caller.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, for
+ *   {@link checkUnknownLabels}. `null`/absent checks nothing.
  * @returns {RelativeFinding[]} Findings with line numbers relative to `text`.
  */
-function lintSection(text) {
+function lintSection(text, { labels = null } = {}) {
     const codeLines = codeLineSet(text);
     const maskedRegions = codeRegions(text, { spans: true });
     const scaffoldLines = scaffoldLineSet(text);
     const bullets = topLevelBullets(text, codeLines);
+    const blocks = topLevelBlocks(text, codeLines, scaffoldLines);
 
     return [
         ...checkCommitHash(text, codeLines, scaffoldLines),
@@ -544,6 +666,7 @@ function lintSection(text) {
         ...checkTooManyBullets(bullets),
         ...checkTooManyLines(text),
         ...checkCodeLikeTokens(text, maskedRegions),
+        ...checkUnknownLabels(blocks, labels),
     ].sort((a, b) => a.line - b.line || (a.column ?? 0) - (b.column ?? 0));
 }
 
@@ -593,12 +716,19 @@ function extractReleaseSection(text) {
  * Lint one pending changeset (`.changeset/*.md`).
  *
  * @param {string} text - The file's full contents, frontmatter included.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order, or `null`/absent when the repository declares none —
+ *   {@link checkUnknownLabels} checks nothing in that case.
  * @returns {{findings: Array<{line: number, column?: number,
  *   severity: "error"|"warning", message: string}>}}
  */
-export function lintChangesetText(text) {
+export function lintChangesetText(text, { labels = null } = {}) {
     const { body, startLine } = stripFrontmatter(text);
-    const findings = lintSection(body).map((f) => ({ ...f, line: f.line + startLine - 1 }));
+    const findings = lintSection(body, { labels }).map((f) => ({
+        ...f,
+        line: f.line + startLine - 1,
+    }));
     return { findings };
 }
 
@@ -606,10 +736,14 @@ export function lintChangesetText(text) {
  * Lint the first `## <version>` release section of a `CHANGELOG.md`.
  *
  * @param {string} text - The changelog's full contents.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order, or `null`/absent when the repository declares none —
+ *   {@link checkUnknownLabels} checks nothing in that case.
  * @returns {{findings: Array<{line?: number, column?: number,
  *   severity: "error"|"warning", message: string}>}}
  */
-export function lintReleaseText(text) {
+export function lintReleaseText(text, { labels = null } = {}) {
     const section = extractReleaseSection(text);
     if (!section) {
         return {
@@ -621,9 +755,34 @@ export function lintReleaseText(text) {
             ],
         };
     }
-    const findings = lintSection(section.body).map((f) => ({
+    const findings = lintSection(section.body, { labels }).map((f) => ({
         ...f,
         line: f.line + section.startLine - 1,
     }));
     return { findings };
 }
+
+/**
+ * The first `## <version>` release section of a changelog, as raw character
+ * offsets rather than {@link extractReleaseSection}'s line-joined copy.
+ *
+ * `extractReleaseSection` rebuilds its `body` by joining a slice of
+ * `text.split("\n")`, which is fine for reporting a line number but drops
+ * the exact byte the next `## ` heading sits after — a caller rewriting the
+ * file in place, such as `changelog group`, needs `text.slice(start, end)`
+ * to be the section verbatim, so it can splice a replacement back in without
+ * guessing at the whitespace on either side.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @returns {{start: number, end: number}|null} `null` when no `## ` heading
+ *   is present. `text.slice(start, end)` is the section, byte-exact,
+ *   including whatever separates it from the next `## ` heading or the end
+ *   of the file.
+ */
+export function releaseSectionRange(text) {
+    const matches = [...text.matchAll(/^## /gm)];
+    if (matches.length === 0) return null;
+    const start = matches[0].index;
+    const end = matches.length > 1 ? matches[1].index : text.length;
+    return { start, end };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.2",
+    "version": "22.4.3",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -91,6 +91,7 @@
             "types": "./types/templates.d.mts",
             "import": "./templates.mjs"
         },
+        "./changelog": "./changelog.cjs",
         "./package.json": "./package.json"
     },
     "bin": {
@@ -106,6 +107,7 @@
         "packagebuild-metadata.jsonl",
         "bin",
         "bundle.mjs",
+        "changelog.cjs",
         "ci",
         "config.mjs",
         "container.mjs",
@@ -177,8 +179,7 @@
         "lint:content-format:schema": "node bin/content-build.mjs content-format schema --schema sohl=tests/fixtures/content-format/schema-sohl.json --schema hm3=tests/fixtures/content-format/schema-hm3.json",
         "lint:content-format:fields": "node bin/content-build.mjs content-format fields --fields sohl && node bin/content-build.mjs content-format fields --fields hm3",
         "changeset": "changeset",
-        "changeset:check": "changeset status --since=origin/main",
-        "changeset:version": "changeset version && npm install --package-lock-only",
+        "changeset:version": "changeset version && node bin/package-build.mjs changelog group && npm install --package-lock-only",
         "prepare": "git config core.hooksPath .githooks || true"
     },
     "engines": {

package/types/engine/changelog-group.d.mts

@@ -0,0 +1,28 @@
+/**
+ * `changelog group`: fold the newest release's changeset blocks together by
+ * their bold label, order them, and file an undeclared one last.
+ *
+ * Every earlier release section is untouched, byte for byte — only the
+ * first `## <version>` section's `### <Bump> Changes` bodies are rewritten,
+ * each independently (a label groups within its own bump level, never
+ * across one). Running this on its own output is a no-op: a release already
+ * in label order, with each label merged to one block, groups to itself.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order. `null`/absent orders every group by first appearance
+ *   instead, lead paragraph first, and files nothing as unknown.
+ * @returns {{text: string, findings: Array<{line: number,
+ *   severity: "warning", message: string}>}}
+ */
+export function groupChangelogText(text: string, { labels }?: {
+    labels?: readonly string[] | null | undefined;
+}): {
+    text: string;
+    findings: Array<{
+        line: number;
+        severity: "warning";
+        message: string;
+    }>;
+};