@heroiclands/package-build 25.1.3 → 25.2.0

package/docs/reference/note-types.md

@@ -15,18 +15,18 @@ The [first-note guide](../authoring/first-note.md) teaches the shape of a note.
 
 These are the only keys a note writes at its top level, in the order the formatter puts them. A key absent from this table is a lint error at its own line: the region is closed, so the key reaches no document and no page. Facts about the subject belong under `data`, and values for one game system belong inside that system's block.
 
-| Key           | Meaning                                                                                   |
-| ------------- | ----------------------------------------------------------------------------------------- |
-| `shortcode`   | The note's own address segment, unique within its type.                                   |
-| `name`        | The display names — a required `full`, and any `aliases` and `sort`.                      |
-| `type`        | What the note is about, which decides its vocabulary and its document.                    |
-| `subType`     | The type's own genre, where it declares one.                                              |
-| `description` | The short page summary.                                                                   |
-| `tags`        | Draft state, GM routing, and the descriptive labels a page list reads.                    |
-| `data`        | The facts about the subject itself, shared by every system.                               |
-| `dnd5e`       | What the `dnd5e` system makes of the subject — its document's mechanics, routing and art. |
-| `hm3`         | What the `hm3` system makes of the subject — its document's mechanics, routing and art.   |
-| `sohl`        | What the `sohl` system makes of the subject — its document's mechanics, routing and art.  |
+| Key           | Meaning                                                                                                                            |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `shortcode`   | The note's own address segment, unique within its type.                                                                            |
+| `name`        | The display names — a required `full`, the English name; the other names, listed under the code of their language; and any `sort`. |
+| `type`        | What the note is about, which decides its vocabulary and its document.                                                             |
+| `subType`     | The type's own genre, where it declares one.                                                                                       |
+| `description` | The short page summary.                                                                                                            |
+| `tags`        | Draft state, GM routing, and the descriptive labels a page list reads.                                                             |
+| `data`        | The facts about the subject itself, shared by every system.                                                                        |
+| `dnd5e`       | What the `dnd5e` system makes of the subject — its document's mechanics, routing and art.                                          |
+| `hm3`         | What the `hm3` system makes of the subject — its document's mechanics, routing and art.                                            |
+| `sohl`        | What the `sohl` system makes of the subject — its document's mechanics, routing and art.                                           |
 
 ## Shared `data` fields
 
@@ -34,6 +34,7 @@ These fields are accepted by every note type. A field's value can still be irrel
 
 | Field             | Shape                                           | Meaning                                                                                                                                                                                    |
 | ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `data.lang`       | a language code `languages:` declares, or `en`  | The language the note is in. Absent, the content index derives it: the note's culture's language, then its `data.parents`' nearest first, then `en`.                                       |
 | `data.seeAlso`    | list of `{ address, gloss? }`                   | Deliberate cross-references in reading order, with optional glosses; shown on the site, in journals and in books.                                                                          |
 | `data.calendar`   | an Address                                      | The calendar this note's dates print in, as a calendar lore note. Absent, the note takes its culture's calendar, then — for a place — its parents', then the configured `defaultCalendar`. |
 | `data.id`         | string                                          | A fixed document identity when the derived identity is unsuitable.                                                                                                                         |
@@ -139,7 +140,6 @@ These fields are accepted by every note type. A field's value can still be irrel
 | `data.lore`               | list of Addresses                                                               | Lore concerning it — the peoples it draws on, the god a faith venerates, its law, its calendar.                                                                                                                                                                                                                                                                                    |
 | `data.parents`            | list of Addresses                                                               | Affiliations it is subordinate to.                                                                                                                                                                                                                                                                                                                                                 |
 | `data.culture`            | an Address                                                                      | The people this affiliation belongs to, as a culture lore note.                                                                                                                                                                                                                                                                                                                    |
-| `data.language`           | an Address                                                                      | The trade, temple or order tongue the affiliation keeps, as a language skill note. A glossary entry that states no `language` is in it. The affiliation chooses its own common vocabulary and context meanings.                                                                                                                                                                    |
 | `data.glossary`           | list of `{ name, name_sort?, common?, definition?, pronunciation?, language? }` | Its own glossary entries: common vocabulary, dictionary words with a contextual meaning, and phrases, compounds or terms of art. A named dictionary word supplies its senses and class unless `definition` supplies the sense. Common marks belong to this owner. Every entry resolves to a language. Empty when unstated. See [glossary terms](format-details.md#glossary-terms). |
 | `data.relations`          | a map keyed by Address                                                          | Standing with other affiliations — aligned, unaligned, rival, nemesis.                                                                                                                                                                                                                                                                                                             |
 
@@ -200,7 +200,7 @@ These fields are accepted by every note type. A field's value can still be irrel
 | `data.glossary[].common`                             | `true` or `false`                                                                     | no       | Core vocabulary for this glossary's owner; `false` when unstated.                                                                                                                           |
 | `data.glossary[].definition`                         | a string                                                                              | no       | The sense text, overriding the word's or governance sources' senses. Unstated, a named dictionary word supplies all its senses and class; a named rank or office supplies its descriptions. |
 | `data.glossary[].pronunciation`                      | a respelling such as `sol-MEH-reh`                                                    | no       | A respelling, held to the same rule as a word's; the dictionary word's when unstated.                                                                                                       |
-| `data.glossary[].language`                           | a language skill Address                                                              | no       | The language the term is in. Unstated, it is the affiliation's language, its parents', or its culture's, or the culture's own.                                                              |
+| `data.glossary[].language`                           | a language skill Address                                                              | no       | The language the term is in. Unstated, it is the note of the language the note is in, its `data.lang` as the content index derives it.                                                      |
 
 **System mappings**
 
@@ -791,11 +791,10 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 | `data.namedDays`         | list of `{ name, abbreviation?, day }`                                              | Names assigned to particular days of the year.                                                                                                                                                                                                                                                                                                                                                     |
 | `data.eras`              | list of `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, label? }` | The year-counts kept in this calendar. A marker names one era and uses these months.                                                                                                                                                                                                                                                                                                               |
 | `data.formats`           | map of named Calendaria format strings                                              | Named patterns for reading and writing this calendar's dates.                                                                                                                                                                                                                                                                                                                                      |
-| `data.parents`           | list of Addresses                                                                   | Culture only: parent culture lore notes, searched in listed depth-first order for omitted language and appearance profile fields.                                                                                                                                                                                                                                                                  |
+| `data.parents`           | list of Addresses                                                                   | Culture only: parent culture lore notes, searched in listed depth-first order for an omitted appearance profile, and nearest first for an omitted `data.lang`.                                                                                                                                                                                                                                     |
 | `data.culture`           | an Address                                                                          | The people this lore belongs to — for a work of literature, the people whose work it is — as a culture lore note. A culture note is its own culture, and states the field only as itself.                                                                                                                                                                                                          |
 | `data.form`              | string                                                                              | The kind of work in its people's own terms — an epic, a saga, a praise-song, an elegy. Free text.                                                                                                                                                                                                                                                                                                  |
 | `data.subjects`          | list of Addresses                                                                   | The beings, places, gods and other notes the work concerns, and each event it concerns, named as `place-ironfells#sack`.                                                                                                                                                                                                                                                                           |
-| `data.language`          | an Address                                                                          | The tongue the note is in, as a language skill note: the tongue a work is composed in, a culture's people speak, or an affiliation keeps as its trade, temple or order tongue. `package-build npc new` draws a culture's names from its language's `data.names`. A `literature` or `culture` lore note, or an affiliation, only.                                                                   |
 | `data.events`            | list of event entries                                                               | What happened to or at this subject — each entry one dated, attributed event: a founding, a war, a fall, or an occasion that recurs.                                                                                                                                                                                                                                                               |
 | `data.appearanceProfile` | an appearance profile                                                               | What this culture's people look like, for `package-build npc new`: `frame`, `eye_color`, `hair_color`, `skin_color` and `complexion` each map words of that field's vocabulary to positive weights, and `height` maps a gender to a `{min, max}` range, `female` and `male` required. A culture note only. See [appearance profiles](format-details.md#appearance-profiles).                       |
 | `data.glossary`          | list of `{ name, name_sort?, common?, definition?, pronunciation?, language? }`     | `culture` only: Its own glossary entries: common vocabulary, dictionary words with a contextual meaning, and phrases, compounds or terms of art. A named dictionary word supplies its senses and class unless `definition` supplies the sense. Common marks belong to this owner. Every entry resolves to a language. Empty when unstated. See [glossary terms](format-details.md#glossary-terms). |
@@ -875,7 +874,7 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 | `data.glossary[].common`                   | `true` or `false`                                                                                                | no       | Core vocabulary for this glossary's owner; `false` when unstated.                                                                                                                           |
 | `data.glossary[].definition`               | a string                                                                                                         | no       | The sense text, overriding the word's or governance sources' senses. Unstated, a named dictionary word supplies all its senses and class; a named rank or office supplies its descriptions. |
 | `data.glossary[].pronunciation`            | a respelling such as `sol-MEH-reh`                                                                               | no       | A respelling, held to the same rule as a word's; the dictionary word's when unstated.                                                                                                       |
-| `data.glossary[].language`                 | a language skill Address                                                                                         | no       | The language the term is in. Unstated, it is the affiliation's language, its parents', or its culture's, or the culture's own.                                                              |
+| `data.glossary[].language`                 | a language skill Address                                                                                         | no       | The language the term is in. Unstated, it is the note of the language the note is in, its `data.lang` as the content index derives it.                                                      |
 
 ### map
 

package/engine/changelog-group.mjs

@@ -12,29 +12,28 @@
  */
 
 /**
- * Fold a release's changeset blocks together by their bold label.
+ * Turn Changesets' output for the newest release into its final shape.
  *
  * `@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.
+ * changeset's summary into `CHANGELOG.md` verbatim, under a
+ * `### Major Changes`, `### Minor Changes` or `### Patch Changes` heading,
+ * one block per changeset in whatever order Changesets read the files. A
+ * release is read by subject, not by bump, so `groupChangelogText` removes
+ * every one of those headings, merges the blocks that share a label into one,
+ * and orders the labels as the changelog `labels` declares them. A label the list
+ * does not declare follows the declared ones, in order of first appearance,
+ * and `Miscellaneous`, which every repository has without declaring it, is
+ * always last.
+ *
+ * It reuses {@link module:engine/changelog-lint.topLevelBlocks}, the block
+ * model `changelog check` reads a block's label from, rather than parsing the
+ * markdown a second way.
  *
  * @module
  */
 
 import {
+    MISCELLANEOUS,
     codeLineSet,
     lineColOf,
     releaseSectionRange,
@@ -43,43 +42,13 @@ import {
 } from "./changelog-lint.mjs";
 
 /** A `### <Bump> Changes` heading — the generated scaffold, never authored. */
-const CHANGES_HEADING_RE = /^### (?:Major|Minor|Patch) Changes$/gm;
-
-/**
- * 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, introduction: string, rest: string}} The
- *   introduction retains hard wrapping and stops before a bullet or code.
- */
-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,
-        introduction: introduction.join("\n"),
-        rest: lines.slice(cursor).join("\n").replace(/^\n+/, ""),
-    };
-}
+const CHANGES_HEADING_RE = /^### (?:Major|Minor|Patch) Changes\s*$/;
 
 /**
  * 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).
+ * @param {string} text - A block's content, label line already stripped.
  * @returns {string[]}
  */
 function itemsOf(text) {
@@ -111,7 +80,7 @@ function itemsOf(text) {
 
 /**
  * The first occurrence of each item, exact-duplicate text dropped, order
- * preserved — the "an exact-duplicate bullet once" rule.
+ * preserved.
  *
  * @param {string[]} items
  * @returns {string[]}
@@ -129,66 +98,43 @@ function dedupeItems(items) {
 }
 
 /**
- * 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 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.
+ * One label's blocks, folded into the single block `group` writes for it:
+ * the label line, a blank line, then every bullet in file order. Bullets are
+ * adjacent; any other item is separated by a blank line.
  *
  * @param {Array<{label: string|null, text: string}>} blocks - Every block
- *   sharing one label, in file order. All carry the same `label`.
+ *   sharing one label, in file order.
  * @returns {string}
  */
 function mergeGroup(blocks) {
-    if (blocks[0].label === null) {
-        return joinItems(dedupeItems(blocks.flatMap((block) => itemsOf(block.text))));
-    }
-    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)}` : "");
+    const labelled = blocks[0].label !== null;
+    const items = dedupeItems(
+        blocks.flatMap((block) => {
+            if (!labelled) return itemsOf(block.text);
+            const [, ...rest] = block.text.replace(/\s+$/, "").split("\n");
+            return itemsOf(rest.join("\n"));
+        }),
+    );
+    const joined = items.join(items.every((item) => /^-\s/.test(item)) ? "\n" : "\n\n");
+    if (!labelled) return joined;
+    const labelLine = blocks[0].text.split("\n")[0].trimEnd();
+    return joined ? `${labelLine}\n\n${joined}` : 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`.
+ * Where a group sorts in its release: an unlabelled block first, then the
+ * declared labels in their declared order, then any other label in order of
+ * first appearance, and `Miscellaneous` last. With no vocabulary declared,
+ * every label but `Miscellaneous` keeps its order of first appearance.
+ *
+ * @param {string|null} key - A group's label, or `null` for an unlabelled one.
+ * @param {string[]} appearanceOrder - Every key, in order of first appearance.
+ * @param {readonly string[]|null} labels - the changelog `labels`, or `null`.
  * @returns {[number, number]} `[tier, rank]`, compared tier first.
  */
 function groupRank(key, appearanceOrder, labels) {
     if (key === null) return [-1, 0];
+    if (key === MISCELLANEOUS) return [2, 0];
     if (labels) {
         const configured = labels.indexOf(key);
         return configured === -1 ? [1, appearanceOrder.indexOf(key)] : [0, configured];
@@ -197,26 +143,40 @@ function groupRank(key, appearanceOrder, labels) {
 }
 
 /**
- * Fold one `### <Bump> Changes` section's blocks together by label.
+ * `changelog group`: give the newest release its final shape.
+ *
+ * Every earlier release section is untouched, byte for byte. Running this on
+ * its own output is a no-op.
  *
- * @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.
+ * @param {string} text - The changelog's full contents.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - the changelog `labels`, in
+ *   display order. `null`/absent orders by first appearance and reports
+ *   nothing as undeclared.
+ * @returns {{text: string, findings: Array<{line: number,
+ *   severity: "warning", message: string}>}}
  */
-function groupSection(bodyText, labels) {
-    const codeLines = codeLineSet(bodyText);
-    const blocks = topLevelBlocks(bodyText, codeLines);
-    if (blocks.length === 0) return { text: "", unknown: [] };
+export function groupChangelogText(text, { labels = null } = {}) {
+    const range = releaseSectionRange(text);
+    if (!range) return { text, findings: [] };
 
-    /** @type {string[]} */
+    const section = text.slice(range.start, range.end);
+    const headingEnd = section.indexOf("\n");
+    if (headingEnd === -1) return { text, findings: [] };
+    const heading = section.slice(0, headingEnd);
+
+    // The scaffold headings become blank lines, so every line keeps its number.
+    const codeLines = codeLineSet(section.slice(headingEnd + 1));
+    const body = section
+        .slice(headingEnd + 1)
+        .split("\n")
+        .map((line, i) => (!codeLines.has(i + 1) && CHANGES_HEADING_RE.test(line) ? "" : line))
+        .join("\n");
+
+    const blocks = topLevelBlocks(body, codeLines);
+    /** @type {Array<string|null>} */
     const appearanceOrder = [];
-    /** @type {Map<string|null, Array<{label: string|null, text: string}>>} */
+    /** @type {Map<string|null, Array<{startLine: number, label: string|null, text: string}>>} */
     const groups = new Map();
     for (const block of blocks) {
         if (!groups.has(block.label)) {
@@ -225,77 +185,28 @@ function groupSection(bodyText, labels) {
         }
         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 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);
-    /** @type {Array<{line: number, severity: "warning", message: string}>} */
+    const { line: bodyFirstLine } = lineColOf(text, range.start + headingEnd + 1);
     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) {
+    if (labels)
+        for (const key of sortedKeys) {
+            if (key === null || key === MISCELLANEOUS || labels.includes(key)) continue;
             findings.push({
-                line: bodyFirstLine + (startLine - 1),
-                severity: "warning",
+                line: bodyFirstLine + (groups.get(key)[0].startLine - 1),
+                severity: /** @type {const} */ ("warning"),
                 message:
-                    `changelog-group/unknown-label "${label}" is not declared in ` +
-                    "`changelog.labels` — filed last, in order of first appearance",
+                    `changelog-group/unknown-label "${key}" is not declared in ` +
+                    "the changelog `labels` — filed after the declared labels, in order of first appearance",
             });
         }
-    }
 
+    const grouped = sortedKeys.map((key) => mergeGroup(groups.get(key))).join("\n\n");
+    const rebuilt =
+        heading + (grouped ? `\n\n${grouped}` : "") + (range.end === text.length ? "\n" : "\n\n");
     return { text: text.slice(0, range.start) + rebuilt + text.slice(range.end), findings };
 }

package/engine/changelog-labels.mjs

@@ -0,0 +1,73 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The labels a repository's changesets group under.
+ *
+ * They are the options of the changelog entry in `.changeset/config.json`,
+ * beside the generator they configure:
+ *
+ * ```json
+ * "changelog": ["@heroiclands/package-build/changelog", { "labels": ["Verse", "Rendering"] }]
+ * ```
+ *
+ * `changelog check` accepts a label only if it is listed there or is
+ * `Miscellaneous`, which every repository has and never declares.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { MISCELLANEOUS } from "./changelog-lint.mjs";
+
+/**
+ * Read `labels` from the changelog options in `.changeset/config.json`.
+ *
+ * @param {string} [cwd] - The repository root.
+ * @returns {readonly string[]|null} The labels in display order, or `null`
+ *   when the file, the options or `labels` is absent.
+ * @throws {Error} When `config.json` is not JSON, or `labels` is not an array
+ *   of distinct non-empty strings or names `Miscellaneous`.
+ */
+export function readChangelogLabels(cwd = process.cwd()) {
+    const file = path.join(cwd, ".changeset", "config.json");
+    if (!fs.existsSync(file)) return null;
+    const where = path.relative(cwd, file);
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch (error) {
+        throw new Error(`${where}: is not valid JSON (${error.message})`);
+    }
+    const entry = config?.changelog;
+    const options = Array.isArray(entry) ? entry[1] : undefined;
+    if (options === undefined || options === null) return null;
+    if (typeof options !== "object" || Array.isArray(options))
+        throw new Error(`${where}: the changelog options must be an object`);
+    if (options.labels === undefined) return null;
+    const { labels } = options;
+    const bad = (problem) => new Error(`${where}: changelog \`labels\` ${problem}`);
+    if (!Array.isArray(labels)) throw bad("must be an array of strings");
+    const seen = new Set();
+    for (const label of labels) {
+        if (typeof label !== "string" || label.trim() === "")
+            throw bad("must hold only non-empty strings");
+        if (label === MISCELLANEOUS)
+            throw bad(`declares \`${MISCELLANEOUS}\`, which is always available and always last`);
+        if (seen.has(label)) throw bad(`declares \`${label}\` more than once`);
+        seen.add(label);
+    }
+    return Object.freeze([...labels]);
+}