@heroiclands/package-build 0.6.0 → 3.0.0

package/types/engine/scenes.d.mts

@@ -0,0 +1,48 @@
+/**
+ * Every SoHL action name this build knows about, for the `action:` warning on a
+ * region trigger.
+ *
+ * Deliberately a **superset**, gathered from the localization keys every
+ * intrinsic action's `title:` points at and from the `shortcode:` / `executor:`
+ * string literals the action definitions carry. A warning that fires on a real
+ * action would be worse than one that misses a typo, so the wider net is the
+ * right one: this only has to recognise the names that exist, not enumerate
+ * them exactly.
+ *
+ * @param {string} repoRoot - The repository root.
+ * @returns {Set<string>} The known action names.
+ */
+export function collectKnownActionNames(repoRoot: string): Set<string>;
+export class Scenes extends BasePackCompiler {
+    constructor({ contentBase, dest, companionDests, folderResolver, repoRoot, }: {
+        contentBase: any;
+        dest: any;
+        companionDests?: {} | undefined;
+        folderResolver?: (() => null) | undefined;
+        repoRoot?: string | undefined;
+    });
+    /** @type {string} */
+    adventureDir: string;
+    /**
+     * Adventures this pass bundled, for the summary.
+     *
+     * @type {number}
+     */
+    adventureCount: number;
+    index: Map<string, object> | undefined;
+    effectsByAddress: Map<string, object> | undefined;
+    knownActions: Set<string> | undefined;
+    /** place key → `{name, img, scenes: [], journal: []}` */
+    places: Map<any, any> | undefined;
+    /**
+     * Bundle each pinned place into an Adventure, once every map of it has
+     * compiled.
+     *
+     * @returns {Promise<void>}
+     */
+    finish(): Promise<void>;
+    /** @inheritdoc */
+    reportCompiled(stats: any): void;
+    #private;
+}
+import { BasePackCompiler } from "./base-compiler.mjs";

package/types/engine/site-build.d.mts

@@ -0,0 +1,214 @@
+/**
+ * Every `.md` file under `dir`, depth-first in directory order.
+ *
+ * Deliberately *not* {@link walkMarkdownTree}, whose stack-based walk yields a
+ * tree in reverse. Order is load-bearing here and nowhere else: the address
+ * index resolves a bare `[[Name]]` on a first-writer-wins basis, so reversing
+ * the walk silently changes which page an ambiguous name resolves to. A pack
+ * compile has no such dependency, which is why the two walks can differ.
+ *
+ * @param {string} dir - Directory to walk.
+ * @param {readonly string[]} skip - Directory names to ignore at any depth.
+ * @returns {string[]} Absolute paths.
+ */
+export function walkSiteTree(dir: string, skip?: readonly string[]): string[];
+/**
+ * The content tree's pages, and what could not be addressed.
+ *
+ * @param {string} contentBase - Absolute path to the content tree.
+ * @param {object} ctx - `{ packages, skipDirectories, mount, scheme }`.
+ * @returns {{pages: object[], slugFindings: object[], fmLinkFindings: object[]}}
+ */
+export function collectContentPages(contentBase: string, ctx: object): {
+    pages: object[];
+    slugFindings: object[];
+    fmLinkFindings: object[];
+};
+/**
+ * An extra tree's pages — a documentation tree published alongside the content.
+ *
+ * These preserve their **source layout** below the section rather than being
+ * addressed by type and slug: they are a book with chapters, and a reader
+ * follows their paths. A `README` is its directory's landing.
+ *
+ * @param {object} tree - `{ from, rel, section, route }`.
+ * @param {object} ctx - `{ mount }`.
+ * @returns {{pages: object[], fmLinkFindings: object[]}}
+ */
+export function collectTreePages(tree: object, ctx: object): {
+    pages: object[];
+    fmLinkFindings: object[];
+};
+/**
+ * The integrity gates a site build runs before it writes anything.
+ *
+ * Every one of these was an inline `process.exit` in both consumer scripts, so
+ * none of them had a test. They are grouped here, reporting rather than exiting,
+ * because the order matters and the reasons are worth stating once:
+ *
+ * - **Frontmatter wikilinks** first, because frontmatter is copied to the page
+ *   verbatim and a link written in one reaches the reader as literal `[[…]]`.
+ * - **Slugs and collisions** next: a note that derives no URL, or two that
+ *   derive the same one, would silently drop or overwrite a page.
+ * - **Foreign manifests** last, in two steps. *Unusable* is a file this build
+ *   cannot read; *unaddressable* is one it can read but cannot look anything up
+ *   in — a distinction worth keeping, because the second surfaces as a pile of
+ *   dead links blaming the notes that cite them rather than the file at fault.
+ *
+ * @param {object[]} pages - Every page, from both walks.
+ * @param {object} findings - `{ slugFindings, fmLinkFindings }` from collection.
+ * @param {object} options - `{ manifestDir }`.
+ * @returns {object} The gate results and, when they pass, the built index.
+ */
+export function siteGates(pages: object[], findings: object, { manifestDir }: object): object;
+/** Whether any gate produced a finding. */
+export function gatesFailed(gates: any): boolean;
+/**
+ * The universe a generated table searches, grouped by package.
+ *
+ * Reference pages only, and grouped so a page never tabulates another package's
+ * content: a table is a claim about what this package ships.
+ *
+ * @param {object[]} pages - Every page.
+ * @returns {Map<string, object[]>} Package → the notes it may tabulate.
+ */
+export function tableUniverse(pages: object[]): Map<string, object[]>;
+/**
+ * The frontmatter a page publishes with.
+ *
+ * An authored `aliases` is Obsidian's — a list of *names* a reader might call
+ * the note, which is vault addressing and stays in the vault. Hugo reads
+ * `aliases` as **URL redirects**, so passing them through would publish a
+ * redirect stub at each name. They are dropped, and this build emits no
+ * redirects of its own.
+ *
+ * @param {object} page - The page.
+ * @param {object} options - `{ sections, readmeSections, decorate }`.
+ * @returns {object} The frontmatter to write.
+ */
+export function pageFrontmatter(page: object, { readmeSections, decorate }: object): object;
+/** Where a page is written, relative to the output root. */
+export function pageDestination(page: any): string;
+/**
+ * Renders and writes every page.
+ *
+ * The order inside a page is load-bearing and is the same order the pack
+ * compilers use:
+ *
+ * 1. **Tables expand first**, and outside code-fence protection. A table is
+ *    authored as a fenced `dataview` block, which `protectCode` would otherwise
+ *    stash away before the expander saw it. Expanding first leaves an ordinary
+ *    markdown table to walk, with every other fence still protected.
+ * 2. **Then, inside protection**: the consumer's `beforeLinks` pass, wikilink
+ *    resolution, and the consumer's `afterLinks` pass. A `{@link}` tag may sit
+ *    in prose a wikilink also touches, so the repository's own rewrites bracket
+ *    the shared one rather than replacing it.
+ *
+ * @param {object[]} pages - Every page.
+ * @param {object} options - Everything the render needs.
+ * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}
+ */
+export function renderPages(pages: object[], options: object): {
+    written: number;
+    byKind: Record<string, number>;
+    tableErrors: object[];
+    wikiErrors: object[];
+};
+/**
+ * Writes the section landings a published tree needs but no note supplies.
+ *
+ * Two separate jobs, and both exist because of how Hugo decides what a section
+ * is:
+ *
+ * - **Declared sections** get a titled `_index.md` with their hero, so a landing
+ *   matches the card that links to it instead of showing Hugo's auto-humanised
+ *   directory name. The body is empty, which lets the theme list the section's
+ *   children — or say it is empty, for a section whose content has not shipped.
+ * - **Every other section directly under the mount** gets a bare `_index.md`,
+ *   or its own address publishes nothing. Hugo generates a section page
+ *   automatically only for a *top-level* content directory; below that, a
+ *   directory without an `_index.md` is not a section, so its URL 404s while
+ *   its children publish normally. Mounting a tree one level down demotes every
+ *   section it holds, and the ones with no landing of their own quietly stop
+ *   existing while every page inside them keeps working.
+ *
+ * Scoped to one level on purpose. A directory further down was not a section
+ * before the move either, and giving it one here would silently re-scope the
+ * prev/next navigation of every page inside it.
+ *
+ * @param {string} outRoot - The mount directory.
+ * @param {object} options - `{ sections, landing, sectionTitle }`.
+ * @returns {number} How many landings were written.
+ */
+export function writeSectionLandings(outRoot: string, { sections, landing, sectionTitle }: object): number;
+/**
+ * A section landing's title, from its directory name — `macro` → `Macros`.
+ *
+ * Hugo derives exactly this for a section page it generates itself, but not for
+ * one backed by an `_index.md`: an explicit file with no `title` renders a blank
+ * heading. So a backfilled landing states its own, in plain English
+ * pluralisation rather than Hugo's inflector, which spells that section
+ * "Macroes".
+ *
+ * @param {string} name - The directory name.
+ * @returns {string} The display title.
+ */
+export function pluralTitle(name: string): string;
+/**
+ * Resolves `site.pass` to its bundle.
+ *
+ * @param {string|undefined} name - The configured name.
+ * @param {object} options - The configured options, plus `repoRoot`.
+ * @returns {{beforeLinks?: Function, afterLinks?: Function}} The bundle.
+ */
+export function resolveSitePass(name: string | undefined, options: object): {
+    beforeLinks?: Function;
+    afterLinks?: Function;
+};
+/**
+ * The output root, having established that it is safe to delete.
+ *
+ * The whole tree is a build artifact and is wiped on every run, so this
+ * resolution is the difference between clearing a build directory and clearing
+ * the repository. An unset `site.out` resolves to `rootDir` itself, and the
+ * wipe then deletes the working tree — which is not a hypothetical: it happened
+ * while this module was being written, on a configuration that simply had no
+ * `site` section yet.
+ *
+ * So the path is refused unless it is **strictly inside** the repository root.
+ * Both failing shapes are ordinary rather than exotic — an absent setting, and a
+ * `..` that climbs out — and neither should be recoverable by being careful.
+ *
+ * @param {string} rootDir - The repository root.
+ * @param {string} out - The configured `site.out`.
+ * @returns {string} The absolute output root.
+ * @throws {Error} When it is unset, or is not below `rootDir`.
+ */
+export function resolveOutputRoot(rootDir: string, out: string): string;
+/**
+ * Builds a Hugo content tree from a content tree, and reports what it found.
+ *
+ * Returns rather than exits, in every case. A caller — the command, or a test —
+ * decides what a finding means; the gates below are grouped so it can report
+ * the first that fired and stop, which is what keeps a wall of dead links from
+ * burying the one manifest that caused them.
+ *
+ * @param {object} [options] - Options.
+ * @param {object} [options.config] - A resolved configuration; loaded when
+ *   omitted.
+ * @param {string} [options.outRoot] - Override the configured output mount.
+ * @returns {{gates: object, stats: object|null, tableErrors: object[],
+ *   wikiErrors: object[], manifests: object|null}}
+ */
+export function buildSite({ config, outRoot }?: {
+    config?: object | undefined;
+    outRoot?: string | undefined;
+}): {
+    gates: object;
+    stats: object | null;
+    tableErrors: object[];
+    wikiErrors: object[];
+    manifests: object | null;
+};
+export { formatUnaddressableFinding };
+import { formatUnaddressableFinding } from "./foreign-manifests.mjs";

package/types/engine/site-index.d.mts

@@ -0,0 +1,141 @@
+/**
+ * Build the address index a site's wikilink resolver reads.
+ *
+ * @param {readonly SiteEntry[]} entries - Every page the site will publish,
+ *   each already knowing its own `url`.
+ * @param {object} [options] - Cross-package inputs.
+ * @param {Map<string, {package: string, type?: string}>} [options.foreignIndex]
+ *   The merged index from `loadForeignManifests`. Omit when the build publishes
+ *   no cross-package links.
+ * @returns {SiteIndex} The index, and what could not be addressed unambiguously.
+ */
+export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex }?: {
+    foreignIndex?: Map<string, {
+        package: string;
+        type?: string;
+    }> | undefined;
+}): SiteIndex;
+/**
+ * The per-page context a wikilink resolver takes.
+ *
+ * Assembled here so a consumer spells out only what is genuinely its own — the
+ * source path, the citing note's type, and where errors collect — instead of
+ * restating the whole index every call. Both site builds wrote this object by
+ * hand, identically.
+ *
+ * @param {SiteIndex} built - The result of {@link buildSiteIndex}.
+ * @param {object} options - Per-page inputs.
+ * @param {string} options.src - Source path of the page being resolved, for
+ *   diagnostics.
+ * @param {string|null} [options.type] - The citing note's type, which scopes a
+ *   bare alias lookup.
+ * @param {object[]} options.errors - Collector the resolver appends to.
+ * @param {Map<string, object>} [options.foreignIndex] - The foreign index, for
+ *   resolvers that distinguish a foreign hit from a local one.
+ * @param {boolean} [options.manifestsComplete] - Whether every package this
+ *   build links into supplied a manifest. When false, a resolver may soften an
+ *   unresolved cross-package link rather than fail.
+ * @returns {object} The resolver context.
+ */
+export function wikiContext(built: SiteIndex, { src, type, errors, foreignIndex, manifestsComplete, }: {
+    src: string;
+    type?: string | null | undefined;
+    errors: object[];
+    foreignIndex?: Map<string, object> | undefined;
+    manifestsComplete?: boolean | undefined;
+}): object;
+/**
+ * One page the site will publish, as the index needs to see it.
+ */
+export type SiteEntry = {
+    /**
+     * `"content"` for a note compiled from the content
+     * tree, anything else for a page that carries no
+     * `type`/`shortcode` (a developer doc, say). Only
+     * content entries take part in type-scoped indexing.
+     */
+    kind: string;
+    /**
+     * The note's frontmatter.
+     */
+    fm: object;
+    /**
+     * Display name.
+     */
+    name: string;
+    /**
+     * URL segment.
+     */
+    slug: string;
+    /**
+     * Section the page is filed under.
+     */
+    sec: string;
+    /**
+     * Source file's basename, e.g. `Climbing.md`.
+     */
+    base: string;
+    /**
+     * The page's published address.
+     */
+    url: string;
+    /**
+     * Whether the page is its section's landing.
+     */
+    isReadme: boolean;
+};
+/**
+ * The resolved index and everything a wikilink resolver reads beside it.
+ */
+export type SiteIndex = {
+    /**
+     * Address → page.
+     */
+    index: Map<string, {
+        url: string;
+        name?: string;
+    }>;
+    /**
+     * Keys claimed by two pages, and so
+     * deliberately absent from `index`.
+     */
+    ambiguous: Set<string>;
+    /**
+     * `type|alias`.
+     */
+    typeAlias: Map<string, {
+        url: string;
+        name?: string;
+    }>;
+    /**
+     * Type-scoped aliases claimed twice.
+     */
+    typeCollide: Set<string>;
+    /**
+     * Every type the resolver should read as
+     * an address qualifier, local and foreign.
+     */
+    contentTypes: Set<string>;
+    /**
+     * Section names, lowercased.
+     */
+    sections: Set<string>;
+    /**
+     * `type:shortcode`
+     * → page, for callers resolving embedded
+     * references (a being's items, say).
+     */
+    refIndex: Map<string, {
+        name: string;
+        url: string;
+    }>;
+    /**
+     * Addresses claimed by
+     * more than one package. Non-empty is a
+     * build failure; the caller reports it.
+     */
+    conflicts: {
+        key: string;
+        package: string;
+    }[];
+};

package/types/engine/web-wikilinks.d.mts

@@ -0,0 +1,67 @@
+/**
+ * Every wikilink authored inside a frontmatter value (#1428).
+ *
+ * Wikilinks are resolved in a note's **body** — by {@link resolveWebWikilinks}
+ * here, and by the pack compilers' `convertWikilinks` for Foundry. Frontmatter
+ * is not markdown and is never walked by either, so a link written in one is
+ * copied through verbatim and reaches the reader as literal `[[…]]` text, in
+ * whatever the theme renders that field as (an infobox row, a description, a
+ * card subtitle). Nothing downstream notices: the value is a valid string, the
+ * page builds, and the defect is visible only to someone who looks at it.
+ *
+ * So the form is refused rather than resolved. Resolving it would mean choosing
+ * an output syntax for a field whose renderer is unknown to this build — a
+ * markdown link is inert in a Hugo template that prints the value as text, and
+ * an `<a>` is unusable in one that escapes it — and would quietly bless an
+ * authoring habit that the pack build has no way to honour at all. Frontmatter
+ * carries data; a link belongs in prose.
+ *
+ * Values are read from the *parsed* frontmatter, so a `[[` inside a YAML comment
+ * is not a hit, and every hit can be named by the path a reader would look at.
+ *
+ * @param {unknown} fm - Parsed frontmatter, as `gray-matter` returns it.
+ * @returns {Array<{path: string, link: string}>} In reading order; `path` is the
+ *   dotted key path of the offending value (`government.summary`, `aliases.1`).
+ */
+export function frontmatterWikilinks(fm: unknown): Array<{
+    path: string;
+    link: string;
+}>;
+/**
+ * Rewrites the wikilinks in a markdown body as KB-local markdown links.
+ *
+ * A target is looked up case-insensitively: first as an alias scoped to the
+ * source's own **type** (`ctx.typeAlias`, keyed `type|alias`) — a note's
+ * directory and `category` play no part — then in the KB-wide `ctx.index` (keyed
+ * by the unambiguous `section/slug` and `type/shortcode`, plus name/filename/slug
+ * fallbacks).
+ *
+ * An unresolved target fails the build only when it is a genuine intra-KB
+ * problem — an ambiguous alias, or a qualified `prefix/key` whose prefix is a
+ * real KB section or content directory. Anything else is treated as an external
+ * reference — until every package's manifest is present, after which any
+ * `type-shortcode` address resolving nowhere fails too. Failures are collected
+ * in `ctx.errors`.
+ *
+ * Whether or not it fails the build, a target that resolves nowhere renders
+ * through {@link unresolvedLink} rather than as bare prose (#1665): the author's
+ * text is kept, marked so a reader can see a link was intended. Not failing the
+ * build is a statement that the link *may* be legitimate prose — it was never a
+ * reason to make a dead link indistinguishable from the sentence around it.
+ *
+ * A target that **resolved** to an entry with no page is not this case and is
+ * not marked: a pack-only package (#1516) publishes Foundry addresses and no
+ * web pages, so the author wrote a real address and there is simply nothing to
+ * link to.
+ *
+ * @param {string} body - The markdown body.
+ * @param {object} ctx - `{ index, typeAlias, collide, typeCollide, sections,
+ *   contentTypes, foreign, manifestsComplete, type, errors, src }`. `foreign`
+ *   is the cross-package manifest index (#1446); `manifestsComplete` says
+ *   whether every linkable package is accounted for. Together they decide
+ *   whether an unresolved address is a typo or a package merely absent.
+ * @returns {string} The body with wikilinks rewritten.
+ */
+export function resolveWebWikilinks(body: string, ctx: object): string;
+export { slugify };
+import { slugify } from "./content-slug.mjs";

package/types/engine/wikilink-syntax.d.mts

@@ -0,0 +1,101 @@
+/**
+ * The parts of a wikilink's interior.
+ *
+ * @typedef {object} ParsedWikilink
+ * @property {string} inner - The whole interior, unescaped and trimmed. What an
+ *   unlabelled link displays, anchor and all.
+ * @property {string} target - What is linked to: an address, an alias, or `""`
+ *   for a link to a section of the same page.
+ * @property {string} anchor - The `#section` slug, `""` when there is none.
+ * @property {string|null} display - The text after `|`, or `null` when the link
+ *   is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
+ * @property {boolean} labelled - Whether a `|` was present at all. What an
+ *   unlabelled link shows depends on whether its target read as an address
+ *   (SoHL#1409), so the caller needs to know.
+ */
+/**
+ * Split a wikilink's interior into its parts.
+ *
+ * Takes the **inside** of the brackets — the capture group of {@link WIKILINK} —
+ * not the whole link, so a caller that has already matched does not re-match.
+ *
+ * @param {string} rawInner - The text between `[[` and `]]`.
+ * @returns {ParsedWikilink} The parts, each trimmed.
+ */
+export function parseWikilink(rawInner: string): ParsedWikilink;
+/**
+ * Whether a parsed link addresses a section of the page it is written on.
+ *
+ * `[[#some-heading]]` — no target, only an anchor. Both resolvers special-case
+ * it before consulting any index, because there is nothing to look up.
+ *
+ * @param {ParsedWikilink} parsed - A parsed wikilink.
+ * @returns {boolean} True when the link is same-page.
+ */
+export function isSamePage({ target, anchor }: ParsedWikilink): boolean;
+/**
+ * What a `[[…]]` **is**, before anything decides where it points.
+ *
+ * One authored link compiles to two different addresses — a Foundry `@UUID`
+ * enricher for the packs, a URL for the web — and those two destinations are the
+ * *only* thing that legitimately differs. The syntax is the author's, and it is
+ * the same syntax whichever build is reading it.
+ *
+ * It was written twice, and the two copies had already drifted:
+ *
+ * | Body | `foundry` side | `web` side |
+ * | --- | --- | --- |
+ * | `[[weapongear-bsw` ⏎ `]]` in a table cell | not a link | a link whose target ends in a newline |
+ * | a stray `[[`, a real link two paragraphs later | finds the real link | swallows both paragraphs as one target |
+ *
+ * The web side's pattern omitted `\n` from the excluded set, so an unclosed
+ * bracket consumed everything up to the next `]]` anywhere in the document —
+ * the same shape of corruption a hand-rolled code-fence regex caused on the one
+ * page whose subject is link syntax (SoHL#1665). It was also internally
+ * inconsistent: its *frontmatter* scan excluded newlines while its body scan did
+ * not.
+ *
+ * So the parse lives here, once. A resolver receives the parts and decides only
+ * what it is actually for: which address space the target belongs to.
+ *
+ * @module
+ */
+/**
+ * A wikilink, as authored.
+ *
+ * **Newlines are excluded deliberately.** A link is written on one line; an
+ * unclosed `[[` is a typo, and the alternative is letting it swallow arbitrary
+ * prose in search of a closer. Erring towards "not a link" leaves the author's
+ * text as written, which is the safe direction for a rewriter.
+ */
+export const WIKILINK: RegExp;
+/**
+ * The parts of a wikilink's interior.
+ */
+export type ParsedWikilink = {
+    /**
+     * - The whole interior, unescaped and trimmed. What an
+     * unlabelled link displays, anchor and all.
+     */
+    inner: string;
+    /**
+     * - What is linked to: an address, an alias, or `""`
+     * for a link to a section of the same page.
+     */
+    target: string;
+    /**
+     * - The `#section` slug, `""` when there is none.
+     */
+    anchor: string;
+    /**
+     * - The text after `|`, or `null` when the link
+     * is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
+     */
+    display: string | null;
+    /**
+     * - Whether a `|` was present at all. What an
+     * unlabelled link shows depends on whether its target read as an address
+     * (SoHL#1409), so the caller needs to know.
+     */
+    labelled: boolean;
+};