@heroiclands/package-build 17.0.0 → 17.1.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @heroiclands/package-build
 
+## 17.1.0
+
+### Minor Changes
+
+- 9d6a52f: **New: `package-build labels check`.** The issue-label registry has two faces
+  that must agree — `.github/labels.yml`, which is synced to GitHub, and the §3
+  table in `.github/ISSUE_REPORTING.md`, which is what a person reads. Neither
+  derives from the other, so either can drift, and nothing notices until an issue
+  is filed against a label that does not exist or the sync pushes one the
+  documentation never mentions.
+  
+  It arrives here because **every repository wants it and only the paths ever
+  differed** — it was a `utils/check-labels.mjs` copied per repository, which is
+  the shape a shared check takes just before its copies start disagreeing. Same
+  argument that moved the no-attribution check to a shared action.
+  
+  Two things improve in the move:
+  
+  - **Findings are compiler-parseable and located.** The original printed prose
+    to stderr; this reports `.github/labels.yml:73:9: error: …` against the file
+    each finding belongs to, so a missing row is located in the documentation and
+    a missing entry in the registry.
+  - **The documentation path is an option.** `--doc` defaults to
+    `.github/ISSUE_REPORTING.md`; `Song-of-Heroic-Lands-FoundryVTT` keeps its at
+    `kb/dev-docs/how-to/issue-reporting.md` and now needs no separate script.
+    `--registry` likewise.
+  
+  A missing §3 is reported once, as its own failure, rather than as every label
+  having drifted. An over-long description is caught here too — GitHub answers a
+  bare 422 naming neither the label nor the limit.
+  
+  Verified against every repository that has a registry: `sohl-thalorna` (12),
+  `sohl-kethira-basic` (11), `harn-adventures` (11), `harn-ensemble` (12) and
+  `Song-of-Heroic-Lands-FoundryVTT` (16) all agree — and it found real drift in
+  `HarnMaster-3-FoundryVTT`, where `good first issue` and `help wanted` are in
+  the registry and absent from §3.
+
 ## 17.0.0
 
 ### Major Changes

package/bin/package-build.mjs

@@ -83,6 +83,7 @@ import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
 import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
 import { validateLangSource } from "../lang.mjs";
+import { checkLabelRegistry } from "../labels.mjs";
 import {
     analyzeCoverage,
     collectScriptReferences,
@@ -712,6 +713,77 @@ function langHardcoded(config) {
  *
  * @returns {object} The yargs command module.
  */
+/**
+ * `labels check` — do the machine registry and the documented table agree?
+ *
+ * `.github/labels.yml` is synced to GitHub and the §3 table in
+ * `.github/ISSUE_REPORTING.md` is what a person reads. Neither derives from the
+ * other, so either can drift, and nothing notices until an issue is filed
+ * against a label that does not exist.
+ *
+ * Every repository wants this and only the paths ever differed, which is why it
+ * is here rather than copied into each as a `utils/` script.
+ *
+ * @returns {object} The yargs command module.
+ */
+function labelsCommand() {
+    return {
+        command: "labels <action>",
+        describe: "Issue-label registry checks",
+        builder: (y) =>
+            y
+                .positional("action", {
+                    choices: ["check"],
+                    describe: "check: the registry and the documented table name the same labels",
+                })
+                .option("registry", {
+                    type: "string",
+                    default: ".github/labels.yml",
+                    describe: "The machine registry synced to GitHub",
+                })
+                .option("doc", {
+                    type: "string",
+                    default: ".github/ISSUE_REPORTING.md",
+                    describe: "The documented reference whose §3 table lists the same labels",
+                }),
+        handler: handler(async (args) => labelsCheck(args)),
+    };
+}
+
+/**
+ * Read both faces of the registry and report where they disagree.
+ *
+ * Findings are reported against the file each belongs to, so a missing row is
+ * located in the documentation and a missing entry in the registry, rather than
+ * both being attributed to whichever file was read first.
+ *
+ * @param {object} args - Parsed CLI arguments.
+ */
+function labelsCheck(args) {
+    for (const target of [args.registry, args.doc]) {
+        if (!fs.existsSync(target)) die(`labels check: ${target} does not exist.`);
+    }
+    const registryText = fs.readFileSync(args.registry, "utf8");
+    const docText = fs.readFileSync(args.doc, "utf8");
+
+    const { registry, doc, count } = checkLabelRegistry({
+        registryText,
+        docText,
+        docPath: args.doc,
+    });
+
+    const errors =
+        reportFindings(registry, { file: args.registry }) + reportFindings(doc, { file: args.doc });
+    if (errors) {
+        console.error(
+            `\nThe registry and ${args.doc} §3 are edited together — ` +
+                `change one and change the other.`,
+        );
+        process.exit(1);
+    }
+    console.log(`package-build: registry and §3 agree (${count} labels).`);
+}
+
 function langCommand() {
     return {
         command: "lang <action>",
@@ -992,6 +1064,7 @@ yargs(hideBin(process.argv))
     .command(manifestCommand())
     .command(schemaCommand())
     .command(langCommand())
+    .command(labelsCommand())
     .command(bundleCommand())
     .command(releaseCommand())
     .command(deployCommand())

package/package.json

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