@heroiclands/package-build 18.0.0 → 18.1.1

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @heroiclands/package-build
 
+## 18.1.1
+
+### Patch Changes
+
+- 029cf03: **A homepage note is no longer refused for an `id` it did not author** (#319).
+  
+  `resolveNoteId` fills `fm.id` **in place**, so every downstream reader sees one
+  derived value — deliberate, and documented as such. The homepage refusal
+  iterated that same object, so a note that authors no `id` was reported with a
+  message telling the author to delete a field that is not in the file.
+  
+  It was an **error**, so it failed `lint:addresses`, and `lint` heads the build
+  chain — which meant it failed every pull request opened against a repository
+  carrying a homepage note, whatever that pull request changed.
+  
+  A refused field must now be one the note actually wrote. The caller already owns
+  the raw note text and already positions these findings with it, so it answers
+  which keys are declared at the note's own top level; `positionInFrontmatter`'s
+  `topLevel` option is the existing helper for exactly that question, so a nested
+  `id:` under some other key is not mistaken for the note's own. With no answer
+  supplied, every key in `fm` still counts — the previous behaviour, and the right
+  one for a caller holding authored frontmatter only.
+  
+  Measured on `sohl`: `lint:addresses` goes from one error to **clean across all
+  1,685 notes**.
+
+## 18.1.0
+
+### Minor Changes
+
+- e9a4200: **The gear-suffixed note types are restored** — `armorgear`, `concoctiongear`
+  and `projectilegear` are the vocabulary again, reversing #78.
+  
+  #78 renamed them to `armor`, `concoction` and `projectile`, on the argument that
+  the suffix named the _SoHL document subtype_ a note compiled into rather than
+  the thing the note is about. The argument had a cost the rename did not pay for.
+  
+  **Nothing adopted the bare spellings.** Across all five content trees, every note
+  still authors the suffix — 331 `armorgear` and 18 `projectilegear` in `sohl`, 71
+  `concoctiongear` in `thalorna` — and **not one note anywhere** writes `armor`,
+  `concoction` or `projectile`. The rename produced **349 warnings and zero
+  adopters**, and it was those warnings that made `lint:addresses` noise on every
+  consumer that took 18.0.0.
+  
+  **It also cost a property worth more than the argument.** `weapongear` and
+  `containergear` kept their suffix — SoHL and HM3 both call those documents that —
+  so the rename left three of the five gear types spelled one way and two the
+  other. With it reversed, every SoHL row of the note-type → document-subtype map
+  is the identity again, all fourteen of them, which is what lets two tests drop
+  their exception lists entirely.
+  
+  `RENAMED_TYPES` is reversed rather than emptied, so the bare spellings are still
+  _read_ and _reported_ rather than refused — the same retirement window the
+  rename itself used, pointing the other way. `armorlocation`, the type #78 added,
+  is unaffected: it was new, not renamed.
+
 ## 18.0.0
 
 ### Major Changes

package/docs/content-format.md

@@ -24,11 +24,11 @@ note.** A type that both systems support always shows both system boxes, and a
 box whose system this particular note produces no document for reads
 **"Not available"**.
 
-| note type                                                         | system boxes shown                                 |
-| ----------------------------------------------------------------- | -------------------------------------------------- |
-| `weapon`, `skill`, `being`, `armor`, `containergear`, `miscgear`… | SoHL **and** HM3 — either may read _Not available_ |
-| `affiliation`, `affliction`, `attribute`, `concoction`, `mystery` | SoHL only                                          |
-| `armorlocation`                                                   | HM3 only                                           |
+| note type                                                             | system boxes shown                                 |
+| --------------------------------------------------------------------- | -------------------------------------------------- |
+| `weapon`, `skill`, `being`, `armorgear`, `containergear`, `miscgear`… | SoHL **and** HM3 — either may read _Not available_ |
+| `affiliation`, `affliction`, `attribute`, `concoctiongear`, `mystery` | SoHL only                                          |
+| `armorlocation`                                                       | HM3 only                                           |
 
 This is stated rather than inferred from an empty block, because an absence is a
 poor signal: noticing that something is missing requires already knowing it
@@ -178,7 +178,7 @@ at all in any particular system.
 
 Each system then declares a map from the note's `(type, subType)` onto its own
 document type — and, for SoHL, its own `system.subType`. The map is **declared**,
-never inferred from a coincidence of names: `skill`, `weapongear`, `armor`,
+never inferred from a coincidence of names: `skill`, `weapongear`, `armorgear`,
 `containergear` and `miscgear` exist in both systems with _different_ data
 models, so name-matching there would not fail, it would succeed wrongly.
 
@@ -902,7 +902,7 @@ A fenced `dataview` block is replaced by the table its query selects:
 ````markdown
 ```dataview
 TABLE WITHOUT ID name.full AS "Name", shortcode AS "Code"
-WHERE type = "armor"
+WHERE type = "armorgear"
 ```
 ````
 
@@ -1423,7 +1423,7 @@ If `sohl` is present, this becomes an `affliction` item.
 | `data.healingCheckDurationFormula` | `system.healingCheckDurationFormula` | NA    |
 | `data.resolutionDurationFormula`   | `system.resolutionDurationFormula`   | NA    |
 
-### type: armor
+### type: armorgear
 
 Note: `data.quantity` may not be specified. Quantity is always 1.
 
@@ -1437,9 +1437,7 @@ Note: `data.quantity` may not be specified. Quantity is always 1.
 
 If a `sohl` property is present, a SoHL item of type "armorgear" will be created.
 
-if a `hm3` property is present, an HM3 item of type "armorgear" will be created. The
-note type is `armor` in both cases: the `gear` suffix named a document subtype rather
-than the thing the note is about.
+The note type is `armorgear` in both cases. The `gear` suffix was briefly renamed away on the argument that it named a SoHL document subtype rather than the thing the note is about; that rename is reversed. Nothing had adopted the bare spelling — every note in every tree still writes the suffix — and dropping it from three of the five gear types while `weapongear` and `containergear` kept theirs cost more consistency than the argument bought.
 
 | shared source     | → sohl                  | → hm3           |
 | ----------------- | ----------------------- | --------------- |
@@ -1471,7 +1469,7 @@ if a `sohl` property is present, a SoHL item of type "attribute" will be created
 | shared source | → sohl | → hm3 |
 | ------------- | ------ | ----- |
 
-### type: concoction
+### type: concoctiongear
 
 **subType**:
 
@@ -1624,7 +1622,7 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 | `data.charges.value`    | `system.charges.value`        | NA            |
 | `data.charges.max`      | `system.charges.max`          | NA            |
 
-### type: projectile
+### type: projectilegear
 
 **subTypes**:
 
@@ -1649,7 +1647,7 @@ if a `sohl` property is present, a SoHL item of type "projectilegear" will be cr
 If an `hm3` property is present, then an HM3 item of type "missilegear" will be created.
 
 Note that `weapon` can also produce an HM3 `missilegear`. Since `(type, shortcode)` is a
-flat namespace, a `projectile` and a `weapon` sharing a shortcode would collide on the
+flat namespace, a `projectilegear` and a `weapon` sharing a shortcode would collide on the
 HM3 side while remaining distinct on the SoHL side.
 
 | shared source     | → sohl                  | → hm3             |

package/engine/frontmatter-lint.mjs

@@ -890,7 +890,18 @@ export function lintNote(
     // so the finding must survive the early returns below.
     findings.push(...checkTags(note, { type }));
 
-    for (const { locator, message } of checkHomepageAddressFields(fm)) {
+    // A refused field must be one the note *wrote*: `resolveNoteId` fills
+    // `fm.id` in place, so the parsed frontmatter carries a derived id the
+    // author never typed (#319). The raw text is the only place that
+    // distinguishes them, and `positionInFrontmatter` already answers it —
+    // `topLevel` so a nested `id:` under some other key is not mistaken for the
+    // note's own.
+    const authoredAtTopLevel = (key) =>
+        positionInFrontmatter(note.raw ?? "", key, undefined, { topLevel: true }).line !==
+        undefined;
+    for (const { locator, message } of checkHomepageAddressFields(fm, {
+        isAuthored: authoredAtTopLevel,
+    })) {
         findings.push({
             file: note.file,
             ...at(locator.key, locator.literal),

package/engine/homepage.mjs

@@ -192,12 +192,24 @@ export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
  * belong to the caller. This mirrors {@link module:engine/retired-fields},
  * whose retired-field messages are likewise positioned by whoever reports them.
  *
+ * **A refused field must be one the note *wrote*.** `resolveNoteId` fills
+ * `fm.id` **in place** so every downstream reader sees one derived value —
+ * deliberately, and documented as such — and this ran over the same object, so
+ * a homepage that authors no `id` was told to delete one that is not there
+ * (#319). Since the caller already owns the raw note text, it also answers
+ * which keys the note actually declared; without an answer every key in `fm`
+ * counts, which is the old behaviour and right for a caller holding authored
+ * frontmatter only.
+ *
  * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {object} [options] - Options.
+ * @param {(key: string) => boolean} [options.isAuthored] - Whether the note
+ *   declares this key at its own top level. Defaults to "every key in `fm`".
  * @returns {Array<{field: string, locator: {key: string, literal?: string},
  *   message: string}>} One entry per finding, empty for any note that is not a
  *   homepage and declares nothing wrong.
  */
-export function checkHomepageAddressFields(fm) {
+export function checkHomepageAddressFields(fm, { isAuthored } = {}) {
     if (!isHomepage(fm)) return [];
     const out = [];
 
@@ -218,7 +230,9 @@ export function checkHomepageAddressFields(fm) {
 
     for (const key of Object.keys(fm)) {
         const message = HOMEPAGE_REFUSED_FIELDS.get(key);
-        if (message) out.push({ field: key, locator: { key }, message });
+        if (!message) continue;
+        if (isAuthored && !isAuthored(key)) continue;
+        out.push({ field: key, locator: { key }, message });
     }
     return out;
 }

package/engine/ids.mjs

@@ -186,13 +186,22 @@ export function assertTypeNotRetired(type, where) {
  * reason: a consumer must be able to adopt the new toolchain before its content
  * moves, and there are some 31,000 references to move.
  *
- * **Why these three (#78).** `armorgear`, `concoctiongear` and `projectilegear`
- * named the *SoHL document subtype* a note happened to compile into rather than
- * the thing the note is about. A note's `type` sits outside the `sohl:` and
- * `hm3:` blocks precisely because it belongs to no system, and HM3 already
- * compiles a `projectile` into a `missilegear` — so the suffix was never a fact
- * about the note. `weapongear` keeps its name: SoHL and HM3 both call the
- * document that, and #78's table has no row for it.
+ * **Why these three, and why the other way round now.** #78 renamed
+ * `armorgear`, `concoctiongear` and `projectilegear` to `armor`, `concoction`
+ * and `projectile`, on the argument that the suffix named the *SoHL document
+ * subtype* a note compiled into rather than the thing the note is about. That
+ * rename is **reversed**: the gear-suffixed spellings are the vocabulary, and
+ * the bare ones are what retires.
+ *
+ * Nothing had adopted the bare spellings, which is what makes the reversal
+ * cheap and the direction obvious: across all five content trees, **every note
+ * still authors the suffix** — 331 `armorgear` and 18 `projectilegear` in
+ * `sohl`, 71 `concoctiongear` in `thalorna`, and not one note anywhere writes
+ * `armor`, `concoction` or `projectile`. The rename produced 349 warnings and
+ * zero adopters.
+ *
+ * `weapongear` never moved, and the reversal restores the consistency its
+ * staying put had broken: all five gear types spell the suffix again.
  *
  * **Keyed by the retired spelling**, which is the opposite of
  * `RETIRED_FIELD_ALIASES`. The direction follows the operation: a field alias
@@ -210,9 +219,9 @@ export function assertTypeNotRetired(type, where) {
  * @type {Readonly<Record<string, string>>}
  */
 export const RENAMED_TYPES = Object.freeze({
-    armorgear: "armor",
-    concoctiongear: "concoction",
-    projectilegear: "projectile",
+    armor: "armorgear",
+    concoction: "concoctiongear",
+    projectile: "projectilegear",
 });
 
 /**

package/engine/note-vocabulary.mjs

@@ -590,7 +590,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
     }),
 
-    armor: Object.freeze({
+    armorgear: Object.freeze({
         // Quantity is always one, so the specification refuses the key rather
         // than defaulting it.
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR]),
@@ -605,7 +605,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         data: Object.freeze([TEMPLATE_PRIORITY]),
     }),
 
-    concoction: Object.freeze({
+    concoctiongear: Object.freeze({
         subTypes: Object.freeze(["mundane", "exotic", "elixir"]),
         data: Object.freeze([
             TEMPLATE_PRIORITY,
@@ -680,7 +680,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
     }),
 
-    projectile: Object.freeze({
+    projectilegear: Object.freeze({
         subTypes: Object.freeze(["none", "arrow", "bolt", "bullet", "dart", "other"]),
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR, QUANTITY]),
     }),

package/hm3/default-item-art.mjs

@@ -42,12 +42,12 @@
  * @type {Readonly<Record<string, string>>}
  */
 export const HM3_DEFAULT_ITEM_ART = Object.freeze({
-    armor: "systems/hm3/images/icons/svg/armor.svg",
+    armorgear: "systems/hm3/images/icons/svg/armor.svg",
     armorlocation: "systems/hm3/images/icons/svg/anatomy.svg",
     containergear: "systems/hm3/images/icons/svg/sack.svg",
     miscgear: "systems/hm3/images/icons/svg/miscgear.svg",
     mysticalability: "systems/hm3/images/icons/svg/psionics.svg",
-    projectile: "systems/hm3/images/icons/svg/arrow.svg",
+    projectilegear: "systems/hm3/images/icons/svg/arrow.svg",
     skill: "systems/hm3/images/icons/svg/skills.svg",
     trauma: "systems/hm3/images/icons/svg/injury.svg",
     weapongear: "systems/hm3/images/icons/svg/sword.svg",

package/hm3/document-subtypes.mjs

@@ -89,7 +89,7 @@ export const HM3_TYPE_KEY = "type";
 export const HM3_DOCUMENT_SUBTYPES = defineDocumentSubtypes({
     system: "hm3",
     types: {
-        armor: { document: "Item", subType: "armorgear" },
+        armorgear: { document: "Item", subType: "armorgear" },
         // HM3-only: SoHL resolves a hit location from a being's own body
         // structure, so it has no item of this kind and no note type for one.
         armorlocation: { document: "Item", subType: "armorlocation" },
@@ -97,7 +97,7 @@ export const HM3_DOCUMENT_SUBTYPES = defineDocumentSubtypes({
         miscgear: { document: "Item", subType: "miscgear" },
         // The one outright rename. A note calls it a projectile; HM3 calls the
         // document a missile.
-        projectile: { document: "Item", subType: "missilegear" },
+        projectilegear: { document: "Item", subType: "missilegear" },
         skill: { document: "Item", subType: "skill" },
 
         // ── the four one-to-many rows ───────────────────────────────────────

package/hm3/item-fields.mjs

@@ -127,7 +127,7 @@ const QUANTITY = Object.freeze({
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const HM3_ITEM_FIELDS = Object.freeze({
-    armor: Object.freeze([...GEAR_COMMON]),
+    armorgear: Object.freeze([...GEAR_COMMON]),
 
     // The one subtype that extends the Foundry base directly, with none of the
     // shared templates. Its content-format table has a single row, and that row
@@ -152,7 +152,7 @@ export const HM3_ITEM_FIELDS = Object.freeze({
     // A note's `projectile` is HM3's `missilegear`; the fields are the gear
     // template's, and the aspect, impact and range that make it a missile are
     // authored under `hm3.system`.
-    projectile: Object.freeze([...GEAR_COMMON, QUANTITY]),
+    projectilegear: Object.freeze([...GEAR_COMMON, QUANTITY]),
 
     // `hm3.system.type` — "Craft", "Physical", "Communication", "Combat",
     // "Magic", "Ritual" — has no shared source: the content format states

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "18.0.0",
+    "version": "18.1.1",
     "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/being-info.mjs

@@ -76,11 +76,11 @@ export function isBeing(fm) {
  */
 export const GEAR_TYPE_TO_KEY = Object.freeze({
     weapongear: "weapons",
-    armor: "armor",
-    projectile: "projectiles",
+    armorgear: "armor",
+    projectilegear: "projectiles",
     miscgear: "misc",
     containergear: "containers",
-    concoction: "concoctions",
+    concoctiongear: "concoctions",
 });
 
 /** Whether a value is a plain mapping. */

package/sohl/document-subtypes.mjs

@@ -71,14 +71,14 @@ export const SOHL_DOCUMENT_SUBTYPES = defineDocumentSubtypes({
     types: {
         affiliation: { document: "Item", subType: "affiliation" },
         affliction: { document: "Item", subType: "affliction" },
-        armor: { document: "Item", subType: "armorgear" },
+        armorgear: { document: "Item", subType: "armorgear" },
         attribute: { document: "Item", subType: "attribute" },
-        concoction: { document: "Item", subType: "concoctiongear" },
+        concoctiongear: { document: "Item", subType: "concoctiongear" },
         containergear: { document: "Item", subType: "containergear" },
         miscgear: { document: "Item", subType: "miscgear" },
         mystery: { document: "Item", subType: "mystery" },
         mysticalability: { document: "Item", subType: "mysticalability" },
-        projectile: { document: "Item", subType: "projectilegear" },
+        projectilegear: { document: "Item", subType: "projectilegear" },
         skill: { document: "Item", subType: "skill" },
         trauma: { document: "Item", subType: "trauma" },
         weapongear: { document: "Item", subType: "weapongear" },

package/sohl/item-fields.mjs

@@ -416,7 +416,7 @@ export const ITEM_FIELDS = Object.freeze({
         },
     ]),
 
-    armor: Object.freeze([
+    armorgear: Object.freeze([
         ...GEAR_COMMON,
         {
             name: "material",
@@ -531,7 +531,7 @@ export const ITEM_FIELDS = Object.freeze({
         },
     ]),
 
-    concoction: Object.freeze([
+    concoctiongear: Object.freeze([
         ...GEAR_COMMON,
         {
             name: "subType",
@@ -674,7 +674,7 @@ export const ITEM_FIELDS = Object.freeze({
         },
     ]),
 
-    projectile: Object.freeze([
+    projectilegear: Object.freeze([
         ...GEAR_COMMON,
         {
             name: "subType",

package/sohl/note-schemas.mjs

@@ -244,7 +244,7 @@ const MAP_FIELDS = Object.freeze([
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 const PRESENTATION_FIELDS = Object.freeze({
-    armor: Object.freeze([
+    armorgear: Object.freeze([
         {
             name: "craft",
             ...MAP,
@@ -291,7 +291,7 @@ const PRESENTATION_FIELDS = Object.freeze({
                 "The craft that makes it — `{skill, secondary}` — for knowledgebase grouping.",
         },
     ]),
-    projectile: Object.freeze([
+    projectilegear: Object.freeze([
         {
             name: "craft",
             ...MAP,

package/types/engine/homepage.d.mts

@@ -42,12 +42,26 @@ export function isHomepage(fm: object | null | undefined): boolean;
  * belong to the caller. This mirrors {@link module:engine/retired-fields},
  * whose retired-field messages are likewise positioned by whoever reports them.
  *
+ * **A refused field must be one the note *wrote*.** `resolveNoteId` fills
+ * `fm.id` **in place** so every downstream reader sees one derived value —
+ * deliberately, and documented as such — and this ran over the same object, so
+ * a homepage that authors no `id` was told to delete one that is not there
+ * (#319). Since the caller already owns the raw note text, it also answers
+ * which keys the note actually declared; without an answer every key in `fm`
+ * counts, which is the old behaviour and right for a caller holding authored
+ * frontmatter only.
+ *
  * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {object} [options] - Options.
+ * @param {(key: string) => boolean} [options.isAuthored] - Whether the note
+ *   declares this key at its own top level. Defaults to "every key in `fm`".
  * @returns {Array<{field: string, locator: {key: string, literal?: string},
  *   message: string}>} One entry per finding, empty for any note that is not a
  *   homepage and declares nothing wrong.
  */
-export function checkHomepageAddressFields(fm: object | null | undefined): Array<{
+export function checkHomepageAddressFields(fm: object | null | undefined, { isAuthored }?: {
+    isAuthored?: ((key: string) => boolean) | undefined;
+}): Array<{
     field: string;
     locator: {
         key: string;

package/types/engine/ids.d.mts

@@ -201,13 +201,22 @@ export const RETIRED_TYPES: Readonly<Record<string, string>>;
  * reason: a consumer must be able to adopt the new toolchain before its content
  * moves, and there are some 31,000 references to move.
  *
- * **Why these three (#78).** `armorgear`, `concoctiongear` and `projectilegear`
- * named the *SoHL document subtype* a note happened to compile into rather than
- * the thing the note is about. A note's `type` sits outside the `sohl:` and
- * `hm3:` blocks precisely because it belongs to no system, and HM3 already
- * compiles a `projectile` into a `missilegear` — so the suffix was never a fact
- * about the note. `weapongear` keeps its name: SoHL and HM3 both call the
- * document that, and #78's table has no row for it.
+ * **Why these three, and why the other way round now.** #78 renamed
+ * `armorgear`, `concoctiongear` and `projectilegear` to `armor`, `concoction`
+ * and `projectile`, on the argument that the suffix named the *SoHL document
+ * subtype* a note compiled into rather than the thing the note is about. That
+ * rename is **reversed**: the gear-suffixed spellings are the vocabulary, and
+ * the bare ones are what retires.
+ *
+ * Nothing had adopted the bare spellings, which is what makes the reversal
+ * cheap and the direction obvious: across all five content trees, **every note
+ * still authors the suffix** — 331 `armorgear` and 18 `projectilegear` in
+ * `sohl`, 71 `concoctiongear` in `thalorna`, and not one note anywhere writes
+ * `armor`, `concoction` or `projectile`. The rename produced 349 warnings and
+ * zero adopters.
+ *
+ * `weapongear` never moved, and the reversal restores the consistency its
+ * staying put had broken: all five gear types spell the suffix again.
  *
  * **Keyed by the retired spelling**, which is the opposite of
  * `RETIRED_FIELD_ALIASES`. The direction follows the operation: a field alias

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

@@ -199,7 +199,7 @@ export const NOTE_VOCABULARY: Readonly<{
         subTypes: readonly string[];
         data: readonly DataFieldSpec[];
     }>;
-    armor: Readonly<{
+    armorgear: Readonly<{
         data: readonly DataFieldSpec[];
     }>;
     armorlocation: Readonly<{
@@ -209,7 +209,7 @@ export const NOTE_VOCABULARY: Readonly<{
     attribute: Readonly<{
         data: readonly DataFieldSpec[];
     }>;
-    concoction: Readonly<{
+    concoctiongear: Readonly<{
         subTypes: readonly string[];
         data: readonly (DataFieldSpec | Readonly<{
             describe: "How many of the thing there are; one when unstated.";
@@ -237,7 +237,7 @@ export const NOTE_VOCABULARY: Readonly<{
         subTypes: readonly string[];
         data: readonly DataFieldSpec[];
     }>;
-    projectile: Readonly<{
+    projectilegear: Readonly<{
         subTypes: readonly string[];
         data: readonly (DataFieldSpec | Readonly<{
             describe: "How many of the thing there are; one when unstated.";