@heroiclands/package-build 19.0.0 → 20.2.0

package/types/engine/field-spec.d.mts

@@ -17,6 +17,26 @@
  * @returns {boolean} True when the value came from the retiring position.
  */
 export function readsLegacyKey(field: FieldSpec, from: import("./system-block.mjs").FieldSource): boolean;
+/**
+ * Whether a resolution read a field from the top-level key `data:` gathered it
+ * off — the shared level's retiring position (#332).
+ *
+ * {@link readsLegacyKey}'s sibling, and the same signal: a finding here counts
+ * one note still on the pre-`data:` spelling, so the sweep has something to
+ * count down instead of a corpus nobody has surveyed.
+ *
+ * The `from` tag already carries the whole answer — step 3b is the only thing
+ * that produces it, and it produces it only for a `data.` source — so this is a
+ * name for the question rather than a second test of it. Named all the same,
+ * because a compile-time report and the frontmatter lint both ask it and must
+ * not drift apart about what counts.
+ *
+ * @param {FieldSpec} field - The declaration.
+ * @param {import("./system-block.mjs").FieldSource} from - Where
+ *   {@link resolveFieldValue} said the value came from.
+ * @returns {boolean} True when the value came from the retiring top-level key.
+ */
+export function readsRetiredTopLevel(field: FieldSpec, from: import("./system-block.mjs").FieldSource): boolean;
 /**
  * Read one declared field out of a note's frontmatter.
  *
@@ -38,12 +58,77 @@ export function readsLegacyKey(field: FieldSpec, from: import("./system-block.mj
  *   rather than a returned list because the caller is a compiler, which already
  *   knows the note and how to locate a key in it; this module knows neither and
  *   would have to invent a finding shape to say so.
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Called with
+ *   each field read from the top-level key `data:` gathered it off (#332). The
+ *   shared level's counterpart to `onLegacyKey`, and a separate callback
+ *   because it is a separate position: a note may have moved one of the two and
+ *   not the other, and a caller that conflated them would tell its author to
+ *   fix the wrong line.
  * @returns {any} The value to emit.
  */
-export function readField(field: FieldSpec, fm: object, { block, onLegacyKey }?: {
+export function readField(field: FieldSpec, fm: object, options?: {
     block?: string | undefined;
     onLegacyKey?: ((field: FieldSpec) => void) | undefined;
+    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
 }): any;
+/**
+ * The same read, reporting **where the value came from** as well.
+ *
+ * {@link readField} answers "what does this field hold", which is what almost
+ * every caller wants. A builder has one further question — *should the key be
+ * written at all* — and it cannot be answered from the value: `null` from a
+ * note and `null` from a declared default are the same value and opposite
+ * facts (#329).
+ *
+ * So the position rides back beside the value, resolved **once**. The
+ * alternative is a builder that calls {@link resolveFieldValue} for the source
+ * and {@link readField} for the value, which resolves the position twice and
+ * states in two places the rule that a field is authored in exactly one.
+ *
+ * @param {FieldSpec} field - The declaration.
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} [options] - Options, as {@link readField} takes them.
+ * @param {string} [options.block="sohl"] - Which system's block to resolve
+ *   against.
+ * @param {(field: FieldSpec) => void} [options.onLegacyKey] - See
+ *   {@link readField}.
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - See
+ *   {@link readField}.
+ * @returns {{value: any, from: import("./system-block.mjs").FieldSource}} The
+ *   value to emit, and the position it was read from.
+ */
+export function readFieldEntry(field: FieldSpec, fm: object, { block, onLegacyKey, onRetiredTopLevel }?: {
+    block?: string | undefined;
+    onLegacyKey?: ((field: FieldSpec) => void) | undefined;
+    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
+}): {
+    value: any;
+    from: import("./system-block.mjs").FieldSource;
+};
+/**
+ * Whether a note supplied a value for a field, as opposed to a default doing it.
+ *
+ * The question {@link FieldSpec.omitWhenAbsent} turns on, asked of the
+ * *position* rather than of the value — which cannot answer it, since a
+ * declared `default: null` and an authored `null` are indistinguishable once
+ * the value is in hand (#329).
+ *
+ * `undefined` counts as absent whatever position reported it, because writing
+ * the key then emits a value `JSON.stringify` drops — the key present in the
+ * object and absent from the pack, which is the sort of disagreement this
+ * package exists to remove. It arrives from one place: the in-block step
+ * answers `value ?? field.default` for a key authored as `null`, so a field
+ * declaring no default resolves through "authored" to nothing at all. A field
+ * that also declares a `read` never reaches this, since its coercion has by
+ * then turned the `undefined` into whatever it makes of an absent value —
+ * ordinarily `null`, which is a value the note asked for and is emitted.
+ *
+ * @param {import("./system-block.mjs").FieldSource} from - Where
+ *   {@link resolveFieldValue} said the value came from.
+ * @param {any} value - The value it gave back.
+ * @returns {boolean} True when the note wrote one.
+ */
+export function isAuthored(from: import("./system-block.mjs").FieldSource, value: any): boolean;
 /**
  * Turn a field declaration into the builder it declares.
  *
@@ -55,11 +140,15 @@ export function readField(field: FieldSpec, fm: object, { block, onLegacyKey }?:
  * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Passed through to
  *   {@link readField}: called with each field the note authored at the position
  *   it is being swept off (#305).
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Passed
+ *   through to {@link readField}: called with each field the note authored at
+ *   the top-level key `data:` gathered it off (#332).
  * @returns {(fm: object) => object} A `system`-block builder.
  */
-export function buildFromFields(fields: readonly FieldSpec[], { block, onLegacyKey }?: {
+export function buildFromFields(fields: readonly FieldSpec[], { block, onLegacyKey, onRetiredTopLevel }?: {
     block?: string | undefined;
     onLegacyKey?: ((field: FieldSpec) => void) | undefined;
+    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
 }): (fm: object) => object;
 /**
  * The fields of a declaration an author actually writes.
@@ -73,6 +162,20 @@ export function buildFromFields(fields: readonly FieldSpec[], { block, onLegacyK
  * @returns {FieldSpec[]} Only the fields with a frontmatter `name`.
  */
 export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
+/**
+ * The fields of a declaration a note may **never** write.
+ *
+ * The complement of {@link authoredFields} in the direction that matters: those
+ * are the fields an author may write, these are the ones authoring is an error
+ * (#330). Everything else in a declaration — a constant, a derived value — is
+ * simply not authored, which is a statement about the *builder* rather than
+ * about the author, and says nothing about what happens if a note writes the
+ * path anyway.
+ *
+ * @param {readonly FieldSpec[]} fields - The declaration.
+ * @returns {FieldSpec[]} Only the fields declaring `runtimeOnly`.
+ */
+export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
 /**
  * @typedef {object} FieldSpec
  * @property {string} to - Dotted path in the emitted `system` block — and,
@@ -135,6 +238,13 @@ export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   describe the *document* rather than the note: `<system>.system.<to>` and
  *   the legacy in-block `<system>.<name>`. Absent means the ordinary case —
  *   the top level is read, as the third step.
+ *
+ *   **It is read from the other side too**, because the statement is symmetric:
+ *   if the two positions hold unrelated quantities then the *in-block* position
+ *   is not the note-level field either, so a check about the note-level field
+ *   reads past it. `engine/frontmatter-lint.mjs` resolves that through
+ *   `collidingBlockKeys`. Read for the emitted field alone until #312, which is
+ *   how an affiliation's office style came to answer for its page heading.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
  * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -
@@ -164,6 +274,78 @@ export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   note, so it declares none.
  * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
  *   the constant, or a function deriving it from the frontmatter.
+ * @property {boolean} [omitWhenAbsent] - **The key is left out entirely when
+ *   the note does not carry the field** (#329), rather than written from a
+ *   declared default.
+ *
+ *   Every other field answers absence with a value: an unauthored `weight` is
+ *   `0`, an unauthored `seat` is `null`. That is right wherever the type has an
+ *   opinion about the empty case. It is wrong wherever the **DataModel** is the
+ *   one holding the answer — an affliction's `onsetDurationFormula` has no
+ *   compile-time value, and writing `null` over it does not merely fail to
+ *   help: it makes "the author said none" and "the author said nothing"
+ *   indistinguishable to every reader downstream, and it overwrites an
+ *   `initial` the system chose on purpose.
+ *
+ *   It is the other conditional row of the same table
+ *   {@link FieldSpec.runtimeOnly} completes, and the two differ only in what
+ *   they do about an *authored* value:
+ *
+ *   | declaration      | authored | absent |
+ *   | --- | --- | --- |
+ *   | ordinary         | emitted  | default written |
+ *   | `omitWhenAbsent` | emitted  | key omitted |
+ *   | `runtimeOnly`    | refused  | key omitted |
+ *
+ *   **A field declaring it must declare no `default`**, and the two are
+ *   contradictory rather than merely redundant — a default is a value for the
+ *   absent case, which is the case this says has none. Nor may it be combined
+ *   with `required` (which fails the build on absence, so nothing is ever
+ *   omitted) or with `runtimeOnly` (which is never emitted at all). The shipped
+ *   declarations are checked for all three in `tests/item-fields.test.ts`.
+ *
+ *   Unlike `runtimeOnly` this is a flag rather than a reason, because there is
+ *   only ever one reason and no message prints it: the DataModel's `initial`
+ *   stands. What an author needs to know is *that* the field has no default,
+ *   which the generated reference states in the field's own row.
+ * @property {string} [runtimeOnly] - **What the field holds once play has
+ *   started** — declared on a field the *document* writes for itself, which no
+ *   note may author (#330).
+ *
+ *   A schema declares plenty of fields a compiled document has no business
+ *   carrying: an affliction's `onsetDate` is the world time its onset fired
+ *   at, crystallized when the phase runs. World time does not exist while
+ *   content is compiled, so there is no authoring-time value — and `0` is
+ *   itself a valid world time, which is why such a field is nullable rather
+ *   than sentinelled and why a default cannot stand in for one.
+ *
+ *   Nothing used to stop a note writing one. The three checks that might have
+ *   each declined for its own correct reason —
+ *   {@link module:engine/system-block.unknownBlockKeys} reads the block's top
+ *   level and never descends into `system:`;
+ *   {@link module:engine/system-block.mergeSystemData} passes through every
+ *   authored path no declared field claims; and the schema check's fatal
+ *   direction is *undeclared*, which a field the schema really does declare
+ *   satisfies. What was missing was a rule saying "declared by the system,
+ *   but never authorable", and this is it.
+ *
+ *   Declaring it does two things, which are the two directions of one fact:
+ *
+ *   | declaration | authored | absent |
+ *   | --- | --- | --- |
+ *   | ordinary | emitted | default written |
+ *   | runtime-only | **refused** | key omitted |
+ *
+ *   The refusal is {@link module:engine/runtime-only-fields.assertNoRuntimeOnlyFields}'s;
+ *   the omission is {@link buildFromFields}'s. A runtime-only entry declares a
+ *   `to` and **no `name`**, so it stays out of {@link authoredFields} and every
+ *   author-facing surface built on it, while still giving `mergeSystemData` a
+ *   claimed path and the refusal something to name.
+ *
+ *   **The value is the reason**, as {@link FieldSpec.topLevelMeans}'s is: a
+ *   boolean would record the decision and lose the case for it, and the reason
+ *   is what the refusal's message and the generated reference both print. It
+ *   completes the sentence "it holds …".
  * @property {string} describe - One line, for the author-facing reference.
  */
 /** Whatever the author wrote, unconverted. */
@@ -290,6 +472,13 @@ export type FieldSpec = {
      * describe the *document* rather than the note: `<system>.system.<to>` and
      * the legacy in-block `<system>.<name>`. Absent means the ordinary case —
      * the top level is read, as the third step.
+     *
+     * **It is read from the other side too**, because the statement is symmetric:
+     * if the two positions hold unrelated quantities then the *in-block* position
+     * is not the note-level field either, so a check about the note-level field
+     * reads past it. `engine/frontmatter-lint.mjs` resolves that through
+     * `collidingBlockKeys`. Read for the emitted field alone until #312, which is
+     * how an affiliation's office style came to answer for its page heading.
      */
     topLevelMeans?: string | undefined;
     /**
@@ -348,11 +537,90 @@ export type FieldSpec = {
      * the constant, or a function deriving it from the frontmatter.
      */
     value?: any | ((fm: object) => any);
+    /**
+     * - **The key is left out entirely when
+     * the note does not carry the field** (#329), rather than written from a
+     * declared default.
+     *
+     * Every other field answers absence with a value: an unauthored `weight` is
+     * `0`, an unauthored `seat` is `null`. That is right wherever the type has an
+     * opinion about the empty case. It is wrong wherever the **DataModel** is the
+     * one holding the answer — an affliction's `onsetDurationFormula` has no
+     * compile-time value, and writing `null` over it does not merely fail to
+     * help: it makes "the author said none" and "the author said nothing"
+     * indistinguishable to every reader downstream, and it overwrites an
+     * `initial` the system chose on purpose.
+     *
+     * It is the other conditional row of the same table
+     * {@link FieldSpec.runtimeOnly} completes, and the two differ only in what
+     * they do about an *authored* value:
+     *
+     * | declaration      | authored | absent |
+     * | --- | --- | --- |
+     * | ordinary         | emitted  | default written |
+     * | `omitWhenAbsent` | emitted  | key omitted |
+     * | `runtimeOnly`    | refused  | key omitted |
+     *
+     * **A field declaring it must declare no `default`**, and the two are
+     * contradictory rather than merely redundant — a default is a value for the
+     * absent case, which is the case this says has none. Nor may it be combined
+     * with `required` (which fails the build on absence, so nothing is ever
+     * omitted) or with `runtimeOnly` (which is never emitted at all). The shipped
+     * declarations are checked for all three in `tests/item-fields.test.ts`.
+     *
+     * Unlike `runtimeOnly` this is a flag rather than a reason, because there is
+     * only ever one reason and no message prints it: the DataModel's `initial`
+     * stands. What an author needs to know is *that* the field has no default,
+     * which the generated reference states in the field's own row.
+     */
+    omitWhenAbsent?: boolean | undefined;
+    /**
+     * - **What the field holds once play has
+     * started** — declared on a field the *document* writes for itself, which no
+     * note may author (#330).
+     *
+     * A schema declares plenty of fields a compiled document has no business
+     * carrying: an affliction's `onsetDate` is the world time its onset fired
+     * at, crystallized when the phase runs. World time does not exist while
+     * content is compiled, so there is no authoring-time value — and `0` is
+     * itself a valid world time, which is why such a field is nullable rather
+     * than sentinelled and why a default cannot stand in for one.
+     *
+     * Nothing used to stop a note writing one. The three checks that might have
+     * each declined for its own correct reason —
+     * {@link module :engine/system-block.unknownBlockKeys} reads the block's top
+     * level and never descends into `system:`;
+     * {@link module :engine/system-block.mergeSystemData} passes through every
+     * authored path no declared field claims; and the schema check's fatal
+     * direction is *undeclared*, which a field the schema really does declare
+     * satisfies. What was missing was a rule saying "declared by the system,
+     * but never authorable", and this is it.
+     *
+     * Declaring it does two things, which are the two directions of one fact:
+     *
+     * | declaration | authored | absent |
+     * | --- | --- | --- |
+     * | ordinary | emitted | default written |
+     * | runtime-only | **refused** | key omitted |
+     *
+     * The refusal is {@link module :engine/runtime-only-fields.assertNoRuntimeOnlyFields}'s;
+     * the omission is {@link buildFromFields}'s. A runtime-only entry declares a
+     * `to` and **no `name`**, so it stays out of {@link authoredFields} and every
+     * author-facing surface built on it, while still giving `mergeSystemData` a
+     * claimed path and the refusal something to name.
+     *
+     * **The value is the reason**, as {@link FieldSpec.topLevelMeans}'s is: a
+     * boolean would record the decision and lose the case for it, and the reason
+     * is what the refusal's message and the generated reference both print. It
+     * completes the sentence "it holds …".
+     */
+    runtimeOnly?: string | undefined;
     /**
      * - One line, for the author-facing reference.
      */
     describe: string;
 };
 import { legacyKeyOf } from "./system-block.mjs";
+import { retiredTopLevelKey } from "./system-block.mjs";
 import { setPath } from "./system-block.mjs";
-export { legacyKeyOf, setPath };
+export { legacyKeyOf, retiredTopLevelKey, setPath };

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

@@ -18,6 +18,26 @@ export function bareAddress(value: string | null): string | null;
  * @returns {string} `<pkg>-none-folder-<shortcode>`.
  */
 export function folderAddress(pkg: string, shortcode: string): string;
+/**
+ * The Foundry `_id` a folder note's documents are filed under.
+ *
+ * **The one derivation, because two passes need the same answer.** The folder
+ * pass hashes it here on its way to emitting the `Folder` documents; the
+ * content index publishes it, through `noteDocId`, for a consumer who will
+ * never run this build. Deriving it twice is how the index came to publish a
+ * plausible-looking id that resolved to nothing — the general id rule hashes a
+ * note's address under the `document` namespace, and a folder's is hashed under
+ * {@link FOLDER_ID_NAMESPACE} (#310).
+ *
+ * An **authored `id` still wins**, and is applied by the caller: this is the
+ * derivation, not the resolution, so the pin rule stays stated once, where
+ * every other note type states it ({@link module:engine/note-ids.noteDocId}).
+ *
+ * @param {string} pkg - The content package.
+ * @param {string} shortcode - The folder's shortcode.
+ * @returns {string} The folder's 16-character Foundry id.
+ */
+export function folderDocId(pkg: string, shortcode: string): string;
 /**
  * Collect every folder note in a content tree.
  *

package/types/engine/foreign-catalog.d.mts

@@ -32,6 +32,25 @@ export function catalogDir(config: object, id: string, version: string): string;
  * @returns {string} The path, whether or not it exists.
  */
 export function cachedSchemaPath(config: object, id: string, version: string): string;
+/**
+ * What to record about the packs being extracted.
+ *
+ * Exported so the pair is one fact: {@link foreignItemCatalogDirs} reads what
+ * this writes, and a test that hand-wrote the file would prove the reader
+ * against a transcription of the format rather than against the format.
+ *
+ * A pack declaring no `system` records `null` — Foundry requires the field on
+ * an Item pack, so this is the shape of a manifest that is wrong rather than a
+ * case with a meaning, and `null` reads as "neutral", which is the safe way to
+ * be wrong: a neutral pack is read by every system rather than by none.
+ *
+ * @param {readonly object[]} itemPacks - The manifest's Item pack entries.
+ * @returns {Array<{name: string, system: string|null}>} What each one is.
+ */
+export function itemPackManifest(itemPacks: readonly object[]): Array<{
+    name: string;
+    system: string | null;
+}>;
 /**
  * Write an unzipped archive's entries under `dest`.
  *
@@ -159,10 +178,27 @@ export function fetchAllCatalogs(config: object): Promise<number>;
  * Reads the cache only. A cold cache is an error naming the command that fills
  * it, rather than a download nobody asked for.
  *
+ * **Scoped to one system when the caller compiles for one (#58)**, exactly as
+ * {@link module:engine/generate.itemPackJsonDirs} scopes the local half. The
+ * two halves answer the same lookup — `loadItemsMap` merges them into one
+ * address space keyed by `subType:shortcode` — so scoping only the local one
+ * leaves the collision it was meant to remove: `skill:awar` is a real address
+ * in both vocabularies, and a `harn-ensemble` actor compiled for `hm3` would
+ * resolve three quarters of its references against whichever document the
+ * dependency's `sohl` pack happened to supply. A pack that declares no system
+ * is neutral and always read; asking for no system reads every pack, which is
+ * every single-system build.
+ *
  * @param {object} config - The resolved build configuration.
- * @returns {string[]} Every cached dependency's item directories.
+ * @param {string|null} [system] - The system the caller is compiling for.
+ *   Omitted or `null`, every cached pack is read.
+ * @returns {Array<{dir: string, package: string}>} Every cached dependency's
+ *   item directories, each with the package that published it.
  */
-export function foreignItemCatalogDirs(config: object): string[];
+export function foreignItemCatalogDirs(config: object, system?: string | null): Array<{
+    dir: string;
+    package: string;
+}>;
 /**
  * The file a system publishes its `system` field sets as (#60).
  *

package/types/engine/foundry-entries.d.mts

@@ -29,6 +29,12 @@ export function anchorsOf(entryUuid: string, entryId: string, body: string, name
  * @param {string} name - The note's display name.
  * @param {string} address - The note's package-relative address.
  * @param {string} body - The note's markdown body.
+ * **Each entry carries the `id` of the document it addresses**, not only its
+ * UUID. The two are one fact — a UUID ends in the id — but only the entry knows
+ * which derivation produced it: an item's is its note's `fm.id`, and its
+ * documentation journal's is {@link itemDocEntryId} of that. Stating it here is
+ * what lets the content index publish an identity it did not re-derive (#310).
+ *
  * @param {object} ctx - Resolved identities: `{ contentPackage,
  *   foundryPackageId, packRouter }`.
  * @returns {Array<object>} One or two entries, in {@link buildManifest}'s shape.