@heroiclands/package-build 22.4.0 → 22.4.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @heroiclands/package-build
 
+## 22.4.1
+
+### Patch Changes
+
+- 37d874d: Adds `package-build changelog check`, which lints a pending changeset or a
+  `CHANGELOG.md` release section for the marks a pull-request description
+  leaves behind — a commit hash, an issue reference, a code fence, a
+  "Verified" paragraph, a byte or test count, an over-long or nested bullet,
+  a stray heading, or simply too many bullets or lines for one entry — and
+  refuses to let one merge. The shipped `pre-commit` hook runs it on a staged
+  changeset automatically.
+- 0007964: **A module that embeds HârnMaster 3 items resolves them from a release that
+  stores their shortcodes under the system's own flags.** The actor pass reads
+  an item's `(type, shortcode)` address from `system.shortcode` where a system's
+  data model declares one, and otherwise from that system's own flag namespace —
+  never another system's, so a catalogue extracted for one system resolves
+  against its own handles only.
+
 ## 22.4.0
 
 ### Minor Changes

package/CONTENT.md

@@ -1784,6 +1784,13 @@ fetch time, so a cache filled before this rule existed is treated as incomplete
 and `deps fetch` refills it — the alternative is a lookup that answers with the
 wrong system's document and reports nothing.
 
+**Within one document, the shortcode itself comes from `system.shortcode`
+where the data model declares such a field, and otherwise from
+`flags.<systemId>.shortcode` in that same system's own flag namespace** — a
+system writes its per-document handle into its own flags and never another
+system's, so a document carrying its shortcode under a different system's flag
+namespace is not resolved by it.
+
 **`--from` is for two packages changing together.** It fills the cache from a
 locally built artifact — a package zip or the directory it was built from — so a
 consumer can be built against a dependency that has not shipped. Without it,

package/bin/package-build.mjs

@@ -53,6 +53,7 @@
  *   npx package-build lang check
  *   npx package-build lang coverage [--unused]
  *   npx package-build lang hardcoded
+ *   npx package-build changelog check [--release] [paths..]
  *   npx package-build bundle check
  *   npx package-build release
  *   npx package-build deploy <stage>
@@ -88,6 +89,7 @@ import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
 import { validateLangSource } from "../lang.mjs";
 import { checkLabelRegistry } from "../labels.mjs";
 import { lintYaml } from "../engine/yaml-lint.mjs";
+import { lintChangesetText, lintReleaseText } from "../engine/changelog-lint.mjs";
 import { bumpDependencies } from "../engine/dependency-bump.mjs";
 import {
     analyzeCoverage,
@@ -776,6 +778,86 @@ function yamlCommand() {
     };
 }
 
+/**
+ * `changelog check` — lint release prose against the rules a changeset is
+ * actually held to (`check` is the only action).
+ *
+ * A changeset answers one question — who notices, and what do they see — and
+ * nothing enforced it, so a pull-request description pasted into one ships
+ * verbatim as a release note. Default reads every pending changeset;
+ * `--release` reads the first `## <version>` section of `CHANGELOG.md`
+ * instead, for the **Version Packages** branch a merge to `main` opens.
+ *
+ * @returns {object} The yargs command module.
+ */
+function changelogCommand() {
+    return {
+        command: "changelog <action> [paths..]",
+        describe: "Release-prose checks",
+        builder: (y) =>
+            y
+                .positional("action", {
+                    choices: ["check"],
+                    describe: "check: lint pending changesets, or a release section",
+                })
+                .positional("paths", {
+                    describe:
+                        "Files to check. Defaults to `.changeset/*.md` (config.json and " +
+                        "README.md excluded), or `CHANGELOG.md` with --release.",
+                    type: "string",
+                })
+                .option("release", {
+                    type: "boolean",
+                    default: false,
+                    describe:
+                        "Check the first `## <version>` section of CHANGELOG.md instead of " +
+                        "pending changesets",
+                }),
+        handler: handler(async (args) => changelogCheck(args)),
+    };
+}
+
+/**
+ * The files `changelog check` reads by default: every pending changeset, or
+ * `CHANGELOG.md` alone under `--release`.
+ *
+ * `config.json` is excluded by the glob itself (it is not `.md`); `README.md`
+ * is excluded by name, since it is prose about changesets rather than one.
+ *
+ * @param {object} args - Parsed CLI arguments.
+ * @returns {string[]} Paths, relative to the working directory.
+ */
+function changelogFiles(args) {
+    if (args.paths?.length) return args.paths;
+    if (args.release) return ["CHANGELOG.md"];
+    return globSync(".changeset/*.md", { cwd: process.cwd() }).filter(
+        (file) => path.basename(file) !== "README.md",
+    );
+}
+
+/**
+ * Run `changelog check` over every resolved file and report the result.
+ *
+ * @param {object} args - Parsed CLI arguments.
+ */
+function changelogCheck(args) {
+    const files = changelogFiles(args);
+    let errors = 0;
+    let total = 0;
+    for (const file of files) {
+        if (!fs.existsSync(file)) die(`changelog check: ${file} does not exist.`);
+        const text = fs.readFileSync(file, "utf8");
+        const { findings } = args.release ? lintReleaseText(text) : lintChangesetText(text);
+        errors += reportFindings(findings, { file });
+        total += findings.length;
+    }
+    console.log(
+        `package-build: ${files.length} file(s) checked · ` +
+            `${errors} error(s) · ${total - errors} warning(s)`,
+    );
+    if (errors) process.exitCode = 1;
+}
+
 /**
  * `labels check` — do the machine registry and the documented table agree?
  *
@@ -1237,6 +1319,7 @@ yargs(hideBin(process.argv))
     .command(labelsCommand())
     .command(bumpCommand())
     .command(yamlCommand())
+    .command(changelogCommand())
     .command(bundleCommand())
     .command(releaseCommand())
     .command(deployCommand())

package/docs/commands.md

@@ -611,6 +611,73 @@ package-build: 2 file(s) checked · 0 error(s) · 0 warning(s)
 
 [Diagnostics](diagnostics.md).
 
+### `package-build changelog check`
+
+**NAME**
+
+Lint release prose — pending changesets, or a `CHANGELOG.md` release section
+— against the rules a changeset is actually held to (`check` is the only
+action).
+
+**SYNOPSIS**
+
+```
+package-build changelog check [--release] [paths..]
+```
+
+**DESCRIPTION**
+
+A changeset answers one question — who notices, and what do they see — and
+nothing enforced that, so a pull-request description pasted into one ships
+verbatim as a release note: commit hashes, issue references, code fences,
+"Verified" paragraphs, byte counts and test tallies, a paragraph disguised as
+a bullet, a nested checklist, a `#` heading that outranks the version heading
+above it once wrapped into a list item, or simply too many bullets or too
+many lines for one entry. Each finding names the rule it tripped and says
+what to write instead.
+
+Default reads every pending changeset (`.changeset/*.md`; `config.json` and
+`README.md` excluded) and checks each one's body, frontmatter fence dropped.
+`--release` reads the first `## <version>` section of `CHANGELOG.md` instead
+— the section a **Version Packages** branch is about to publish — with its
+generated `## <version>` and `### <Bump> Changes` scaffold lines exempted
+from the heading rule, since neither is authored.
+
+A token that reads as code — `camelCase()`, a `path/with/slashes.ext`,
+`SCREAMING_SNAKE` — outside any code span is a warning, not a failure: a
+user-facing note sometimes needs one (`Compendium.hm3.items.Item.<id>`), but
+rarely. Every other finding is an error. Reads the files given, or resolves
+its own defaults; writes nothing.
+
+**OPTIONS**
+
+| Positional  | Type      | Default                                                                                     | Description                                                                             |
+| ----------- | --------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `paths`     | string(s) | `.changeset/*.md` (`config.json`, `README.md` excluded), or `CHANGELOG.md` with `--release` | Files to check.                                                                         |
+| `--release` | boolean   | `false`                                                                                     | Check the first `## <version>` section of `CHANGELOG.md` instead of pending changesets. |
+
+**EXIT STATUS**
+
+1 if a named file does not exist. 1 if any finding is an error. A run with
+only warnings — the code-like-token case — exits 0.
+
+**EXAMPLES**
+
+```
+$ package-build changelog check
+package-build: 1 file(s) checked · 0 error(s) · 0 warning(s)
+```
+
+```
+$ package-build changelog check --release
+CHANGELOG.md:5:3: error: changelog-check/commit-hash a commit hash is a commit-log artefact; the changelog generator should not write one — set `changelog` to `@changesets/cli/changelog`
+package-build: 1 file(s) checked · 1 error(s) · 0 warning(s)
+```
+
+**SEE ALSO**
+
+[Diagnostics](diagnostics.md).
+
 ### `package-build bundle check`
 
 **NAME**

package/engine/actor-compiler.mjs

@@ -200,13 +200,39 @@ export function catalogueKey(subType, shortcode, pkg) {
     return pkg ? packagedItemAddress(pkg, subType, folded) : itemAddress(subType, folded);
 }
 
+/**
+ * An item's own shortcode, read off its compiled document.
+ *
+ * **`system.shortcode`**, where a system's data model declares such a field.
+ * Where it does not — HM3's has no such field — the handle instead lives in
+ * that system's own flag namespace, `flags.<systemId>.shortcode`: a system
+ * writes its per-document handle into its own flags and never another
+ * system's, so a document extracted from one system's catalogue is read
+ * through that system's namespace and no other. `system.shortcode` wins where
+ * both are present.
+ *
+ * @param {object} doc - A compiled Item document, or an embedded item merged
+ *   from one.
+ * @param {string|null} [systemId] - The system whose catalogue `doc` was read
+ *   from. Omitted or `null`, only `system.shortcode` is read.
+ * @returns {string|undefined} The shortcode, or `undefined` when the document
+ *   states neither.
+ */
+export function shortcodeOf(doc, systemId = null) {
+    const own = doc?.system?.shortcode;
+    if (own) return own;
+    if (!systemId) return undefined;
+    return doc?.flags?.[systemId]?.shortcode;
+}
+
 /**
  * What identifies one embedded item on its actor.
  *
- * **Its own `system.shortcode`** — not the entry's top-level `shortcode`, which
- * merely *selects* the catalogue template the entry is written from and is
- * never written to the document. Two daggers may share a selector; they are two
- * embodiments and each must declare its own.
+ * **Its own shortcode** — read by {@link shortcodeOf} — not the entry's
+ * top-level `shortcode`, which merely *selects* the catalogue template the
+ * entry is written from and is never written to the document. Two daggers
+ * may share a selector; they are two embodiments and each must declare its
+ * own.
  *
  * The name is a last resort, for a **stand-alone** entry that names no template
  * and states no shortcode. It is a poor identity — presentation, and free to be
@@ -215,10 +241,13 @@ export function catalogueKey(subType, shortcode, pkg) {
  * message says to state a `system.shortcode`.
  *
  * @param {object} item - The merged embedded item.
+ * @param {string|null} [systemId] - The system this item's document was
+ *   compiled or extracted for, so a document whose own data model carries no
+ *   `system.shortcode` field is still read by its own flag namespace.
  * @returns {string} The identity, for {@link embeddedItemId}.
  */
-export function embeddedIdentity(item) {
-    const own = item?.system?.shortcode;
+export function embeddedIdentity(item, systemId = null) {
+    const own = shortcodeOf(item, systemId);
     if (typeof own === "string" && own.trim()) return own.trim();
     return typeof item?.name === "string" ? item.name : "";
 }
@@ -253,9 +282,9 @@ export function embeddedItemId(actorId, subType, identity) {
 /**
  * Load every JSON file under each of `itemsSourceDirs`, returning one Map keyed
  * by {@link itemAddress} — the compiled document's **subtype** and its
- * `system.shortcode`. Folder docs and entries without a shortcode are skipped.
- * The `_key` field is stripped from each entry — it is not part of the item
- * data model.
+ * shortcode, read by {@link shortcodeOf}. Folder docs and entries without a
+ * shortcode are skipped. The `_key` field is stripped from each entry — it is
+ * not part of the item data model.
  *
  * The directories are read as one address space, because an actor names an item
  * by `(type, shortcode)` and never by the pack it happens to ship in. Two local
@@ -269,12 +298,22 @@ export function embeddedItemId(actorId, subType, identity) {
  * colliding with it. Local directories are therefore read first, and anything
  * already claimed is left alone.
  *
+ * **Each foreign directory reads its own flag namespace.** A foreign entry's
+ * `package` is the system whose catalogue it was extracted from, and that is
+ * the only namespace {@link shortcodeOf} is asked to fall back to for it — a
+ * document carrying another system's flag, sitting in this system's catalogue,
+ * is exactly the defect a system writing outside its own namespace produces,
+ * and is silently skipped rather than resolved.
+ *
  * @param {readonly string[]} itemsSourceDirs - Every local Item pack's JSON tree.
  * @param {readonly string[]} [foreignSourceDirs] - Extracted dependency
  *   catalogues, consulted only for addresses no local pack defines.
+ * @param {string|null} [system] - The system `itemsSourceDirs` were compiled
+ *   for, so a local document whose data model carries no `system.shortcode`
+ *   field is still read by its own flag namespace.
  * @returns {Map<string, object>} The predefined items, by address.
  */
-export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
+export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = [], system = null) {
     const map = new Map();
     const source = new Map();
     const shadowed = [];
@@ -307,7 +346,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
                 });
                 continue;
             }
-            const shortcode = doc?.system?.shortcode;
+            const shortcode = shortcodeOf(doc, system);
             if (!doc?.type || !shortcode) continue;
             const address = catalogueKey(doc.type, shortcode);
             const owner = source.get(address);
@@ -349,7 +388,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
                 });
                 continue;
             }
-            const shortcode = doc?.system?.shortcode;
+            const shortcode = shortcodeOf(doc, foreignPackage);
             if (!doc?.type || !shortcode) continue;
             const address = catalogueKey(doc.type, shortcode);
             // eslint-disable-next-line no-unused-vars
@@ -574,7 +613,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      */
     async prepare() {
         await super.prepare();
-        this.itemsMap = loadItemsMap(this.itemsSourceDirs, this.foreignSourceDirs);
+        this.itemsMap = loadItemsMap(this.itemsSourceDirs, this.foreignSourceDirs, this.system);
         log.info(`Loaded ${this.itemsMap.size} predefined items for actor resolution`);
     }
 
@@ -787,7 +826,7 @@ export class SystemActorCompiler extends BasePackCompiler {
         // ships blank on purpose rather than collecting a default.
         merged.img =
             this.artPath(overlay ?? {}, "icon") ?? merged.img ?? itemArt(type, this.system);
-        const identity = embeddedIdentity(merged);
+        const identity = embeddedIdentity(merged, this.system);
         const claim = `${actorId}\u0000${itemAddress(/** @type {string} */ (subType), identity)}`;
         const first = this.#embeddedClaims.get(claim);
         if (first !== undefined) {

package/engine/changelog-lint.mjs

@@ -0,0 +1,629 @@
+/*
+ * 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
+ */
+
+/**
+ * Lint release prose — a pending changeset, or the release section a
+ * **Version Packages** branch is about to publish — against the rules a
+ * changelog entry is actually held to.
+ *
+ * **Why this exists.** A changeset answers one question: *who notices, and
+ * what do they see?* Nothing enforced that, so a pull-request description
+ * pasted into one ships verbatim as a release note — commit hashes, issue
+ * numbers, code fences, byte counts and "Verified" paragraphs, all of it
+ * meant for a reviewer and none of it for someone deciding whether to
+ * upgrade. Every rule here names one way that happens and says what to write
+ * instead.
+ *
+ * **Where the text comes from is the caller's job.** This module lints a
+ * *section* of prose — the pending-changeset body with its frontmatter fence
+ * stripped, or the first `## <version>` section of a generated
+ * `CHANGELOG.md` — and reports every finding at the line it actually falls on
+ * in the file the caller read, via the `startLine` each entry point takes.
+ *
+ * **Code is found the same way a rewriter finds it** —
+ * {@link module:engine/code-fences.codeRegions}, not a second fence scanner —
+ * because a fenced sample, a verbatim path and a backticked literal must never
+ * be misread as the violation they merely *contain*.
+ *
+ * @module
+ */
+
+import { codeRegions } from "./code-fences.mjs";
+
+/** The generated scaffold `content-build`/Changesets writes, never authored prose. */
+const RELEASE_HEADING_RE = /^## /;
+const CHANGES_HEADING_RE = /^### (?:Major|Minor|Patch) Changes\s*$/;
+
+/** A top-level bullet: a hyphen at column 0. Never indented — that is a nested list. */
+const TOP_BULLET_RE = /^-\s+/;
+/** A list item indented under something else. */
+const NESTED_BULLET_RE = /^[ \t]+[-*+]\s+/;
+
+/** 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]|$)/;
+
+/**
+ * An issue or pull-request reference: `#123`, `owner/repo#123`.
+ *
+ * No leading `\b` — `#` is not a word character, so a boundary assertion
+ * immediately before it never matches the ordinary case of a bare `#123`
+ * preceded by whitespace or punctuation.
+ */
+const ISSUE_REF_RE = /(?:[\w.-]+\/[\w.-]+)?#\d+\b/g;
+
+/** A paragraph or bullet headed by a verification word, bold or plain. */
+const VERIFY_HEADING_RE =
+    /^(?:[-*+]\s+)?(?:\*\*|__)?(Verification|Verified|Bump|What was run|Commands)(?:\*\*|__)?(?=[\s:.]|$)/i;
+
+/** The five scoreboard shapes a release note carries when it is really a test log. */
+const SCOREBOARD_PATTERNS = [
+    { re: /\bbyte-identical\b/gi, phrase: "byte-identical" },
+    { re: /\b\d+\s+files?\b/gi, phrase: "an N files count" },
+    { re: /\b\d+\s+tests?\s+pass(?:ed|ing)?\b/gi, phrase: "an N tests pass count" },
+    { re: /\b\d+\s*→\s*\d+\b/g, phrase: "an N → M tally" },
+    { re: /[+＋]\d+\s*\/\s*[−–-]\d+/g, phrase: "a +N / −M tally" },
+];
+
+/** A token that reads as code but sits outside any code span — warning only. */
+const CODE_TOKEN_RE =
+    /\b[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*(?:\(\))?\b|\b[\w-]+(?:\/[\w-]+)+\.[A-Za-z]{1,8}\b|\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/g;
+
+/** Bullets over this many words read as a paragraph, not a release note. */
+const MAX_BULLET_WORDS = 40;
+/** Bullets over this many read as an itemized log, not "who notices". */
+const MAX_TOP_BULLETS = 15;
+/** Lines over this many read as a pull-request description. */
+const MAX_SECTION_LINES = 60;
+
+/**
+ * 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}}
+ */
+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 };
+}
+
+/**
+ * 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.
+ */
+function codeLineSet(text) {
+    const lines = new Set();
+    for (const region of codeRegions(text, { spans: false })) {
+        const from = lineColOf(text, region.start).line;
+        const to = lineColOf(text, Math.max(region.start, region.end - 1)).line;
+        for (let l = from; l <= to; l++) lines.add(l);
+    }
+    return lines;
+}
+
+/**
+ * Is this character offset inside a code region — block or inline span?
+ *
+ * @param {Array<{start: number, end: number}>} regions - Sorted, from
+ *   {@link module:engine/code-fences.codeRegions}.
+ * @param {number} offset - A character offset into the text the regions were
+ *   computed against.
+ * @returns {boolean}
+ */
+function isMasked(regions, offset) {
+    for (const region of regions) {
+        if (offset < region.start) return false;
+        if (offset < region.end) return true;
+    }
+    return false;
+}
+
+/**
+ * The finding one rule reports, before its line is mapped into the caller's
+ * file.
+ *
+ * @typedef {object} RelativeFinding
+ * @property {number} line - 1-based line within the section text.
+ * @property {number} [column] - 1-based column, dropped when not meaningful.
+ * @property {"error"|"warning"} severity
+ * @property {string} message - Prefixed `changelog-check/<class> `, so a
+ *   finding names the rule it tripped as well as what to write instead.
+ */
+
+/**
+ * The opening line of every fenced code block — not an indented one, which
+ * reads as a sample and not as a pasted terminal transcript.
+ *
+ * @param {string} text - Section text.
+ * @returns {RelativeFinding[]}
+ */
+function checkCodeFences(text) {
+    const lines = text.split("\n");
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (const region of codeRegions(text, { spans: false })) {
+        const { line } = lineColOf(text, region.start);
+        if (!/^[ \t]*(`{3,}|~{3,})/.test(lines[line - 1])) continue; // an indented block, not a fence
+        findings.push({
+            line,
+            severity: "error",
+            message:
+                "changelog-check/code-fence a fenced code block reads like a pull-request " +
+                "description, not a release note — describe what a user sees in prose",
+        });
+    }
+    return findings;
+}
+
+/**
+ * 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}>}
+ */
+function topLevelBullets(text, codeLines) {
+    const lines = text.split("\n");
+    /** @type {Array<{startLine: number, text: string}>} */
+    const bullets = [];
+    /** @type {{startLine: number, parts: string[]}|null} */
+    let current = null;
+
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        const raw = lines[i];
+
+        if (codeLines.has(lineNo)) {
+            if (current) current.parts.push(raw);
+            continue;
+        }
+        if (TOP_BULLET_RE.test(raw)) {
+            if (current)
+                bullets.push({ startLine: current.startLine, text: current.parts.join("\n") });
+            current = { startLine: lineNo, parts: [raw] };
+            continue;
+        }
+        if (/^[ \t]+\S/.test(raw) || raw.trim() === "") {
+            if (current) current.parts.push(raw);
+            continue;
+        }
+        // Column 0, not a bullet: a bold subsection label or a scaffold
+        // heading closes whatever bullet was open.
+        current = null;
+    }
+    if (current) bullets.push({ startLine: current.startLine, text: current.parts.join("\n") });
+    return bullets;
+}
+
+/**
+ * A bullet's word count, the bullet marker and markdown decoration stripped.
+ *
+ * @param {string} bulletText - As {@link topLevelBullets} collects it.
+ * @returns {number}
+ */
+function wordCount(bulletText) {
+    return bulletText.replace(TOP_BULLET_RE, "").split(/\s+/).filter(Boolean).length;
+}
+
+/**
+ * A commit hash opening a bullet — the artefact a changeset generator that is
+ * not `@changesets/cli/changelog` writes on every entry.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines
+ * @param {Set<number>} scaffoldLines
+ * @returns {RelativeFinding[]}
+ */
+function checkCommitHash(text, codeLines, scaffoldLines) {
+    const lines = text.split("\n");
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        if (codeLines.has(lineNo) || scaffoldLines.has(lineNo)) continue;
+        const m = COMMIT_HASH_RE.exec(lines[i]);
+        if (!m) continue;
+        findings.push({
+            line: lineNo,
+            column: lines[i].indexOf(m[1]) + 1,
+            severity: "error",
+            message:
+                "changelog-check/commit-hash a commit hash is a commit-log artefact; the " +
+                "changelog generator should not write one — set `changelog` to " +
+                "`@changesets/cli/changelog`",
+        });
+    }
+    return findings;
+}
+
+/**
+ * An issue or pull-request reference, wherever it appears outside code.
+ *
+ * @param {string} text - Section text.
+ * @param {Array<{start: number, end: number}>} maskedRegions
+ * @returns {RelativeFinding[]}
+ */
+function checkIssueReferences(text, maskedRegions) {
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (const m of text.matchAll(ISSUE_REF_RE)) {
+        if (isMasked(maskedRegions, m.index)) continue;
+        const { line, column } = lineColOf(text, m.index);
+        findings.push({
+            line,
+            column,
+            severity: "error",
+            message:
+                `changelog-check/issue-reference "${m[0]}" is an issue or pull-request ` +
+                "reference — that belongs on the pull request's own `Closes #<n>` line, " +
+                "not the changelog; a released package has no tracker for its reader to open",
+        });
+    }
+    return findings;
+}
+
+/**
+ * A paragraph or bullet whose first words announce how the change was
+ * verified, rather than what it does.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines
+ * @returns {RelativeFinding[]}
+ */
+function checkVerificationParagraphs(text, codeLines) {
+    const lines = text.split("\n");
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        if (codeLines.has(lineNo)) continue;
+        const trimmed = lines[i].replace(/^[ \t]+/, "");
+        const m = VERIFY_HEADING_RE.exec(trimmed);
+        if (!m) continue;
+        findings.push({
+            line: lineNo,
+            column: lines[i].length - trimmed.length + 1,
+            severity: "error",
+            message:
+                `changelog-check/verification-paragraph "${m[1]}" is how the change was ` +
+                "checked, not what it does — say what a user sees, and move this to the " +
+                "pull request's own description",
+        });
+    }
+    return findings;
+}
+
+/**
+ * A byte count, file count, pass tally or before/after count — every one a
+ * verification artefact, not something a user meets.
+ *
+ * @param {string} text - Section text.
+ * @param {Array<{start: number, end: number}>} maskedRegions
+ * @returns {RelativeFinding[]}
+ */
+function checkScoreboardPhrases(text, maskedRegions) {
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (const { re, phrase } of SCOREBOARD_PATTERNS) {
+        for (const m of text.matchAll(re)) {
+            if (isMasked(maskedRegions, m.index)) continue;
+            const { line, column } = lineColOf(text, m.index);
+            findings.push({
+                line,
+                column,
+                severity: "error",
+                message:
+                    `changelog-check/scoreboard-phrase "${m[0]}" is ${phrase} — a scoreboard ` +
+                    "a reviewer wanted, not a change a user meets; describe the user-visible " +
+                    "effect instead",
+            });
+        }
+    }
+    return findings;
+}
+
+/**
+ * A bullet running past {@link MAX_BULLET_WORDS} words.
+ *
+ * @param {Array<{startLine: number, text: string}>} bullets
+ * @returns {RelativeFinding[]}
+ */
+function checkLongBullets(bullets) {
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (const bullet of bullets) {
+        const words = wordCount(bullet.text);
+        if (words <= MAX_BULLET_WORDS) continue;
+        findings.push({
+            line: bullet.startLine,
+            column: 1,
+            severity: "error",
+            message:
+                `changelog-check/long-bullet this bullet runs to ${words} words — a ` +
+                `changeset bullet is one sentence naming who notices and what they see; ` +
+                "split it, or move the detail to the pull request's description",
+        });
+    }
+    return findings;
+}
+
+/**
+ * The first line of every contiguous run of nested list items.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines
+ * @returns {RelativeFinding[]}
+ */
+function checkNestedLists(text, codeLines) {
+    const lines = text.split("\n");
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    let prevNested = false;
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        if (codeLines.has(lineNo)) {
+            prevNested = false;
+            continue;
+        }
+        const isNested = NESTED_BULLET_RE.test(lines[i]);
+        if (isNested && !prevNested) {
+            const marker = /^[ \t]*/.exec(lines[i])[0];
+            findings.push({
+                line: lineNo,
+                column: marker.length + 1,
+                severity: "error",
+                message:
+                    "changelog-check/nested-list a nested list reads like a pull-request " +
+                    "checklist — write one flat sentence per bullet instead",
+            });
+        }
+        prevNested = isNested;
+    }
+    return findings;
+}
+
+/**
+ * A `#` heading of any level inside the prose — the scaffold `## <version>`
+ * and `### <Bump> Changes` lines excepted, since neither is authored.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines
+ * @param {Set<number>} scaffoldLines
+ * @returns {RelativeFinding[]}
+ */
+function checkHeadings(text, codeLines, scaffoldLines) {
+    const lines = text.split("\n");
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        if (codeLines.has(lineNo) || scaffoldLines.has(lineNo)) continue;
+        if (!/^#{1,6}\s/.test(lines[i])) continue;
+        findings.push({
+            line: lineNo,
+            column: 1,
+            severity: "error",
+            message:
+                "changelog-check/heading a `#` heading inside a changelog entry outranks the " +
+                "version heading above it once the entry is wrapped into a list item — use a " +
+                "bold label instead",
+        });
+    }
+    return findings;
+}
+
+/**
+ * More than {@link MAX_TOP_BULLETS} top-level bullets in one section.
+ *
+ * @param {Array<{startLine: number, text: string}>} bullets
+ * @returns {RelativeFinding[]}
+ */
+function checkTooManyBullets(bullets) {
+    if (bullets.length <= MAX_TOP_BULLETS) return [];
+    return [
+        {
+            line: bullets[MAX_TOP_BULLETS].startLine,
+            severity: "error",
+            message:
+                `changelog-check/too-many-bullets ${bullets.length} top-level bullets is an ` +
+                `itemized log, not a release note — one to six, so a reader sees the shape ` +
+                "of the release at a glance",
+        },
+    ];
+}
+
+/**
+ * More than {@link MAX_SECTION_LINES} lines in one section.
+ *
+ * @param {string} text - Section text.
+ * @returns {RelativeFinding[]}
+ */
+function checkTooManyLines(text) {
+    const lines = text.split("\n");
+    if (lines.length <= MAX_SECTION_LINES) return [];
+    return [
+        {
+            line: MAX_SECTION_LINES + 1,
+            severity: "error",
+            message:
+                `changelog-check/too-many-lines ${lines.length} lines in one release section ` +
+                "reads like a pull-request description — trim to what a user meets",
+        },
+    ];
+}
+
+/**
+ * A token that reads as code — `camelCase()`, `a/path.ext`, `SCREAMING_SNAKE`
+ * — outside any code span. A warning: a user-facing note sometimes needs one
+ * (`Compendium.hm3.items.Item.<id>`), but rarely.
+ *
+ * @param {string} text - Section text.
+ * @param {Array<{start: number, end: number}>} maskedRegions
+ * @returns {RelativeFinding[]}
+ */
+function checkCodeLikeTokens(text, maskedRegions) {
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (const m of text.matchAll(CODE_TOKEN_RE)) {
+        if (isMasked(maskedRegions, m.index)) continue;
+        const { line, column } = lineColOf(text, m.index);
+        findings.push({
+            line,
+            column,
+            severity: "warning",
+            message:
+                `changelog-check/code-like-token "${m[0]}" looks like code outside a code ` +
+                "span — wrap it in backticks if it is a literal a user would type",
+        });
+    }
+    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>`
+ * opening and any `### <Bump> Changes` line.
+ *
+ * @param {string} text - Section text.
+ * @returns {Set<number>}
+ */
+function scaffoldLineSet(text) {
+    const lines = text.split("\n");
+    const set = new Set();
+    if (RELEASE_HEADING_RE.test(lines[0] ?? "")) set.add(1);
+    for (let i = 0; i < lines.length; i++) {
+        if (CHANGES_HEADING_RE.test(lines[i])) set.add(i + 1);
+    }
+    return set;
+}
+
+/**
+ * Run every rule over one section of release prose.
+ *
+ * @param {string} text - The section, already isolated by the caller.
+ * @returns {RelativeFinding[]} Findings with line numbers relative to `text`.
+ */
+function lintSection(text) {
+    const codeLines = codeLineSet(text);
+    const maskedRegions = codeRegions(text, { spans: true });
+    const scaffoldLines = scaffoldLineSet(text);
+    const bullets = topLevelBullets(text, codeLines);
+
+    return [
+        ...checkCommitHash(text, codeLines, scaffoldLines),
+        ...checkIssueReferences(text, maskedRegions),
+        ...checkCodeFences(text),
+        ...checkVerificationParagraphs(text, codeLines),
+        ...checkScoreboardPhrases(text, maskedRegions),
+        ...checkLongBullets(bullets),
+        ...checkNestedLists(text, codeLines),
+        ...checkHeadings(text, codeLines, scaffoldLines),
+        ...checkTooManyBullets(bullets),
+        ...checkTooManyLines(text),
+        ...checkCodeLikeTokens(text, maskedRegions),
+    ].sort((a, b) => a.line - b.line || (a.column ?? 0) - (b.column ?? 0));
+}
+
+/**
+ * A pending changeset's frontmatter fence, stripped.
+ *
+ * @param {string} text - The changeset file's full contents.
+ * @returns {{body: string, startLine: number}} The body, and the 1-based line
+ *   in the original file its first line falls on.
+ */
+function stripFrontmatter(text) {
+    const lines = text.split("\n");
+    if (lines[0] !== "---") return { body: text, startLine: 1 };
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === "---") {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1) return { body: text, startLine: 1 };
+    return { body: lines.slice(end + 1).join("\n"), startLine: end + 2 };
+}
+
+/**
+ * The first `## <version>` section of a `CHANGELOG.md`.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @returns {{body: string, startLine: number}|null} `null` when no `## `
+ *   heading is present at all.
+ */
+function extractReleaseSection(text) {
+    const lines = text.split("\n");
+    const start = lines.findIndex((line) => RELEASE_HEADING_RE.test(line));
+    if (start === -1) return null;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (RELEASE_HEADING_RE.test(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    return { body: lines.slice(start, end).join("\n"), startLine: start + 1 };
+}
+
+/**
+ * Lint one pending changeset (`.changeset/*.md`).
+ *
+ * @param {string} text - The file's full contents, frontmatter included.
+ * @returns {{findings: Array<{line: number, column?: number,
+ *   severity: "error"|"warning", message: string}>}}
+ */
+export function lintChangesetText(text) {
+    const { body, startLine } = stripFrontmatter(text);
+    const findings = lintSection(body).map((f) => ({ ...f, line: f.line + startLine - 1 }));
+    return { findings };
+}
+
+/**
+ * Lint the first `## <version>` release section of a `CHANGELOG.md`.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @returns {{findings: Array<{line?: number, column?: number,
+ *   severity: "error"|"warning", message: string}>}}
+ */
+export function lintReleaseText(text) {
+    const section = extractReleaseSection(text);
+    if (!section) {
+        return {
+            findings: [
+                {
+                    severity: "error",
+                    message: "changelog-check/no-release-section no `## <version>` heading found",
+                },
+            ],
+        };
+    }
+    const findings = lintSection(section.body).map((f) => ({
+        ...f,
+        line: f.line + section.startLine - 1,
+    }));
+    return { findings };
+}

package/githooks/pre-commit

@@ -1,7 +1,12 @@
 #!/usr/bin/env sh
 #
-# Refuse to commit on a protected branch. See protected-branch.sh for the rule
-# and its opt-outs; pre-merge-commit is this hook's counterpart for merges.
+# Refuse to commit on a protected branch, and refuse a staged changeset that
+# reads like a pull-request description.
+#
+# See protected-branch.sh for the branch rule and its opt-outs;
+# pre-merge-commit is that guard's counterpart for merges. The changeset check
+# below has no merge-commit counterpart — a merge commit stages no new
+# changeset of its own.
 #
 # Installed for everyone via the package.json "prepare" script, which points git
 # at this directory (`git config core.hooksPath .githooks`) on `npm install`.
@@ -9,3 +14,49 @@
 . "$(dirname "$0")/protected-branch.sh"
 
 guard_protected_branch
+
+# On unless refused: `changelog check` reads only the files this commit is
+# about to stage and runs in-process, so it costs a fraction of what the
+# pre-push container check does and stays on by the same default as the
+# no-attribution guard.
+. "$(dirname "$0")/hook-enabled.sh"
+
+hook_enabled changelogCheck true || exit 0
+
+# Pending changesets this commit actually stages — added, copied or modified.
+# A deleted changeset has nothing left to lint, and a changeset already on
+# `main` was linted by the commit that staged it. `README.md` documents the
+# changeset format; it is not one.
+staged=""
+while IFS= read -r file; do
+    [ -z "$file" ] && continue
+    case "$file" in
+        */README.md | README.md) continue ;;
+    esac
+    staged="$staged $file"
+done <<EOF
+$(git diff --cached --name-only --diff-filter=ACM -- '.changeset/*.md')
+EOF
+
+if [ -z "$staged" ]; then
+    exit 0
+fi
+
+# The binary lives beside this hook inside the package. If it is not there,
+# this hook is being used from somewhere else — a global `core.hooksPath`, a
+# copy — in a repository that does not install the package, and there is
+# nothing to run.
+runner="$(dirname "$0")/../bin/package-build.mjs"
+if [ ! -f "$runner" ]; then
+    exit 0
+fi
+
+# shellcheck disable=SC2086
+node "$runner" changelog check $staged
+status=$?
+
+if [ "$status" -ne 0 ]; then
+    echo ""
+    echo "pre-commit: fix the changeset above, or skip this check with 'git commit --no-verify'."
+    exit 1
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.0",
+    "version": "22.4.1",
     "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",

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

@@ -90,13 +90,33 @@ export function packagedItemAddress(pkg: string, subType: string, shortcode: str
  * @returns {string} The catalogue key.
  */
 export function catalogueKey(subType: string, shortcode: string, pkg?: string): string;
+/**
+ * An item's own shortcode, read off its compiled document.
+ *
+ * **`system.shortcode`**, where a system's data model declares such a field.
+ * Where it does not — HM3's has no such field — the handle instead lives in
+ * that system's own flag namespace, `flags.<systemId>.shortcode`: a system
+ * writes its per-document handle into its own flags and never another
+ * system's, so a document extracted from one system's catalogue is read
+ * through that system's namespace and no other. `system.shortcode` wins where
+ * both are present.
+ *
+ * @param {object} doc - A compiled Item document, or an embedded item merged
+ *   from one.
+ * @param {string|null} [systemId] - The system whose catalogue `doc` was read
+ *   from. Omitted or `null`, only `system.shortcode` is read.
+ * @returns {string|undefined} The shortcode, or `undefined` when the document
+ *   states neither.
+ */
+export function shortcodeOf(doc: object, systemId?: string | null): string | undefined;
 /**
  * What identifies one embedded item on its actor.
  *
- * **Its own `system.shortcode`** — not the entry's top-level `shortcode`, which
- * merely *selects* the catalogue template the entry is written from and is
- * never written to the document. Two daggers may share a selector; they are two
- * embodiments and each must declare its own.
+ * **Its own shortcode** — read by {@link shortcodeOf} — not the entry's
+ * top-level `shortcode`, which merely *selects* the catalogue template the
+ * entry is written from and is never written to the document. Two daggers
+ * may share a selector; they are two embodiments and each must declare its
+ * own.
  *
  * The name is a last resort, for a **stand-alone** entry that names no template
  * and states no shortcode. It is a poor identity — presentation, and free to be
@@ -105,9 +125,12 @@ export function catalogueKey(subType: string, shortcode: string, pkg?: string):
  * message says to state a `system.shortcode`.
  *
  * @param {object} item - The merged embedded item.
+ * @param {string|null} [systemId] - The system this item's document was
+ *   compiled or extracted for, so a document whose own data model carries no
+ *   `system.shortcode` field is still read by its own flag namespace.
  * @returns {string} The identity, for {@link embeddedItemId}.
  */
-export function embeddedIdentity(item: object): string;
+export function embeddedIdentity(item: object, systemId?: string | null): string;
 /**
  * The `_id` of one item embedded on an actor.
  *
@@ -135,9 +158,9 @@ export function embeddedItemId(actorId: string, subType: string, identity: strin
 /**
  * Load every JSON file under each of `itemsSourceDirs`, returning one Map keyed
  * by {@link itemAddress} — the compiled document's **subtype** and its
- * `system.shortcode`. Folder docs and entries without a shortcode are skipped.
- * The `_key` field is stripped from each entry — it is not part of the item
- * data model.
+ * shortcode, read by {@link shortcodeOf}. Folder docs and entries without a
+ * shortcode are skipped. The `_key` field is stripped from each entry — it is
+ * not part of the item data model.
  *
  * The directories are read as one address space, because an actor names an item
  * by `(type, shortcode)` and never by the pack it happens to ship in. Two local
@@ -151,12 +174,22 @@ export function embeddedItemId(actorId: string, subType: string, identity: strin
  * colliding with it. Local directories are therefore read first, and anything
  * already claimed is left alone.
  *
+ * **Each foreign directory reads its own flag namespace.** A foreign entry's
+ * `package` is the system whose catalogue it was extracted from, and that is
+ * the only namespace {@link shortcodeOf} is asked to fall back to for it — a
+ * document carrying another system's flag, sitting in this system's catalogue,
+ * is exactly the defect a system writing outside its own namespace produces,
+ * and is silently skipped rather than resolved.
+ *
  * @param {readonly string[]} itemsSourceDirs - Every local Item pack's JSON tree.
  * @param {readonly string[]} [foreignSourceDirs] - Extracted dependency
  *   catalogues, consulted only for addresses no local pack defines.
+ * @param {string|null} [system] - The system `itemsSourceDirs` were compiled
+ *   for, so a local document whose data model carries no `system.shortcode`
+ *   field is still read by its own flag namespace.
  * @returns {Map<string, object>} The predefined items, by address.
  */
-export function loadItemsMap(itemsSourceDirs: readonly string[], foreignSourceDirs?: readonly string[]): Map<string, object>;
+export function loadItemsMap(itemsSourceDirs: readonly string[], foreignSourceDirs?: readonly string[], system?: string | null): Map<string, object>;
 /**
  * The Actor compile pass of one game system.
  *

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

@@ -0,0 +1,50 @@
+/**
+ * Lint one pending changeset (`.changeset/*.md`).
+ *
+ * @param {string} text - The file's full contents, frontmatter included.
+ * @returns {{findings: Array<{line: number, column?: number,
+ *   severity: "error"|"warning", message: string}>}}
+ */
+export function lintChangesetText(text: string): {
+    findings: Array<{
+        line: number;
+        column?: number;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+};
+/**
+ * Lint the first `## <version>` release section of a `CHANGELOG.md`.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @returns {{findings: Array<{line?: number, column?: number,
+ *   severity: "error"|"warning", message: string}>}}
+ */
+export function lintReleaseText(text: string): {
+    findings: Array<{
+        line?: number;
+        column?: number;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+};
+/**
+ * The finding one rule reports, before its line is mapped into the caller's
+ * file.
+ */
+export type RelativeFinding = {
+    /**
+     * - 1-based line within the section text.
+     */
+    line: number;
+    /**
+     * - 1-based column, dropped when not meaningful.
+     */
+    column?: number | undefined;
+    severity: "error" | "warning";
+    /**
+     * - Prefixed `changelog-check/<class> `, so a
+     * finding names the rule it tripped as well as what to write instead.
+     */
+    message: string;
+};