@heroiclands/package-build 3.1.0 → 3.3.0

package/types/engine/base-compiler.d.mts

@@ -1,11 +1,19 @@
 /**
  * The tallies one pass accumulates while walking the tree.
  *
+ * `declined` and `skippedOther` are deliberately separate numbers. A declined
+ * note is one this build **refused** — it names a package this repository does
+ * not compile — and it is an error; a skipped one legitimately belongs to
+ * another pass, and there are thousands of those. Folding the first into the
+ * second is what let a whole tree be filtered out in silence (#56).
+ *
  * @typedef {object} PassStats
  * @property {number} compiled - Notes that became a document.
  * @property {number} skippedDraft - Notes marked `draft: true`.
  * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
  * @property {number} skippedOther - Notes this pass does not claim.
+ * @property {number} declined - Notes refused because they declare another
+ *   package. Counted as errors, never as skips.
  */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
@@ -136,8 +144,9 @@ export class BasePackCompiler {
     /**
      * Whether this pass claims a note. **Required.**
      *
-     * Called only for a note of the configured content package, so a subclass
-     * decides on `type` alone.
+     * Called only for a note this build compiles — every note in the tree
+     * belongs to the configured content package (#56) — so a subclass decides
+     * on `type` alone.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True to compile it.
@@ -299,6 +308,12 @@ export class BasePackCompiler {
 }
 /**
  * The tallies one pass accumulates while walking the tree.
+ *
+ * `declined` and `skippedOther` are deliberately separate numbers. A declined
+ * note is one this build **refused** — it names a package this repository does
+ * not compile — and it is an error; a skipped one legitimately belongs to
+ * another pass, and there are thousands of those. Folding the first into the
+ * second is what let a whole tree be filtered out in silence (#56).
  */
 export type PassStats = {
     /**
@@ -317,4 +332,9 @@ export type PassStats = {
      * - Notes this pass does not claim.
      */
     skippedOther: number;
+    /**
+     * - Notes refused because they declare another
+     * package. Counted as errors, never as skips.
+     */
+    declined: number;
 };

package/types/engine/content-package.d.mts

@@ -1,10 +1,23 @@
 /**
- * The **content** package: the distribution unit a note declares in its
- * `package:` frontmatter. The pack compilers select their entries by it.
+ * The **content** package: the distribution unit this repository's notes belong
+ * to, and the **address namespace** every one of them is published under.
+ *
+ * It is the first segment of every canonical key (`sohl-skill-clmb`), the name
+ * of the link manifest this build emits (`sohl.json`), and the package a
+ * cross-package wikilink writes to reach one of these notes. So it is the
+ * repository's identity in the address space, not a switch — and never dead
+ * configuration, whatever else changes.
+ *
+ * It was also, until #56, a **selector**: a note declared the same value in its
+ * `package:` frontmatter and the compilers kept the ones that matched. Every
+ * content tree is single-package — each is single-sourced in the repository that
+ * ships it — so the field restated this constant once per note while a value
+ * that matched nothing filtered the whole tree out in silence. The field is
+ * being retired; the value stays, here, where it is declared once.
  *
  * Stable across compilation targets. If this content were ever compiled for a
- * second game system, its notes would still declare `package: sohl` — only the
- * Foundry package below would differ.
+ * second game system, it would still be published as `sohl` — only the Foundry
+ * package below would differ.
  *
  * An accessor rather than a hoisted constant, so that importing this module
  * needs no configuration (#2).
@@ -18,7 +31,7 @@ export function contentPackage(): string;
  * compendium UUID the compilers emit.
  *
  * Distinct from {@link contentPackage}, and equal to it only by coincidence
- * here: a note says `package: sohl` and its documents are addressed as
+ * here: a note is published under `sohl` and its documents are addressed as
  * `Compendium.sohl.<pack>.<Type>.<id>`. In `sohl-thalorna` the two differ
  * (`thalorna` vs `sohl-thalorna`), which is why they are separate values rather
  * than one — treating them as interchangeable is what #1498 was.

package/types/engine/generate.d.mts

@@ -20,9 +20,9 @@ export function itemPackJsonDirs(config?: object): string[];
  * The passes that compiled nothing when they were expected to compile
  * something — a build failure, not a quiet no-op.
  *
- * A pack compiler selects its entries by the configured content package, so a
- * single wrong package id rejects every note in a perfectly good tree and every
- * pack ships blank while the build exits 0 (#1502). The empty-tree guard in
+ * A pack ships blank whenever every note in a full tree was rejected — by a
+ * `selects` that claims nothing, or a `pack:` that routes everything elsewhere
+ * — and the build then exits 0 (#1502). The empty-tree guard in
  * {@link generatePacksJson} cannot see that: the tree is full, it is the
  * *output* that is empty.
  *

package/types/engine/helpers.d.mts

@@ -274,14 +274,17 @@ export function collectContentDocs(contentBase: string): Array<{
  * Expand the fenced `dataview` tables in one note's markdown, before wikilinks
  * are resolved — so a generated cell may itself be a wikilink.
  *
- * A table searches only notes of the source note's own `package`, so a SoHL
- * page never tabulates setting-package content (and vice versa).
+ * A table searches only notes of the source note's own package, so a SoHL page
+ * never tabulates setting-package content (and vice versa). Each candidate's
+ * package is **derived** rather than read out of its frontmatter: `package:` is
+ * optional, and comparing a declared value with an absent one would drop every
+ * unswept — or every swept — note from the table (#56).
  *
  * @param {string} body - The note's markdown body.
  * @param {object} ctx
  * @param {Array<object>} ctx.docs - From {@link collectContentDocs}.
  * @param {string} ctx.name - The note, for the error message.
- * @param {string} [ctx.pkg] - The source note's `package`.
+ * @param {string} [ctx.pkg] - The source note's package.
  * @param {object} [ctx.fm] - The source note's frontmatter, which is what a
  *   query's `this` reads. Its entry in `docs` supplies the path as well.
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line,

package/types/engine/index.d.mts

@@ -5,6 +5,7 @@ export * as contentTree from "./content-tree.mjs";
 export * as packConfig from "./pack-config.mjs";
 export * as packRouter from "./pack-router.mjs";
 export * as contentPackage from "./content-package.mjs";
+export * as notePackage from "./note-package.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";

package/types/engine/macros.d.mts

@@ -122,8 +122,8 @@ export const DEFAULT_MACRO_IMG: "icons/svg/dice-target.svg";
 /**
  * Macros pack compiler.
  *
- * Walks the content tree and compiles every `package: sohl`, `type: macro`
- * note into one Macro document. The same note's documentation is compiled by
+ * Walks the content tree and compiles every `type: macro` note into one Macro
+ * document. The same note's documentation is compiled by
  * the journals pass; neither pass reads the other's output.
  */
 export class Macros extends BasePackCompiler {

package/types/engine/manifest-emit.d.mts

@@ -39,9 +39,12 @@ export function entriesForNote(fm: object, name: string, address: string, body:
  *
  * 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

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

@@ -0,0 +1,54 @@
+/**
+ * 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: object | null | undefined, configured?: string): string;
+/**
+ * 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: object | null | undefined, configured?: string): object | null | undefined;
+/**
+ * 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: object | null | undefined, { file, configured }?: {
+    file?: string | undefined;
+    configured?: string | undefined;
+}): string;

package/types/engine/pack-router.d.mts

@@ -46,8 +46,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/types/engine/site-build.d.mts

@@ -16,7 +16,9 @@ export function walkSiteTree(dir: string, skip?: readonly string[]): string[];
  * 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: string, ctx: object): {

package/types/sohl/actors.d.mts

@@ -25,6 +25,33 @@ export class Actors extends BasePackCompiler {
      * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
      */
     buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): any[];
+    /**
+     * 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: object[], ctx: string): void;
     buildBeing(itemsMap: any, fm: any, body: any): {
         name: any;
         type: string;

package/types/sohl/skill-base.d.mts

@@ -0,0 +1,53 @@
+/**
+ * The HârnMaster Skill Base reduction, mirroring SoHL's `sb()` helper exactly.
+ *
+ * @param {...number} values - One or more attribute values.
+ * @returns {number} The reduced Skill Base.
+ * @throws {Error} If called with no arguments.
+ */
+export function sb(...values: number[]): number;
+/**
+ * Evaluate a `skillBaseFormula` against an actor's attribute scores.
+ *
+ * Mirrors `SkillLogic.computeSkillBase`: an absent or blank formula is Skill
+ * Base `0` (not an error — a skill may legitimately have none), and the result
+ * is clamped to `>= 0`.
+ *
+ * @param {string|null|undefined} formula - The expression source.
+ * @param {Record<string, number>} attrs - Attribute scores by shortcode.
+ * @returns {{ value: number, error?: string }} The Skill Base, or the reason it
+ *   could not be computed. On error `value` is `0`, matching the client.
+ */
+export function evaluateSkillBase(formula: string | null | undefined, attrs?: Record<string, number>): {
+    value: number;
+    error?: string;
+};
+/**
+ * The mastery level an unopened skill opens at, or `null` when it does not
+ * open at all.
+ *
+ * The client's rule (`SkillLogic.initialize`) is `Skill Base × initSkillMult`,
+ * applied only when `masteryLevelBase` is unset and the skill is on an actor.
+ * Two build-side refinements, neither of which changes what a client computes:
+ *
+ * - **A zero or absent `initSkillMult` stays `null`.** The multiplier is the
+ *   switch for whether a skill opens at all, so writing the `0` the arithmetic
+ *   yields would claim the skill opened at zero rather than that it never
+ *   opened. `null` is what the field means by *not yet opened*, and the client
+ *   arrives at the same place either way.
+ * - **A fractional product is an error, not a rounding.** `masteryLevelBase` is
+ *   an integer field (`min: 0`), so a fractional value cannot be persisted
+ *   honestly — where the client multiplies raw into a modifier and is free to
+ *   carry the fraction, this is not. Reporting it follows
+ *   `resolveSkillAptitudes`, which rejects a fractional modifier rather than
+ *   rounding one.
+ *
+ * @param {object} system - The merged skill `system` block.
+ * @param {Record<string, number>} attrs - Attribute scores by shortcode.
+ * @returns {{ value: number|null, error?: string }} The opening mastery level,
+ *   `null` to leave the field unset, or the reason it could not be computed.
+ */
+export function openingMasteryLevel(system?: object, attrs?: Record<string, number>): {
+    value: number | null;
+    error?: string;
+};