@heroiclands/package-build 3.3.0 → 4.0.0

package/engine/journals.mjs

@@ -38,9 +38,8 @@
  * Not a standalone script — exports the `Journals` compiler class, imported
  * and driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
- * The walk itself — filtering by package and type, skipping drafts,
- * expanding tables, converting wikilinks, writing the JSON and counting
- * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * The walk itself — filtering by type, expanding tables, converting
+ * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
  * states only what makes this pass its own (#1509).
  */
 

package/engine/macros.mjs

@@ -44,9 +44,8 @@
  * Not a standalone script — exports the `Macros` compiler class, imported and
  * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
- * The walk itself — filtering by package and type, skipping drafts,
- * expanding tables, converting wikilinks, writing the JSON and counting
- * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * The walk itself — filtering by type, expanding tables, converting
+ * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
  * states only what makes this pass its own (#1509).
  */
 

package/engine/manifest-emit.mjs

@@ -54,7 +54,8 @@ import { canonicalKey, writeManifests } from "./kb-manifest.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { compendiumUuid, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
-import { assertNotePackage } from "./note-package.mjs";
+import { assertNoDeclaredPackage } from "./note-package.mjs";
+import { assertNoDraftField } from "./retired-fields.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
@@ -193,14 +194,13 @@ export function entriesForNote(fm, name, address, body, ctx) {
 /**
  * Every note this package publishes, as manifest entries.
  *
- * Drafts are excluded because the site does not publish them, and an entry for
- * an unpublished page is exactly the dead link the manifest exists to prevent.
- *
- * Every note in the tree is this package's note, whether or not it says so:
- * `package:` is optional and merely has to agree (#56). A note naming a
- * different package **throws** rather than being skipped — this build is not
- * authoritative for it, and skipping it silently is how a whole tree came to be
- * filtered out of a manifest that then claimed the package published nothing.
+ * Every note in the tree is this package's, so nothing here selects by package:
+ * the key's first segment is `contentPackage` (#56). A note still declaring the
+ * retired `package:` or `draft:` field **throws** rather than being skipped —
+ * skipping one silently is how a whole tree came to be filtered out of a
+ * manifest that then claimed the package published nothing, and it is what let
+ * a drafted note's inbound links look like links to a note that never existed
+ * (#69).
  *
  * A note that has no address is **reported, not guessed** — the finding carries
  * the file and the reason, so a caller can print it or fail on it. Inventing an
@@ -226,8 +226,12 @@ export function collectManifestEntries(contentBase, ctx) {
     )) {
         if (!fm) continue;
         const rel = path.relative(contentBase, absPath);
-        assertNotePackage(fm, { file: rel, configured: ctx.contentPackage });
-        if (fm.draft === true) continue;
+        assertNoDeclaredPackage(fm, {
+            file: rel,
+            absPath,
+            configured: ctx.contentPackage,
+        });
+        assertNoDraftField(fm, { file: rel, absPath });
         if (!fm.type || !fm.shortcode) continue;
 
         const base = path.basename(absPath);

package/engine/note-package.mjs

@@ -14,10 +14,10 @@
 /**
  * Which content package a note belongs to.
  *
- * **It is the repository's configured `contentPackage`.** A content tree holds
- * exactly one package's notes — every package is single-sourced in the
- * repository that ships it — so the package is a property of the *repository*,
- * not of the note.
+ * **It is the repository's configured `contentPackage`, and nothing else.** A
+ * content tree holds exactly one package's notes — every package is
+ * single-sourced in the repository that ships it — so the package is a property
+ * of the *repository*, not of the note, and no note declares it.
  *
  * It used to be a property of the note, and a **selector**: the compile loop
  * read `package:` out of frontmatter and skipped anything that did not match
@@ -27,100 +27,107 @@
  * **zero notes and exited 0** — which is exactly the state the un-migrated
  * `hm-loc-*` / `hm-adv-*` repositories are in today.
  *
- * So the field is being retired, in three steps, of which this is the first:
+ * The field was retired in three steps, and all three have landed:
  *
- * 1. **Optional here.** An absent `package:` is normal and the note compiles; a
- *    present one is accepted while it agrees, and is a loud, named error when
- *    it does not. Non-breaking, so a consumer adopts it before changing a note.
- * 2. **Swept** out of every content tree in the org, on this version.
- * 3. **Rejected outright**, as a major, once the sweeps have merged.
+ * 1. **Optional** (3.3.0). An absent `package:` was normal and a present one
+ *    was accepted while it agreed. Non-breaking, so a consumer adopted it
+ *    before changing a note.
+ * 2. **Swept** out of every content tree on the org — 6,235 notes across
+ *    `sohl`, `thalorna`, `kethira` and `harnensemble`.
+ * 3. **Rejected outright**, as this major. A note declaring the field fails the
+ *    build naming the file, whatever the value says.
  *
- * The distinction between the two functions here is which question is being
- * asked. {@link assertNotePackage} is for a site that used to *select* — it
- * answers "may this build compile this note", and a disagreement is a finding.
- * {@link notePackage} is for a site that *derives an address* — it answers
- * "which package's namespace does this address sit in", where a disagreement
- * has already been reported by the compile pass and repeating it would print
- * the same fault twice.
+ * Step 3 is deliberately a rejection rather than continued tolerance: a field
+ * accepted while it agrees is a field that grows back, one note at a time, and
+ * every one of them is a line restating a constant the configuration already
+ * carries. There is no value that makes writing it correct, so the diagnostic
+ * says what to write instead rather than which value to change.
+ *
+ * **One `package` survives, and it is synthesised.** A `dataview` table scopes
+ * itself with `WHERE … and package = "<pkg>"`, and that clause resolves against
+ * frontmatter like any other field. {@link searchableFrontmatter} supplies the
+ * derived value to the search so the 45 authored clauses across `sohl` and
+ * `thalorna` keep matching. It is a *search* value, never an authored one, and
+ * it is never written back to a note.
  *
  * @module
  */
 
 import { contentPackage } from "./content-package.mjs";
+import { locateFrontmatterKey } from "./retired-fields.mjs";
 
 /**
- * The package a note belongs to.
- *
- * Non-validating: the answer for a note that declares nothing, and for one that
- * declares the configured package, is the same value. A note declaring some
- * *other* package is answered literally here rather than corrected — the
- * compile pass reports that, once, through {@link assertNotePackage}.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {string} [configured] - The package this build compiles. Defaults to
- *   the configured `contentPackage`; passed explicitly by callers that already
- *   carry it in a context object, so a caller's configuration drives every read.
- * @returns {string} The package.
- */
-export function notePackage(fm, configured) {
-    const declared = fm?.package;
-    // A blank is a declaration of nothing, not a package named "".
-    if (declared != null && declared !== "") return declared;
-    // Resolved only when it is needed, so a caller holding a note that declares
-    // one never touches the configuration (#2).
-    return configured ?? contentPackage();
-}
-
-/**
- * A note's frontmatter as a generated table searches it — its package present
- * whether or not the note declares one.
+ * A note's frontmatter as a generated table searches it — its package present,
+ * though no note declares one.
  *
  * A `dataview` query resolves `package` out of frontmatter like any other
  * field, so a collection note that scopes itself with `WHERE … and package =
- * "sohl"` matches nothing once the field is deleted, and renders an **empty
- * table** in silence. Deriving the value here keeps the two spellings
- * equivalent, so a sweep that deletes the field is mechanical rather than a
- * trap (#56) — and a query that never mentions `package` is unaffected either
- * way.
+ * "sohl"` would match nothing now that the field is gone, and would render an
+ * **empty table** in silence. Supplying the derived value here is what kept the
+ * sweep mechanical rather than a trap (#56) — and a query that never mentions
+ * `package` is unaffected either way.
  *
- * The declared value is left alone when there is one, so nothing about an
- * unswept tree changes.
+ * The frontmatter is copied rather than written into: it is the note's own
+ * parsed object, shared with every other reader, and the derived package is a
+ * property of *this search*, not of the note.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
- * @param {string} [configured] - The package this build compiles.
- * @returns {object|null|undefined} The frontmatter itself when it declares a
- *   package, else a shallow copy carrying the derived one.
+ * @param {string} [configured] - The package this build compiles. Defaults to
+ *   the configured `contentPackage`; passed explicitly by callers that already
+ *   carry it in a context object, so a caller's configuration drives every read.
+ * @returns {object|null|undefined} A shallow copy carrying the derived package,
+ *   or whatever was passed when it is not frontmatter at all.
  */
 export function searchableFrontmatter(fm, configured) {
     if (!fm || typeof fm !== "object") return fm;
-    if (fm.package != null && fm.package !== "") return fm;
-    return { ...fm, package: notePackage(fm, configured) };
+    return { ...fm, package: configured ?? contentPackage() };
 }
 
 /**
- * The package a note belongs to, refusing one that names another package.
+ * Refuse a note that declares `package:` at all.
  *
- * @param {object|null|undefined} fm - Parsed frontmatter.
+ * Presence is the whole test — a declaration that *agrees* with the
+ * configuration is as retired as one that disagrees, and an empty one
+ * (`package:`, which parses as `null`) is still the field.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
  * @param {object} [options] - Options.
  * @param {string} [options.file] - The note's path, named in the message. Omit
  *   it where the caller emits through a diagnostic, which puts the locator at
  *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
  * @param {string} [options.configured] - The package this build compiles.
  *   Defaults to the configured `contentPackage`.
- * @returns {string} The package, which is always `configured`.
- * @throws {Error} When the note declares a different package.
+ * @returns {void}
+ * @throws {Error} When the note declares the field.
  */
-export function assertNotePackage(fm, { file, configured } = {}) {
+export function assertNoDeclaredPackage(
+    fm,
+    { file, absPath, configured } = {},
+) {
+    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "package")) return;
+
     const target = configured ?? contentPackage();
-    const pkg = notePackage(fm, target);
-    if (pkg === target) return target;
-    throw new Error(
-        `note declares \`package: ${pkg}\`, but this repository compiles ` +
-            `"${target}"` +
+    const declared = fm.package;
+    const wrote =
+        declared === null || declared === undefined || declared === "" ?
+            "`package:`"
+        :   `\`package: ${declared}\``;
+
+    const err = new Error(
+        `${wrote} is a retired frontmatter field — delete it` +
             (file ? ` — ${file}` : "") +
-            `. A note's package is the configured \`contentPackage\`, so the ` +
-            `field is redundant and is being retired: delete it, or correct ` +
-            `\`contentPackage\` in package-build.config.yaml.`,
+            `. A note's package is this repository's configured ` +
+            `\`contentPackage\` ("${target}", in package-build.config.yaml), ` +
+            `and every note in the tree belongs to it.`,
     );
+    // Where the field is, so the caller's diagnostic opens on the line that has
+    // to be deleted. Read here rather than carried through every walk: this is
+    // the failing path, and the build stops on it.
+    const position = locateFrontmatterKey(absPath, "package");
+    if (position) err.position = position;
+    throw err;
 }

package/engine/pack-router.mjs

@@ -69,10 +69,10 @@ export class PackRoutingError extends Error {
 /**
  * The frontmatter field a note declares its pack in.
  *
- * Deliberately close to the retiring `package:` and deliberately not the same
+ * Deliberately close to the retired `package:` and deliberately not the same
  * word: `package:` said which *distribution* owned a note — now the
- * repository's `contentPackage` (#56) — while `pack:` says which *compendium*
- * receives its document.
+ * repository's `contentPackage`, and no longer authorable (#56) — while `pack:`
+ * says which *compendium* receives its document.
  */
 export const PACK_FIELD = "pack";
 

package/engine/retired-fields.mjs

@@ -0,0 +1,123 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Frontmatter fields a note may no longer declare.
+ *
+ * A retired field has exactly two possible fates, and only one of them is
+ * honest. Left honoured, it keeps doing whatever it did — which is why it was
+ * retired. Left *ignored*, it reads to its author as though it still works: the
+ * note says one thing and the build does another, and nothing says so. So a
+ * retired field is **refused**, naming the file and the line, and the message
+ * says what to write instead rather than which value to correct.
+ *
+ * `package:` is retired the same way and is refused from `note-package.mjs`,
+ * where the concept it belonged to still lives. `draft:` has no such home —
+ * there is no surviving concept it was part of — so it is refused here.
+ *
+ * **What `draft:` did (#69).** It excluded a note from the compiled packs, from
+ * the link manifest and from a consuming site build. Nothing reported the
+ * consequence: `content-links.mjs`, `site-index.mjs` and `content-lint.mjs`
+ * never read the field, so a link into a drafted note was indistinguishable
+ * from a link to a note that does not exist, and the checkers could not say
+ * which. The field's entire effect was to move a note from *published* to
+ * *unresolvable*, silently — and it also suppressed real build failures, since
+ * a note the compilers never reached could not fail on the defects it carried.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+
+import { positionInFrontmatter } from "./diagnostics.mjs";
+
+/**
+ * What a note declaring `draft:` is told, in one place.
+ *
+ * Written once and shared by the compile-time refusal and the frontmatter lint,
+ * because an author meets whichever of the two runs first and they should read
+ * the same. It says what the field did and what to write instead, rather than
+ * which value to correct: no value makes declaring it right.
+ *
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function draftRetiredMessage(file) {
+    return (
+        "`draft:` is a retired frontmatter field — delete it" +
+        (file ? ` — ${file}` : "") +
+        ". It excluded the note from the compiled packs, the link manifest " +
+        "and the site, and no checker reported the exclusion, so every " +
+        "wikilink into it read as a link to a note that does not exist. To " +
+        "mark a note as unfinished, tag it `#draft` instead: the build " +
+        "ignores tags, and a `FROM #draft` query still finds it"
+    );
+}
+
+/**
+ * Refuse a note that declares `draft:` at all.
+ *
+ * Presence is the whole test. `draft: false` is as retired as `draft: true` —
+ * it reads as "publish this note", which is what happens either way, and is
+ * exactly the belief the message exists to correct.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note declares the field.
+ */
+export function assertNoDraftField(fm, { file, absPath } = {}) {
+    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "draft")) return;
+
+    const err = new Error(`${draftRetiredMessage(file)}.`);
+    // Where the field is, so the caller's diagnostic opens on the line that has
+    // to be deleted. Read here rather than carried through every walk: this is
+    // the failing path, and the build stops on it.
+    const position = locateFrontmatterKey(absPath, "draft");
+    if (position) err.position = position;
+    throw err;
+}
+
+/**
+ * A frontmatter key's position in a note's file, or nothing.
+ *
+ * {@link positionInFrontmatter} answers the same question from the file's
+ * *text*; this reads the file to ask it. Kept apart from either caller because
+ * both refusals need it and a second copy is a second thing to keep correct.
+ *
+ * @param {string|undefined} absPath - The note's file.
+ * @param {string} key - The top-level frontmatter key.
+ * @returns {{line?: number, column?: number}|undefined} Spreadable position
+ *   fields, dropped rather than guessed when the file cannot be read or the key
+ *   cannot be found — as `formatDiagnostic` requires.
+ */
+export function locateFrontmatterKey(absPath, key) {
+    if (!absPath) return undefined;
+    let raw;
+    try {
+        raw = fs.readFileSync(absPath, "utf8");
+    } catch {
+        return undefined;
+    }
+    const at = positionInFrontmatter(raw, key);
+    return at.line === undefined ? undefined : at;
+}

package/engine/scenes.mjs

@@ -42,9 +42,8 @@
  * Not a standalone script — exports the `Scenes` compiler class, imported and
  * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
- * The walk itself — filtering by package and type, skipping drafts,
- * expanding tables, converting wikilinks, writing the JSON and counting
- * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * The walk itself — filtering by type, expanding tables, converting
+ * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
  * states only what makes this pass its own (#1509).
  */
 
@@ -192,10 +191,11 @@ export class Scenes extends BasePackCompiler {
         for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(
             this.contentBase,
         )) {
-            // No package test: every note in the tree is this package's, and
-            // this pass's own walk — the shared compile loop — is where a note
-            // declaring another one is reported, once (#56). Repeating the
-            // check here would either double the diagnostic or throw past it.
+            // No retired-field test: this pass's own walk — the shared compile
+            // loop — is where a note still declaring `package:` (#56) or
+            // `draft:` (#69) is reported, once. Repeating either check here
+            // would double the diagnostic or throw past it. A refused note is
+            // indexed and then never compiled, so it reaches no document.
             if (!fm || !fm.id) continue;
             if (
                 fm.shortcode &&
@@ -216,10 +216,6 @@ export class Scenes extends BasePackCompiler {
                 });
             }
             if (!isMapType(fm.type)) continue;
-            if (fm.draft === true) {
-                log.debug(`Skipping draft map: ${absPath}`);
-                continue;
-            }
             maps.push({ fm, body, absPath });
         }
         return { maps, effectsByAddress };

package/engine/site-build.mjs

@@ -62,7 +62,7 @@ import {
 } from "./foreign-manifests.mjs";
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
-import { notePackage, searchableFrontmatter } from "./note-package.mjs";
+import { searchableFrontmatter } from "./note-package.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -132,11 +132,10 @@ export function collectContentPages(contentBase, ctx) {
         const note = readNote(file);
         if (!note) continue;
         const { fm, body } = note;
-        // Derived rather than read: `package:` is optional, and a note that
-        // declares nothing belongs to the package this repository compiles
-        // (#56). Once the field is retired outright this collapses to
-        // `ctx.contentPackage` and the set membership becomes a formality.
-        const pkg = notePackage(fm, ctx.contentPackage);
+        // The configuration's, never a note's: `package:` is retired, so every
+        // note in the tree belongs to the package this repository compiles
+        // (#56).
+        const pkg = ctx.contentPackage;
         if (!ctx.packages.has(pkg) || !fm.type) continue;
 
         for (const hit of frontmatterWikilinks(fm)) {
@@ -162,9 +161,9 @@ export function collectContentPages(contentBase, ctx) {
         pages.push({
             kind: "content",
             fm,
-            // The page's package, resolved once here so every consumer — the
+            // The page's package, recorded once here so every consumer — the
             // index's canonical keys, the table universe, the local-package set
-            // — reads one derived value instead of frontmatter (#56).
+            // — reads one configured value and never frontmatter (#56).
             pkg,
             body,
             name,
@@ -347,7 +346,8 @@ export function tableUniverse(pages) {
         const pkg = p.pkg;
         if (!byPackage.has(pkg)) byPackage.set(pkg, []);
         byPackage.get(pkg).push({
-            // Package present however the note spells it — see
+            // Package present for a `WHERE … package = "…"` clause,
+            // synthesised rather than authored — see
             // {@link searchableFrontmatter} (#56).
             fm: searchableFrontmatter(p.fm, pkg),
             path: p.relPath,
@@ -367,6 +367,16 @@ export function tableUniverse(pages) {
  * redirect stub at each name. They are dropped, and this build emits no
  * redirects of its own.
  *
+ * A content page carries the package the build **derived** (#65). No note
+ * declares one — `package:` is retired (#56) — so the note's frontmatter alone
+ * would publish a page that does not say which package it belongs to. The
+ * emitted page is what a
+ * theme reads: `breadcrumbs.html` builds its middle crumb from
+ * `.Params.package`, so without it that crumb degrades from a linked, labelled
+ * section to a bare type slug. Writing the derived value keeps a page
+ * self-describing and makes sweeping the field out of a content tree
+ * output-preserving for a site as it already is for the packs.
+ *
  * @param {object} page - The page.
  * @param {object} options - `{ sections, readmeSections, decorate }`.
  * @returns {object} The frontmatter to write.
@@ -375,7 +385,15 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
     const { fm, name, slug, sec, isReadme } = page;
     let data;
     if (page.kind === "content") {
-        data = { ...fm, slug, title: fm.title ?? name, kbfolder: page.folder };
+        data = {
+            ...fm,
+            // Spread after the note's own frontmatter. Guarded because
+            // `package: undefined` is not a value YAML can carry.
+            ...(page.pkg ? { package: page.pkg } : {}),
+            slug,
+            title: fm.title ?? name,
+            kbfolder: page.folder,
+        };
         if (decorate) decorate(data, page);
         if (isReadme) {
             const meta = readmeSections[sec];
@@ -714,7 +732,8 @@ export function buildSite({ config, outRoot } = {}) {
 
     const ctx = {
         packages,
-        // What a note that declares no `package:` belongs to (#56).
+        // The package every note in the tree belongs to. `package:` is
+        // retired, so this is the only source of it (#56).
         contentPackage: resolved.contentPackage,
         skipDirectories: resolved.skipDirectories,
         mount,

package/engine/site-index.mjs

@@ -53,7 +53,7 @@ import path from "node:path";
 
 import { canonicalKey, readCanonicalKey } from "./kb-manifest.mjs";
 import { hasDocEntry } from "./item-docs.mjs";
-import { notePackage } from "./note-package.mjs";
+import { contentPackage } from "./content-package.mjs";
 
 /**
  * One page the site will publish, as the index needs to see it.
@@ -239,11 +239,11 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             // stays because a bare `[[skill-lang]]` defaults to the citing
             // note's own package and must keep resolving unchanged; the
             // canonical form is what cross-package links use (#1499).
-            // The page's package is derived — the site collection resolves it
-            // and records it as `pkg` — rather than read out of frontmatter,
-            // where `package:` is optional and on its way out (#56).
+            // The page's package is the configured one — the site collection
+            // resolves it and records it as `pkg`. Never read out of
+            // frontmatter: `package:` is retired (#56).
             index.set(
-                canonicalKey(e.pkg ?? notePackage(e.fm), type, shortcode),
+                canonicalKey(e.pkg ?? contentPackage(), type, shortcode),
                 value,
             );
             // In Foundry an item and its documentation are two documents, so

package/package.json

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

@@ -34,9 +34,8 @@
  * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`). Must run
  * after the items pass, since it reads the items pack's generated JSON tree.
  *
- * The walk itself — filtering by package and type, skipping drafts,
- * expanding tables, converting wikilinks, writing the JSON and counting
- * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * The walk itself — filtering by type, expanding tables, converting
+ * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
  * states only what makes this pass its own (#1509).
  */
 

package/sohl/item-fields.mjs

@@ -598,14 +598,6 @@ export const ITEM_FIELDS = Object.freeze({
             describe:
                 "Shortcode of the affiliation whose standing confers the ability — a religion, school, or ancestor/totem/spirit.",
         },
-        {
-            name: "assocMysteryCode",
-            to: "assocMysteryCode",
-            ref: "mystery",
-            ...AS_AUTHORED,
-            default: "",
-            describe: "Shortcode of the mystery the ability draws on.",
-        },
         {
             name: "masteryLevelBase",
             to: "masteryLevelBase",

package/sohl/items.mjs

@@ -29,9 +29,8 @@
  * Not a standalone script — exports the `Items` compiler class, imported and
  * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
- * The walk itself — filtering by package and type, skipping drafts,
- * expanding tables, converting wikilinks, writing the JSON and counting
- * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * The walk itself — filtering by type, expanding tables, converting
+ * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
  * states only what makes this pass its own (#1509).
  */