@heroiclands/package-build 0.6.1 → 3.0.1

package/types/content-config.d.mts

@@ -0,0 +1,571 @@
+/**
+ * Validate and normalize a content configuration.
+ *
+ * Every configuration reaches this function — a YAML one through the loader in
+ * `engine/pack-config.mjs`, an `.mjs` one by calling it itself — so that a
+ * malformed configuration fails at load with a message naming the offending
+ * field, rather than surfacing much later as an empty pack or a missing asset.
+ * The returned object is a deeply frozen **copy**: mutating the input
+ * afterwards cannot reach the configuration the build reads.
+ *
+ * @param {ContentBuildConfigInput} config  The configuration to validate.
+ * @returns {ContentBuildConfig}            The frozen, defaulted configuration.
+ * @throws {TypeError} If any field is missing, mistyped, or unrecognized.
+ */
+export function defineConfig(config: ContentBuildConfigInput): ContentBuildConfig;
+/**
+ * The two kinds of Foundry package a content module can be built into. The
+ * value is also the directory Foundry installs the package under, which is why
+ * it is plural.
+ *
+ * @satisfies {readonly PackageKind[]}
+ */
+export const PACKAGE_KINDS: readonly ["systems", "modules"];
+export namespace DEFAULT_PATHS {
+    let content: "assets/content";
+    let manifests: "assets/manifests";
+    let manifestOut: "build/manifests";
+    let packJson: "build/packs-json";
+    let stage: "build/stage/packs";
+    let unpack: "build/tmp/packs";
+    let foreignCache: "build/cache/foreign";
+}
+/**
+ * The Foundry document types a compendium pack may hold. This is the set the
+ * toolchain is able to compile a pack of; a document type Foundry supports but
+ * this toolchain does not compile is deliberately absent (see #1501 — playlists
+ * and roll tables are out of scope).
+ *
+ * @satisfies {readonly PackDocumentType[]}
+ */
+export const PACK_DOCUMENT_TYPES: readonly ["Actor", "Adventure", "Item", "JournalEntry", "Macro", "Scene"];
+/**
+ * The landing-page rules a repository may route by.
+ *
+ * A *landing page* is a note that addresses a whole section rather than a page
+ * within one, so it has no slug of its own. Which note that is differs between
+ * repositories, and both live rules are represented here because switching
+ * either one on for the other repository moves addresses that are already
+ * published:
+ *
+ * - `readme` — a `README.md` **is** its section's landing page. This is `sohl`'s
+ *   rule, and a `doc` note routes by its `category` like any other, so `sohl`'s
+ *   eleven `category: collection` notes publish under a literal `collection/`
+ *   section (`kb/collection/skills/`).
+ * - `collection` — a `doc` note whose `category` is `collection` addresses the
+ *   section it introduces, named by its authored `section`. This is `thalorna`'s
+ *   rule, under which the same note publishes at `creature/`.
+ *
+ * The two are not disjoint and cannot simply both apply: each tree holds notes
+ * the other rule would move.
+ *
+ * @type {readonly string[]}
+ */
+export const LANDING_RULES: readonly string[];
+/**
+ * A repository's address scheme, with the defaults an unconfigured one gets.
+ *
+ * `prefix` is where the content tree mounts *inside the package* — `"kb/"` for
+ * `sohl`, whose knowledgebase is one surface among several, and empty for
+ * `thalorna`, whose site is nothing but its content. It is not the package's
+ * own mount point: where the package itself is served is the consuming build's
+ * knowledge, held in `PACKAGE_BASE` (`engine/kb-manifest.mjs`) and prefixed at
+ * resolve time, so it is never recorded here (#1465).
+ */
+export const DEFAULT_ADDRESS_SCHEME: Readonly<{
+    prefix: "";
+    landing: "readme";
+}>;
+export type PackageKind = "systems" | "modules";
+export type PackDocumentType = "Actor" | "Adventure" | "Item" | "JournalEntry" | "Macro" | "Scene";
+/**
+ * One compendium pack the build compiles, named exactly as it is declared in
+ * the package manifest's `packs` array.
+ *
+ * Several packs may share a `type`. The `type` selects the **compiler** that
+ * fills the pack; a note's `pack:` frontmatter selects **which pack of that
+ * type** receives its document. The two are orthogonal, and both are needed
+ * once a repository groups same-type documents editorially — which it may have
+ * to, since a compendium UUID carries its pack name and collapsing such a
+ * layout breaks every stored reference (#1566).
+ */
+export type PackSpec = {
+    /**
+     * Pack name — the manifest `name`, and the
+     * directory under `packs/`.
+     */
+    name: string;
+    /**
+     * Foundry document type the pack holds.
+     */
+    type: PackDocumentType;
+    /**
+     * Human-readable label. Defaults to `name`.
+     */
+    label?: string | undefined;
+    /**
+     * Whether the pack is GM-only. Default `false`.
+     */
+    private?: boolean | undefined;
+    /**
+     * The pack's folder-hierarchy file, relative
+     *     to `paths.content`. Default `null` — no
+     *     folder documents are emitted.
+     */
+    folders?: string | null | undefined;
+    /**
+     * Packs written by this pack's own compiler
+     *   pass rather than a pass of their own (the
+     *   scenes pass also emits the adventures
+     *   bundling them). Default `[]`.
+     */
+    companions?: PackSpec[] | undefined;
+    /**
+     * Whether a pass compiling zero entries is
+     *      legitimate rather than a build failure.
+     *      Default `false`.
+     */
+    mayBeEmpty?: boolean | undefined;
+    /**
+     * Whether this is the pack of its `type`
+     *         that receives notes declaring no `pack:`
+     *         of their own. Default `false`. A type
+     *         with exactly one pack is its default
+     *         implicitly; a type with several and no
+     *         `default: true` requires every note of
+     *         that type to declare one. Not permitted
+     *         on a companion — no note is routed into
+     *         one. See `engine/pack-router.mjs`.
+     */
+    default?: boolean | undefined;
+};
+/**
+ * The normalized form of a {@link PackSpec}: every optional half filled in.
+ */
+export type ResolvedPackSpec = {
+    name: string;
+    type: PackDocumentType;
+    label: string;
+    private: boolean;
+    folders: string | null;
+    companions: readonly Readonly<ResolvedPackSpec>[];
+    mayBeEmpty: boolean;
+    default: boolean;
+};
+/**
+ * The directories a consumer may relocate, each relative to `rootDir`.
+ */
+export type PathsInput = {
+    /**
+     * Content tree root.
+     */
+    content?: string | undefined;
+    /**
+     * Vendored cross-package link manifests,
+     *         read by `links`. Inbound.
+     */
+    manifests?: string | undefined;
+    /**
+     * Where `manifest` writes this package's
+     *       own link manifest. Outbound, and a
+     *       build artifact — the published copy is
+     *       the one a consumer vendors into its
+     *       `manifests` directory.
+     */
+    manifestOut?: string | undefined;
+    /**
+     * Build-only per-entry JSON intermediate.
+     */
+    packJson?: string | undefined;
+    /**
+     * Compiled LevelDB packs.
+     */
+    stage?: string | undefined;
+    /**
+     * Where `unpack` extracts JSON back to.
+     */
+    unpack?: string | undefined;
+};
+/**
+ * {@link PathsInput}, resolved to absolute paths against `rootDir`.
+ */
+export type ResolvedPaths = {
+    content: string;
+    manifests: string;
+    manifestOut: string;
+    packJson: string;
+    stage: string;
+    unpack: string;
+};
+/**
+ * The identity every compiled document's `_stats` block carries.
+ *
+ * `coreVersion` is **not** here: it is the top-level `compatibility.minimum`,
+ * so the floor is declared in one place and stamped from it.
+ */
+export type StatsSpec = {
+    /**
+     * The game system the documents are for —
+     * `"sohl"` even for a module, which ships
+     * content *for* the system rather than being it.
+     */
+    systemId: string;
+    /**
+     * The system version the packs were built against.
+     */
+    systemVersion: string;
+    /**
+     * The 16-character id stamped as the author.
+     */
+    lastModifiedBy: string;
+};
+/**
+ * The section of the configuration belonging to `@heroiclands/package-build`.
+ *
+ * **Opaque here, on purpose.** One repository describes itself in one file, so
+ * the two shared build packages share it — but they split by *input*, and
+ * neither should learn the other's schema. This validator checks only that the
+ * section is a mapping and hands it back frozen; package-build validates what
+ * is inside it, exactly as this module validates the keys around it.
+ *
+ * That is also why it is a section rather than a scatter of top-level keys: one
+ * reserved name keeps {@link ContentBuildConfig}'s unknown-key guard intact for
+ * everything else, which is the guard that catches a typo'd `packs` before it
+ * becomes an empty compendium.
+ *
+ * The values package-build needs that are *not* in here — `packageKind`,
+ * `foundryPackage` — it reads from the top level, where they already are. They
+ * were duplicated in each consumer's deploy script until this existed, which is
+ * two places for one fact.
+ */
+export type PackageBuildSection = Record<string, unknown>;
+/**
+ * The two manifest switches. A package may publish a link manifest, consume
+ * other packages' manifests, both, or neither — the four combinations are all
+ * real (see #1385/#1446: `kethira` consumes but never publishes).
+ */
+export type ManifestSwitches = {
+    /**
+     * Emit this package's link manifest.
+     */
+    publish: boolean;
+    /**
+     * Resolve cross-package links through vendored manifests.
+     */
+    consume: boolean;
+};
+export type PublishSwitches = {
+    /**
+     * Render this package's knowledgebase/site pages.
+     */
+    site: boolean;
+    manifests: ManifestSwitches;
+};
+export type ManifestSwitchesInput = {
+    publish?: boolean | undefined;
+    consume?: boolean | undefined;
+};
+/**
+ * The **Foundry core** version range this package supports.
+ *
+ * `minimum` is stamped into every compiled document as `_stats.coreVersion`, so
+ * a document never claims to predate the migrations that would rewrite it.
+ *
+ * `verified` names the newest build the full suite has **actually passed** —
+ * never an aspiration. Moving this out of the hand-authored manifest and into a
+ * configuration file does not soften that; if anything it makes the claim
+ * easier to edit casually, so it is written down here beside the key rather
+ * than left behind in the template.
+ *
+ * Not to be confused with `relationships.systems[].compatibility`, which is the
+ * **game system's** version range. Same key, different subject.
+ */
+export type CompatibilitySpec = {
+    /**
+     * Oldest Foundry core this package supports.
+     */
+    minimum: string;
+    /**
+     * Newest Foundry core the suite has passed on.
+     */
+    verified?: string | undefined;
+};
+/**
+ * What this package declares about other packages, in Foundry's own shape.
+ *
+ * Passed through to the shipped manifest, and read here for one derivation: a
+ * module's `_stats.systemVersion` comes from the `verified` field of the system
+ * it declares a relationship with, because a module's own `package.json`
+ * version is the *module's* and stamping it would claim a system version that
+ * never existed.
+ */
+export type Relationships = {
+    /**
+     * Game systems this package targets.
+     */
+    systems?: RelationshipSpec[] | undefined;
+    /**
+     * Packages this one needs.
+     */
+    requires?: RelationshipSpec[] | undefined;
+    /**
+     * Packages it works well with.
+     */
+    recommends?: RelationshipSpec[] | undefined;
+    /**
+     * Packages it cannot run beside.
+     */
+    conflicts?: RelationshipSpec[] | undefined;
+};
+/**
+ * One declared relationship.
+ */
+export type RelationshipSpec = {
+    /**
+     * The other package's id.
+     */
+    id: string;
+    /**
+     * `system`, `module`, or `world`.
+     */
+    type?: string | undefined;
+    /**
+     * Where its manifest is published.
+     */
+    manifest?: string | undefined;
+    /**
+     * The version range of *that*
+     * package this one targets — for a system
+     * relationship, `verified` is what
+     * `_stats.systemVersion` is stamped from.
+     */
+    compatibility?: CompatibilitySpec | undefined;
+};
+/**
+ * How a generated documentation page is framed in the repository publishing it.
+ *
+ * The tables come from the `itemBuilders` registry and are the same wherever
+ * they are rendered. Everything around them is the consumer's: the heading, the
+ * "See also" line its section's pages carry, the orientation a reader needs
+ * before the tables start, and where the page is filed. Those were the reason
+ * every consumer wrapped the renderer in a script of its own.
+ */
+export type DocPageSpec = {
+    /**
+     * The page's H1.
+     */
+    title?: string | undefined;
+    /**
+     * Where to write it, relative to `rootDir`.
+     *         Without it the page goes to stdout.
+     */
+    out?: string | undefined;
+    /**
+     * Lines between the generated banner and the
+     *  first table. Markdown, emitted verbatim.
+     */
+    preamble?: string[] | undefined;
+};
+/**
+ * The documentation pages this repository generates.
+ */
+export type DocsSpec = {
+    /**
+     * The item-frontmatter reference,
+     *   rendered by `content-build docs
+     *   item-fields`.
+     */
+    itemFields?: DocPageSpec | undefined;
+};
+export type PublishSwitchesInput = {
+    site?: boolean | undefined;
+    manifests?: ManifestSwitchesInput | undefined;
+};
+/**
+ * One entry of a consumer's `itemBuilders` registry.
+ *
+ * Either a bare builder function, or that builder paired with the type's
+ * default art and the frontmatter fields it declares. See
+ * {@link normalizeItemBuilders} for why the paired form exists.
+ *
+ * `fields` is what makes the type documentable: a builder function says
+ * nothing about the vocabulary it consumes, so a consumer that declares its
+ * fields can generate its own authoring reference and check its own notes,
+ * while one that does not is simply undocumented rather than broken (#22).
+ */
+export type ItemBuilderEntry = ((fm: object) => object) | {
+    system: (fm: object) => object;
+    img?: string;
+    fields?: readonly object[];
+};
+/**
+ * The configuration a consumer writes.
+ */
+export type ContentBuildConfigInput = {
+    /**
+     * Absolute path of the consuming
+     * repository — every configured path is
+     * resolved against it, so the build never
+     * depends on the working directory.
+     */
+    rootDir: string;
+    /**
+     * Content package name — the value each
+     * content note carries in its `package:`
+     * frontmatter.
+     */
+    contentPackage: string;
+    /**
+     * Foundry package id, as it appears in
+     * `system.json` / `module.json`.
+     */
+    foundryPackage: string;
+    /**
+     * Whether the package is a system or a module.
+     */
+    packageKind: PackageKind;
+    /**
+     * Identity stamped into every document's `_stats`.
+     */
+    stats: StatsSpec;
+    /**
+     * The consumer's
+     * item-type registry: each content `type`
+     * that compiles into an Item, paired with
+     * the builder producing its `system` block
+     * — and, optionally, the default art a
+     * note of that type gets when it sets no
+     * `img:` of its own. Default `{}` — a
+     * content module that ships no items
+     * declares none.
+     */
+    itemBuilders?: Record<string, ItemBuilderEntry> | undefined;
+    /**
+     * Packs to compile. More than one entry
+     * may share a `type`: a note then names
+     * the pack it belongs in with its
+     * `pack:` frontmatter, and one pack of
+     * the type is marked `default: true` to
+     * receive the notes that name none
+     * (#1566).
+     */
+    packs: PackSpec[];
+    /**
+     * Layout overrides. See {@link DEFAULT_PATHS}.
+     */
+    paths?: PathsInput | undefined;
+    /**
+     * Directory names the content walk ignores
+     *    wherever they appear (e.g. Obsidian's
+     *    `Templates`). Default `[]`.
+     */
+    skipDirectories?: string[] | undefined;
+    /**
+     * Reserved for
+     * `@heroiclands/package-build`, which
+     * validates it. Not read here.
+     */
+    packageBuild?: PackageBuildSection | undefined;
+    /**
+     * How this repository frames the
+     *               documentation pages it generates.
+     */
+    docs?: DocsSpec | undefined;
+    /**
+     * The Foundry core range this
+     * package supports. Required for any
+     * repository that ships one — reading
+     * the floor throws without it — and
+     * absent for a content-only consumer,
+     * which has none to invent.
+     */
+    compatibility?: CompatibilitySpec | undefined;
+    /**
+     * What this package declares about
+     * others, in Foundry's own shape.
+     */
+    relationships?: Relationships | undefined;
+    /**
+     * Publishing switches. Each defaults to off.
+     */
+    publish?: PublishSwitchesInput | undefined;
+};
+/**
+ * The normalized, frozen configuration the toolchain reads.
+ */
+export type ContentBuildConfig = {
+    rootDir: string;
+    contentPackage: string;
+    foundryPackage: string;
+    packageKind: PackageKind;
+    /**
+     * Derived: the served Foundry asset root,
+     * `<packageKind>/<foundryPackage>/assets`.
+     */
+    assetRoot: string;
+    paths: Readonly<ResolvedPaths>;
+    stats: Readonly<StatsSpec>;
+    /**
+     * Derived: the
+     * `system` builder of each entry, whichever
+     * of the two spellings declared it.
+     */
+    itemBuilders: Readonly<Record<string, Function>>;
+    /**
+     * Derived: the default art
+     * of each entry that paired one. Sparse — a
+     * type absent here has no default, and a note
+     * of it must carry `img:` (#7).
+     */
+    itemArt: Readonly<Record<string, string>>;
+    /**
+     * Derived:
+     * the frontmatter fields each entry
+     * declared. Sparse, like `itemArt` — a type
+     * absent here compiles normally and is
+     * simply undocumented (#22).
+     */
+    itemFields: Readonly<Record<string, readonly object[]>>;
+    /**
+     * Derived: the keys of
+     * {@link ContentBuildConfigInput.itemBuilders},
+     * so the accepted item types and the builder
+     * table are one list (#1504).
+     */
+    itemTypes: ReadonlySet<string>;
+    /**
+     * Derived: every type whose prose
+     * compiles into a JournalEntry of its own —
+     * the item types, plus `macro`, plus the map
+     * types. The one set the compilers and the
+     * link-manifest emitter both read.
+     */
+    docEntryTypes: ReadonlySet<string>;
+    skipDirectories: readonly string[];
+    packs: readonly Readonly<ResolvedPackSpec>[];
+    /**
+     * Derived: every pack directory
+     * the build produces, in compile order —
+     * each pack followed by its companions.
+     */
+    packDirectories: readonly string[];
+    /**
+     * Passed through
+     * frozen, uninterpreted. `{}` when absent.
+     */
+    packageBuild: Readonly<PackageBuildSection>;
+    /**
+     * Frozen; `{}` when absent.
+     */
+    docs: Readonly<DocsSpec>;
+    /**
+     * The Foundry core
+     * range, or `null` when none is declared.
+     */
+    compatibility: Readonly<CompatibilitySpec> | null;
+    /**
+     * Frozen; `{}` when absent.
+     */
+    relationships: Readonly<Relationships>;
+    publish: Readonly<PublishSwitches>;
+};

package/types/engine/abbreviations.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Replace whole words with their abbreviations.
+ *
+ * Greedy and longest-first: at each position the longest run of tokens that
+ * names an entry wins, so `tribunus militum` never abbreviates as
+ * `trib militum`, and `countess` is never reached by `count`'s rule.
+ *
+ * @param {readonly string[]} tokens - Lowercased, alphanumeric-only tokens.
+ * @returns {string[]} The tokens, with each matched run replaced by one token.
+ */
+export function abbreviateTokens(tokens: readonly string[]): string[];
+/**
+ * The abbreviations a slug may use to stay short.
+ *
+ * Names in this setting are long and formulaic — a rank, an office, a material,
+ * a unit — so a slug built from one runs to a mouthful that says little more
+ * than a short one would. These are the conventional shortenings for that
+ * vocabulary.
+ *
+ * **Whole words only.** `count` abbreviates, `countess` does not become
+ * `ctess`: it has its own entry. Matching is greedy and longest-first, so a
+ * multi-word phrase wins over its own first word — `tribunus militum` is
+ * `tribmil`, a bare `tribunus` is `trib` — and a longer word wins over a
+ * shorter one that prefixes it.
+ *
+ * **Abbreviations are not unique, and that is the caller's problem.** Several
+ * words share one: `abbess` and `abbot` are both `abb`, `monk` and `brother`
+ * both `br`, `emperor` and `empress` both `emp`. Two names that differ only in
+ * such a word therefore slug alike, which for a URL is a collision — the
+ * build's existing slug-collision guard is what catches it, and the fix is a
+ * more specific name.
+ *
+ * @module
+ */
+/**
+ * Word (or phrase) → abbreviation.
+ *
+ * Keys are lowercase and space-separated as they read; a hyphenated key like
+ * `shire-reeve` is stored with its hyphen because that is how the word is
+ * written, and the matcher tokenises the same way it tokenises a name.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const ABBREVIATIONS: Readonly<Record<string, string>>;