@heroiclands/package-build 19.0.0 → 20.0.0

package/types/engine/index.d.mts

@@ -10,6 +10,7 @@ export * as folderNotes from "./folder-notes.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
+export * as runtimeOnlyFields from "./runtime-only-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";

package/types/engine/map-notes.d.mts

@@ -158,8 +158,8 @@ export function buildScene(fm: object, ctx: object): object;
  * @param {string} sceneId - The owning scene's `_id`.
  * @param {string} [img] - The background art, already resolved from the note.
  *   Passed by {@link buildScene}, which reads it from the note rather than from
- *   the block; defaults to whichever spelling the block itself carries, so a
- *   direct two-argument call still works (#142).
+ *   the block; defaults to the block's own `img`, so a direct two-argument call
+ *   still works.
  * @returns {object} The Level document, keyed for the pack.
  */
 export function buildLevel(sohl: object, sceneId: string, img?: string): object;

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

@@ -1,6 +1,20 @@
 /**
  * The document id a note compiles under: its pin, or its address.
  *
+ * **One type hashes its address differently, and that is not an exception to
+ * the rule but an application of it.** A `Folder` is a document of its own
+ * class, and its id is hashed under the `folder` namespace so that a folder and
+ * an item sharing a shortcode cannot derive one id — a collision Foundry would
+ * not report, since it keys folders and documents in separate collections
+ * (#258). So the answer for a folder comes from
+ * {@link module:engine/folder-notes.folderDocId}, the pass that emits those
+ * documents, rather than from a second derivation here.
+ *
+ * That this function ever answered differently was invisible from inside a
+ * build — no pass reads a folder's id from here — and surfaced only in the
+ * content index, which is read from outside and had no way to be checked
+ * against what shipped (#310).
+ *
  * Returns `undefined` for a file with **no address** — no `type`, or no
  * `shortcode`. Such a file is not an addressable note, so it has no document
  * and inventing an id for one would file it under nothing. Every caller already

package/types/engine/retired-fields.d.mts

@@ -258,6 +258,30 @@ export function legacyKeyMessage(block: string, field: {
     name?: string;
     legacyKey?: string;
 }, file?: string): string;
+/**
+ * What a note writing a field at the **top-level key `data:` gathered it off**
+ * is told (#332).
+ *
+ * {@link legacyKeyMessage}'s counterpart for the other retiring position. #128
+ * did not invent the facts `data:` holds — it collected them out of the note's
+ * open top level — so `portrait:` beside `img:` is the *pre-`data:`* spelling
+ * of `data.portrait`, and both are read for the same reason both in-block
+ * spellings are: a package moves its corpus when it is ready, not on a flag day.
+ *
+ * It says nothing about which value is emitted, because that is not what an
+ * author needs from it. The value is the same either way; what the finding
+ * counts is one more note still on the old position.
+ *
+ * @param {{name?: string}} field - The declaration, which names the current
+ *   position; the retiring one is derived from it.
+ * @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 retiredTopLevelMessage(field: {
+    name?: string;
+}, file?: string): string;
 /**
  * Whether a note writes the retired spelling of a field, wherever it put it.
  *
@@ -279,9 +303,9 @@ export function declaresRetiredAlias(fm: object | null | undefined, current: str
  * first, then the note's top level — so a renamed field keeps working wherever
  * it was already written while the canonical home is the top level.
  *
- * A blank value counts as absent: `img:` cleared in an editor means the note
- * names no art there, and falling through to the retired spelling is what an
- * author part-way through the rename means by it.
+ * A blank value counts as absent: `relations:` cleared in an editor means the
+ * note records no standings there, and falling through to the retired spelling
+ * is what an author part-way through the rename means by it.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} current - The field's current name.
@@ -295,8 +319,8 @@ export function readAliasedField(fm: object | null | undefined, current: string)
  * and what every reader asks for; the value is the spelling still honoured.
  * The table is therefore scoped by the schema without saying so twice: an alias
  * applies to a note only where that note's type declares the current field, so
- * `image` is retired on a map — which declares `img` — and remains an unknown
- * key anywhere else.
+ * `relation` is retired on an affiliation — which declares `relations` — and
+ * remains an unknown key anywhere else.
  *
  * **`templatePriority` (#266).** The number that decides which of several
  * competing templates the Create dialog offers was called `archetype`, and
@@ -311,14 +335,6 @@ export function readAliasedField(fm: object | null | undefined, current: string)
  * read past. Only `affiliation` declares the field, so the alias is reported
  * there and the old spelling stays an ordinary unknown key everywhere else.
  *
- * **`img` (#142).** Every note type names its artwork `img`, at the note's top
- * level, and resolves it the same way. A map alone named its background art
- * `image` and read it out of the `sohl:` block — two spellings for one idea,
- * with nothing to reconcile them, and a specification that had to hedge rather
- * than state a rule. Art is not system-specific: a Scene is a core Foundry
- * document and HM3 would want the identical one, so the field belongs beside
- * every other note's `img`, not inside a system block.
- *
  * @type {Readonly<Record<string, string>>}
  */
 export const RETIRED_FIELD_ALIASES: Readonly<Record<string, string>>;

package/types/engine/runtime-only-fields.d.mts

@@ -0,0 +1,102 @@
+/**
+ * What a note authoring a runtime-only field is told, in one place.
+ *
+ * Shared by every caller that can meet one, because an author meets whichever
+ * runs first and they should read the same. It says what the field holds and
+ * that deleting the key is the whole fix — there is no value to correct, which
+ * is what separates this from an out-of-range one.
+ *
+ * The reason comes from the declaration rather than from here: this module
+ * knows no field names, and a message written per field would be a second
+ * statement of the fact the declaration already carries.
+ *
+ * @param {string} key - The **whole key the note wrote**, from the region it
+ *   sits in down to the field: `sohl.system.onsetDate` on the item's own note,
+ *   `sohl.items[2].system.contractDate` on an actor's embedded entry. Composed
+ *   by the caller, because only it knows where it found the value — and a
+ *   message naming the leaf alone leaves an author a note to search.
+ * @param {import("./field-spec.mjs").FieldSpec} field - The declaration, which
+ *   carries the reason.
+ * @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 runtimeOnlyMessage(key: string, field: import("./field-spec.mjs").FieldSpec, file?: string): string;
+/**
+ * The runtime-only fields a note actually writes, in declaration order.
+ *
+ * **Presence is the whole test**, as it is for every retired field: an authored
+ * `onsetDate: null` is as much a claim about play state as a number is, and it
+ * is exactly the belief the message exists to correct. So the question is
+ * whether the path resolves to anything at all, never whether the value is a
+ * usable one.
+ *
+ * Only `<block>.system.<to>` is searched, because it is the only position a
+ * runtime-only field is reachable at. Such a declaration carries no `name`, so
+ * it has neither a legacy in-block key nor a shared top-level source — and a
+ * bare `<block>.onsetDate` is an unrecognized block key, which
+ * {@link module:engine/system-block.unknownBlockKeys} already reports as an
+ * error naming the note and the line.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @returns {import("./field-spec.mjs").FieldSpec[]} The offending declarations.
+ */
+export function authoredRuntimeOnlyFields(fm: object | null | undefined, fields?: readonly import("./field-spec.mjs").FieldSpec[], { block }?: {
+    block: string;
+}): import("./field-spec.mjs").FieldSpec[];
+/**
+ * The same question asked of a `system` block directly.
+ *
+ * A note's own block is reached through {@link authoredRuntimeOnlyFields}, but
+ * it is not the only place an author writes one: an actor note's `items:`
+ * entries carry a `system:` overlay that is deep-merged onto the template
+ * verbatim, with no field declaration in the path at all. That overlay is a
+ * `system` block by every meaning except where it sits, and a `contractDate`
+ * written there ships exactly as one written on the trauma's own note.
+ *
+ * @param {Record<string, unknown>|null|undefined} data - The authored `system`
+ *   data.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration.
+ * @returns {import("./field-spec.mjs").FieldSpec[]} The offending declarations.
+ */
+export function runtimeOnlyIn(data: Record<string, unknown> | null | undefined, fields?: readonly import("./field-spec.mjs").FieldSpec[]): import("./field-spec.mjs").FieldSpec[];
+/**
+ * Refuse a note that authors any of its type's runtime-only fields.
+ *
+ * Refused rather than reported: the note is not compiled, so nothing it would
+ * have emitted reaches a pack. What that costs is the caller's to decide — each
+ * of them counts the refused note and emits a located diagnostic, so a refusal
+ * is never a silent skip.
+ *
+ * The **first** offending field is thrown on. A note authoring a whole phase
+ * triplet would otherwise produce three findings that are one mistake, and the
+ * build stops on this note either way; the fix for the first is the fix for all
+ * of them.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration. A type that declares none — or declares no
+ *   runtime-only field — passes.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @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 authors one.
+ */
+export function assertNoRuntimeOnlyFields(fm: object | null | undefined, fields?: readonly import("./field-spec.mjs").FieldSpec[], { block, file, absPath }?: {
+    block: string;
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): void;

package/types/engine/schema-check.d.mts

@@ -46,11 +46,20 @@ export function declaredFields(artifact: SchemaArtifact, documentType: string, s
  * the path beneath it separately, so a comparison that knew only the leaf would
  * report the container as unemitted and the leaf as undeclared.
  *
- * @param {readonly {to: string}[]} fields - A type's field declaration.
+ * **A runtime-only field is not in it** (#330). It declares a `to` in order to
+ * *claim* the path — so the verbatim passthrough leaves it alone and the
+ * refusal has something to name — and `buildFromFields` deliberately skips it,
+ * because the document writes that field in play. Counting it here would make
+ * the check assert the builder writes a key it never writes; the *unemitted*
+ * direction handles it instead, in {@link compareFields}.
+ *
+ * @param {readonly {to: string, runtimeOnly?: string}[]} fields - A type's
+ *   field declaration.
  * @returns {Set<string>} The paths, parents included.
  */
 export function emittedFields(fields: readonly {
     to: string;
+    runtimeOnly?: string;
 }[]): Set<string>;
 /**
  * Compare one system's builders against one system's published schemas.

package/types/engine/subtype-registry.d.mts

@@ -47,3 +47,24 @@ export function schemaSubtypeOf(system: string | undefined, type: string): strin
  * @type {readonly import("./document-subtypes.mjs").DocumentSubtypeMap[]}
  */
 export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[];
+/**
+ * Every note type any shipped map compiles into an **Actor**.
+ *
+ * Derived from the maps rather than written out, so a system that adds an actor
+ * type is covered without a second list to keep in step — the same reason
+ * {@link KNOWN_DOCUMENT_SUBTYPE_MAPS} exists rather than a hand-kept table.
+ *
+ * It exists because an actor note publishes documentation like every other
+ * system-bearing note (#337). `docEntryTypes` was `itemTypes` plus `macro` and
+ * the map types, which left a being as the one system-bearing note with no
+ * `none` address — nothing a prose link could land on, since its only address
+ * named the Actor. Composing that set needs to know which types are actors, and
+ * this is where the maps that know already live.
+ *
+ * **Not an item type.** This widens what carries *documentation*; it must never
+ * widen what the items pass compiles, or a being note would be compiled into an
+ * Item beside its Actor.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const ACTOR_TYPES: ReadonlySet<string>;

package/types/engine/system-block.d.mts

@@ -114,6 +114,32 @@ export function legacyKeyOf(field: {
     name?: string;
     legacyKey?: string;
 }): string | undefined;
+/**
+ * The bare top-level key a `data:`-sourced field is being swept off — step 3b.
+ *
+ * `data:` (#128) did not invent the facts it holds; it *gathered* them, out of
+ * the note's open top level where each was a sibling of `img` and `shortcode`.
+ * So the retiring spelling of `data.portrait` is not a second declaration
+ * anyone has to write — it is `portrait`, mechanically, and the same holds for
+ * every other key that move relocated. Deriving it is what keeps the two
+ * spellings of one field from disagreeing the way two declarations would.
+ *
+ * **Only a `data.` source has one.** `protection.blunt` and `impact.die` are
+ * paths into containers a note has always written at the top level; they were
+ * never `blunt:` or `die:`, and reading those would invent a position rather
+ * than remember one.
+ *
+ * A field declaring {@link module:engine/field-spec.FieldSpec `topLevelMeans`}
+ * has no shared position at all, retiring or otherwise — the resolver checks
+ * that before asking.
+ *
+ * @param {{name?: string}} field - The declaration.
+ * @returns {string|undefined} The retiring top-level path, or `undefined` for a
+ *   field whose shared source never lived there.
+ */
+export function retiredTopLevelKey(field: {
+    name?: string;
+}): string | undefined;
 /**
  * Where a declared field's value came from.
  *
@@ -121,7 +147,7 @@ export function legacyKeyOf(field: {
  * can distinguish a value an author wrote from one a default supplied, which
  * the value alone never says.
  *
- * @typedef {"system"|"block"|"shared"|"default"|"value"} FieldSource
+ * @typedef {"system"|"block"|"shared"|"topLevel"|"default"|"value"} FieldSource
  */
 /**
  * Resolve one declared field against a note, in the declared order.
@@ -317,4 +343,4 @@ export const SYSTEM_BLOCK_KEYS: ReadonlySet<string>;
  * can distinguish a value an author wrote from one a default supplied, which
  * the value alone never says.
  */
-export type FieldSource = "system" | "block" | "shared" | "default" | "value";
+export type FieldSource = "system" | "block" | "shared" | "topLevel" | "default" | "value";

package/types/sohl/actors.d.mts

@@ -12,7 +12,7 @@ export class Actors extends SystemActorCompiler {
      * Build all embedded items for an actor: one per `sohl.attributes`
      * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
      */
-    buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): object[];
+    buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): any[];
     /**
      * Bake each unopened skill's opening mastery level into the document (#46).
      *
@@ -48,11 +48,11 @@ export class Actors extends SystemActorCompiler {
         system: {
             shortcode: any;
             templatePriority: number | null;
-            portrait: string;
+            portrait: any;
             appearance: string;
             dossier: string;
         };
-        items: object[];
+        items: any[];
         prototypeToken: {
             name: any;
             displayName: number;