@heroiclands/package-build 22.4.0 → 22.4.2

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/hm3/actors.mjs

@@ -162,6 +162,35 @@ function defaultActorImg(subType) {
     return img;
 }
 
+/**
+ * Default art for the three subtypes HM3's one-to-many `mysticalability` row
+ * permits — `spell`, `invocation` and `psionic` — keyed by the **document**
+ * subtype rather than the note type.
+ *
+ * `hm3/default-item-art.mjs` is keyed the other way on purpose: a registry
+ * entry is addressed by what a note calls itself, and no note ever authors
+ * `type: spell` — only `mysticalability`, discriminated by its own
+ * `hm3.type`. But a being's `(type, shortcode)` reference has no note to
+ * discriminate, so it names the subtype it wants directly, and an embedded
+ * entry that supplies neither a template's own `img` nor a `data.icon` of its
+ * own reaches {@link Hm3Actors#embeddedItemArt} in exactly that vocabulary.
+ *
+ * Each path is the icon HM3's own item sheet assigns a freshly created item
+ * of that subtype — `HM3.defaultMagicIconName`, `HM3.defaultRitualIconName`
+ * and `HM3.defaultPsionicsIconName` in the system's own `config.js` — so a
+ * compiled item looks like one created in the client. `weapongear` and
+ * `missilegear` need no row here: a reference spelled either resolves through
+ * `HM3_DEFAULT_ITEM_ART`'s own `weapongear` key (see #582), and every
+ * predefined weapon and missile in HM3's catalogue carries its own `img`.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const EMBEDDED_ITEM_ART = Object.freeze({
+    invocation: "systems/hm3/images/icons/svg/circle.svg",
+    psionic: "systems/hm3/images/icons/svg/psionics.svg",
+    spell: "systems/hm3/images/icons/svg/pentacle.svg",
+});
+
 /**
  * HM3's Actor compile pass.
  *
@@ -192,6 +221,19 @@ export class Hm3Actors extends SystemActorCompiler {
         return this.buildActor(this.itemsMap, fm, markdown);
     }
 
+    /**
+     * @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, subType) {
+        const art = /** @type {Record<string, string|undefined>} */ (EMBEDDED_ITEM_ART)[subType];
+        return art ?? super.embeddedItemArt(type, subType);
+    }
+
     /**
      * Build every embedded item an HM3 actor carries, from `hm3.items`.
      *

package/package.json

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

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`.
      *