@heroiclands/package-build 22.9.2 → 22.11.0

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

@@ -0,0 +1,95 @@
+/**
+ * An Address position, as a field declaration states it.
+ *
+ * @typedef {object} AddressPosition
+ * @property {string} type - The type an omitted `<type>` segment takes.
+ * @property {readonly string[]} accepts - Every type the position accepts.
+ * @property {"value"|"items"|"keys"} [holds] - Where the Addresses are.
+ *   Defaults to `value`.
+ * @property {"uuid"} [emit] - Resolve each exact target to its published Item UUID.
+ */
+/**
+ * What a reduction could not do, for a caller to report.
+ *
+ * @typedef {object} AddressFinding
+ * @property {string} key - The field, named as an author writes it.
+ * @property {string} written - The authored value, so the caller can locate the
+ *   finding at the line carrying it rather than at the key.
+ * @property {string} message - One sentence, naming the fix.
+ */
+/**
+ * The declarations that state an Address position.
+ *
+ * @param {readonly object[]} fields - A field declaration.
+ * @returns {object[]} Only the fields carrying an `address` statement.
+ */
+export function addressFields(fields: readonly object[]): object[];
+/**
+ * Reduce every Address a compiled block holds to the Shortcode it names.
+ *
+ * The block is edited in place, as {@link
+ * module:engine/system-block.mergeSystemData} edits it: what the caller holds is
+ * the document being assembled, and a field the reduction cannot read is left
+ * exactly as authored — the findings stop the build, so nothing ships either
+ * way, and an untouched value is what a reader of the failing note sees.
+ *
+ * @param {object} emitted - The `system` block, already built.
+ * @param {readonly object[]} fields - The type's field declaration.
+ * @param {import("./address.mjs").AddressVocabulary & {package?: string}}
+ *   vocabulary - The tree's vocabularies and the package the values are written
+ *   in.
+ * @returns {AddressFinding[]} Every value that could not be reduced.
+ */
+export function reduceAddressFields(emitted: object, fields: readonly object[], vocabulary?: import("./address.mjs").AddressVocabulary & {
+    package?: string;
+}): AddressFinding[];
+/**
+ * How many values a position holds.
+ *
+ * - `value` — the field's value is one Address.
+ * - `items` — every element of a list is one.
+ * - `keys` — every **key** of a map is one, and the values are untouched.
+ *
+ * @type {readonly string[]}
+ */
+export const ADDRESS_FIELD_SHAPES: readonly string[];
+/**
+ * An Address position, as a field declaration states it.
+ */
+export type AddressPosition = {
+    /**
+     * - The type an omitted `<type>` segment takes.
+     */
+    type: string;
+    /**
+     * - Every type the position accepts.
+     */
+    accepts: readonly string[];
+    /**
+     * - Where the Addresses are.
+     * Defaults to `value`.
+     */
+    holds?: "keys" | "value" | "items" | undefined;
+    /**
+     * - Resolve each exact target to its published Item UUID.
+     */
+    emit?: "uuid" | undefined;
+};
+/**
+ * What a reduction could not do, for a caller to report.
+ */
+export type AddressFinding = {
+    /**
+     * - The field, named as an author writes it.
+     */
+    key: string;
+    /**
+     * - The authored value, so the caller can locate the
+     * finding at the line carrying it rather than at the key.
+     */
+    written: string;
+    /**
+     * - One sentence, naming the fix.
+     */
+    message: string;
+};

package/types/engine/address-values.d.mts

@@ -0,0 +1,34 @@
+/**
+ * Render typed properties at a generated-output boundary.
+ * @param {any} value - A tuple-bearing tree.
+ * @param {WeakMap<object, object>} [seen] - Shared containers in this output.
+ * @returns {any} A serializable tree containing full Addresses.
+ */
+export function encodeAddresses(value: any, seen?: WeakMap<object, object>): any;
+/**
+ * Clone mutable note state while retaining immutable Address identities.
+ * @param {any} value - Typed note state.
+ * @returns {any} An independent mutable container tree.
+ */
+export function cloneAddressState(value: any): any;
+/** Address-keyed properties hold typed entries rather than string object keys. */
+export class AddressEntries {
+    /** @param {Array<{target: object, value: unknown, sourceKey: string}>} entries - Typed entries and diagnostic source keys. */
+    constructor(entries: Array<{
+        target: object;
+        value: unknown;
+        sourceKey: string;
+    }>);
+    entries: {
+        target: object;
+        value: unknown;
+        sourceKey: string;
+    }[];
+}
+/** An Address and the section within its document. */
+export class AddressLink {
+    /** @param {object} target - Complete tuple. @param {string} anchor - Section slug. */
+    constructor(target: object, anchor: string);
+    target: object;
+    anchor: string;
+}

package/types/engine/address.d.mts

@@ -0,0 +1,452 @@
+/**
+ * A complete Address: four segments, and nothing else.
+ *
+ * `type` is the segment the canonical string carries, after the `doc<type>`
+ * redirect. There is no fifth field recording the written form, because the
+ * written form is a rendering rather than part of the value.
+ *
+ * @typedef {object} AddressTuple
+ * @property {string} package - The owning **content** package.
+ * @property {string} system - The system whose document this addresses, or
+ *   `none`.
+ * @property {string} type - The type segment of the canonical Address.
+ * @property {string} shortcode - The note's `shortcode`.
+ */
+/**
+ * Why a written value is not an Address.
+ *
+ * The vocabulary is shared with the resolvers, so one authored mistake gets one
+ * verdict however many surfaces report it.
+ *
+ * - `not-an-address` — the value does not parse as one, which for body prose is
+ *   an ordinary note name rather than a mistake.
+ * - `no-type` — the `<type>` segment is omitted and the position declares no
+ *   default to fill it in, so nothing says what the value names.
+ * - `unknown-type` — the value is definitely qualified and names no known type.
+ * - `no-content-index` — the package named publishes no content index, so there
+ *   is nothing to resolve the rest of the target against.
+ * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `invalid-segment` — a declared Address contains a malformed segment.
+ * - `no-package` — a declared Address cannot supply its package.
+ * - `invalid-system` — a declared Address cannot supply a registered system.
+ *
+ * @typedef {{reason: string, package?: string}} AddressProblem
+ */
+/**
+ * Every content type whose **prose compiles into a JournalEntry of its own**,
+ * addressed by the virtual `doc<type>` qualifier.
+ *
+ * Every item type, every actor type, every map type, plus `macro` — a macro
+ * note's body documents the script the note also compiles into a Macro, which
+ * is the same shape as an item and its description: one note, two documents,
+ * the prose living in the journals pack.
+ *
+ * **One set, read by the compilers and by the grammar alike.** The journals
+ * pass decides what to compile from it, the link manifest decides what to
+ * publish a `doc<type>` entry for, and the parser decides whether `doc<type>`
+ * is a legal type segment. Held apart, the three drift into a manifest that
+ * asserts documentation nothing compiled, a compiled entry no consumer can
+ * address, or an authored `doc<type>` link that stops parsing. It is composed
+ * exactly once, in `defineConfig`, and read from there — never recomposed at a
+ * call site.
+ *
+ * `doc` notes are absent, for the reason that applies to them alone: a `doc`
+ * note's single document *is* its prose, so there is no second document for a
+ * `doc<type>` address to name.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration.
+ *
+ * @returns {ReadonlySet<string>} The configured doc-carrying types.
+ */
+export function docEntryTypes(): ReadonlySet<string>;
+/**
+ * Whether a content note's type is one whose prose becomes a JournalEntry of
+ * its own.
+ *
+ * @param {string} type - The note's `type` frontmatter.
+ * @returns {boolean} True for an item type, an actor type, a map type and
+ *   `macro`; false for `doc`.
+ */
+export function hasDocEntry(type: string): boolean;
+/**
+ * Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is
+ * not one.
+ *
+ * A document and its documentation are two documents in two packs, so they need
+ * two addresses. `skill-wpnc` is the item; `docskill-wpnc` is the JournalEntry
+ * its prose compiled into, and `docmacro-autoattack` is the same arrangement
+ * for a macro.
+ *
+ * The virtual form exists for a type that carries separate documentation
+ * ({@link docEntryTypes} — the set the journals compiler and the link manifest
+ * read too), **or** for one that routes to the items pack. The second clause
+ * covers the open, unenumerated set: types that compile into items are not
+ * enumerated anywhere, and a foreign package may publish an item type this
+ * build has never heard of. Dropping it would silently unlink every `doc<type>`
+ * address into such a package.
+ *
+ * A **real** type of the same name always wins: the virtual reading is only
+ * consulted for a qualifier no authored note claims.
+ *
+ * @param {string} qualifier - The already-normalised type segment.
+ * @param {Set<string>} types - Every type the content tree contains.
+ * @returns {string|null} The underlying document type, or `null` when the
+ *   qualifier is not a virtual one.
+ */
+export function resolveItemDocType(qualifier: string, types: Set<string>): string | null;
+/**
+ * The vocabularies a written Address is read against.
+ *
+ * These are the tree's, not the position's — every position reads against the
+ * same ones — and they travel beside the defaults so that reading an Address is
+ * one call.
+ *
+ * @typedef {object} AddressVocabulary
+ * @property {Set<string>} [types] - Every type the content tree contains.
+ * @property {Set<string>} [packages] - Every package an Address may name.
+ *   Omitted by callers that resolve within one package, where the fully
+ *   qualified form cannot occur.
+ * @property {Set<string>} [noIndexPackages] - Packages declared
+ *   `contentIndex: false` — a Foundry dependency only, with no fetched index. A
+ *   fully qualified target naming one is refused with `no-content-index` before
+ *   its type is even considered.
+ */
+/**
+ * What a position contributes: the defaults for the segments an author may omit.
+ *
+ * `package` and `system` are always supplied; `type` is supplied only by a
+ * position that accepts exactly one, and a position accepting several declares
+ * none, so a value omitting the `<type>` segment is refused rather than guessed
+ * at.
+ *
+ * @typedef {AddressVocabulary & {package?: string, system?: string,
+ *   type?: string}} AddressDefaults
+ */
+/**
+ * Parse a written Address into the one complete tuple it names.
+ *
+ * **An omitted segment defaults from where the value is written** — it is not a
+ * wildcard, and resolution is not a search. So every short form has exactly one
+ * expansion, computed before anything is looked up, and there is no candidate
+ * set to disambiguate.
+ *
+ * @param {unknown} written - The value as authored, with any Wikilink anchor and
+ *   label already removed.
+ * @param {AddressDefaults} [defaults] - The position's defaults and the tree's
+ *   vocabularies.
+ * @param {{declared?: boolean, legacyShortcodeCase?: boolean}} [options] - A declared Address validates every
+ *   segment and requires complete defaults. Package membership is a separate
+ *   resolution question in this mode; prose recognition keeps its vocabulary checks.
+ *   `legacyShortcodeCase` accepts case-insensitive model Shortcodes while the
+ *   completed tuple contains their canonical lowercase identity.
+ * @returns {AddressTuple|AddressProblem} The complete Address, or why there is
+ *   none.
+ */
+export function parseAddress(written: unknown, defaults?: AddressDefaults, { declared, legacyShortcodeCase }?: {
+    declared?: boolean;
+    legacyShortcodeCase?: boolean;
+}): AddressTuple | AddressProblem;
+/**
+ * Whether a value is an internally parsed Address.
+ * @param {unknown} value - A property value.
+ * @returns {boolean} Whether it is a typed tuple.
+ */
+export function isAddressTuple(value: unknown): boolean;
+/**
+ * Render a complete Address as its canonical string.
+ *
+ * Lowercased, because an Address has one spelling: two names differing only in
+ * case are two names nobody can tell apart.
+ *
+ * @param {AddressTuple} tuple - The complete Address.
+ * @returns {string} `package-system-type-shortcode`.
+ */
+export function renderAddress(tuple: AddressTuple): string;
+/**
+ * Whether the type an Address names is one this position accepts.
+ *
+ * The second of the two questions, and separate from the first because the
+ * accepted **set** is a property of the position while the grammar is not.
+ *
+ * **An accepted type carries its documentation form with it.** A position
+ * accepting `weapongear` accepts `docweapongear`, because the journal that
+ * documents a weapon is the same thing to a position that wanted a weapon — and
+ * a prose address of one *is* the journal, so refusing it would refuse the form
+ * an author most often writes. It is the widening `defineConfig` applies to the
+ * types a package may claim, applied here to the types a position may take.
+ *
+ * @param {AddressTuple} tuple - A parsed Address.
+ * @param {Iterable<string>} allowed - The types this position accepts.
+ * @returns {boolean} True when the Address names one of them.
+ */
+export function acceptsType(tuple: AddressTuple, allowed: Iterable<string>): boolean;
+/**
+ * Apply the defaults to a partial reading, giving a complete Address.
+ *
+ * The three rules of the module note, applied in the order they depend on each
+ * other: the package, then the system the type may fix, then the redirect the
+ * system may force.
+ *
+ * @param {{type: string, shortcode: string, package?: string, system?: string,
+ *   itemDoc?: boolean}} read - A partial reading, as {@link readQualifier}
+ *   returns one.
+ * @param {{package?: string, system?: string}} [where] - The citing context: the
+ *   tree's own content package, and the system of the block the value sits in.
+ * @returns {AddressTuple} The complete Address.
+ */
+export function completeAddress(read: {
+    type: string;
+    shortcode: string;
+    package?: string;
+    system?: string;
+    itemDoc?: boolean;
+}, where?: {
+    package?: string;
+    system?: string;
+}): AddressTuple;
+/**
+ * Expand a written Address to the one canonical Address it names.
+ *
+ * {@link completeAddress} and {@link renderAddress} under one name, for the
+ * index keys and cache keys that hold an Address as a string.
+ *
+ * @param {{type: string, shortcode: string, package?: string, system?: string,
+ *   itemDoc?: boolean}} read - A partial reading, as {@link readQualifier}
+ *   returns one.
+ * @param {{package: string, system?: string}} where - The citing context.
+ * @returns {string} The canonical `package-system-type-shortcode`.
+ */
+export function expandAddress(read: {
+    type: string;
+    shortcode: string;
+    package?: string;
+    system?: string;
+    itemDoc?: boolean;
+}, where: {
+    package: string;
+    system?: string;
+}): string;
+/**
+ * The canonical Address of a document, from its four segments.
+ *
+ * Global uniqueness is what lets a dependency's index merge straight into a
+ * local one: the keys cannot collide by accident, so a key already present on
+ * merge is a real conflict rather than an artefact of two packages sharing a
+ * namespace. `(type, shortcode)` alone is unique only *within* a package, and
+ * two independently authored packages reaching for the same short string is a
+ * matter of time.
+ *
+ * **The system segment.** A package may ship content for more than one system,
+ * and one note then compiles into a document per system — an actor in
+ * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
+ * land on one key, so the address cannot name either of them.
+ *
+ * The value is a system id, or the literal **`none`** for a document no game
+ * system defines: a journal, a macro, a scene, and an item's documentation
+ * journal — which is `none` however many systems the item itself declares,
+ * because it is one journal. `none` rather than `any`, because every segment of
+ * an address is an exact literal and `any` reads as a wildcard, which a
+ * resolver written to that misreading would act on silently; and not `null` or
+ * `~`, both of which are YAML nulls that parse to an absent value and drop the
+ * segment entirely.
+ *
+ * @param {string} pkg - The owning **content** package (`sohl`, `thalorna`) —
+ *   not the Foundry package, which varies per compilation target.
+ * @param {string} system - The system whose document this addresses, or `none`.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {string} `package-system-type-shortcode`, lowercased.
+ */
+export function canonicalKey(pkg: string, system: string, type: string, shortcode: string): string;
+/**
+ * Reads a canonical Address back into its segments.
+ *
+ * **Nothing to read and nothing readable are different answers.** An Address
+ * that cannot be canonical — `harn-adventures-sohl-skill-melee`, five segments,
+ * because the package name carries the separator — yields `null`, while an
+ * absent or blank input yields `undefined`. Both are falsy, so every call site
+ * is unaffected; the distinction is there so a caller reporting "this address is
+ * unreadable" can tell that it has one to report about.
+ *
+ * @param {unknown} key - A canonical Address, or nothing.
+ * @returns {{package: string, system: string, type: string, shortcode: string}
+ *   |null|undefined}
+ *   The segments; `null` when there is a string that is not in canonical form;
+ *   `undefined` when there is no Address at all.
+ */
+export function readCanonicalKey(key: unknown): {
+    package: string;
+    system: string;
+    type: string;
+    shortcode: string;
+} | null | undefined;
+/**
+ * Read a written Address as the **partial** reading, before any default applies.
+ *
+ * The first of the two questions, giving the segments the author supplied and
+ * nothing more. It exists for the callers that still hold a partial; the Address
+ * is completed by {@link completeAddress}, and **nothing an omitted segment does
+ * here is a wildcard.** Every omitted segment expands from the position's
+ * defaults, exactly as the specification's table states, so a short form names
+ * exactly one canonical Address and a lookup finds one entry or none. There is no
+ * candidate set and no ambiguity by construction.
+ *
+ * Two separators are accepted, and they are **not** interchangeable in how
+ * confidently they mark a value as qualified:
+ *
+ * - **`type-shortcode`** and its qualified forms — the canonical spelling.
+ *   Obsidian reads `/` inside a wikilink as a *path* and resolves it against the
+ *   vault's folders, so a slash-qualified link is a broken link in the editor
+ *   where the content is authored.
+ * - **`type/shortcode`** — resolved so that a link written before the vault
+ *   migrated does not silently die. A slash is *unconditionally* a qualifier:
+ *   nothing else uses one, so an unknown type before it is reported rather than
+ *   guessed at. The split is at the **last** slash.
+ *
+ * **Package, system and type are lowercase; the shortcode is not.** A shortcode
+ * is routinely mixed — `Clb`, `LtShoe`, `HsTunic` — and is folded rather than
+ * refused. The three segments in front of it are closed vocabularies with one
+ * spelling each, and accepting `Skill` beside `skill` would bless two ways of
+ * writing one address, so a capital there is reported. It is tested only once
+ * the value *parses*: a note name is full of capitals (`[[Shock State]]`), and
+ * calling that a badly-cased address rather than not an address would name the
+ * wrong mistake.
+ *
+ * @param {string} target - The value as authored, anchor already removed.
+ * @param {Set<string>} types - Every type the content tree contains.
+ * @param {Set<string>} [packages] - Every package an Address may name.
+ * @param {Set<string>} [noIndexPackages] - Packages declared
+ *   `contentIndex: false`.
+ * @returns {{type: string, shortcode: string, itemDoc: boolean,
+ *   package?: string, system?: string, reason?: undefined}
+ *   | AddressProblem | null}
+ *   The partial reading, carrying only the segments written; a `reason` when the
+ *   value is definitely qualified but names no known type, no fetched index or a
+ *   badly-cased segment; or `null` when it is not an Address at all.
+ */
+export function readQualifier(target: string, types: Set<string>, packages?: Set<string>, noIndexPackages?: Set<string>): {
+    type: string;
+    shortcode: string;
+    itemDoc: boolean;
+    package?: string;
+    system?: string;
+    reason?: undefined;
+} | AddressProblem | null;
+export { NO_SYSTEM };
+/**
+ * The one character that separates an Address's segments.
+ *
+ * Named because it is the *grammar*, not an implementation detail: it is what a
+ * change to the address form would move, and what a reader of that change has
+ * to find.
+ *
+ * @type {string}
+ */
+export const ADDRESS_SEPARATOR: string;
+/**
+ * How many segments a canonical Address has, and therefore how many
+ * {@link readCanonicalKey} counts.
+ *
+ * @type {number}
+ */
+export const CANONICAL_KEY_SEGMENTS: number;
+/**
+ * The qualifier prefix that addresses a note's **documentation** rather than
+ * the note's own document: `docskill-wpnc` is the JournalEntry that
+ * `skill-wpnc`'s prose compiled into.
+ *
+ * Every doc-carrying type has a `doc<type>` counterpart, formed by prefix and
+ * never enumerated, so the prefix itself is the whole of that vocabulary.
+ *
+ * @type {string}
+ */
+export const ITEM_DOC_PREFIX: string;
+/**
+ * A complete Address: four segments, and nothing else.
+ *
+ * `type` is the segment the canonical string carries, after the `doc<type>`
+ * redirect. There is no fifth field recording the written form, because the
+ * written form is a rendering rather than part of the value.
+ */
+export type AddressTuple = {
+    /**
+     * - The owning **content** package.
+     */
+    package: string;
+    /**
+     * - The system whose document this addresses, or
+     * `none`.
+     */
+    system: string;
+    /**
+     * - The type segment of the canonical Address.
+     */
+    type: string;
+    /**
+     * - The note's `shortcode`.
+     */
+    shortcode: string;
+};
+/**
+ * Why a written value is not an Address.
+ *
+ * The vocabulary is shared with the resolvers, so one authored mistake gets one
+ * verdict however many surfaces report it.
+ *
+ * - `not-an-address` — the value does not parse as one, which for body prose is
+ *   an ordinary note name rather than a mistake.
+ * - `no-type` — the `<type>` segment is omitted and the position declares no
+ *   default to fill it in, so nothing says what the value names.
+ * - `unknown-type` — the value is definitely qualified and names no known type.
+ * - `no-content-index` — the package named publishes no content index, so there
+ *   is nothing to resolve the rest of the target against.
+ * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `invalid-segment` — a declared Address contains a malformed segment.
+ * - `no-package` — a declared Address cannot supply its package.
+ * - `invalid-system` — a declared Address cannot supply a registered system.
+ */
+export type AddressProblem = {
+    reason: string;
+    package?: string;
+};
+/**
+ * The vocabularies a written Address is read against.
+ *
+ * These are the tree's, not the position's — every position reads against the
+ * same ones — and they travel beside the defaults so that reading an Address is
+ * one call.
+ */
+export type AddressVocabulary = {
+    /**
+     * - Every type the content tree contains.
+     */
+    types?: Set<string> | undefined;
+    /**
+     * - Every package an Address may name.
+     * Omitted by callers that resolve within one package, where the fully
+     * qualified form cannot occur.
+     */
+    packages?: Set<string> | undefined;
+    /**
+     * - Packages declared
+     * `contentIndex: false` — a Foundry dependency only, with no fetched index. A
+     * fully qualified target naming one is refused with `no-content-index` before
+     * its type is even considered.
+     */
+    noIndexPackages?: Set<string> | undefined;
+};
+/**
+ * What a position contributes: the defaults for the segments an author may omit.
+ *
+ * `package` and `system` are always supplied; `type` is supplied only by a
+ * position that accepts exactly one, and a position accepting several declares
+ * none, so a value omitting the `<type>` segment is refused rather than guessed
+ * at.
+ */
+export type AddressDefaults = AddressVocabulary & {
+    package?: string;
+    system?: string;
+    type?: string;
+};
+import { NO_SYSTEM } from "./systems.mjs";