@heroiclands/package-build 9.0.0 → 10.0.0

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

@@ -0,0 +1,251 @@
+/**
+ * The declared tags a note of this type may carry, flattened.
+ *
+ * @param {string} type - The note's type.
+ * @param {object} [groups] - The grouped declaration.
+ * @returns {readonly string[]} The tags, in declaration order.
+ */
+export function declaredTags(type: string, groups?: object): readonly string[];
+/**
+ * The `data:` keys a note type may carry.
+ *
+ * @param {string} type - The note's `type`.
+ * @param {Readonly<Record<string, TypeVocabulary>>} [vocabulary] - The registry
+ *   to read, defaulting to {@link NOTE_VOCABULARY}.
+ * @returns {readonly DataFieldSpec[]|undefined} The declaration, or `undefined`
+ *   when the type declares none — which is not the same as declaring an empty
+ *   one, and is why the lint makes no claim rather than refusing every key.
+ */
+export function dataFields(type: string, vocabulary?: Readonly<Record<string, TypeVocabulary>>): readonly DataFieldSpec[] | undefined;
+/**
+ * The `subType` values a note type declares.
+ *
+ * @param {string} type - The note's `type`.
+ * @param {Readonly<Record<string, TypeVocabulary>>} [vocabulary] - The registry
+ *   to read, defaulting to {@link NOTE_VOCABULARY}.
+ * @returns {readonly string[]|null|undefined} The closed set; `null` when the
+ *   type has a `subType` whose values are not yet enumerated; `undefined` when
+ *   it has no `subType` at all — see {@link TypeVocabulary}.
+ */
+export function subTypes(type: string, vocabulary?: Readonly<Record<string, TypeVocabulary>>): readonly string[] | null | undefined;
+/**
+ * Every note type this toolchain compiles, and the closed vocabulary it
+ * declares.
+ *
+ * Taken from the content-format specification, one `### type:` section per
+ * entry. Where the specification and the shape notes are authored in today
+ * disagree, the specification wins on the **name** — that is what a `data:`
+ * key will be called — and the disagreement is recorded on the field rather
+ * than resolved silently.
+ *
+ * @type {Readonly<Record<string, TypeVocabulary>>}
+ */
+/**
+ * The tags that **classify** a note, grouped by what they classify (#172).
+ *
+ * `tags:` lives at the open top level and most tags belong there: a theme, a
+ * region, a working state is the author's own and this build has no opinion
+ * about it. A classifying tag is different, because something queries it — a
+ * settlement tagged `village` appears in the list of villages and an untagged
+ * one does not, so `vilage` does not merely look wrong, it removes the note from
+ * an index while the index still renders a table that looks complete.
+ *
+ * **This list is not a closed set.** An unrecognised tag is legal, because the
+ * region is open; what is reported is a **near miss** — a tag close enough to a
+ * declared one to be a typo of it.
+ *
+ * **Each group names the types it applies to**, and that scope is what makes the
+ * check sound rather than noisy. A place's kinds are only a place's: `azravan`
+ * on a faith, `barter` on an economy note and `secret` on three lore notes all
+ * sit within a typo's distance of `caravan`, `border` and `sacred`, and not one
+ * is a mistake. Checked against every group at once the rule was wrong on every
+ * note it touched; scoped to the type it is wrong on none. `types: null` is a
+ * group any note may carry.
+ *
+ * Kind and character are separate groups because one slot could not hold both: a
+ * fishing village is a `village` that is `fishing`, and the single-valued field
+ * this replaced had to spell it `Fishing Village` as a value of its own.
+ */
+export const DECLARED_TAGS: Readonly<{
+    /** What a place *is*. */
+    placeKind: Readonly<{
+        types: string[];
+        tags: readonly string[];
+    }>;
+    /** What a place is known for. */
+    placeCharacter: Readonly<{
+        types: string[];
+        tags: readonly string[];
+    }>;
+    /** A place's scale, where the subtype does not distinguish it. */
+    placeScale: Readonly<{
+        types: string[];
+        tags: readonly string[];
+    }>;
+    /** Which kind of body a being belongs to — a station rather than a rank. */
+    beingStation: Readonly<{
+        types: string[];
+        tags: readonly string[];
+    }>;
+    /** A note's working state, which any note may carry. */
+    state: Readonly<{
+        types: null;
+        tags: readonly string[];
+    }>;
+}>;
+export const NOTE_VOCABULARY: Readonly<{
+    being: Readonly<{
+        subTypes: null;
+        data: readonly DataFieldSpec[];
+    }>;
+    affiliation: Readonly<{
+        subTypes: readonly string[];
+        data: readonly DataFieldSpec[];
+    }>;
+    affliction: Readonly<{
+        subTypes: readonly string[];
+        data: readonly DataFieldSpec[];
+    }>;
+    armorgear: Readonly<{
+        data: readonly DataFieldSpec[];
+    }>;
+    attribute: Readonly<{
+        data: readonly DataFieldSpec[];
+    }>;
+    concoctiongear: Readonly<{
+        subTypes: readonly string[];
+        data: readonly (DataFieldSpec | Readonly<{
+            describe: "How many of the thing there are; one when unstated.";
+            shape: "number";
+            kind: "number";
+            name: "quantity";
+        }>)[];
+    }>;
+    containergear: Readonly<{
+        data: readonly DataFieldSpec[];
+    }>;
+    miscgear: Readonly<{
+        data: readonly (DataFieldSpec | Readonly<{
+            describe: "How many of the thing there are; one when unstated.";
+            shape: "number";
+            kind: "number";
+            name: "quantity";
+        }>)[];
+    }>;
+    mystery: Readonly<{
+        subTypes: readonly string[];
+        data: readonly DataFieldSpec[];
+    }>;
+    mysticalability: Readonly<{
+        subTypes: readonly string[];
+        data: readonly DataFieldSpec[];
+    }>;
+    projectilegear: Readonly<{
+        subTypes: readonly string[];
+        data: readonly (DataFieldSpec | Readonly<{
+            describe: "How many of the thing there are; one when unstated.";
+            shape: "number";
+            kind: "number";
+            name: "quantity";
+        }>)[];
+    }>;
+    skill: Readonly<{
+        subTypes: readonly string[];
+        data: readonly DataFieldSpec[];
+    }>;
+    trauma: Readonly<{
+        subTypes: readonly string[];
+        data: readonly DataFieldSpec[];
+    }>;
+    weapongear: Readonly<{
+        data: readonly DataFieldSpec[];
+    }>;
+    doc: Readonly<{
+        subTypes: readonly string[];
+        data: readonly never[];
+    }>;
+    macro: Readonly<{
+        data: readonly never[];
+    }>;
+    homepage: Readonly<{
+        data: readonly never[];
+    }>;
+    map: Readonly<{
+        subTypes: readonly string[];
+        data: readonly ({
+            describe: string;
+            shape: "string";
+            kind: "string";
+            name: string;
+        } | {
+            describe: string;
+            shape: "list";
+            kind: "list";
+            name: string;
+        } | {
+            describe: string;
+            shape: "number";
+            kind: "number";
+            name: string;
+        } | {
+            describe: string;
+            shape: "as authored";
+            name: string;
+        })[];
+    }>;
+}>;
+/**
+ * One `data:` key a note type may carry.
+ *
+ * A deliberate subset of {@link import ("./field-spec.mjs").FieldSpec}: no `to`,
+ * because nothing here builds anything yet. Reading `data.*` through into a
+ * document's `system` block is the passthrough slice (#126), and claiming an
+ * emitted path this does not produce would be a lie in the one place a reader
+ * would trust it.
+ */
+export type DataFieldSpec = {
+    /**
+     * - The key under `data:`, dotted for a nested one
+     * (`charges.value`).
+     */
+    name: string;
+    /**
+     * - The value's
+     * shape, for the lint. Absent means no claim is made about the value — which
+     * is the honest answer wherever the specification's stated shape and the
+     * shape notes are authored in today disagree.
+     */
+    kind?: "string" | "number" | "boolean" | "map" | "list" | undefined;
+    /**
+     * - Human-readable shape, for a finding and for
+     * documentation.
+     */
+    shape?: string | undefined;
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};
+/**
+ * What one note type declares.
+ *
+ * `subTypes` is three-valued, and the difference matters:
+ *
+ * - **omitted** — the type has no `subType` at all, and a note carrying one is
+ *   a finding. A `weapon` is the deliberate case: SoHL distinguishes a
+ *   weapon's uses by strike mode rather than by kind.
+ * - **`null`** — the type has a `subType` whose values the specification does
+ *   not yet enumerate. Presence is permitted and the value is unchecked.
+ * - **a list** — the closed set of values, and anything else is a finding.
+ */
+export type TypeVocabulary = {
+    /**
+     * - The `data:` keys, closed.
+     */
+    data: readonly DataFieldSpec[];
+    /**
+     * - The top-level `subType`
+     * values, as above.
+     */
+    subTypes?: readonly string[] | null | undefined;
+};

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

@@ -46,9 +46,10 @@ export function locateConfigError(err: unknown, configPath?: string): unknown;
  * - **`rootDir`** is the configuration's own directory, always. A data file
  *   cannot write `import.meta.dirname`, and any absolute path it wrote instead
  *   would be one machine's — so authoring it is rejected rather than honoured.
- * - **`itemBuilders`** is a *name* (`sohl`), resolved against the built-in
- *   registries. A registry of a consumer's own is code, and code goes in an
- *   `.mjs` configuration.
+ * - **`itemBuilders`** is a *name* (`sohl`) — or a list of names, for a tree
+ *   feeding more than one system (#58) — resolved against the built-in
+ *   registries. A registry's name is the system it belongs to. A registry of a
+ *   consumer's own is code, and code goes in an `.mjs` configuration.
  * - **`stats.systemVersion`** is derived from the adjacent `package.json` when
  *   the configuration does not state it. Stating it is still allowed: a
  *   repository shipping content *for* another package (a module declaring

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

@@ -6,14 +6,14 @@
  *
  * @param {readonly object[]} packs - The resolved `packs` list from
  *   `defineConfig`.
- * @returns {{resolve: (fm: object, docType: string) => string,
- *   resolveOrNull: (fm: object, docType: string) => string|undefined,
+ * @returns {{resolve: (fm: object, docType: string, system?: string) => string,
+ *   resolveOrNull: (fm: object, docType: string, system?: string) => string|undefined,
  *   packsOfType: (docType: string) => string[],
  *   defaultOf: (docType: string) => string|undefined}} The router.
  */
 export function createPackRouter(packs: readonly object[]): {
-    resolve: (fm: object, docType: string) => string;
-    resolveOrNull: (fm: object, docType: string) => string | undefined;
+    resolve: (fm: object, docType: string, system?: string) => string;
+    resolveOrNull: (fm: object, docType: string, system?: string) => string | undefined;
     packsOfType: (docType: string) => string[];
     defaultOf: (docType: string) => string | undefined;
 };

package/types/engine/prose-lint.d.mts

@@ -12,11 +12,15 @@
  * @param {readonly string[]} [opts.paths] - Files or directories to check
  *   instead of the whole root.
  * @param {boolean} [opts.write=false] - Rewrite unformatted files in place
- *   rather than reporting them.
+ *   rather than reporting them. Each file is formatted to a fixpoint (up to
+ *   {@link MAX_FORMAT_PASSES} passes), so a written tree is one a second run
+ *   leaves alone; a file that will not converge is reported and left unchanged
+ *   (#125).
  * @param {object} [opts.prettier] - The Prettier module, for tests.
  * @returns {Promise<{findings: Array<{file: string, severity: string,
  *   message: string}>, checked: number, written: string[]}>} The findings, how
- *   many files were considered, and what was rewritten.
+ *   many files were considered, and what was rewritten. `--write` reports
+ *   findings too — a file it cannot parse, or cannot format to a fixpoint.
  */
 export function checkFormatting(root: string, opts?: {
     paths?: readonly string[] | undefined;

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

@@ -43,12 +43,83 @@ export function assertNoDraftField(fm: object | null | undefined, { file, absPat
  * both refusals need it and a second copy is a second thing to keep correct.
  *
  * @param {string|undefined} absPath - The note's file.
- * @param {string} key - The top-level frontmatter key.
+ * @param {string} key - The frontmatter key.
+ * @param {string} [value] - When given, prefer the occurrence whose line also
+ *   carries this text — so a finding about one entry of a block opens on that
+ *   entry rather than on the key that introduces it.
  * @returns {{line?: number, column?: number}|undefined} Spreadable position
  *   fields, dropped rather than guessed when the file cannot be read or the key
  *   cannot be found — as `formatDiagnostic` requires.
  */
-export function locateFrontmatterKey(absPath: string | undefined, key: string): {
+export function locateFrontmatterKey(absPath: string | undefined, key: string, value?: string): {
     line?: number;
     column?: number;
 } | undefined;
+/**
+ * What a note writing a renamed field is told, in one place.
+ *
+ * Shared by the compile-time report and the frontmatter lint, because an author
+ * meets whichever runs first and they should read the same. It names the key to
+ * write rather than a value to correct — no value makes the retired spelling
+ * right — and it says the note compiles either way, so a reader knows this is a
+ * rename to schedule rather than a build to unbreak.
+ *
+ * @param {string} retired - The spelling the note used.
+ * @param {string} current - What to write instead.
+ * @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 retiredAliasMessage(retired: string, current: string, file?: string): string;
+/**
+ * Whether a note writes the retired spelling of a field, wherever it put it.
+ *
+ * Both regions are searched, because {@link sohlField} reads both: a note that
+ * moved the key to the top level without renaming it has done half the
+ * migration, and should be told so rather than passing in silence.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} current - The field's current name.
+ * @returns {boolean} Whether the retired spelling is declared.
+ */
+export function declaresRetiredAlias(fm: object | null | undefined, current: string): boolean;
+/**
+ * Read a field that has a retired spelling, the current name winning.
+ *
+ * This is the whole of the retirement window's behaviour, in one function, so
+ * the compiler and the linter cannot disagree about which value a note carries.
+ * Resolution within each spelling is {@link sohlField}'s — the `sohl:` block
+ * 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.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} current - The field's current name.
+ * @returns {any} The value, or `undefined` when neither spelling carries one.
+ */
+export function readAliasedField(fm: object | null | undefined, current: string): any;
+/**
+ * The current field name a retired spelling was renamed to.
+ *
+ * Keyed by the **current** name, because that is what a type's schema declares
+ * 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.
+ *
+ * **`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/schema-check.d.mts

@@ -85,6 +85,56 @@ export function compareFields({ builders, artifact, documentType, subtypeOf, }:
     unemitted: object[];
     skipped: string[];
 };
+/**
+ * What a **compiled document** carries in `system`, against what the receiving
+ * subtype declares (#155).
+ *
+ * The third of the three checks, and the only one whose emitted set is
+ * *observed*. {@link compareFields} reads the `itemBuilders` declarations and
+ * {@link checkAuthoredSystemData} reads a note's `<system>.system`; between them
+ * they miss every key a compiler writes on its own initiative, which is not a
+ * residue — it is `shortcode`, `actionDefs`, `notes`, `docHtml` and `archetype`.
+ *
+ * **The keys come from the object the compiler built, after a JSON round trip.**
+ * That is exactly what the pack file receives, so a key whose value is
+ * `undefined` — dropped by `JSON.stringify`, never written, nothing for Foundry
+ * to discard — is correctly not a finding. Reading the assembled block is also
+ * the only derivation that cannot go stale: a compiler that grows a key is
+ * checked on the next build without anyone remembering to add it to a list.
+ *
+ * **Authored paths are left alone.** A note's own `<system>.system` is reported
+ * by {@link checkAuthoredSystemData}, which can point at the line the author
+ * wrote; reporting it again here would be the same defect twice, once without a
+ * position.
+ *
+ * **A subtree the artifact does not describe is not checked**, rather than
+ * reported wholesale — see {@link enumeratedContainers} for the
+ * `TypedSchemaField` case that makes the distinction load-bearing.
+ *
+ * @param {object} opts
+ * @param {object} opts.system - The `system` block the compiler assembled.
+ * @param {SchemaArtifact} opts.artifact - The receiving system's schemas.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subtype - The document subtype being emitted.
+ * @param {string} opts.type - The content type whose note produced it, for the
+ *   message.
+ * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+ *   declaration, which decides a finding's {@link EmissionFinding.origin}.
+ * @param {ReadonlySet<string>} [opts.authored] - Paths the note authored, left
+ *   to the note-side check.
+ * @returns {EmissionFinding[]} One per undeclared path, shallowest-first.
+ */
+export function compareEmittedSystem({ system, artifact, documentType, subtype, type, fields, authored, }: {
+    system: object;
+    artifact: SchemaArtifact;
+    documentType: string;
+    subtype: string;
+    type: string;
+    fields?: readonly {
+        to?: string;
+    }[] | undefined;
+    authored?: ReadonlySet<string> | undefined;
+}): EmissionFinding[];
 /**
  * The published schema this build should check itself against, or `null`.
  *
@@ -140,6 +190,107 @@ export function undeclaredMessage(finding: object): string;
  * @returns {string} The message.
  */
 export function unemittedMessage(finding: object): string;
+/**
+ * What an author is told about an emitted key the target system does not
+ * define — in the terms of whoever can actually fix it.
+ *
+ * The failure is identical in both cases and the remedies are not, which is
+ * why the two are told apart at all:
+ *
+ * | origin | who writes it | what fixes it |
+ * | --- | --- | --- |
+ * | `builder` | a `fields:` entry in this repository's `itemBuilders` | change the field's `to`, or get the system to declare it |
+ * | `compiler` | this package, on every document of the subtype | **nothing here** — the system must declare it, or this package must be pinned to a build that does not write it |
+ *
+ * A `compiler` finding is the one worth spelling out, because the obvious first
+ * move — go and look for the field in `itemBuilders` — leads nowhere: there is
+ * no declaration to correct. It means the build is running ahead of the system
+ * it compiles for, and the version named in the message is what says so.
+ *
+ * @param {EmissionFinding} finding - One entry from
+ *   {@link compareEmittedSystem}.
+ * @returns {string} The message.
+ */
+export function emittedUndeclaredMessage(finding: EmissionFinding): string;
+/**
+ * What a note authors under `<system>.system`, against what the receiving
+ * subtype declares (#58).
+ *
+ * The **note-side** half of the check `compareFields` performs on the
+ * declarations. A field list is checked once for the whole build because it is
+ * the same for every document; an authored `system` block is a property of one
+ * note, so it is checked where that note is compiled and reported against that
+ * note's file.
+ *
+ * It is the same failure either way, and the reason both halves exist: Foundry
+ * discards an unknown `system` key at construction and says nothing, so a
+ * mistyped path is lost at load while the build reports success.
+ *
+ * **Silent where there is nothing to check against.** A module pinning a system
+ * version released before the artifact existed, or a subtype the artifact does
+ * not name, produces no findings — the same stance `compareFields` takes, where
+ * an unknown subtype is a routing question rather than a field one. The
+ * whole-build check in `content-build lint` is where a missing artifact is said
+ * out loud, once, instead of per note.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} opts
+ * @param {string} opts.block - The system block to read, e.g. `"sohl"`.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subType - The document subtype the note compiles into.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @returns {{path: string, message: string}[]} One finding per undeclared path,
+ *   shallowest-first.
+ */
+export function checkAuthoredSystemData(fm: object, { block, documentType, subType, config }: {
+    block: string;
+    documentType: string;
+    subType: string;
+    config?: object | undefined;
+}): {
+    path: string;
+    message: string;
+}[];
+/**
+ * The `system` block a compiler just assembled, against what the receiving
+ * subtype declares (#155).
+ *
+ * The build-time face of {@link compareEmittedSystem}: it resolves the schema
+ * the way every other check here does — the system's own committed artifact, or
+ * the cached one from the release a module pins — and attaches the message a
+ * reader sees.
+ *
+ * **Silent where there is nothing to check against**, exactly as its two
+ * siblings are: a module pinning a system version released before the artifact
+ * existed, or a subtype the artifact does not name, produces no findings.
+ * `content-build lint` is where a missing artifact is said out loud, once.
+ *
+ * @param {object} system - The `system` block the compiler produced.
+ * @param {object} opts
+ * @param {object} opts.fm - The note's frontmatter, for the authored paths this
+ *   check leaves to {@link checkAuthoredSystemData}.
+ * @param {string} opts.block - The system block to read, e.g. `"sohl"`.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subType - The document subtype the note compiles into.
+ * @param {string} opts.type - The note's content type, for the message.
+ * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+ *   declaration, which decides each finding's origin.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @returns {(EmissionFinding & {message: string})[]} One per undeclared path.
+ */
+export function checkEmittedSystemData(system: object, { fm, block, documentType, subType, type, fields, config }: {
+    fm: object;
+    block: string;
+    documentType: string;
+    subType: string;
+    type: string;
+    fields?: readonly {
+        to?: string;
+    }[] | undefined;
+    config?: object | undefined;
+}): (EmissionFinding & {
+    message: string;
+})[];
 /**
  * The artifact version this module reads.
  *
@@ -174,3 +325,34 @@ export type SchemaArtifact = {
         inherited: string[];
     }>>;
 };
+/**
+ * One `system` key a compiled document carries that its subtype does not
+ * declare.
+ */
+export type EmissionFinding = {
+    /**
+     * - The content type whose note produced the document.
+     */
+    type: string;
+    /**
+     * - The document subtype it compiled into.
+     */
+    subtype: string;
+    /**
+     * - `Item`, `Actor`, …
+     */
+    documentType: string;
+    /**
+     * - The undeclared path, dotted.
+     */
+    field: string;
+    /**
+     * - The version checked against.
+     */
+    systemVersion: string;
+    /**
+     * - What wrote it. See
+     * {@link emittedUndeclaredMessage}.
+     */
+    origin: "builder" | "compiler";
+};