@heroiclands/package-build 3.2.0 → 3.4.0

package/engine/manifest-emit.mjs

@@ -54,6 +54,7 @@ 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 { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
@@ -194,9 +195,12 @@ export function entriesForNote(fm, name, address, body, ctx) {
  *
  * 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.
- * A note belonging to another content package is skipped for the same reason in
- * reverse: this build is not authoritative for it, and its own build says where
- * it lives.
+ *
+ * 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.
  *
  * 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
@@ -220,11 +224,12 @@ export function collectManifestEntries(contentBase, ctx) {
         contentBase,
         { skipDirectories: ctx.skipDirectories },
     )) {
-        if (!fm || fm.package !== ctx.contentPackage) continue;
+        if (!fm) continue;
+        const rel = path.relative(contentBase, absPath);
+        assertNotePackage(fm, { file: rel, configured: ctx.contentPackage });
         if (fm.draft === true) continue;
         if (!fm.type || !fm.shortcode) continue;
 
-        const rel = path.relative(contentBase, absPath);
         const base = path.basename(absPath);
         const name = fm.name?.full ?? path.basename(absPath, ".md");
 

package/engine/note-package.mjs

@@ -0,0 +1,126 @@
+/*
+ * 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
+ */
+
+/**
+ * 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 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
+ * the configured value. That is the defect this module exists to remove
+ * (#56). The skip was silent and it was bucketed as "belongs to another pass",
+ * so a tree whose notes named a package no configuration answered to compiled
+ * **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:
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @module
+ */
+
+import { contentPackage } from "./content-package.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 `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.
+ *
+ * The declared value is left alone when there is one, so nothing about an
+ * unswept tree changes.
+ *
+ * @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.
+ */
+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) };
+}
+
+/**
+ * The package a note belongs to, refusing one that names another package.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @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.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.
+ */
+export function assertNotePackage(fm, { file, configured } = {}) {
+    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}"` +
+            (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.`,
+    );
+}

package/engine/pack-router.mjs

@@ -69,8 +69,9 @@ export class PackRoutingError extends Error {
 /**
  * The frontmatter field a note declares its pack in.
  *
- * Deliberately close to `package:` and deliberately not the same word: a note's
- * `package:` says which *distribution* owns it, `pack:` which *compendium*
+ * Deliberately close to the retiring `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.
  */
 export const PACK_FIELD = "pack";

package/engine/scenes.mjs

@@ -63,7 +63,7 @@ import { BasePackCompiler } from "./base-compiler.mjs";
 import { buildJournalEntry, splitPages, journalPageId } from "./journals.mjs";
 import { compendiumUuid, makeId, packForType } from "./ids.mjs";
 import { packRouter } from "./pack-router.mjs";
-import { contentPackage, foundryPackageId } from "./content-package.mjs";
+import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
 import {
     behaviorDocId,
@@ -192,7 +192,11 @@ export class Scenes extends BasePackCompiler {
         for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(
             this.contentBase,
         )) {
-            if (!fm || fm.package !== contentPackage() || !fm.id) continue;
+            // 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.
+            if (!fm || !fm.id) continue;
             if (
                 fm.shortcode &&
                 Array.isArray(fm.effects) &&

package/engine/site-build.mjs

@@ -62,6 +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";
 
 const require = createRequire(import.meta.url);
 
@@ -117,7 +118,9 @@ function readNote(file) {
  * The content tree's pages, and what could not be addressed.
  *
  * @param {string} contentBase - Absolute path to the content tree.
- * @param {object} ctx - `{ packages, skipDirectories, mount, scheme }`.
+ * @param {object} ctx - `{ packages, contentPackage, skipDirectories, mount,
+ *   scheme }`. `contentPackage` is the package a note that declares none
+ *   belongs to.
  * @returns {{pages: object[], slugFindings: object[], fmLinkFindings: object[]}}
  */
 export function collectContentPages(contentBase, ctx) {
@@ -129,7 +132,12 @@ export function collectContentPages(contentBase, ctx) {
         const note = readNote(file);
         if (!note) continue;
         const { fm, body } = note;
-        if (!ctx.packages.has(fm.package) || !fm.type) continue;
+        // 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);
+        if (!ctx.packages.has(pkg) || !fm.type) continue;
 
         for (const hit of frontmatterWikilinks(fm)) {
             fmLinkFindings.push({ file, ...hit });
@@ -154,6 +162,10 @@ export function collectContentPages(contentBase, ctx) {
         pages.push({
             kind: "content",
             fm,
+            // The page's package, resolved 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).
+            pkg,
             body,
             name,
             slug,
@@ -287,7 +299,7 @@ export function siteGates(pages, findings, { manifestDir }) {
     // and that is only known once the tree is walked — reading it from a
     // configured list instead silently discarded the manifest of any package
     // the list named but the tree did not contain.
-    const localPackages = new Set(content.map((p) => p.fm.package));
+    const localPackages = new Set(content.map((p) => p.pkg));
     const foreign = loadForeignManifests(manifestDir, localPackages);
     out.foreign = foreign;
     if (foreign.stale.length) {
@@ -332,10 +344,12 @@ export function tableUniverse(pages) {
     const byPackage = new Map();
     for (const p of pages) {
         if (p.kind !== "content") continue;
-        const pkg = p.fm.package;
+        const pkg = p.pkg;
         if (!byPackage.has(pkg)) byPackage.set(pkg, []);
         byPackage.get(pkg).push({
-            fm: p.fm,
+            // Package present however the note spells it — see
+            // {@link searchableFrontmatter} (#56).
+            fm: searchableFrontmatter(p.fm, pkg),
             path: p.relPath,
             tld: p.tld,
             folder: p.folder,
@@ -353,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**, whether or not the
+ * note declared one (#65). `package:` became optional in 3.3.0, so a swept tree
+ * declares none — and the note's frontmatter alone would then 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.
@@ -361,7 +385,17 @@ 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, so a note that declares
+            // the field keeps its authored position and value and an unswept
+            // tree emits byte-identically. 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];
@@ -457,10 +491,13 @@ export function renderPages(pages, options) {
         let body = page.body;
         if (page.kind === "content") {
             const { markdown, errors } = expandContentTables(body, {
-                docs: universe.get(page.fm.package) ?? [],
+                docs: universe.get(page.pkg) ?? [],
                 linkable,
                 source: src,
-                self: { fm: page.fm, path: page.relPath },
+                self: {
+                    fm: searchableFrontmatter(page.fm, page.pkg),
+                    path: page.relPath,
+                },
             });
             tableErrors.push(...errors);
             body = markdown;
@@ -697,6 +734,8 @@ export function buildSite({ config, outRoot } = {}) {
 
     const ctx = {
         packages,
+        // What a note that declares no `package:` belongs to (#56).
+        contentPackage: resolved.contentPackage,
         skipDirectories: resolved.skipDirectories,
         mount,
         scheme,

package/engine/site-index.mjs

@@ -53,6 +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";
 
 /**
  * One page the site will publish, as the index needs to see it.
@@ -238,7 +239,13 @@ 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).
-            index.set(canonicalKey(e.fm.package, type, shortcode), value);
+            // 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).
+            index.set(
+                canonicalKey(e.pkg ?? notePackage(e.fm), type, shortcode),
+                value,
+            );
             // In Foundry an item and its documentation are two documents, so
             // `skill/wpnc` and `docskill/wpnc` are two UUIDs (#1362). Here the
             // item note renders as one page which *is* its documentation, so

package/package.json

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

@@ -55,6 +55,7 @@ import {
     md,
 } from "../engine/helpers.mjs";
 import { emitDiagnostic } from "../engine/diagnostics.mjs";
+import { openingMasteryLevel } from "./skill-base.mjs";
 import { BasePackCompiler } from "../engine/base-compiler.mjs";
 import { contentPackage } from "../engine/content-package.mjs";
 
@@ -498,9 +499,63 @@ export class Actors extends BasePackCompiler {
             });
         }
 
+        this.openUnopenedSkills(items, ctx);
         return items;
     }
 
+    /**
+     * Bake each unopened skill's opening mastery level into the document (#46).
+     *
+     * A skill whose `masteryLevelBase` is still null once the note's frontmatter
+     * has been merged onto the catalogue entry is *not yet opened*, and the
+     * client fills it in on import — `Skill Base × initSkillMult`, in
+     * `SkillLogic.initialize`. Computing it here instead leaves the compiled
+     * pack self-describing: what a being's skills open at is visible in the
+     * document, reviewable in a diff, and testable without standing up Foundry.
+     *
+     * This runs last because the Skill Base formula reads the actor's
+     * attributes, so every attribute item has to exist first. It only ever
+     * fills nulls — a skill that states a `masteryLevelBase`, whether from the
+     * catalogue or the note, keeps it untouched.
+     *
+     * **The scores used are the ones just written.** `SkillLogic` resolves
+     * `attr.<code>` to an attribute's *effective* score, after active effects;
+     * all this pass has is the `scoreBase` it set from `sohl.attributes`. For a
+     * compiled being carrying no attribute-altering effects the two agree,
+     * which is every being in content today. One that did carry such an effect
+     * would bake a Skill Base its client then disagrees with — that is the
+     * limit of doing this at build time, and the point to revisit if it bites.
+     *
+     * @param {object[]} items - The actor's embedded items, attributes included.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     */
+    openUnopenedSkills(items, ctx) {
+        const skills = items.filter(
+            (item) =>
+                item.type === "skill" &&
+                item.system &&
+                item.system.masteryLevelBase == null,
+        );
+        if (!skills.length) return;
+
+        const attrs = {};
+        for (const item of items) {
+            if (item.type !== "attribute") continue;
+            const code = item.system?.shortcode?.toLowerCase();
+            if (code) attrs[code] = Number(item.system.scoreBase) || 0;
+        }
+
+        for (const skill of skills) {
+            const { value, error } = openingMasteryLevel(skill.system, attrs);
+            if (error) {
+                this.noteError(`${ctx}: skill "${skill.name}": ${error}`);
+                this.errorCount++;
+                continue;
+            }
+            if (value !== null) skill.system.masteryLevelBase = value;
+        }
+    }
+
     buildBeing(itemsMap, fm, body) {
         const name = resolveName(fm);
         const id = fm.id;

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",