@heroiclands/package-build 18.1.0 → 18.1.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @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

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/package.json

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