@heroiclands/package-build 22.4.2 → 22.4.4

package/docs/project-setup.md

@@ -82,12 +82,13 @@ carries no hook files of its own and cannot drift from the others. `|| true` so
 that an install outside a git checkout — a Docker build, a CI cache step —
 does not fail on it.
 
-Three hooks arrive with it, each with its own switch, read with git's normal
+Four hooks arrive with it, each with its own switch, read with git's normal
 precedence: a plain `git config` sets one clone, `--global` sets a machine.
 
 | Hook                             | What it does                                                    | Key                                  | Default |
 | -------------------------------- | --------------------------------------------------------------- | ------------------------------------ | ------- |
 | `pre-commit`, `pre-merge-commit` | Refuse a commit on a protected branch.                          | `hooks.allowCommitOnMain` (inverted) | on      |
+| `pre-commit`                     | Lint any `.changeset/*.md` the commit stages.                   | `hooks.changelogCheck`               | on      |
 | `commit-msg`                     | Refuse AI attribution in a commit message.                      | `hooks.noAttribution`                | on      |
 | `pre-push`                       | Run this repository's own Build & Test workflow in a container. | `hooks.prePushCi`                    | off     |
 
@@ -130,19 +131,20 @@ anything to remove.
 
 ### `lint:*` — the checks, one per question
 
-Six checks, each answering one question and blind to what the others see. They
-are separate scripts rather than one because a failing chain stops at its first
-failure, and knowing _which_ question failed is most of the diagnosis.
+Seven checks, each answering one question and blind to what the others see.
+They are separate scripts rather than one because a failing chain stops at its
+first failure, and knowing _which_ question failed is most of the diagnosis.
 
 ```json
-"lint": "run-s lint:format lint:markdown lint:addresses lint:content-links lint:lang lint:labels",
+"lint": "run-s lint:format lint:markdown lint:addresses lint:content-links lint:lang lint:labels lint:changelog",
 "lint:format": "content-build format",
 "lint:markdown": "content-build markdown",
 "lint:markdown:fix": "content-build markdown --fix",
 "lint:addresses": "content-build lint",
 "lint:content-links": "content-build links",
 "lint:lang": "package-build lang check",
-"lint:labels": "package-build labels check"
+"lint:labels": "package-build labels check",
+"lint:changelog": "package-build changelog check"
 ```
 
 - **`lint:format`** — is every file formatted to the shared Prettier options?
@@ -165,6 +167,10 @@ failure, and knowing _which_ question failed is most of the diagnosis.
 - **`lint:labels`** — do `.github/labels.yml` and §3 of
   `.github/ISSUE_REPORTING.md` still list the same labels? Neither derives from
   the other, so nothing else notices when they drift.
+- **`lint:changelog`** — does every pending `.changeset/*.md` read like a
+  release note rather than a pasted pull-request description? Passes
+  trivially when nothing is pending: no pull request is required to carry a
+  changeset, only to write one that reads well when it does.
 
 `run-s` comes from `npm-run-all`, a devDependency. It runs scripts in sequence
 and stops at the first failure, which is what makes a named chain readable.
@@ -227,16 +233,19 @@ reads better with one and a CI workflow reads better with the other.
 
 ```json
 "changeset": "changeset",
-"changeset:check": "changeset status --since=origin/main",
 "changeset:version": "changeset version && npm install --package-lock-only"
 ```
 
-`changeset` adds one. `changeset:check` reports what is pending against `main`,
-which is what a CI job gates on so that a behaviour change cannot merge without
-declaring its bump. `changeset:version` consumes the pending changesets, writes
-`CHANGELOG.md` and bumps `package.json` — and the `npm install --package-lock-only`
-after it is what keeps `package-lock.json`'s recorded version in step, since
-changesets does not touch the lockfile.
+`changeset` adds one, written only when a consumer will notice the change —
+nothing gates a pull request on carrying one. `changeset:version` consumes the
+pending changesets, writes `CHANGELOG.md` and bumps `package.json` — and the
+`npm install --package-lock-only` after it is what keeps `package-lock.json`'s
+recorded version in step, since changesets does not touch the lockfile.
+
+What a pending changeset is held to is quality, not existence: `lint:changelog`
+and the `pre-commit` hook `prepare` installs both run
+`package-build changelog check` against it, in CI and at commit time
+respectively, and both pass trivially when there is none.
 
 ### The site scripts
 

package/engine/changelog-group.mjs

@@ -0,0 +1,277 @@
+/*
+ * 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, 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.
+ */
+function splitLabelLine(blockText) {
+    const nl = blockText.indexOf("\n");
+    if (nl === -1) return { labelLine: blockText, rest: "", hadBlankLine: false };
+    const after = blockText.slice(nl + 1);
+    return {
+        labelLine: blockText.slice(0, nl),
+        rest: after.replace(/^\n+/, ""),
+        hadBlankLine: after.startsWith("\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.
+ *
+ * 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.
+ *
+ * @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, 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)}`;
+}
+
+/**
+ * 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,113 @@ 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.
+ * A plain column-0 line that is neither a label nor a bullet continues
+ * whatever block is open, because Prettier's `proseWrap` puts every line of
+ * a hard-wrapped paragraph at column 0 — it starts a new "lead" block
+ * (`label: null`) only at a paragraph boundary, the start of the section or
+ * a line right after a blank one, which is the case `changelog group`
+ * sorts first and `check` never flags. A blank line never closes a block by
+ * itself; it only ends the run of continuation lines a following column-0
+ * line can attach to. `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;
+    };
+    // A paragraph boundary — the start of the section, or right after a
+    // blank line — is the only place an unlabelled lead block may start.
+    let afterBlank = true;
+
+    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);
+            afterBlank = raw.trim() === "";
+            continue;
+        }
+        if (scaffoldLines.has(lineNo)) {
+            close();
+            afterBlank = true;
+            continue;
+        }
+        const atColumnZero = raw.trim() !== "" && !/^[ \t]/.test(raw);
+        if (!atColumnZero) {
+            if (current) current.parts.push(raw);
+            afterBlank = raw.trim() === "";
+            continue;
+        }
+        const label = LABEL_LINE_RE.exec(raw)?.[1] ?? null;
+        if (label !== null) {
+            close();
+            current = { startLine: lineNo, label, parts: [raw] };
+            afterBlank = false;
+            continue;
+        }
+        if (TOP_BULLET_RE.test(raw) && current) {
+            current.parts.push(raw);
+            afterBlank = false;
+            continue;
+        }
+        // Plain prose at column 0: it continues whatever block is already
+        // open unless it opens a new paragraph — Prettier's `proseWrap`
+        // puts every line of a hard-wrapped paragraph at column 0, so a
+        // continuation line must never be read as a new lead block.
+        if (current && !afterBlank) {
+            current.parts.push(raw);
+            afterBlank = false;
+            continue;
+        }
+        close();
+        current = { startLine: lineNo, label: null, parts: [raw] };
+        afterBlank = false;
+    }
+    close();
+    return blocks;
+}
+
 /**
  * A bullet's word count, the bullet marker and markdown decoration stripped.
  *
@@ -502,6 +605,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 +662,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 +686,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 +736,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 +756,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 +775,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/engine/homepage.mjs

@@ -378,15 +378,23 @@ export function homepageTitle(fm, config) {
  * redirect stub at each one. The field is retired and refused before a
  * build reaches here, which makes this a guard rather than a working path.
  *
+ * `related` is derived like every other page's — what links to the homepage
+ * is a fact about the rest of the tree — so an authored value is dropped and
+ * the caller's block, where it has one, is written in its place.
+ *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
+ * @param {object} [options.related] - The homepage's backlinks and mentions,
+ *   where the site build found either.
  * @returns {object} The frontmatter to write.
  */
-export function homepageFrontmatter(fm, { contentPackage, title }) {
+export function homepageFrontmatter(fm, { contentPackage, title, related }) {
     const data = { ...fm, package: contentPackage, title };
     delete data.aliases;
+    delete data.related;
+    if (related) data.related = related;
     return data;
 }