@heroiclands/package-build 22.4.2 → 22.4.4

package/engine/related-pages.mjs

@@ -0,0 +1,161 @@
+/*
+ * 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
+ */
+
+/**
+ * What links to a page, and what it links to.
+ *
+ * The site build resolves every wikilink through the address index, so by the
+ * time it writes a page it holds the whole link graph. This is the half that
+ * turns the graph into front matter: the `related` block the theme's Related
+ * card reads, on every page, in one shape.
+ *
+ * **A page is identified by its URL.** An address is unique within a package
+ * and a page publishes at exactly one, so the URL is the one key both a
+ * resolved wikilink and a homepage's markdown link can be reduced to — the
+ * link resolver answers with a URL, and a homepage link *is* one. It is also
+ * what makes a `doc<type>-<shortcode>` link a link to the same page as the
+ * `<type>-<shortcode>` form: the site index keys one page under both, and both
+ * answer with one URL.
+ *
+ * **Only a page of this site is an endpoint.** A link into another package
+ * resolves to a URL the build renders but no page it writes, so it appears
+ * on neither side: a backlink can only be counted on a page this build emits,
+ * and listing a foreign mention beside local ones would make the two lists
+ * disagree about what a connection is.
+ *
+ * @module
+ */
+
+import { homepageAddresses } from "./homepage.mjs";
+
+/**
+ * One entry in a `related` list — the page a reader is pointed at.
+ *
+ * @typedef {object} RelatedEntry
+ * @property {string} title The page's published title.
+ * @property {string} url   `<base><slug>/` — the page's address as every href
+ *                          this build renders composes it, never the
+ *                          site-root-relative form the page states for itself.
+ * @property {string} type  The note's `type`, which the theme groups by.
+ */
+
+/**
+ * The `related` block one page publishes.
+ *
+ * @typedef {object} Related
+ * @property {RelatedEntry[]} backlinks Pages that link to this one.
+ * @property {RelatedEntry[]} mentions  Pages this one links to.
+ */
+
+/**
+ * A stable order for a list: by type, then title.
+ *
+ * The theme groups a list by type and reads each group in the order it
+ * arrives, so the order is fixed here rather than left to walk order — which
+ * is content-path order, and would reshuffle a page's card whenever a note was
+ * filed elsewhere.
+ *
+ * @param {RelatedEntry} a
+ * @param {RelatedEntry} b
+ * @returns {number}
+ */
+function byTypeThenTitle(a, b) {
+    return a.type.localeCompare(b.type, "en") || a.title.localeCompare(b.title, "en");
+}
+
+/**
+ * Inverts a link graph into each page's backlinks and mentions.
+ *
+ * An edge is `(source URL, target URL)`, and a URL that is not in `entries` is
+ * not a page of this site, so an edge touching one is dropped. A self-link says
+ * nothing a reader is not already looking at, and a page that links another
+ * three times is connected to it once, so both collapse.
+ *
+ * The result holds only pages with at least one connection, so the caller can
+ * write nothing on a page with none — the theme's silent-disappear convention,
+ * kept at the source rather than papered over with an empty block.
+ *
+ * @param {Iterable<readonly [string, string]>} edges - Every resolved link, as
+ *   the source page's URL and the target page's.
+ * @param {ReadonlyMap<string, RelatedEntry>} entries - Every page of this
+ *   site, keyed by URL.
+ * @returns {Map<string, Related>} URL → the page's `related` block, both lists
+ *   sorted, for every page with at least one entry in either.
+ */
+export function relatedPages(edges, entries) {
+    /** @type {Map<string, {backlinks: Set<string>, mentions: Set<string>}>} */
+    const graph = new Map();
+    const node = (url) => {
+        let found = graph.get(url);
+        if (!found) {
+            found = { backlinks: new Set(), mentions: new Set() };
+            graph.set(url, found);
+        }
+        return found;
+    };
+
+    for (const [source, target] of edges) {
+        if (source === target) continue;
+        if (!entries.has(source) || !entries.has(target)) continue;
+        node(source).mentions.add(target);
+        node(target).backlinks.add(source);
+    }
+
+    const list = (urls) =>
+        [...urls]
+            .map((url) => /** @type {RelatedEntry} */ (entries.get(url)))
+            .sort(byTypeThenTitle);
+
+    const out = new Map();
+    for (const [url, { backlinks, mentions }] of graph) {
+        out.set(url, { backlinks: list(backlinks), mentions: list(mentions) });
+    }
+    return out;
+}
+
+/**
+ * The pages a homepage's body links to, as URLs.
+ *
+ * A homepage is published verbatim — no wikilink on it resolves, and its links
+ * are ordinary markdown the browser resolves against the page's own address,
+ * which is the package root. So its edges are read the same way: each target
+ * resolved against `base`, the way a browser would. A package-relative
+ * `being-x/`, a root-relative `/pkg/being-x/` and a `./being-x/#anchor` all
+ * name the same page; a bare `#anchor` names the homepage itself.
+ *
+ * A link that names a host or a scheme leaves the site, whatever path it
+ * carries, and yields nothing: the site's own pages are addressed without one.
+ *
+ * @param {string} body - The homepage's markdown body.
+ * @param {string} base - Where the package is served — the homepage's own URL.
+ * @returns {string[]} The targets' URLs, in body order, repeats included.
+ */
+export function homepageLinkTargets(body, base) {
+    const out = [];
+    // A placeholder origin, so a relative target resolves the way a browser
+    // resolves it from the homepage. It never reaches the result: only the
+    // path is read, and only when the target stayed on this origin.
+    const origin = "http://site.invalid";
+    for (const { url } of homepageAddresses(body)) {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith("//")) continue;
+        let resolved;
+        try {
+            resolved = new URL(url, `${origin}${base}`);
+        } catch {
+            continue;
+        }
+        if (resolved.origin !== origin) continue;
+        out.push(resolved.pathname);
+    }
+    return out;
+}

package/engine/site-build.mjs

@@ -81,6 +81,7 @@ import {
 } from "./homepage.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { HUGO_CONTENT } from "./site-config.mjs";
+import { homepageLinkTargets, relatedPages } from "./related-pages.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -291,18 +292,30 @@ export function collectHomepages(contentBase, ctx) {
  * states no `url` — the home kind has none to state — and the mount below it
  * holds pages and nothing else, so this is the only `_index.md` in the tree.
  *
+ * **Verbatim, but not unconnected.** The homepage is a page like any other on
+ * both sides of the link graph: a content page reaches it through
+ * `[[homepage-root|Text]]`, and its own markdown links name content pages. So
+ * it carries the same `related` block every content page does — handed in by
+ * the caller, since the graph is read off the content render and homepage-only
+ * mode has none.
+ *
  * @param {string} outRoot - The package's site root — the content mount's
  *   root, `build/hugo/content`, one level above the mount itself.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
+ * @param {object} [options] - Options.
+ * @param {import("./related-pages.mjs").Related} [options.related] - The
+ *   homepage's backlinks and mentions. Absent where nothing connects to it,
+ *   and in homepage-only mode, where no link resolves.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot, pages, config) {
+export function writeHomepages(outRoot, pages, config, { related } = {}) {
     for (const page of pages) {
         const data = homepageFrontmatter(page.fm, {
             contentPackage: config.contentPackage,
             title: homepageTitle(page.fm, config),
+            related,
         });
         const dest = path.join(outRoot, HOMEPAGE_DESTINATION);
         fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -472,6 +485,12 @@ export function tableUniverse(pages) {
  * self-describing and makes sweeping the field out of a content tree
  * output-preserving for a site as it already is for the packs.
  *
+ * **`related` is derived, never authored.** What links to a page is a fact
+ * about every other page, known only once the whole tree has resolved — see
+ * {@link module:engine/related-pages} — so an authored value is dropped the
+ * way `aliases` is, and {@link renderPages} writes the derived block once it
+ * holds the graph.
+ *
  * @param {object} page - The page.
  * @param {object} options
  * @param {(data: object, page: object) => void} [options.decorate] - Called
@@ -486,7 +505,7 @@ export function tableUniverse(pages) {
  * @returns {object} The frontmatter to write.
  */
 export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
-    const { fm, name, slug } = page;
+    const { fm, slug } = page;
     const data = {
         ...fm,
         // Spread after the note's own frontmatter. Guarded because
@@ -500,15 +519,31 @@ export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
         // from the filename.
         slug,
         url: `/${slug}/`,
-        title: fm.title ?? name,
+        title: pageTitle(page),
         kbfolder: page.folder,
     };
     if (decorate) decorate(data, page);
     delete data.aliases;
+    delete data.related;
     if (webSrc && artSrc) resolveArtFields(data, webSrc, artSrc);
     return data;
 }
 
+/**
+ * The title a content page publishes under: an authored `title`, else the
+ * note's name.
+ *
+ * One rule, read by the page's own front matter and by every `related` entry
+ * that names the page, so a card lists a page by exactly the title its heading
+ * shows.
+ *
+ * @param {object} page - The page, from {@link collectContentPages}.
+ * @returns {string} The title.
+ */
+function pageTitle(page) {
+    return page.fm.title ?? page.name;
+}
+
 /**
  * Rewrite a page's artwork addresses into the URLs the website serves.
  *
@@ -585,10 +620,23 @@ export function pageDestination(page) {
  *    touches, so the repository's own rewrite runs before the shared one
  *    rather than replacing it.
  *
+ * **Every page is rendered before any is written.** What links *to* a page is
+ * known only once every other page has resolved, and it is written into the
+ * page's own front matter, so the render is one pass over the tree and the
+ * write is a second — with the link graph read off the first, at the one
+ * point the resolver answers, and inverted once between them. Nothing is
+ * resolved twice.
+ *
  * @param {object[]} pages - Every page.
- * @param {object} options - Everything the render needs.
+ * @param {object} options - Everything the render needs. `homepages` is the
+ *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
+ *   no part in the render and every part in the graph: a content page links
+ *   it by wikilink, and its own markdown links name content pages.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[]}}
+ *   wikiErrors: object[], imageErrors: object[],
+ *   related: Map<string, import("./related-pages.mjs").Related>}} `related`
+ *   is keyed by page URL, and holds the homepage's block beside every content
+ *   page's, so the caller can write it on the page this render does not.
  */
 export function renderPages(pages, options) {
     const {
@@ -602,6 +650,7 @@ export function renderPages(pages, options) {
         sqlTables,
         config,
         records = [],
+        homepages = [],
     } = options;
 
     // The address space the art slots and the body's embeds resolve against:
@@ -616,6 +665,29 @@ export function renderPages(pages, options) {
     const wikiErrors = [];
     const imageErrors = [];
     const byKind = {};
+    // The link graph, as `(source URL, target URL)` — read off each page's
+    // resolution below, and off the homepage's markdown links.
+    /** @type {Array<[string, string]>} */
+    const edges = [];
+    // Every page of this site, as a `related` entry names it.
+    /** @type {Map<string, import("./related-pages.mjs").RelatedEntry>} */
+    const entries = new Map();
+    for (const page of pages) {
+        entries.set(page.url, {
+            title: pageTitle(page),
+            url: page.url,
+            type: String(page.fm.type),
+        });
+    }
+    for (const home of homepages) {
+        entries.set(home.url, { title: home.title, url: home.url, type: String(home.fm.type) });
+        for (const target of homepageLinkTargets(home.body, home.url)) {
+            edges.push([home.url, target]);
+        }
+    }
+    // What each page renders as, held until the graph is whole.
+    /** @type {Array<{page: object, body: string, data: object}>} */
+    const rendered = [];
 
     /**
      * The address the website serves for one authored pathname.
@@ -661,6 +733,8 @@ export function renderPages(pages, options) {
         // The page's path in the tree an author edits, below the content
         // root.
         const src = page.relPath ?? page.base;
+        // Every index entry a link on this page resolved to.
+        const resolved = [];
         const ctx = wikiContext(index, {
             src,
             file: page.file,
@@ -668,6 +742,7 @@ export function renderPages(pages, options) {
             errors: wikiErrors,
             foreignIndex: foreign.index,
             assets: artIndex,
+            resolved,
         });
 
         const webSrc = webAddresses(page.file);
@@ -699,13 +774,26 @@ export function renderPages(pages, options) {
         tableErrors.push(...errors);
 
         const data = pageFrontmatter(page, { decorate, webSrc, artSrc });
+        rendered.push({ page, body: protectCode(body, resolve), data });
+        // A resolved target with no URL is a pack-only package's address:
+        // real, and nowhere on the web, so not an edge.
+        for (const hit of resolved) {
+            if (hit.url) edges.push([page.url, hit.url]);
+        }
+    }
+
+    const related = relatedPages(edges, entries);
+
+    for (const { page, body, data } of rendered) {
+        const block = related.get(page.url);
+        if (block) data.related = block;
         const dest = path.join(outRoot, pageDestination(page));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, matter.stringify(protectCode(body, resolve), data));
+        fs.writeFileSync(dest, matter.stringify(body, data));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
-    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors };
+    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors, related };
 }
 
 /**
@@ -892,11 +980,17 @@ export function buildSite({ config, sqlTables } = {}) {
     // homepage is authored markdown published verbatim, with no table
     // expansion and no link resolution of its own, and routing it through
     // that pipeline would buy it a pass it has no input for.
+    //
+    // It is a node of the link graph all the same: `renderPages` reads its
+    // markdown links for the edges it authors, and the resolver records the
+    // ones that land on it.
     const homepageEntries = homepages.map((page) => ({
         kind: "content",
         fm: page.fm,
+        body: page.body,
         pkg: resolved.contentPackage,
         name: page.fm.name?.full ?? homepageTitle(page.fm, resolved),
+        title: homepageTitle(page.fm, resolved),
         slug: addressSlug(page.fm),
         base: path.basename(page.file),
         url: base,
@@ -926,6 +1020,7 @@ export function buildSite({ config, sqlTables } = {}) {
         index: gates.index,
         foreign: gates.foreign,
         universe: tableUniverse(pages),
+        homepages: homepageEntries,
         pass,
         // What counts as a being is the toolchain's to say, not a consumer's.
         // Asking in a consumer's script is how one came to still be checking
@@ -947,8 +1042,11 @@ export function buildSite({ config, sqlTables } = {}) {
     });
 
     // Last, and outside the mount: the package's front page is not part of the
-    // content tree it introduces.
-    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved);
+    // content tree it introduces. It publishes at `base`, which is where the
+    // graph keys its block.
+    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved, {
+        related: rendered.related.get(base),
+    });
 
     return {
         gates,

package/engine/site-index.mjs

@@ -289,6 +289,9 @@ export function buildSiteIndex(
  *   resolvers that distinguish a foreign hit from a local one.
  * @param {object} [options.assets] - The address space an `![[…]]` embed
  *   resolves against, shaped as every asset resolver reads one.
+ * @param {object[]} [options.resolved] - Collector the resolver appends every
+ *   resolved target's index entry to — the page's outbound edges, read off
+ *   the one pass that resolves them.
  * @returns {object} The resolver context.
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
@@ -299,7 +302,7 @@ export function buildSiteIndex(
  */
 export function wikiContext(
     built,
-    { src, file, type = null, errors, foreignIndex = new Map(), assets },
+    { src, file, type = null, errors, foreignIndex = new Map(), assets, resolved },
 ) {
     return {
         index: built.index,
@@ -321,6 +324,7 @@ export function wikiContext(
         errors,
         src,
         file,
+        resolved,
     };
 }
 

package/engine/web-wikilinks.mjs

@@ -311,9 +311,17 @@ function isPlainMap(value) {
  * {@link module:engine/content-images.renderImageFigures} turns into a figure
  * for the website, and what the book reads its staging list out of.
  *
+ * ## Every hit is recorded, so the page's edges come out of one pass
+ *
+ * A caller that hands in `ctx.resolved` is given every index entry a link on
+ * the page resolved to, in body order, repeats included. That is the link
+ * graph, read at the one point where it exists: the build never has to walk a
+ * page a second time to learn what it links to. Nothing is recorded for a
+ * same-page anchor or for a target that resolved nowhere.
+ *
  * @param {string} body - The markdown body.
  * @param {object} ctx - `{ index, assets, collide, contentTypes,
- *   packages, noIndexPackages, foreign, type, errors, src, file }`.
+ *   packages, noIndexPackages, foreign, type, errors, src, file, resolved }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type;
  *   `noIndexPackages` is every package declared `contentIndex: false`, so a
@@ -322,7 +330,8 @@ function isPlainMap(value) {
  *   is the cross-package manifest index; `assets` is the address space an embed
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
- *   stands in.
+ *   stands in. `resolved`, when supplied, is the array every resolved
+ *   target's index entry is appended to.
  * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body, ctx) {
@@ -425,6 +434,8 @@ export function resolveWebWikilinks(body, ctx) {
                 lookupRead(ctx.foreign, read, ctx.contentPackage)
             :   undefined);
         if (hit) {
+            // The edge, for a caller reading the link graph off this pass.
+            ctx.resolved?.push(hit);
             // An address with an *empty* label has no prose to show (a
             // shortcode is not display text), so the document's **current**
             // name stands in and a rename shows at every citation.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.2",
+    "version": "22.4.4",
     "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;
+    }>;
+};

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

@@ -1,11 +1,91 @@
+/**
+ * Where a character offset in `text` falls, as a 1-based line and column.
+ *
+ * @param {string} text - The text the offset indexes into.
+ * @param {number} index - 0-based character offset.
+ * @returns {{line: number, column: number}}
+ */
+export function lineColOf(text: string, index: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Every code region in `text`, as a set of 1-based line numbers it spans.
+ *
+ * Block-level only (`spans: false`): an inline code span does not remove a
+ * whole line from consideration, only the characters it covers, which the
+ * text-scanning rules mask separately.
+ *
+ * @param {string} text - The section text.
+ * @returns {Set<number>} Lines that fall inside a fenced or indented block.
+ */
+export function codeLineSet(text: string): Set<number>;
+/**
+ * Every top-level bullet, as its own contiguous run of lines.
+ *
+ * A bullet's continuation — a wrapped line, a second paragraph, a nested
+ * elaboration — is indented under it and belongs to it; a line back at
+ * column 0 that is not itself a bullet (a bold subsection label, ordinary
+ * prose) closes it.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines - Lines inside a code region, from
+ *   {@link codeLineSet}.
+ * @returns {Array<{startLine: number, text: string}>}
+ */
+export function topLevelBullets(text: string, codeLines: Set<number>): Array<{
+    startLine: number;
+    text: string;
+}>;
+/**
+ * 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: string, codeLines: Set<number>, scaffoldLines?: Set<number>): Array<{
+    startLine: number;
+    label: string | null;
+    text: string;
+}>;
 /**
  * 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: string): {
+export function lintChangesetText(text: string, { labels }?: {
+    labels?: readonly string[] | null | undefined;
+}): {
     findings: Array<{
         line: number;
         column?: number;
@@ -17,10 +97,16 @@ export function lintChangesetText(text: string): {
  * 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: string): {
+export function lintReleaseText(text: string, { labels }?: {
+    labels?: readonly string[] | null | undefined;
+}): {
     findings: Array<{
         line?: number;
         column?: number;
@@ -28,6 +114,27 @@ export function lintReleaseText(text: string): {
         message: string;
     }>;
 };
+/**
+ * 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: string): {
+    start: number;
+    end: number;
+} | null;
 /**
  * The finding one rule reports, before its line is mapped into the caller's
  * file.