@heroiclands/package-build 17.1.0 → 18.0.0

package/types/engine/kb-manifest.d.mts

@@ -1,241 +0,0 @@
-/**
- * The **canonical** address of a note: fully qualified, one spelling per
- * document, and globally unique.
- *
- * The written form of a link may omit the package (`[[skill-lang]]`), which
- * defaults it to the citing note's own. Everything internal — index keys,
- * manifest keys, every lookup — uses this instead, so no consumer has to know
- * what a short form defaulted to.
- *
- * Global uniqueness is what lets a foreign manifest merge straight into a local
- * index: 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 (#1499).
- *
- * @param {string} pkg - The owning **content** package (`sohl`, `thalorna`) —
- *   not the Foundry package, which varies per compilation target.
- * @param {string} type - The note's `type`.
- * @param {string} shortcode - The note's `shortcode`.
- * @returns {string} `package/type/shortcode`, lowercased.
- */
-export function canonicalKey(pkg: string, type: string, shortcode: string): string;
-/**
- * Reads a canonical key back into its parts.
- *
- * Parsing is plain positional counting: split on the separator, require
- * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
- * **The charset rule is what makes that sound** — every segment is
- * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
- * so the hyphen is purely a separator and the count alone determines every
- * field. That is enforced at each of the three sources rather than assumed of
- * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
- * `defineConfig` (#59), and types are bare words. Were any of them free to
- * carry a hyphen, no amount of counting would recover the fields and the reader
- * would need a vocabulary to match against instead.
- *
- * **Nothing to read and nothing readable are different answers.** A key that
- * cannot be canonical — `harn-adventures-skill-melee`, four segments — yields
- * `null`, while an absent or blank input yields `undefined`. Both are falsy, so
- * every call site (all of which test the result for truthiness) is unaffected;
- * the distinction is there so a caller reporting "this key is unreadable" can
- * tell that it has a key to report about.
- *
- * @param {unknown} key - A canonical key, or nothing.
- * @returns {{package: string, type: string, shortcode: string}|null|undefined}
- *   The parts; `null` when there is a string that is not in canonical form;
- *   `undefined` when there is no key at all.
- */
-export function readCanonicalKey(key: unknown): {
-    package: string;
-    type: string;
-    shortcode: string;
-} | null | undefined;
-/**
- * The package-relative address a site-absolute URL records as.
- *
- * Strips the emitting package's own base, so what lands in the manifest says
- * *where in the package* a page is and nothing about where the package itself
- * is mounted. A URL outside the base is an error rather than a best effort: it
- * would record an address that silently resolves to the wrong place once a
- * consumer prefixes its own base.
- *
- * @param {string} url - The site-absolute URL the emitting build publishes at.
- * @param {string} base - That build's base for the package, e.g. `"/thalorna/"`.
- * @returns {string} The address relative to `base`, with no leading slash.
- */
-export function packageRelative(url: string, base: string): string;
-/**
- * The URL a package-relative address resolves to in this build.
- *
- * Plain concatenation, which is what makes an absolute-origin base work: a base
- * of `"https://thalorna.example.org/"` yields an absolute link, and one of
- * `"/thalorna/"` a root-relative one, with no other rule to keep in step.
- *
- * @param {string} rel - The package-relative address from a manifest entry.
- * @param {string} base - This build's base for that package.
- * @returns {string} The resolved URL.
- */
-export function resolvePackageUrl(rel: string, base: string): string;
-/**
- * Builds one package's manifest from the KB build's own entries.
- *
- * Only notes carrying a `shortcode` appear: the shortcode is the stable
- * identity another package addresses them by, and a note without one cannot be
- * the target of a cross-package link at all.
- *
- * @param {string} pkg - The package name, e.g. `"sohl"`.
- * @param {Array<object>} entries - KB entries (`{ fm, name, url }`).
- * @param {string} [base] - Where *this* build serves `pkg`, stripped from each
- *   entry's URL so the recorded address is package-relative (#1465). Omitted,
- *   this build publishes no web surface for the package and no entry carries a
- *   `path` — see below.
- * @param {string} [foundryPackage] - The Foundry package this build ships the
- *   compiled documents in. Given, each entry also carries the `uuid` /
- *   `docUuid` a pack build resolves against; omitted, the manifest describes
- *   the web surface only.
- * @returns {object} The manifest document.
- */
-export function buildManifest(pkg: string, entries: Array<object>, base?: string, foundryPackage?: string): object;
-/**
- * Writes one manifest per package into `dir`.
- *
- * @param {Map<string, Array<object>>} entriesByPackage - Package → entries.
- * @param {string} dir - Output directory; created if absent.
- * @param {Record<string, string>} bases - Package → where *this* build serves
- *   it, which is what each entry's address is recorded relative to. This is the
- *   emitting build's own layout, not {@link PACKAGE_BASE}: a package's own site
- *   commonly serves it at `"/"` while a consumer mounts it under a prefix.
- * @param {Record<string, string>} [foundryPackages] - Package → the Foundry
- *   package shipping its documents. Only a package this build publishes can
- *   have one, since the UUID names where *this* repository ships them.
- * @returns {Array<{ package: string, file: string, count: number }>} What was written.
- */
-export function writeManifests(entriesByPackage: Map<string, Array<object>>, dir: string, bases: Record<string, string>, foundryPackages?: Record<string, string>): Array<{
-    package: string;
-    file: string;
-    count: number;
-}>;
-/**
- * Loads vendored manifests for packages this build does not itself publish.
- *
- * A package built locally is skipped even if a manifest for it is present: the
- * live build is authoritative and a vendored copy of it can only be stale.
- *
- * Each entry's package-relative address is resolved against this build's base
- * for that package (#1465), so what the index holds is a usable `url` and every
- * consumer downstream is unchanged by the format.
- *
- * @param {string} dir - Directory of vendored `<package>.json` manifests.
- * @param {Iterable<string>} localPackages - Packages this build publishes.
- * @param {Record<string, string>} [bases] - Package → base to resolve against;
- *   defaults to {@link PACKAGE_BASE}.
- * @returns {{ index: Map<string, object>, packages: Set<string>, stale: Array<object> }}
- *   `index` maps the canonical `package-type-shortcode` → `{ url, name, uuid,
- *   doc, anchors, type, package }`. Keys are globally unique, so this merges
- *   directly into a local index with no prefixing and no separate lookup path.
- *   `url` is `undefined` for an entry with no page (#1516) and `uuid` for one
- *   that compiles into no document, so a caller must check the address it
- *   intends to use rather than assume a hit carries it.
- */
-export function loadForeignManifests(dir: string, localPackages: Iterable<string>, bases?: Record<string, string>): {
-    index: Map<string, object>;
-    packages: Set<string>;
-    stale: Array<object>;
-};
-/**
- * Whether every linkable package is accounted for, locally or by manifest.
- *
- * This is what gates the dead-link guard. It is deliberately derived from data
- * rather than set by a flag: the guard turns itself on the moment the last
- * missing manifest appears, instead of waiting for someone to remember.
- *
- * @param {Iterable<string>} localPackages - Packages this build publishes.
- * @param {Iterable<string>} manifestPackages - Packages loaded from manifests.
- * @returns {{ complete: boolean, missing: Array<string> }}
- */
-export function manifestsComplete(localPackages: Iterable<string>, manifestPackages: Iterable<string>): {
-    complete: boolean;
-    missing: Array<string>;
-};
-/**
- * Packages that publish a manifest and therefore exchange addresses.
- *
- * The guard in {@link manifestsComplete} stays off until every one of these is
- * accounted for, so adding a package here without also publishing its manifest
- * relaxes the build rather than breaking it.
- */
-export const LINK_PACKAGES: readonly string[];
-/**
- * How many segments a canonical key has, and therefore how many the reader
- * below counts.
- *
- * Named rather than written as a literal because it is the *grammar*, not an
- * implementation detail of one function: it is the number a change to the
- * address form would move, and the thing a reader of that change has to find.
- *
- * @type {number}
- */
-export const CANONICAL_KEY_SEGMENTS: number;
-/**
- * Manifest format version.
- *
- * Bumped to 2 by #1465: entries changed from a site-absolute `url` to a
- * package-relative `path`. The two shapes are indistinguishable to a naive
- * reader — prefixing a v1 `url` yields `/thalorna/thalorna/…`, which resolves,
- * renders, and 404s — so the version is what makes a stale vendored file an
- * error rather than a wrong link.
- *
- * Bumped to 4 by #1499: keys use the authored hyphen separator
- * (`sohl-affliction-aconite`) so a key *is* the address an author writes; an
- * item's documentation became an entry in its own right
- * (`sohl-docaffliction-aconite`) rather than a second field; and entries gained
- * `anchors`, mapping a note's named sections to the full UUID each compiled to.
- *
- * Bumped to 3 by #1499: keys became **canonical** — fully qualified
- * `package/type/shortcode` rather than `type/shortcode` — and entries gained the
- * Foundry `uuid` / `docUuid` beside the web `path`. A v2 key read as a v3 one
- * addresses a package named after a type, so again the version is what turns a
- * stale vendored file into an error.
- *
- * Bumped to 5 by #1516: `path` became optional, so a package that ships
- * compendiums and publishes no site can still publish the Foundry addresses of
- * its documents — the mirror of an entry that has a `path` and no `uuid`.
- */
-export const MANIFEST_VERSION: 5;
-/**
- * Every version this build can read, newest last.
- *
- * A version exists to stop a file whose values *read differently* from being
- * resolved anyway, and that is the only thing it is allowed to gate. Every bump
- * so far did change a reading — a v2 key read as a v4 one addresses a package
- * named after a type — so each dropped its predecessors. **v5 did not**: it
- * only permits an absent `path`, so every v4 value still means exactly what it
- * meant, and refusing v4 would make a purely relaxing change a flag day in
- * which every package must re-emit on the same afternoon or every build breaks
- * (#1516).
- *
- * The unsafe direction is unchanged and still hard-fails: an older consumer
- * meeting a newer file rejects it, because it cannot know what the new shape
- * permits. Widening is therefore always safe to do here first and adopt
- * elsewhere later.
- */
-export const READABLE_VERSIONS: readonly number[];
-/**
- * Where this build serves each package, keyed by package name.
- *
- * One line per package, and the only edit a relocation requires: point a
- * package at another path (`"/setting/thalorna/"`) or another origin
- * (`"https://thalorna.example.org/"`) and every inbound link into it follows.
- * A base is a prefix, so it must end in `/`.
- *
- * Only *foreign* packages are consulted — a package this build publishes is
- * authoritative in its own entries and never resolves through a manifest — but
- * every linkable package is listed, because which are foreign depends on the
- * consuming repository and this file is vendored into each of them.
- */
-export const PACKAGE_BASE: Readonly<{
-    sohl: "/sohl/";
-    thalorna: "/thalorna/";
-}>;