@heroiclands/package-build 0.6.0 → 3.0.0

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

@@ -0,0 +1,103 @@
+/**
+ * Every declared relationship that opted into supplying an item catalogue.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{id: string, manifest: string, kind: string, verified: string|undefined}>}
+ *   The opted-in relationships, in declaration order.
+ */
+export function itemCatalogRelationships(config: object): Array<{
+    id: string;
+    manifest: string;
+    kind: string;
+    verified: string | undefined;
+}>;
+/**
+ * The cache directory for one dependency at one version.
+ *
+ * Keyed by version so that changing the pinned version is a different cache
+ * rather than a silent overwrite, and so a second build costs nothing.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {string} id - The dependency's package id.
+ * @param {string} version - Its resolved version.
+ * @returns {string} The directory.
+ */
+export function catalogDir(config: object, id: string, version: string): string;
+/**
+ * Write an unzipped archive's entries under `dest`.
+ *
+ * @param {Record<string, Uint8Array>} files - The archive's entries.
+ * @param {string} dest - Where to write them.
+ * @returns {void}
+ */
+export function writeZipEntries(files: Record<string, Uint8Array>, dest: string): void;
+/**
+ * The manifest URL to actually read, pinned to the declared version.
+ *
+ * A consumer writes `releases/latest/download/system.json`, which is the right
+ * thing to publish and the wrong thing to build against: the artifact behind it
+ * changes when somebody else cuts a release, so a build names no particular
+ * dependency and "thalorna 0.1.0" stops being reproducible. The declared
+ * `compatibility.verified` is the version this repository was actually built
+ * against, so that is the one to fetch.
+ *
+ * GitHub's release URLs are rewritable — `releases/latest/download/X` is
+ * `releases/download/v<version>/X`. Where the URL is not that shape there is
+ * nothing to rewrite, so the declared URL is read and its version checked
+ * instead: floating silently is the one outcome not on offer.
+ *
+ * @param {string} url - The declared manifest URL.
+ * @param {string|undefined} verified - The declared verified version.
+ * @returns {{url: string, pinned: boolean}} The URL to read.
+ */
+export function pinnedManifestUrl(url: string, verified: string | undefined): {
+    url: string;
+    pinned: boolean;
+};
+/**
+ * Fetch one dependency and extract its Item packs.
+ *
+ * Idempotent: a complete cache for the resolved version is left alone.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{id: string, manifest: string}} rel - The declared relationship.
+ * @returns {Promise<string>} The dependency's cache directory.
+ */
+export function fetchCatalog(config: object, rel: {
+    id: string;
+    manifest: string;
+}): Promise<string>;
+/**
+ * Fill the cache from a locally built artifact rather than a release.
+ *
+ * `source` is either the `.zip` a package build emits or the directory it was
+ * built from. Either way the manifest inside it names the version, so the cache
+ * stays version-keyed and a compile cannot tell the difference — which is the
+ * point: a consumer can be built against a dependency that has not shipped.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{id: string}} rel - The declared relationship.
+ * @param {string} source - Path to the artifact or its directory.
+ * @returns {Promise<string>} The dependency's cache directory.
+ */
+export function fetchCatalogFromPath(config: object, rel: {
+    id: string;
+}, source: string): Promise<string>;
+/**
+ * Fetch every opted-in dependency. The `deps fetch` command.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Promise<number>} How many dependencies were fetched.
+ */
+export function fetchAllCatalogs(config: object): Promise<number>;
+/**
+ * The extracted item directories the actors pass should resolve against, on
+ * top of this repository's own.
+ *
+ * Reads the cache only. A cold cache is an error naming the command that fills
+ * it, rather than a download nobody asked for.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {string[]} Every cached dependency's item directories.
+ */
+export function foreignItemCatalogDirs(config: object): string[];

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

@@ -0,0 +1,43 @@
+/**
+ * Every foreign package whose manifest entries a build cannot address.
+ *
+ * A package is reported only when it contributes entries and **none** of them
+ * yields a readable canonical key — the total, silent failure described above.
+ * Partial drift is deliberately not reported here: it resolves something, and
+ * whatever it fails to resolve surfaces as an ordinary dead address, pointed at
+ * the note that cites it. A package contributing no entries at all is likewise
+ * not a finding; a pack-only package publishes no addressable pages by design
+ * (#1516), and one being brought up publishes nothing yet.
+ *
+ * @param {Map<string, {package?: string}>} foreignIndex - `foreign.index` as
+ *   returned by `loadForeignManifests`, keyed by canonical key.
+ * @returns {Array<{package: string, entries: number, sampleKey: string}>} One
+ *   finding per drifted package, in the order the index first names each.
+ */
+export function unaddressableForeignPackages(foreignIndex: Map<string, {
+    package?: string;
+}>): Array<{
+    package: string;
+    entries: number;
+    sampleKey: string;
+}>;
+/**
+ * One finding, in the standard `file:line:column: severity: message` form.
+ *
+ * The position is recovered by locating the offending key in the manifest text:
+ * the finding is about a literal the reader can see in the file, so its position
+ * is implicit rather than absent. When the file cannot be read, or the key is
+ * not in it, the locator degrades to the file alone — a dropped field, never a
+ * guessed `1:1` that would send the reader to the top of a 500 KB manifest for a
+ * finding that is not there.
+ *
+ * @param {{package: string, entries: number, sampleKey: string}} finding - One
+ *   finding from {@link unaddressableForeignPackages}.
+ * @param {string} manifestDir - The directory the manifests were loaded from.
+ * @returns {string} The formatted diagnostic, path first on the line.
+ */
+export function formatUnaddressableFinding(finding: {
+    package: string;
+    entries: number;
+    sampleKey: string;
+}, manifestDir: string): string;

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

@@ -0,0 +1,74 @@
+/**
+ * Whether a value satisfies a declared {@link FieldSpec.kind}.
+ *
+ * Deliberately lenient about the spellings YAML makes ambiguous: `"12"` is a
+ * number, because a quoted scalar is how a number arrives from many editors,
+ * and a map authored as an empty list is a map, because Obsidian's property
+ * editor serialises an emptied map that way (#8). What it rejects is a value
+ * that cannot mean what the field is for — `weight: heavy`.
+ *
+ * @param {unknown} value - The authored value.
+ * @param {string} kind - The declared kind.
+ * @returns {boolean} Whether it is acceptable.
+ */
+export function matchesKind(value: unknown, kind: string): boolean;
+/**
+ * Check one note against its type's schema.
+ *
+ * @param {object} note - A note from the link index (`{fm, file, raw, type}`).
+ * @param {object} opts
+ * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @param {object} [opts.index] - The link index, for the reference check. Its
+ *   absence skips that check rather than reporting every reference as dead.
+ * @returns {object[]} Findings, each with a locator where one is obtainable.
+ */
+export function lintNote(note: object, { schemas, index }: {
+    schemas: Record<string, readonly object[]>;
+    index?: object | undefined;
+}): object[];
+/**
+ * Check every note in a built index against its type's schema.
+ *
+ * @param {object} index - From `buildLinkIndex`.
+ * @param {object} opts
+ * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @param {boolean} [opts.references=true] - Whether to check references.
+ * @returns {{findings: object[], notes: number}} The findings, and how many
+ *   notes were inspected.
+ */
+export function lintFrontmatter(index: object, { schemas, references }: {
+    schemas: Record<string, readonly object[]>;
+    references?: boolean | undefined;
+}): {
+    findings: object[];
+    notes: number;
+};
+/**
+ * `sohl:` keys every type accepts, whatever its schema says.
+ *
+ * Neither is part of a type's vocabulary — both are read for *any* note, by
+ * passes that run before a builder sees it — so neither appears in a field
+ * declaration and both would otherwise be reported as unknown on every note
+ * that uses them.
+ *
+ * - `folder` — the compendium folder the document is filed in.
+ * - `pack` — which compendium of the note's document type receives it, for a
+ *   repository shipping several (#1566).
+ * - `archetype` — the archetype flag, read for any note by the walk itself.
+ * - `kbcat` — the knowledgebase category a note is grouped under.
+ *
+ * `kbcat` is the one that matters for what this check *is*. **The pack build is
+ * not the only reader of a note's frontmatter.** A note also feeds a
+ * knowledgebase and a website, and those surfaces consume classification the
+ * compiler never emits — `kbcat` alone is read 51 times across SoHL's
+ * knowledgebase layouts. A check that equated "the vocabulary" with "what the
+ * builder compiles" would report every one of those as an unknown property and
+ * turn a correct tree red, which is exactly what it did on first run: 4,241
+ * findings against SoHL's own content, none of them a defect.
+ *
+ * So a type's schema declares what a note **may write**, which is broader than
+ * what any one consumer reads.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const UNIVERSAL_KEYS: ReadonlySet<string>;

package/types/engine/frontmatter.d.mts

@@ -0,0 +1,99 @@
+/**
+ * Resolves a dotted frontmatter key (e.g., "name.full") into the nested
+ * value. Returns `defaultValue` if any path segment is missing.
+ */
+export function getFrontmatter(fm: any, key: any, defaultValue?: undefined): any;
+/**
+ * Reads a key from `fm.sohl` (the vault's nested system-fields block).
+ * Supports dotted notation, e.g. sohlField(fm, "charges.value", 0).
+ * Falls back to top-level `fm[key]` if `sohl` doesn't carry the key.
+ */
+export function sohlField(fm: any, key: any, defaultValue?: undefined): any;
+/**
+ * Resolve the `charges` block shared by Mystery and Mystical Ability items.
+ *
+ * Charge usage is carried by the **maximum** alone (#1129): a `null` max means
+ * the item does not use charges at all, `0` means it is counted but uncapped,
+ * and a positive number is a real cap. `value` is the current count, with
+ * `null` meaning "infinite remaining". Both persist as nullable NumberFields,
+ * so absent frontmatter must resolve to `null` — coercing it to `0` would ship
+ * every item as an uncapped charge-user.
+ *
+ * A legacy `usesCharges` flag in authored frontmatter is ignored: it was inert
+ * and has been dropped from the schema.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @returns {{value: number|null, max: number|null}} The persisted charges block.
+ */
+export function resolveCharges(fm: object): {
+    value: number | null;
+    max: number | null;
+};
+/**
+ * Resolve an item's `skillAptitudes` map — selector → mastery-level modifier,
+ * where a selector is a skill shortcode or `subType:<value>`.
+ *
+ * Authored values must be whole numbers: the persisted field is an integer
+ * `NumberField`, and a fractional or non-numeric entry would be silently
+ * coerced at load, shipping an aptitude nobody authored. A malformed entry is a
+ * build error rather than a rounded surprise. A `0` is legitimate and must be
+ * kept — an element a sign leaves untouched still beats one another sign
+ * hinders, so it carries real weight when maps merge.
+ *
+ * An absent property, an empty map, and the empty **list** Obsidian's property
+ * editor writes for a cleared map all mean the same thing — see
+ * {@link readMapEntries}.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @param {string} [ctx] - Label for the error (defaults to "item").
+ * @returns {Record<string, number>} The persisted aptitude map (empty when
+ *   the item authors none).
+ * @throws {Error} When the value is not a map, or a value is not an integer.
+ */
+export function resolveSkillAptitudes(fm: object, ctx?: string): Record<string, number>;
+/**
+ * Resolve an affiliation's `relation` map — the shortcode of another
+ * affiliation → this one's standing toward it (#1404).
+ *
+ * An unrecognized standing would fail the schema's `choices` validation at load
+ * and be dropped silently, shipping an affiliation whose authored hostility had
+ * quietly become neutrality — so it is a build error instead.
+ *
+ * An absent property, an empty map, and the empty **list** Obsidian's property
+ * editor writes for a cleared map all mean the same thing — neutral toward
+ * everyone. See {@link readMapEntries}.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @param {string} [ctx] - Label for the error (defaults to "item").
+ * @returns {Record<string, string>} The persisted relation map (empty when the
+ *   affiliation authors none — neutral toward everyone).
+ * @throws {Error} When the map is malformed or names an unknown standing.
+ */
+export function resolveRelation(fm: object, ctx?: string): Record<string, string>;
+/**
+ * Read the mandatory `subType` from an item's frontmatter, throwing when it is
+ * absent or blank.
+ *
+ * Every subType-bearing item type declares `subType` as `required` with **no**
+ * default in its DataModel — a subtype must always be specified, and it is an
+ * error to omit it. The builder therefore substitutes no fallback: a content
+ * file missing `subType` is a build error, surfaced here rather than shipped as
+ * an invalid (typeless-fallback) item.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @param {string} [ctx] - Optional label for the error (defaults to the item's
+ *   title/name, else "item").
+ * @returns {string} The declared subType.
+ * @throws {Error} When `subType` is missing or blank.
+ */
+export function requireSubType(fm: object, ctx?: string): string;
+/**
+ * Parses the valueDesc / threshold array format. Accepts either:
+ *   - Array of "Label:MaxValue" strings, e.g. ["Ugly:4", "Plain:12"]
+ *   - Array of objects, e.g. [{ label, maxValue }]
+ * Returns a normalized array of `{ label, maxValue: number }`.
+ */
+export function parseValueDesc(raw: any): {
+    label: string;
+    maxValue: number;
+}[];

package/types/engine/generate.d.mts

@@ -0,0 +1,56 @@
+/**
+ * The generated JSON of **every** configured Item pack — what the actors pass
+ * reads its predefined items from.
+ *
+ * All of them, not the first: a repository may ship several Item packs (#1566),
+ * and an actor's embedded items may be sourced from any of them. Finding one
+ * pack and stopping is how embedded-item resolution would silently miss every
+ * item that landed in another. Returned in configured order, which is also the
+ * order they compile in, so a pack later in the list cannot be read before it
+ * is written.
+ *
+ * @param {object} [config] - The resolved build configuration. Defaults to this
+ *   repository's.
+ * @returns {string[]} Each Item pack's JSON directory. Empty when the
+ *   repository ships no items at all — the actors pass, which is the only
+ *   caller that needs one, refuses that itself.
+ */
+export function itemPackJsonDirs(config?: object): string[];
+/**
+ * The passes that compiled nothing when they were expected to compile
+ * something — a build failure, not a quiet no-op.
+ *
+ * A pack compiler selects its entries by the configured content package, so a
+ * single wrong package id rejects every note in a perfectly good tree and every
+ * pack ships blank while the build exits 0 (#1502). The empty-tree guard in
+ * {@link generatePacksJson} cannot see that: the tree is full, it is the
+ * *output* that is empty.
+ *
+ * @param {Array<{name: string, compiled: number, mayBeEmpty?: boolean}>} passes -
+ *     One entry per generated pack.
+ * @returns {string[]} One message per pass that must not have been empty.
+ */
+export function emptyPassErrors(passes: Array<{
+    name: string;
+    compiled: number;
+    mayBeEmpty?: boolean;
+}>): string[];
+/**
+ * Generate the build-only JSON for every pack (or one, when `only` is given).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.only] - Restrict to a single pack name.
+ * @param {object} [opts.config] - The resolved build configuration. Defaults to
+ *   this repository's. Supplying one is how a caller compiles a *different*
+ *   package's tree — and how the guard-order test below induces id drift, now
+ *   that the manifest is located by configuration rather than by the working
+ *   directory.
+ * @returns {Promise<number>} Total error count across the generated packs.
+ * @throws {Error} If the configured Foundry package id has drifted from the
+ *   shipped manifest's `id` (see `package-manifest.mjs`).
+ */
+export function generatePacksJson({ only, config, }?: {
+    only?: string | undefined;
+    config?: object | undefined;
+}): Promise<number>;
+export function packJsonDir(name: string, config?: object): string;