@heroiclands/package-build 9.0.0 → 10.0.1

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

@@ -0,0 +1,281 @@
+/**
+ * Write `value` at a dotted path in a document's `system` block, creating the
+ * intermediate objects.
+ *
+ * Insertion order is the emitted JSON's key order, so a declaration's order is
+ * the compiled document's order — which is what lets a field list replace a
+ * hand-written object literal without changing a single byte of output.
+ *
+ * It sits here rather than beside the field declarations because both writers
+ * into a `system` block use it: the declared fields, and the verbatim
+ * `<system>.system` passthrough. `field-spec.mjs` re-exports it, so the name
+ * has one import path as well as one definition.
+ *
+ * @param {object} target - The object to write into (mutated).
+ * @param {string} dotted - Path, e.g. `"locations.flexible"`.
+ * @param {any} value - The value to set.
+ * @returns {object} `target`, for chaining.
+ */
+export function setPath(target: object, dotted: string, value: any): object;
+/**
+ * One system's block, or nothing.
+ *
+ * A block authored as a scalar or a list is **absent** rather than an error
+ * here: this module reports what a note carries, and saying what is wrong with
+ * a malformed one is the linter's job, which can point at the line.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The block key, e.g. `"sohl"`.
+ * @returns {Record<string, unknown>|undefined} The block, or `undefined`.
+ */
+export function systemBlock(fm: object, block: string): Record<string, unknown> | undefined;
+/**
+ * Whether a note carries a system's block at all.
+ *
+ * This is the pack-eligibility question: a pack declaring a system compiles a
+ * note only if the note has something to say about that system. A note that
+ * does not carries no system data, and compiling it anyway produces a hollow
+ * document — one with a subtype and none of the fields that subtype exists for.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The block key.
+ * @returns {boolean} True when the block is present and is a mapping.
+ */
+export function carriesSystemBlock(fm: object, block: string): boolean;
+/**
+ * A system block's `system` sub-block — what maps onto `document.system`.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The block key.
+ * @returns {Record<string, unknown>} The authored data, `{}` when absent.
+ */
+export function systemData(fm: object, block: string): Record<string, unknown>;
+/**
+ * Read a key from one system's block, falling back to the top level.
+ *
+ * The generalization of `sohlField()` to any block, and behaviourally identical
+ * to it for `"sohl"` — the one system every existing tree authors. What changed
+ * is that the block is a parameter rather than a constant, which is the whole
+ * of what a second system needs from this reader.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The block key.
+ * @param {string} key - The property, dotted for a nested one.
+ * @param {any} [defaultValue] - Returned when neither declares it.
+ * @returns {any} The value.
+ */
+export function blockField(fm: object, block: string, key: string, defaultValue?: any): any;
+/**
+ * A **shared** top-level property, read by a possibly-dotted path.
+ *
+ * Deliberately blind to every system block: this is the third step of the
+ * resolution order, and letting a block answer it would make the second step
+ * and the third the same question.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} source - The property, dotted for a path into a container.
+ * @param {any} [defaultValue] - Returned when the path resolves to nothing.
+ * @returns {any} The value.
+ */
+export function sharedProperty(fm: object, source: string, defaultValue?: any): any;
+/**
+ * A property a system block may override, else the shared top-level one.
+ *
+ * This is what gives `pack`, `effects`, `flags` and `img` their per-system form
+ * without inventing a mechanism for each: a note that wants one value for both
+ * systems says it once at the top, and a note that needs them to differ says so
+ * in the block that differs.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The block key.
+ * @param {string} key - The property.
+ * @param {any} [defaultValue] - Returned when neither declares it.
+ * @returns {any} The value.
+ */
+export function blockProperty(fm: object, block: string, key: string, defaultValue?: any): any;
+/**
+ * Where a declared field's value came from.
+ *
+ * Reported alongside the value so a caller — a linter, a migration, a test —
+ * 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
+ */
+/**
+ * Resolve one declared field against a note, in the declared order.
+ *
+ * See the module note for the order and why it is declared rather than
+ * name-matched. The value comes back **raw**; applying the field's own `read`
+ * is {@link module:engine/field-spec.readField}'s job, and it applies the same
+ * coercion wherever the value was authored.
+ *
+ * @param {import("./field-spec.mjs").FieldSpec} field - The declaration.
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} [options] - Options.
+ * @param {string} [options.block="sohl"] - The system block to resolve against.
+ * @returns {{value: any, from: FieldSource}} The raw value and where it came
+ *   from.
+ */
+export function resolveFieldValue(field: import("./field-spec.mjs").FieldSpec, fm: object, { block }?: {
+    block?: string | undefined;
+}): {
+    value: any;
+    from: FieldSource;
+};
+/**
+ * Every path a note authors under `<system>.system`, containers included.
+ *
+ * A container is listed as well as its leaves because a published schema
+ * declares both — `charges` as a `SchemaField` and `charges.value` beneath it —
+ * so a check that knew only the leaves could not tell a misspelled container
+ * from a misspelled leaf.
+ *
+ * An **empty** mapping is a leaf: `body: {}` is a value the author wrote, and
+ * walking into it would make it vanish.
+ *
+ * @param {Record<string, unknown>} data - The authored `system` data.
+ * @param {string} [prefix] - Internal: the path so far.
+ * @returns {string[]} The dotted paths.
+ */
+export function systemDataPaths(data: Record<string, unknown>, prefix?: string): string[];
+/**
+ * The authored paths a system's published schema does not declare.
+ *
+ * **Reported at the shallowest undeclared path.** Everything beneath an
+ * undeclared container is undeclared by construction, so listing it all buries
+ * the one mistake in a wall of consequences — one finding per typo is what an
+ * author can act on.
+ *
+ * Foundry discards an unknown `system` key at construction and says nothing, so
+ * this is the difference between "the field is lost at load" and "the build
+ * told you where".
+ *
+ * @param {Record<string, unknown>} data - The authored `system` data.
+ * @param {ReadonlySet<string>} declared - Every field path the schema declares
+ *   for this subtype, inherited ones included.
+ * @param {string} [prefix] - Internal: the path so far.
+ * @returns {string[]} The undeclared paths, shallowest-first.
+ */
+export function undeclaredPaths(data: Record<string, unknown>, declared: ReadonlySet<string>, prefix?: string): string[];
+/**
+ * Keys directly under a system block that neither this format nor the system
+ * recognizes.
+ *
+ * Until now an unrecognized key under `sohl:` was reported only against SoHL's
+ * *field* vocabulary, and a key under any other system's block was not looked
+ * at at all — dropped in silence, which is the failure class the frontmatter
+ * lint exists for.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The block key.
+ * @param {object} options - Options.
+ * @param {Iterable<string>} options.known - The keys this system declares on
+ *   top of the shared vocabulary: its generators, its toolchain keys, and —
+ *   until #126 moves them — the field names its notes still author in the
+ *   block.
+ * @returns {string[]} The unrecognized keys, in authored order.
+ */
+export function unknownBlockKeys(fm: object, block: string, { known }: {
+    known: Iterable<string>;
+}): string[];
+/**
+ * The `system` paths a field declaration writes, for {@link mergeSystemData}.
+ *
+ * Exactly each field's `to`, and deliberately **not** its ancestors: a field
+ * writing `locations.flexible` does not own `locations`, and claiming the
+ * container would make an authored `locations.facing` disappear — a silent drop
+ * inside the mechanism built to stop them.
+ *
+ * @param {readonly {to?: string}[]} [fields] - A type's field declaration.
+ * @returns {Set<string>} The claimed destinations.
+ */
+export function claimedPaths(fields?: readonly {
+    to?: string;
+}[]): Set<string>;
+/**
+ * Merge a note's `<system>.system` onto a built `system` block, verbatim.
+ *
+ * **Verbatim means the paths are the schema's, not that the merge is a
+ * replacement.** A container the builder already wrote is merged into rather
+ * than overwritten, so authoring one leaf of `body` does not silently discard
+ * the rest of it.
+ *
+ * A path a **declared field** already claims is left alone. That field's value
+ * came from the same authored place, through the field's own `read`; writing it
+ * again uncoerced would make the coercion depend on which of two mechanisms ran
+ * last — the drift a single statement of the mapping exists to prevent.
+ *
+ * @param {object} built - The `system` block the builder produced (mutated).
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} options - Options.
+ * @param {string} options.block - The block key.
+ * @param {ReadonlySet<string>} [options.claimed] - Paths a declared field
+ *   writes, which this merge leaves to it.
+ * @returns {object} `built`, for chaining.
+ */
+export function mergeSystemData(built: object, fm: object, { block, claimed }: {
+    block: string;
+    claimed?: ReadonlySet<string> | undefined;
+}): object;
+/**
+ * The key inside a system block that maps onto the document's `system`
+ * property.
+ *
+ * Named rather than spelled inline: it is the one key whose contents are the
+ * *system's* vocabulary rather than this format's, and every check that has to
+ * treat it differently reads it from here.
+ *
+ * @type {string}
+ */
+export const SYSTEM_DATA_KEY: string;
+/**
+ * The properties inside a system block that map onto a document property, block
+ * key → document key.
+ *
+ * The two names are equal in every row today, and are written out anyway for
+ * the reason every row of a document-subtype map is: a mapping that exists only
+ * because two vocabularies happen to be spelled alike is not a mapping.
+ *
+ * `effects` is **plural**, matching both the existing top-level frontmatter
+ * field (authored on 24 notes in `sohl-kethira-basic`) and the Foundry document
+ * property. A singular-to-plural rename applying to one property and not its
+ * neighbour reads as a typo for years.
+ *
+ * `items` exists on **actors only**; an item document has no embedded items,
+ * and a note declaring it under a block whose subtype is an Item is authoring
+ * something nothing will read.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const BLOCK_DOCUMENT_PROPERTIES: Readonly<Record<string, string>>;
+/**
+ * Block keys that are **build directives** — they tell the toolchain how to
+ * build the document and land on no document property at all.
+ *
+ * `pack` is the first and, so far, the only one: it names the compendium this
+ * system's document is compiled into, which is what makes "one note, several
+ * packs" expressible per system. Its shared top-level form already exists
+ * (`PACK_FIELD` in `pack-router.mjs`, authored on 352 notes), so the override
+ * rule gives it a per-system form for free.
+ *
+ * @type {readonly string[]}
+ */
+export const BLOCK_DIRECTIVES: readonly string[];
+/**
+ * Every key any system block may carry, whatever the system.
+ *
+ * A system adds its own on top — `archetype`, `kbcat` and the generators — and
+ * names them where it declares its vocabulary; see {@link unknownBlockKeys}.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_BLOCK_KEYS: ReadonlySet<string>;
+/**
+ * Where a declared field's value came from.
+ *
+ * Reported alongside the value so a caller — a linter, a migration, a test —
+ * 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";

package/types/engine/web-wikilinks.d.mts

@@ -30,18 +30,27 @@ export function frontmatterWikilinks(fm: unknown): Array<{
 /**
  * Rewrites the wikilinks in a markdown body as KB-local markdown links.
  *
- * A target is looked up case-insensitively: first as an alias scoped to the
- * source's own **type** (`ctx.typeAlias`, keyed `type|alias`) — a note's
- * directory and `category` play no part — then in the KB-wide `ctx.index` (keyed
- * by the unambiguous `section/slug` and `type/shortcode`, plus name/filename/slug
- * fallbacks).
+ * A target is looked up case-insensitively in **one** of two namespaces, and
+ * the pipe chooses which (#131):
  *
- * An unresolved target fails the build only when it is a genuine intra-KB
- * problem — an ambiguous alias, or a qualified `prefix/key` whose prefix is a
- * real KB section or content directory. Anything else is treated as an external
- * reference — until every package's manifest is present, after which any
- * `type-shortcode` address resolving nowhere fails too. Failures are collected
- * in `ctx.errors`.
+ * - **Unpiped** — an alias scoped to the source's own **type**
+ *   (`ctx.typeAlias`, keyed `type|alias`). A note's directory and `category`
+ *   play no part.
+ * - **Piped** — an address, parsed by {@link readQualifier} and looked up in
+ *   the KB-wide `ctx.index` (the canonical `package-type-shortcode`,
+ *   `type/shortcode`, and the site's own `section/slug`), then in the vendored
+ *   `ctx.foreign` manifests.
+ *
+ * Neither falls back to the other, so the name/basename/slug fallbacks that
+ * share `ctx.index` no longer answer for an address: only a slash-qualified
+ * target reaches the raw key, which is what keeps `section/slug` addressable.
+ *
+ * An unresolved target fails the build when it is a genuine intra-KB problem —
+ * an ambiguous alias, a qualified `prefix/key` whose prefix is a real KB
+ * section or content directory, or a **piped** target that is not an address
+ * at all. Anything else is treated as an external reference — until every
+ * package's manifest is present, after which any address resolving nowhere
+ * fails too. Failures are collected in `ctx.errors`.
  *
  * Whether or not it fails the build, a target that resolves nowhere renders
  * through {@link unresolvedLink} rather than as bare prose (#1665): the author's
@@ -56,7 +65,9 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  *
  * @param {string} body - The markdown body.
  * @param {object} ctx - `{ index, typeAlias, collide, typeCollide, sections,
- *   contentTypes, foreign, manifestsComplete, type, errors, src }`. `foreign`
+ *   contentTypes, packages, foreign, manifestsComplete, type, errors, src }`.
+ *   `packages` is every package an address may name, without which the leading
+ *   package segment of a canonical address reads as an unknown type; `foreign`
  *   is the cross-package manifest index (#1446); `manifestsComplete` says
  *   whether every linkable package is accounted for. Together they decide
  *   whether an unresolved address is a typo or a package merely absent.

package/types/engine/wikilink-syntax.d.mts

@@ -47,6 +47,35 @@ export function parseWikilink(rawInner: string): ParsedWikilink;
 export function authoredLabel({ display }: {
     display: string | null;
 }): string | null;
+/**
+ * Which namespace a link resolves in: the **address** space, or the **alias**
+ * space.
+ *
+ * **The pipe decides, and nothing else does** (#131). `[[x|…]]` is an address,
+ * parsed by the address grammar; `[[x]]` is an alias, looked up within the
+ * source note's own type. Neither falls back to the other.
+ *
+ * Both resolvers used to decide by *shape* instead — try the address, fall
+ * back to the alias — which had three costs. An author could not say which
+ * they meant, so a note whose **name** looked like an address (`Grukar-ahk`)
+ * was read as one, and a genuine address that resolved nowhere silently became
+ * a name lookup and reported nothing. And a positional address grammar could
+ * not split a target confidently until it had first ruled out every note name
+ * in the corpus.
+ *
+ * An **empty** label is still a pipe: `[[x|]]` is an address that renders the
+ * target's *current* name, so a rename shows at every citation with no link
+ * edited. That is why this reads {@link ParsedWikilink.labelled} and not
+ * {@link authoredLabel} — the two answer different questions, and only one of
+ * them is about namespaces.
+ *
+ * @param {{labelled: boolean}} parsed - A parsed wikilink, or anything
+ *   carrying its `labelled`.
+ * @returns {boolean} True when the target is an address.
+ */
+export function resolvesAsAddress({ labelled }: {
+    labelled: boolean;
+}): boolean;
 /**
  * Whether a parsed link addresses a section of the page it is written on.
  *

package/types/sohl/actors.d.mts

@@ -1,4 +1,17 @@
 export class Actors extends BasePackCompiler {
+    /**
+     * The note-type → document-subtype map this pass compiles against.
+     *
+     * Stated by the class rather than reached for through the module import, so
+     * every subtype decision the pass makes — the actor's own, and each
+     * embedded item reference's — reads one declaration that a subclass
+     * compiling for another system can replace. That is also what lets the
+     * non-identity behaviour be exercised without introducing a non-identity
+     * row into SoHL's own map, which is #78's job and moves compiled bytes.
+     *
+     * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
+     */
+    static documentSubtypes: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;
     constructor({ itemsSourceDirs, foreignSourceDirs, ...options }: {
         [x: string]: any;
         itemsSourceDirs?: never[] | undefined;
@@ -10,21 +23,63 @@ export class Actors extends BasePackCompiler {
     itemsMap: Map<string, object> | undefined;
     /** @inheritdoc */
     reportDetail(stats: any): void;
+    /**
+     * The Foundry Item subtype an embedded reference's `type` addresses.
+     *
+     * **The reference is in the note vocabulary; the address is in the
+     * document's** (#140). A being writes `(type, shortcode)` with the type an
+     * author authors, while {@link itemAddress} keys the predefined items by
+     * the subtype each compiled document carries — so exactly one of the two
+     * sides has to translate, and it is this one. The system's map is a
+     * function from note type to subtype by construction; the reverse is not,
+     * and a compiled document records nothing about the note that produced it,
+     * so there is no honest way to key the addresses the other way round.
+     *
+     * The two vocabularies are the same string in every SoHL row today, which
+     * is why looking a reference up verbatim worked. The first non-identity row
+     * (#78: `armor` → `armorgear`) ends that, and a reference resolving to
+     * nothing must be a finding rather than an item quietly missing from the
+     * compiled actor.
+     *
+     * @param {string} type - The type the reference names.
+     * @returns {import("../engine/document-subtypes.mjs").ReferencedSubtype}
+     *   The subtype, or why the reference names none.
+     */
+    embeddedSubtype(type: string): import("../engine/document-subtypes.mjs").ReferencedSubtype;
     /**
      * Resolve one embedded item from a `(type, shortcode?, overlay)`
      * descriptor. If `shortcode` is given, the predefined item is fetched
      * from `itemsMap` and the overlay deep-merged on top. If absent, the
      * descriptor must carry enough fields to stand alone. The embedded
      * item's `_id` is regenerated deterministically from
-     * `(actorId, type, shortcode, indexKey)` so re-exports are stable.
+     * `(actorId, subType, shortcode, indexKey)` so re-exports are stable —
+     * from the **document subtype**, so that renaming a note type (#78) leaves
+     * every embedded id exactly where it was.
      * Returns null if the descriptor cannot be resolved.
+     *
+     * @param {Map<string, object>} itemsMap - The predefined items, by address.
+     * @param {string} actorId - The owning actor's id, seeding embedded ids.
+     * @param {string} type - The **note** type the reference names.
+     * @param {string|null} shortcode - The referenced item's shortcode, or
+     *   `null` for a stand-alone entry.
+     * @param {object} [overlay] - The entry's remaining properties.
+     * @param {string} indexKey - Distinguishes two references to one item.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     * @param {object} [at] - Where to locate a finding.
+     * @param {string} [at.fmKey] - The frontmatter key the reference sits
+     *   under, so an unresolved one is reported at the reference rather than
+     *   at the note.
+     * @returns {object|null} The embedded item, or null when it resolved to
+     *   nothing — always with a finding emitted.
      */
-    resolveEmbedded(itemsMap: any, actorId: any, type: any, shortcode: any, overlay: any, indexKey: any, ctx: any): any;
+    resolveEmbedded(itemsMap: Map<string, object>, actorId: string, type: string, shortcode: string | null, overlay?: object, indexKey: string, ctx: string, { fmKey }?: {
+        fmKey?: string | undefined;
+    }): object | null;
     /**
      * 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): any[];
+    buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): object[];
     /**
      * Bake each unopened skill's opening mastery level into the document (#46).
      *
@@ -59,11 +114,12 @@ export class Actors extends BasePackCompiler {
         _id: any;
         system: {
             shortcode: any;
+            archetype: number | null;
             portrait: string;
             appearance: string;
             dossier: string;
         };
-        items: any[];
+        items: object[];
         prototypeToken: {
             name: any;
             displayName: number;
@@ -78,13 +134,13 @@ export class Actors extends BasePackCompiler {
             };
             detectionModes: never[];
         };
-        effects: never[];
+        effects: any[];
         folder: string | null;
         sort: number;
         ownership: {
             default: number;
         };
-        flags: object;
+        flags: any;
         _stats: object;
         _key: string;
     };

package/types/sohl/document-subtypes.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Every content type SoHL compiles into a Foundry document, and what it
+ * becomes.
+ *
+ * The Item rows are the thirteen types the item registry declares; the one
+ * Actor row is `being`, which was two types (`character` and `creature`)
+ * compiling to the same actor until they were retired in SoHL#1580. Types this
+ * map does not name — `doc`, `macro`, the three map types — compile into
+ * documents that carry no system subtype at all, so they have no row and never
+ * needed one.
+ *
+ * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
+ */
+export const SOHL_DOCUMENT_SUBTYPES: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;

package/types/sohl/index.d.mts

@@ -1,4 +1,5 @@
 export * as itemBuilders from "./item-builders.mjs";
+export * as documentSubtypes from "./document-subtypes.mjs";
 export * as items from "./items.mjs";
 export * as actors from "./actors.mjs";
 export * as kbPasses from "./kb-passes.mjs";

package/types/sohl/items.d.mts

@@ -7,6 +7,27 @@ export class Items extends BasePackCompiler {
      * @type {Record<string, number>}
      */
     counts: Record<string, number>;
+    /**
+     * The Foundry Item subtype a note compiles into.
+     *
+     * **Looked up, not inferred.** For every type this system declares, the
+     * emitted subtype is the map's, so the note vocabulary and the document
+     * vocabulary are two separately-stated things rather than one string
+     * written twice (#79).
+     *
+     * **A type the map does not name belongs to the consumer**, and its
+     * registry entry is the declaration: a repository shipping an item type of
+     * its own writes it once, in the `itemBuilders` table of its
+     * `package-build.config.yaml`, and that key is what the document is a
+     * subtype of. That is an authored statement in the consumer's own
+     * configuration, not a coincidence inside this package's source — and
+     * refusing it here would silently drop every document of a type SoHL has
+     * no opinion about (#7/#1563).
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {string} The document's `type`.
+     */
+    itemSubtype(fm: object): string;
     /** An item is named by its own type in the log, not by "item". */
     noteLabel(fm: any): any;
     /** @inheritdoc */