@heroiclands/package-build 22.4.0 → 22.4.2

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @heroiclands/package-build
 
+## 22.4.2
+
+### Patch Changes
+
+- 8dedb23: **A module embedding HM3 spells, invocations or psionics compiles.** A being's
+  embedded `spell`, `invocation` or `psionic` reference that names no shortcode
+  template and no `data.icon` of its own now takes that subtype's own default
+  art — the icon HM3 itself assigns a freshly created item of that kind —
+  instead of the build refusing the actor outright.
+- 54109cf: **A module embedding HârnMaster 3 weapons compiles.** A being's `(type,
+  shortcode)` reference into HM3's one-to-many `weapongear` row resolves when
+  its `type` names one of the row's own subtypes — `weapongear` or
+  `missilegear` — instead of being refused as ambiguous.
+
+## 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`);
     }
 
@@ -607,6 +646,29 @@ export class SystemActorCompiler extends BasePackCompiler {
         return referencedSubtype(this.documentSubtypes, type, "Item");
     }
 
+    /**
+     * 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, subType) {
+        return itemArt(type, this.system);
+    }
+
     /**
      * Read an entry's `model:` — the address of the item it is a copy of.
      *
@@ -786,8 +848,10 @@ export class SystemActorCompiler extends BasePackCompiler {
         // default answers last. Nullish coalescing throughout, so `icon: ""`
         // 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);
+            this.artPath(overlay ?? {}, "icon") ??
+            merged.img ??
+            this.embeddedItemArt(type, /** @type {string} */ (subType));
+        const identity = embeddedIdentity(merged, this.system);
         const claim = `${actorId}\u0000${itemAddress(/** @type {string} */ (subType), identity)}`;
         const first = this.#embeddedClaims.get(claim);
         if (first !== undefined) {