@heroiclands/package-build 16.0.0 → 17.0.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @heroiclands/package-build
 
+## 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/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.0.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[];
     }>;