@heroiclands/package-build 22.4.1 → 22.4.3

package/package.json

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

package/types/engine/actor-compiler.d.mts

@@ -280,6 +280,26 @@ export class SystemActorCompiler extends BasePackCompiler {
      *   subtype, or why the reference names none.
      */
     embeddedSubtype(type: string): import("./document-subtypes.mjs").ReferencedSubtype;
+    /**
+     * The default art for an embedded item's type, when the entry names none
+     * of its own and copies no template that carries one.
+     *
+     * **The base case is {@link itemArt}**, keyed by the note vocabulary — the
+     * same table an item note's own compile defaults from, because most
+     * references are written in that vocabulary too (`weapongear`, `skill`,
+     * `armorgear`). It is not the whole answer: a reference into a one-to-many
+     * row may instead name one of the row's own **subtypes** directly — HM3's
+     * `spell`, `invocation` and `psionic` are never a note's own `type`, only
+     * `mysticalability`'s `hm3.type` discriminator ever writes them, so no
+     * note-type table has a row for them. A system whose one-to-many rows are
+     * addressed that way overrides this to answer for those subtypes too; see
+     * `hm3/actors.mjs`.
+     *
+     * @param {string} type - The **note** type the reference names.
+     * @param {string} subType - The document subtype it resolved to.
+     * @returns {string} The default image path.
+     */
+    embeddedItemArt(type: string, subType: string): string;
     /**
      * Read an entry's `model:` — the address of the item it is a copy of.
      *

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,89 @@
+/**
+ * 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.
+ * Any other column-0 line (plain prose with no label, a bullet with no
+ * block open yet) starts the one "lead" block (`label: null`) a changeset
+ * with no category writes — the case `changelog group` sorts first and
+ * `check` never flags. Nested detail — a wrapped line, a bullet's own
+ * continuation — stays indented and belongs to whatever it follows.
+ * `changelog group` folds same-label blocks together; `check` warns when a
+ * block's label is not in the declared vocabulary.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines - Lines inside a code region, from
+ *   {@link codeLineSet}.
+ * @param {Set<number>} [scaffoldLines] - Generated heading lines that close
+ *   whatever block is open without starting one, from
+ *   {@link scaffoldLineSet} — empty for a caller that already isolated one
+ *   `### <Bump> Changes` body, since no heading falls inside it.
+ * @returns {Array<{startLine: number, label: string|null, text: string}>}
+ */
+export function topLevelBlocks(text: 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 +95,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 +112,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.

package/types/engine/document-subtypes.d.mts

@@ -140,7 +140,7 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  * dependency catalogue actually carry, and a reference is translated forward
  * here before it is looked up.
  *
- * Four answers, and only the first resolves:
+ * Five answers, and only the last refuses:
  *
  * - _A one-to-one row_ → the subtype it declares. `armor` addresses an
  *   `armorgear`.
@@ -151,12 +151,19 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  *   existed.
  * - _A row for another document class_ → a problem. A being is not an item,
  *   however the address is spelled.
- * - _A one-to-many row_ → a problem naming the candidates. The note that owns
- *   such a row resolves it from its own frontmatter block; a reference has no
- *   block, so nothing here can choose, and choosing anyway would be right about
- *   half the time. No system declares a one-to-many **Item** row today, so this
- *   is a guard rather than a behaviour — but it is a loud one, which is the
- *   whole point of the issue.
+ * - _A one-to-many row, named by one of its own permitted subtypes_ → that
+ *   subtype. HM3's `weapongear` row is keyed by the note type `weapongear` but
+ *   permits `["weapongear", "missilegear"]`; a reference spelled `weapongear`
+ *   is not ambiguous — it already names the subtype it wants, the same as a
+ *   reference spelled `missilegear` does by matching no row at all and taking
+ *   the unmapped fallback above. Only the row's own key can coincide with one
+ *   of its subtypes, so this is never a second guess at the note's
+ *   frontmatter — the row was looked up by this exact spelling.
+ * - _A one-to-many row, named by neither the row's other permitted subtypes
+ *   nor resolved above_ → a problem naming the candidates. The note that owns
+ *   such a row resolves it from its own frontmatter block; a reference naming
+ *   only the row has no block to read a discriminator from, so nothing here
+ *   can choose, and choosing anyway would be right about half the time.
  *
  * A **retired** spelling is refused by name before any of that. Without it a
  * reference left behind by a merge would take the unmapped fallback and address

package/types/hm3/actors.d.mts

@@ -15,6 +15,15 @@ export class Hm3Actors extends SystemActorCompiler {
      * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
      */
     static documentSubtypes: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;
+    /**
+     * @inheritdoc
+     *
+     * Answers for `spell`, `invocation` and `psionic` too — see
+     * {@link EMBEDDED_ITEM_ART} — falling back to the engine's note-type
+     * table for every other reference, `weapongear` and `missilegear`
+     * included.
+     */
+    embeddedItemArt(type: any, subType: any): string;
     /**
      * Build every embedded item an HM3 actor carries, from `hm3.items`.
      *