@heroiclands/package-build 16.0.0 → 17.1.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # @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
+
+- fdd7094: **The linter now implements the format it publishes.** `docs/content-format.md`
+  and the vocabulary had drifted, silently and in both directions, and nothing
+  compared them.
+  
+  **Five documented types reached no schema** — `place`, `lore`, `scenario`,
+  `vehicle` and `armorlocation`. A note using one was reported as having no
+  schema and then _skipped entirely_: `lintNote` returns after that finding, so
+  the note's `data:`, `subType`, references and system block all went
+  unexamined. So the types were legal enough to author and not legal enough to
+  check, and using one **suppressed** every other check on the note (#231).
+  
+  **Three documented `data` properties reached no vocabulary** — `epithet` and
+  `symbol` on `affiliation`, and `lore` on both `affiliation` and `being`. The
+  `data:` container is closed, so a note that followed the specification exactly
+  was told its property did not exist _and the value was dropped_ rather than
+  reaching the page (#232).
+  
+  `peoples` is **removed**, having widened to `lore` — the specification says so
+  outright, and no tree authors it: "Nothing is lost by widening: the target's
+  own subType already distinguishes a `folk` from a `law`." That removal is the
+  reason this is a major; everything else here turns red trees green.
+  
+  Between them, on `sohl-thalorna`: **2,001 findings become 20**. The 1,981 that
+  go were never content defects. The 20 that stay are: 18 embedded shortcode
+  collisions and two genuinely stale keys.
+  
+  **The specification is executable now.** `tests/content-format-agreement.test.ts`
+  parses `docs/content-format.md` and fails if a documented type has no schema or
+  no vocabulary, or if a type's declared `data` properties differ in either
+  direction from its documented table. Nothing compared the two before, which is
+  why this drift lasted.
+  
+  Also corrects the specification itself: `macro`'s `macroType` and `macroScope`
+  were tabled as `data` properties, but the compiler reads them with the
+  `sohl`-field accessor — the `sohl:` block, then the note's top level — so
+  `data.macroType` is not read at all. They are `sohl` properties, and the table
+  now says so.
+
 ## 16.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/docs/content-format.md

@@ -1463,7 +1463,13 @@ shipped as content and run by Foundry's own macro runner under the permission
 model that governs every macro in a world. Nothing evaluates, compiles, or
 revives anything; the compiler copies text from a fence into a JSON field.
 
-| `data` property | Values                      | Description                                                          |
+**Both settings are `sohl` properties, not `data` ones.** The compiler reads
+them with the same accessor every `sohl` field uses — the `sohl:` block first,
+then the note's top level — so `data.macroType` is not read, and a macro is not
+a journal-only note the way `place`, `lore` and `scenario` are: it produces a
+Foundry **Macro**, and these two describe that document.
+
+| `sohl` property | Values                      | Description                                                          |
 | --------------- | --------------------------- | -------------------------------------------------------------------- |
 | `macroType`     | `script`                    | The Foundry macro type. Defaults to `script`, and `chat` is an error |
 | `macroScope`    | `global \| actors \| actor` | How far the macro reaches. Defaults to `global`                      |

package/engine/note-schemas.mjs

@@ -34,6 +34,45 @@
 
 import { HOMEPAGE_FIELDS, HOMEPAGE_TYPE } from "./homepage.mjs";
 
+/**
+ * Every engine-level content type, and what a note of that type may write.
+ *
+ * @type {Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>}
+ */
+/**
+ * A note that compiles to a JournalEntry and nothing else.
+ *
+ * Empty on purpose, and the emptiness is the declaration. `place`, `lore` and
+ * `scenario` produce prose — the JournalEntry every note produces — so none of
+ * them writes a `sohl:` field, and the authored corpus agrees: across
+ * `sohl-thalorna`'s 249 places, 180 lore notes and 21 scenarios, not one
+ * carries a `sohl:` block. Everything they *do* declare is `data:`, which is
+ * the closed container `engine/note-vocabulary.mjs` holds them to.
+ *
+ * Declaring the type with no fields is what distinguishes **a type with no
+ * vocabulary** from **a type that is unknown** — two different findings, and
+ * only the second is a mistake. Until this landed the specification declared
+ * all three and nothing implemented them, so a note using one was reported as
+ * having no schema and then *skipped entirely*: `lintNote` returns after that
+ * finding, so the note's `data:`, `subType`, references and system block all
+ * went unexamined (#231).
+ *
+ * @type {readonly import("./field-spec.mjs").FieldSpec[]}
+ */
+const JOURNAL_ONLY_FIELDS = Object.freeze([]);
+
+/**
+ * An `armorlocation` note — an HM3 item, and no part of the SoHL registry.
+ *
+ * It lives here rather than in `sohl/` for the reachability reason that
+ * governs this whole file: a package declaring no `itemBuilders` never loads
+ * the SoHL registry, and HM3 packages are exactly the ones that author this
+ * type.
+ *
+ * @type {readonly import("./field-spec.mjs").FieldSpec[]}
+ */
+const ARMORLOCATION_FIELDS = Object.freeze([]);
+
 /**
  * Every engine-level content type, and what a note of that type may write.
  *
@@ -41,4 +80,8 @@ import { HOMEPAGE_FIELDS, HOMEPAGE_TYPE } from "./homepage.mjs";
  */
 export const ENGINE_NOTE_SCHEMAS = Object.freeze({
     [HOMEPAGE_TYPE]: HOMEPAGE_FIELDS,
+    place: JOURNAL_ONLY_FIELDS,
+    lore: JOURNAL_ONLY_FIELDS,
+    scenario: JOURNAL_ONLY_FIELDS,
+    armorlocation: ARMORLOCATION_FIELDS,
 });

package/engine/note-vocabulary.mjs

@@ -395,7 +395,13 @@ export const NOTE_VOCABULARY = Object.freeze({
             { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },
             { name: "occupation", ...TEXT, describe: "What the being does for a living." },
             { name: "stations", ...LINKS, describe: "Stations the being holds." },
-            { name: "peoples", ...LINKS, describe: "Peoples the being belongs to." },
+            {
+                name: "lore",
+                ...LINKS,
+                describe:
+                    "Lore concerning this being — the people it is of, the standing it " +
+                    "holds, the law it lives under.",
+            },
             { name: "homes", ...LINKS, describe: "Places the being calls home." },
             {
                 name: "affiliations",
@@ -425,6 +431,14 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
     }),
 
+    vehicle: Object.freeze({
+        subTypes: null,
+        data: Object.freeze([
+            { name: "portrait", ...TEXT, describe: "Path to the portrait image." },
+            TEMPLATE_PRIORITY,
+        ]),
+    }),
+
     /* ----- items ---------------------------------------------------- */
 
     affiliation: Object.freeze({
@@ -448,6 +462,18 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...TEXT,
                 describe: "What one member is called — a Vylarian.",
             },
+            {
+                name: "epithet",
+                ...TEXT,
+                describe: "The by-name it is known by — a god's, an order's, a company's.",
+            },
+            {
+                name: "symbol",
+                ...TEXT,
+                describe:
+                    "Its emblem in words: a feather atop a golden scale, a chisel carving " +
+                    "a star.",
+            },
             {
                 name: "governance.model",
                 ...TEXT,
@@ -481,7 +507,13 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...LINKS,
                 describe: "What its economic life runs on — currencies, banking bodies, goods.",
             },
-            { name: "peoples", ...LINKS, describe: "Peoples associated with it." },
+            {
+                name: "lore",
+                ...LINKS,
+                describe:
+                    "Lore concerning it — the peoples it draws on, the god a faith " +
+                    "venerates, its law, its calendar.",
+            },
             { name: "parents", ...LINKS, describe: "Affiliations it is subordinate to." },
             {
                 name: "relations",
@@ -532,6 +564,11 @@ export const NOTE_VOCABULARY = Object.freeze({
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR]),
     }),
 
+    armorlocation: Object.freeze({
+        subTypes: null,
+        data: Object.freeze([TEMPLATE_PRIORITY]),
+    }),
+
     attribute: Object.freeze({
         data: Object.freeze([TEMPLATE_PRIORITY]),
     }),
@@ -674,6 +711,86 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     macro: Object.freeze({ data: Object.freeze([]) }),
 
+    lore: Object.freeze({
+        subTypes: Object.freeze([
+            "cosmology",
+            "deity",
+            "theology",
+            "arcana",
+            "spirit",
+            "economy",
+            "law",
+            "calendar",
+            "history",
+            "material",
+            "folk",
+            "culture",
+            "bestiary",
+        ]),
+        // Nothing of its own: a lore note is prose, and what it *is* about is
+        // its subType. The specification declares an empty table for it, and
+        // the authored corpus writes no `data:` key on any of the 180.
+        data: Object.freeze([]),
+    }),
+
+    place: Object.freeze({
+        subTypes: Object.freeze(["world", "region", "settlement", "site", "structure", "feature"]),
+        data: Object.freeze([
+            {
+                name: "demonym",
+                ...TEXT,
+                describe: "What a person from this place is called — a Vylarian.",
+            },
+            {
+                name: "lore",
+                ...LINKS,
+                describe:
+                    "Lore concerning this place — its peoples, its law, its calendar, " +
+                    "its history.",
+            },
+            {
+                name: "parents",
+                ...LINKS,
+                describe: "Enclosing places this one sits within.",
+            },
+            {
+                name: "population",
+                ...NUM,
+                describe: "Approximate population, to two significant digits.",
+            },
+        ]),
+    }),
+
+    scenario: Object.freeze({
+        subTypes: Object.freeze(["campaign", "adventure", "encounter"]),
+        data: Object.freeze([
+            { name: "parents", ...LINKS, describe: "Scenarios this one sits within." },
+            { name: "locations", ...LINKS, describe: "Places the scenario takes place in." },
+            { name: "cast", ...LINKS, describe: "Beings who appear in it." },
+            { name: "factions", ...LINKS, describe: "Affiliations with a stake in it." },
+            {
+                name: "follows",
+                ...LINKS,
+                describe: "Scenarios that should be played before this one.",
+            },
+            {
+                name: "status",
+                ...TEXT,
+                describe: "`draft`, `playtested` or `published`.",
+            },
+            {
+                name: "party.size",
+                ...TEXT,
+                describe: "`solo`, `small`, `standard`, `large` or `host`.",
+            },
+            {
+                name: "party.archetypes",
+                ...LIST,
+                describe: "Archetypes the scenario is written for.",
+            },
+        ]),
+    }),
+
     homepage: Object.freeze({ data: Object.freeze([]) }),
 
     map: Object.freeze({

package/package.json

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

package/sohl/note-schemas.mjs

@@ -87,6 +87,22 @@ const MACRO_FIELDS = Object.freeze([
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
+/**
+ * A `vehicle` note — a conveyance that carries goods and people.
+ *
+ * Empty, and the emptiness is the declaration: the specification gives a
+ * vehicle two `data` properties and no `sohl:` field of its own, and the
+ * closed `data:` container is where `engine/note-vocabulary.mjs` holds them.
+ * Declaring the type with no fields distinguishes a type with no vocabulary
+ * from a type that is unknown, which are different findings (#231).
+ *
+ * It is here rather than in the engine because a vehicle is a SoHL actor —
+ * the specification maps it to `sohl` and marks it NA for hm3.
+ *
+ * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
+ */
+const VEHICLE_FIELDS = Object.freeze([]);
+
 const BEING_FIELDS = Object.freeze([
     {
         name: "body",
@@ -330,5 +346,6 @@ export const NOTE_SCHEMAS = Object.freeze({
     doc: DOC_FIELDS,
     macro: MACRO_FIELDS,
     being: Object.freeze([...BEING_FIELDS, ...PRESENTATION_FIELDS.being]),
+    vehicle: VEHICLE_FIELDS,
     map: MAP_FIELDS,
 });

package/types/engine/note-vocabulary.d.mts

@@ -187,6 +187,10 @@ export const NOTE_VOCABULARY: Readonly<{
         subTypes: null;
         data: readonly DataFieldSpec[];
     }>;
+    vehicle: Readonly<{
+        subTypes: null;
+        data: readonly DataFieldSpec[];
+    }>;
     affiliation: Readonly<{
         subTypes: readonly string[];
         data: readonly DataFieldSpec[];
@@ -198,6 +202,10 @@ export const NOTE_VOCABULARY: Readonly<{
     armorgear: Readonly<{
         data: readonly DataFieldSpec[];
     }>;
+    armorlocation: Readonly<{
+        subTypes: null;
+        data: readonly DataFieldSpec[];
+    }>;
     attribute: Readonly<{
         data: readonly DataFieldSpec[];
     }>;
@@ -256,6 +264,48 @@ export const NOTE_VOCABULARY: Readonly<{
     macro: Readonly<{
         data: readonly never[];
     }>;
+    lore: Readonly<{
+        subTypes: readonly string[];
+        data: readonly never[];
+    }>;
+    place: Readonly<{
+        subTypes: readonly string[];
+        data: readonly ({
+            describe: string;
+            shape: "string";
+            kind: "string";
+            name: string;
+        } | {
+            describe: string;
+            shape: "list of wikilinks";
+            kind: "list";
+            name: string;
+        } | {
+            describe: string;
+            shape: "number";
+            kind: "number";
+            name: string;
+        })[];
+    }>;
+    scenario: Readonly<{
+        subTypes: readonly string[];
+        data: readonly ({
+            describe: string;
+            shape: "list of wikilinks";
+            kind: "list";
+            name: string;
+        } | {
+            describe: string;
+            shape: "string";
+            kind: "string";
+            name: string;
+        } | {
+            describe: string;
+            shape: "list";
+            kind: "list";
+            name: string;
+        })[];
+    }>;
     homepage: Readonly<{
         data: readonly never[];
     }>;