@heroiclands/package-build 0.6.0 → 3.0.0

package/types/engine/wikilinks.d.mts

@@ -0,0 +1,172 @@
+/**
+ * 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 (#1362). `skill/wpnc` is the item; `docskill/wpnc` is the
+ * JournalEntry its prose compiled into, and `docmacro/autoattack` is the same
+ * arrangement for a macro (#1514).
+ *
+ * The virtual form exists for a type that carries separate documentation
+ * ({@link sohl.utils.packs.docEntryTypes} — the set the journals compiler and
+ * the link manifest read too), **or** for one that routes to the items pack.
+ * The second clause is the older rule and stays: types that compile into items
+ * are the open, unenumerated set (#1276), 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 text before the `/`.
+ * @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;
+/**
+ * Read a link target as a **qualified** `type-shortcode` reference, or report
+ * that it is a bare alias instead.
+ *
+ * Two separators are accepted, and they are **not** interchangeable in how
+ * confidently they mark a target as qualified:
+ *
+ * - **`type-shortcode`** — the canonical form (#1398). 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 now
+ *   authored. A hyphen qualifies **only when what precedes it is a known type**:
+ *   note names contain hyphens too (`Grukar-ahk`), and those must keep resolving
+ *   as aliases. The split is at the **first** hyphen, so a shortcode may itself
+ *   contain one (`trauma-self-pro` → `trauma` + `self-pro`).
+ * - **`type/shortcode`** — the legacy form, still 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 an error rather than an invitation to try the alias index. The
+ *   split is at the **last** slash, as it always was.
+ *
+ * A leading **package** segment is optional and outermost: `sohl-skill-lang` is
+ * `skill-lang` in the `sohl` package. It is read only when `packages` is given
+ * and names the segment, and only when the remainder is itself a valid address,
+ * so a note called "Grukar-ahk" stays an alias (#1499).
+ *
+ * @param {string} target - The link target, anchor already removed.
+ * @param {Set<string>} types - Every type the content tree contains.
+ * @param {Set<string>} [packages] - Every package an address may name. Omitted
+ *   by callers that resolve within one package, where the form cannot occur.
+ * @returns {{type: string, shortcode: string, itemDoc: boolean,
+ *   package?: string, reason?: undefined} | {reason: "unknown-type"} | null}
+ *   The resolved qualifier; a `reason` when the target is definitely qualified
+ *   but names no known type; or `null` when it is a bare alias.
+ */
+export function readQualifier(target: string, types: Set<string>, packages?: Set<string>): {
+    type: string;
+    shortcode: string;
+    itemDoc: boolean;
+    package?: string;
+    reason?: undefined;
+} | {
+    reason: "unknown-type";
+} | null;
+/**
+ * The deterministic JournalEntryPage id for one anchor: SHA-256 of
+ * `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric
+ * characters a Foundry id allows.
+ *
+ * Base64's `+`, `/`, and `=` are **not** legal in a Foundry document id
+ * (`/^[A-Za-z0-9]{16}$/`), so they are dropped before the first 16 characters
+ * are taken — the value stays a pure function of its two inputs, which is what
+ * lets the link and the page be computed independently.
+ *
+ * @param {string} noteId - The owning JournalEntry's `_id`.
+ * @param {string} anchorSlug - The slug declared by `{#slug}` on the heading.
+ * @returns {string} A 16-character alphanumeric id.
+ */
+export function anchorPageId(noteId: string, anchorSlug: string): string;
+/**
+ * Builds the link-resolution tables for a content tree.
+ *
+ * @param {Array<{type: string, id: string, shortcode?: string|null,
+ *   aliases?: string[], name?: string, pack?: string, docPack?: string}>} docs -
+ *   One entry per content note. `pack` / `docPack` name the packs the note's
+ *   document and its documentation entry landed in; omitted, the conventional
+ *   one-pack-per-type names stand in.
+ * @param {string} packageId - The Foundry package shipping the packs; the first
+ *   segment of every emitted UUID.
+ * @param {Map<string, object>} [foreign] - Canonically keyed entries from
+ *   vendored manifests of packages this build links into but does not publish.
+ * @param {string} [contentPackage] - This build's *content* package, which an
+ *   authored address may name explicitly. Defaults to `packageId`.
+ * @returns {{byShortcode: Map<string, object>, byAlias: Map<string, object|null>,
+ *   types: Set<string>}} `byAlias` holds `null` where a type-scoped alias is
+ *   claimed by more than one document, which makes the bare `[[Text]]` form
+ *   unusable for it. `types` is every type the tree actually contains, so a
+ *   qualifier naming no real type can be told apart from a missing target.
+ */
+export function buildWikilinkIndex(docs: Array<{
+    type: string;
+    id: string;
+    shortcode?: string | null;
+    aliases?: string[];
+    name?: string;
+    pack?: string;
+    docPack?: string;
+}>, packageId: string, foreign?: Map<string, object>, contentPackage?: string): {
+    byShortcode: Map<string, object>;
+    byAlias: Map<string, object | null>;
+    types: Set<string>;
+};
+/** Matches a whole wikilink, capturing its inner text. */
+/**
+ * Rewrites every wikilink in a markdown body as a Foundry UUID enricher.
+ *
+ * A link that cannot be resolved is left exactly as it was and reported in
+ * `unresolved`, so a content gap degrades to visible literal text rather than
+ * a broken link or a failed build.
+ *
+ * **Code is verbatim.** A `[[…]]` inside a fenced or indented code block, or
+ * inside an inline code span, is source text an author wrote to be read as
+ * written, so it is left alone and not reported (#1505). Without that, a
+ * script sample containing `grid[[0]]` became a link — and only for some
+ * array shapes, `[[1,2],[3,4]]` having an inner `]` the pattern cannot cross,
+ * so the corruption looked arbitrary. It reaches the reader through the
+ * *documented* copy of a macro while the executable copy stays correct.
+ *
+ * @param {string} markdown - The note body (frontmatter already stripped).
+ * @param {object} ctx
+ * @param {string} ctx.type - The source note's `type`, which scopes a bare `[[Text]]`.
+ * @param {string} ctx.id - The source note's document id.
+ * @param {string} [ctx.pack] - The pack the source note's own document landed
+ *   in, which addresses a `[[#slug]]` self-link — the one target with no index
+ *   entry.
+ * @param {string} [ctx.docPack] - The pack the source note's documentation
+ *   entry landed in.
+ * @param {{byShortcode: Map, byAlias: Map, types: Set}} ctx.index - From
+ *   {@link buildWikilinkIndex}.
+ * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
+ *   offset: number, reason: "unknown"|"ambiguous"|"unknown-type"}>}} `offset`
+ *   is the link's 0-based position in `markdown`, which is what lets a caller
+ *   report the line and column it sits on (#17).
+ */
+export function convertWikilinks(markdown: string, { type, id, pack, docPack, index }: {
+    type: string;
+    id: string;
+    pack?: string | undefined;
+    docPack?: string | undefined;
+    index: {
+        byShortcode: Map<any, any>;
+        byAlias: Map<any, any>;
+        types: Set<any>;
+    };
+}): {
+    markdown: string;
+    unresolved: Array<{
+        link: string;
+        target: string;
+        offset: number;
+        reason: "unknown" | "ambiguous" | "unknown-type";
+    }>;
+};
+import { ITEM_PACK } from "./ids.mjs";
+import { PACK_BY_TYPE } from "./ids.mjs";
+import { packForType } from "./ids.mjs";
+export { ITEM_PACK, PACK_BY_TYPE, packForType };

package/types/index.d.mts

@@ -1,3 +1,5 @@
+export * as engine from "./engine/index.mjs";
+export * as sohl from "./sohl/index.mjs";
 export * as manifest from "./manifest.mjs";
 export * as bundle from "./bundle.mjs";
 export * as stage from "./stage.mjs";
@@ -8,3 +10,4 @@ export * as e2e from "./e2e.mjs";
 export * as lang from "./lang.mjs";
 export * as coverage from "./coverage.mjs";
 export * as templates from "./templates.mjs";
+export { defineConfig, PACKAGE_KINDS, PACK_DOCUMENT_TYPES } from "./content-config.mjs";

package/types/manifest.d.mts

@@ -45,7 +45,7 @@ export function releaseUrls({ repoUrl, version, artifact }: {
 /**
  * The manifest's `packs`, derived from the one pack list the build already has.
  *
- * The two used to be written separately — `content-build.config.yaml` declared
+ * The two used to be written separately — `package-build.config.yaml` declared
  * a pack's name and type, and the manifest template declared them again beside
  * a label, a path and a system id, with nothing checking that the pairs agreed.
  * They are one list now.
@@ -55,10 +55,26 @@ export function releaseUrls({ repoUrl, version, artifact }: {
  * ships as an ordinary compendium. The order matches `packDirectories`, so the
  * manifest lists packs in the order the build compiles them.
  *
- * @param {object} config - The resolved content-build configuration.
+ * @param {object} config - The resolved content configuration.
  * @returns {object[]} The manifest's `packs` array.
  */
 export function manifestPacks(config: object): object[];
+/**
+ * The `relationships` block as published — every declared dependency, with the
+ * build's own keys dropped.
+ *
+ * Shape is otherwise preserved: kinds keep their order and their entries, an
+ * entry keeps its remaining keys in the order it declared them, and a block
+ * carrying no build-only key comes back equal to what went in. Only
+ * {@link BUILD_ONLY_RELATIONSHIP_KEYS} are removed — an unrecognised key is
+ * left alone, on the same reasoning that lets a declared manifest key through
+ * unread: a key Foundry adds later should not need a release of this package.
+ *
+ * @param {Record<string, unknown>} relationships - The declared block, as
+ *   content-build resolved it.
+ * @returns {Record<string, unknown>} It, without the build-only keys.
+ */
+export function publishedRelationships(relationships: Record<string, unknown>): Record<string, unknown>;
 /**
  * Build a Foundry package manifest from the resolved configuration.
  *
@@ -73,8 +89,12 @@ export function manifestPacks(config: object): object[];
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *
+ * `relationships` is derived but not copied whole: the keys that direct the
+ * build rather than describe the package are dropped first — see
+ * {@link publishedRelationships}.
+ *
  * @param {object} options - Inputs.
- * @param {object} options.config - The resolved content-build configuration.
+ * @param {object} options.config - The resolved content configuration.
  * @param {object} options.packageJson - The repository's `package.json`.
  * @param {string} options.artifact - `system` or `module`.
  * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
@@ -90,7 +110,7 @@ export function buildManifest({ config, packageJson, artifact, flags }: {
  * Write the generated manifest into the staged package.
  *
  * @param {object} options - As {@link buildManifest}, plus where to write.
- * @param {object} options.config - The resolved content-build configuration.
+ * @param {object} options.config - The resolved content configuration.
  * @param {object} options.packageJson - The repository's `package.json`.
  * @param {string} options.artifact - `system` or `module`.
  * @param {string} options.outDir - Directory to write into.
@@ -116,3 +136,31 @@ export function writeManifest({ config, packageJson, artifact, outDir, flags, }:
  * convention this project is free to choose.
  */
 export const ARTIFACTS: readonly string[];
+/**
+ * Relationship keys that direct the **build**, rather than describe the
+ * package.
+ *
+ * `relationships` is the one manifest block with a second reader.
+ * `@heroiclands/content-build` consumes it too, and v1.8.0 added
+ * `itemCatalog: true` as an opt-in on a declared dependency
+ * (content-build#82): it selects that package's Item packs as a resolution
+ * source for the actors pass. That is an instruction to the build, not a fact
+ * about the shipped package — Foundry's relationship schema does not define
+ * it, and someone reading a published manifest cannot tell a build directive
+ * from a declaration about what the package needs.
+ *
+ * So the block is filtered rather than copied whole (#29). The rule is the
+ * distinction, not the name: a key listed here answers *how is this built?*,
+ * and every key that survives answers *what does this package depend on?*.
+ * `itemCatalog` is the first build-time key to land on a relationship and is
+ * unlikely to be the last.
+ *
+ * A list is enough, and needs no prefix agreed between the two packages,
+ * because the input is already closed: content-build normalises a relationship
+ * to `id`, `type`, `manifest`, `compatibility` and its own build keys, and
+ * rejects anything else at configuration time. A key that reaches here is one
+ * the toolchain itself put there.
+ *
+ * @type {readonly string[]}
+ */
+export const BUILD_ONLY_RELATIONSHIP_KEYS: readonly string[];

package/types/markdownlint-config.d.mts

@@ -0,0 +1,8 @@
+declare namespace _default {
+    export { MARKDOWNLINT_CONFIG as config };
+    export let globs: string[];
+    export let ignores: string[];
+    export let gitignore: boolean;
+}
+export default _default;
+import { MARKDOWNLINT_CONFIG } from "./engine/prose-config.mjs";

package/types/prettier-config.d.mts

@@ -0,0 +1 @@
+export { PRETTIER_CONFIG as default } from "./engine/prose-config.mjs";

package/types/sohl/actors.d.mts

@@ -0,0 +1,65 @@
+export class Actors extends BasePackCompiler {
+    constructor({ itemsSourceDirs, foreignSourceDirs, ...options }: {
+        [x: string]: any;
+        itemsSourceDirs: any;
+        foreignSourceDirs?: never[] | undefined;
+    });
+    /** @type {readonly string[]} */
+    itemsSourceDirs: readonly string[];
+    foreignSourceDirs: any;
+    itemsMap: Map<string, object> | undefined;
+    /** @inheritdoc */
+    reportDetail(stats: any): void;
+    /**
+     * Resolve one embedded item from a `(type, shortcode?, overlay)`
+     * descriptor. If `shortcode` is given, the predefined item is fetched
+     * from `itemsMap` and the overlay deep-merged on top. If absent, the
+     * descriptor must carry enough fields to stand alone. The embedded
+     * item's `_id` is regenerated deterministically from
+     * `(actorId, type, shortcode, indexKey)` so re-exports are stable.
+     * Returns null if the descriptor cannot be resolved.
+     */
+    resolveEmbedded(itemsMap: any, actorId: any, type: any, shortcode: any, overlay: any, indexKey: any, ctx: any): any;
+    /**
+     * Build all embedded items for an actor: one per `sohl.attributes`
+     * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
+     */
+    buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): any[];
+    buildBeing(itemsMap: any, fm: any, body: any): {
+        name: any;
+        type: string;
+        img: string;
+        _id: any;
+        system: {
+            shortcode: any;
+            portrait: string;
+            appearance: any;
+            dossier: any;
+        };
+        items: any[];
+        prototypeToken: {
+            name: any;
+            displayName: number;
+            actorLink: boolean;
+            texture: {
+                src: string;
+            };
+            width: number;
+            height: number;
+            sight: {
+                enabled: boolean;
+            };
+            detectionModes: never[];
+        };
+        effects: never[];
+        folder: string | null;
+        sort: number;
+        ownership: {
+            default: number;
+        };
+        flags: object;
+        _stats: object;
+        _key: string;
+    };
+}
+import { BasePackCompiler } from "../engine/base-compiler.mjs";

package/types/sohl/affiliation-standings.d.mts

@@ -0,0 +1,22 @@
+/**
+ * The affiliation standings an authored `relation` map may use — one
+ * affiliation's stance toward another (#1404).
+ *
+ * Plain ESM for the same reason `./default-item-art.mjs` is: the pack scripts
+ * run under bare `node`, so they cannot read the runtime's TypeScript
+ * `AFFILIATION_STANDING`. This module is where the pipeline reads the list
+ * from, rather than restating it inside a compiler (#1510).
+ *
+ * The runtime keeps its own `defineType("SOHL.Affiliation.Standing", { … })`
+ * declaration in `src/utils/constants.ts`, because that literal is *parsed out
+ * of the source* by two build guards — the generated type catalog
+ * (`utils/build-type-catalog.mjs`) and the localization-coverage check
+ * (`utils/check-lang-coverage.mjs`) — and replacing it with an imported
+ * reference would blind both. The two lists are held identical by a test
+ * (`tests/build/src-import-severance.test.ts`), so the drift the
+ * duplication would otherwise allow is a failing build rather than an
+ * affiliation whose authored hostility quietly became neutrality.
+ *
+ * @type {readonly string[]}
+ */
+export const AFFILIATION_STANDINGS: readonly string[];

package/types/sohl/being-info.d.mts

@@ -0,0 +1,78 @@
+/**
+ * Whether a note's frontmatter describes a being.
+ *
+ * @param {{type?: unknown}|null|undefined} fm - A note's frontmatter.
+ * @returns {boolean} `true` when the note is a being.
+ */
+export function isBeing(fm: {
+    type?: unknown;
+} | null | undefined): boolean;
+/**
+ * Derive a being's info-block fields from its raw `sohl.items[]`.
+ *
+ * Each item's `shortcode` is resolved against `index` — keyed
+ * `"<type>:<shortcode>"` — for a display name and a link to the item's own
+ * page. `attributes` already match the sidebar shape and pass through
+ * untouched.
+ *
+ * **Authored values win.** Only fields the author did not supply are derived,
+ * so a note that hand-writes `sohl.skills` keeps exactly what it wrote. An
+ * item's inline `name` beats the index, and an unresolved shortcode falls back
+ * to *itself* rather than being dropped — a page that names an item the index
+ * has not heard of is better than a page silently missing a row.
+ *
+ * Returns a new object; the input is not mutated.
+ *
+ * @param {object|null|undefined} sohl - The note's `sohl` frontmatter block.
+ * @param {Map<string, {name?: string, url?: string}>} index - Content index,
+ *   `"<type>:<shortcode>"` → the item's page.
+ * @returns {object|null|undefined} The block with its info-block fields filled
+ *   in, or the input unchanged when there is nothing to derive from.
+ */
+export function deriveBeingInfo(sohl: object | null | undefined, index: Map<string, {
+    name?: string;
+    url?: string;
+}>): object | null | undefined;
+/**
+ * **A being's info-block fields**, derived from the items it embeds.
+ *
+ * A `being` note carries its embedded documents as `sohl.items` — a flat list
+ * of `{ shortcode, type, system? }` — but the shared theme's sidebar reads
+ * *resolved* shapes: a `skills` map, `gear` grouped by kind, and `spells` /
+ * `talents` split out of the mystical abilities. This is the translation
+ * between the two, and it is SoHL data-model knowledge: which item type is a
+ * skill, where a mastery level lives, what distinguishes a spell from a talent.
+ *
+ * **It lives here because it was living in two places.** Both
+ * `Song-of-Heroic-Lands-FoundryVTT` and `sohl-thalorna` carried a copy, and the
+ * copies drifted: SoHL's caller still gated the derivation on `character` and
+ * `creature`, the two types #1580 merged into `being`, so it had matched
+ * nothing since the merge and all 95 of its being pages published with empty
+ * sidebar sections (SoHL#1696). thalorna's copy checked `being` and was right.
+ * Nothing failed in either repository; the pages built and shipped.
+ *
+ * {@link isBeing} exists for that reason. The bug was not in the derivation —
+ * it was in each caller's idea of what a being *is*, written out per repository
+ * where it could rot independently. One definition, imported.
+ *
+ * @module
+ */
+/**
+ * The note `type` whose pages carry a being info block.
+ *
+ * One name, since #1580 merged `character` and `creature` into the `being` they
+ * had always compiled into. The retired names are deliberately **not** accepted
+ * as aliases: they throw elsewhere in the system, and tolerating them here
+ * would hide the next drift of this kind rather than surface it.
+ */
+export const BEING_TYPE: "being";
+/**
+ * The sidebar group each gear item type is displayed under.
+ *
+ * Presentation naming, not data-model naming: the model says `weapongear`, the
+ * sidebar heading says "weapons". Kept as one table so a new gear type is added
+ * in a single place rather than in each consumer's site build.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const GEAR_TYPE_TO_KEY: Readonly<Record<string, string>>;

package/types/sohl/default-item-art.d.mts

@@ -0,0 +1,28 @@
+/**
+ * The default art path for an item `type`, or throw when the type is unknown —
+ * the build's fail-fast contract, so an unrecognized type is never silently
+ * defaulted (aborting the pack build rather than shipping a mismatched icon).
+ *
+ * Runtime callers that must tolerate unknown or `base`-typed items should read
+ * {@link DEFAULT_ITEM_ART} directly and fall back to Foundry's default instead
+ * of calling this — see `SohlItem.getDefaultArtwork`.
+ *
+ * @param {string} type - the item type.
+ * @returns {string} the default image path for that type.
+ */
+export function defaultItemArt(type: string): string;
+export namespace DEFAULT_ITEM_ART {
+    let affiliation: string;
+    let affliction: string;
+    let armorgear: string;
+    let attribute: string;
+    let concoctiongear: string;
+    let containergear: string;
+    let miscgear: string;
+    let mystery: string;
+    let mysticalability: string;
+    let projectilegear: string;
+    let skill: string;
+    let trauma: string;
+    let weapongear: string;
+}

package/types/sohl/index.d.mts

@@ -0,0 +1,7 @@
+export * as itemBuilders from "./item-builders.mjs";
+export * as items from "./items.mjs";
+export * as actors from "./actors.mjs";
+export * as kbPasses from "./kb-passes.mjs";
+export { AFFILIATION_STANDINGS } from "./affiliation-standings.mjs";
+export { DEFAULT_ITEM_ART, defaultItemArt } from "./default-item-art.mjs";
+export { BEING_TYPE, GEAR_TYPE_TO_KEY, deriveBeingInfo, isBeing } from "./being-info.mjs";

package/types/sohl/item-builders.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Every item type, paired with the builder for its `system` block, the default
+ * art for the type, and the frontmatter fields it declares.
+ *
+ * @type {Readonly<Record<string, Readonly<{system: (fm: object) => object, img: string, fields: readonly object[]}>>>}
+ */
+export const ITEM_BUILDERS: Readonly<Record<string, Readonly<{
+    system: (fm: object) => object;
+    img: string;
+    fields: readonly object[];
+}>>>;

package/types/sohl/item-fields.d.mts

@@ -0,0 +1,20 @@
+/**
+ * Every item type's frontmatter vocabulary, in the order the `system` block
+ * emits it.
+ *
+ * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
+ */
+export const ITEM_FIELDS: Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>;
+/**
+ * The one conditional field in the vocabulary: a combat technique's strike
+ * mode.
+ *
+ * A combat technique is authored as a `skill` of subtype `combattechnique` —
+ * the standalone item type was merged into Skill — and carries an embedded,
+ * discriminated strike mode. It is mandatory for that subtype and absent from
+ * every other skill, which is a conditional a flat field list cannot state, so
+ * it is applied after the declaration runs.
+ *
+ * @type {import("../engine/field-spec.mjs").FieldSpec}
+ */
+export const COMBAT_TECHNIQUE_STRIKE_MODE: import("../engine/field-spec.mjs").FieldSpec;

package/types/sohl/items.d.mts

@@ -0,0 +1,19 @@
+export class Items extends BasePackCompiler {
+    /**
+     * How many of each item type this pass wrote, for the summary. Every type
+     * is present from the start so the tally reads as a census of the
+     * whitelist rather than of what happened to compile.
+     *
+     * @type {Record<string, number>}
+     */
+    counts: Record<string, number>;
+    /** An item is named by its own type in the log, not by "item". */
+    noteLabel(fm: any): any;
+    /** @inheritdoc */
+    onCompiled(fm: any): void;
+    /** @inheritdoc */
+    reportCompiled(stats: any): void;
+    /** @inheritdoc */
+    reportDetail(stats: any): void;
+}
+import { BasePackCompiler } from "../engine/base-compiler.mjs";

package/types/sohl/kb-passes.d.mts

@@ -0,0 +1,71 @@
+/**
+ * Resolves inline TypeDoc `{@link}` / `{@linkcode}` / `{@linkplain}` tags
+ * against the API symbol map.
+ *
+ * - A known target becomes a Markdown link to its page on the API site;
+ *   `@linkcode` renders the text as code.
+ * - Optional display text (`{@link Target | text}` or `{@link Target text}`)
+ *   wins; otherwise the last dotted segment is the link text.
+ * - An external URL target becomes a plain Markdown link.
+ * - Anything the map does not know — `{@link Symbol.member}` written as a syntax
+ *   example, say — degrades to a code span. Never a broken link, never a build
+ *   failure.
+ *
+ * @param {string} body - The markdown body.
+ * @param {Record<string, string>} symbols - The symbol map.
+ * @param {string} apiBase - Where the generated API documentation is served.
+ * @returns {string} The body with every tag resolved.
+ */
+export function resolveApiLinks(body: string, symbols: Record<string, string>, apiBase: string): string;
+/**
+ * Rewrites the relative links in a developer-doc body so they resolve on the
+ * published site.
+ *
+ * Developer docs are authored to link one another and the source tree with
+ * repository-relative paths, and neither target exists at the same path once
+ * rendered. Each link is resolved against the doc's own location:
+ *
+ * - a `*.md` link landing inside the documentation tree becomes the published
+ *   route, preserving any `#anchor`; a `README` is its directory's landing, so
+ *   that segment is dropped.
+ * - anything else — source, templates, a repository-root `*.md` — becomes its
+ *   GitHub blob URL.
+ *
+ * Absolute URLs, anchor-only links, `mailto:` and site-root links are untouched.
+ *
+ * @param {string} body - The markdown body.
+ * @param {string} docRel - The doc's path relative to the documentation tree.
+ * @param {object} options - `{ repoRoot, docsSrc, docsRel, route, blob }`.
+ * @returns {string} The body with every relative link rewritten.
+ */
+export function rewriteRepoLinks(body: string, docRel: string, options: object): string;
+/**
+ * The `sohl` knowledgebase pass bundle, built from its options.
+ *
+ * A pass bundle is two optional hooks the page renderer calls around wikilink
+ * resolution, and the order matters:
+ *
+ * - `beforeLinks` runs on every page, before wikilinks resolve, because a
+ *   `{@link}` tag may sit inside prose a wikilink also touches.
+ * - `afterLinks` runs only on pages from an **extra tree** — the documentation
+ *   tree — because repository-relative links are a property of how those pages
+ *   are authored, not of content notes.
+ *
+ * Both run inside code-fence protection, so neither can rewrite a fenced example.
+ *
+ * @param {object} options - Resolved from `site.passOptions`.
+ * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map.
+ * @param {string} [options.apiBase] - Where the API documentation is served.
+ * @param {string} [options.blob] - GitHub blob base for repository files.
+ * @param {string} options.repoRoot - The repository root, for relative paths.
+ * @returns {{beforeLinks: Function, afterLinks: Function}} The bundle.
+ */
+export function sohlKbPass(options: {
+    symbolMap?: string | undefined;
+    apiBase?: string | undefined;
+    blob?: string | undefined;
+    repoRoot: string;
+}): {
+    beforeLinks: Function;
+    afterLinks: Function;
+};

package/types/sohl/note-schemas.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Every content type this package compiles, and what a note of that type may
+ * write.
+ *
+ * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
+ */
+export const NOTE_SCHEMAS: Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>;