@heroiclands/package-build 20.4.0 → 20.6.0

package/hm3/actors.mjs

@@ -189,6 +189,14 @@ function defaultActorImg(subType) {
     return img;
 }
 
+/**
+ * HM3's Actor compile pass.
+ *
+ * Declares HM3's note-type → document-subtype map and builds a `being` note's
+ * document: the subtype the note authors in `hm3.type`, the mapped fields and
+ * the two anchored prose sections, and the embedded items `hm3.items` names.
+ * Everything else is {@link module:engine/actor-compiler}'s.
+ */
 export class Hm3Actors extends SystemActorCompiler {
     /**
      * HM3's note-type → document-subtype map — the one declaration that says

package/hm3/items.mjs

@@ -54,6 +54,14 @@ import { SystemItemCompiler } from "../engine/item-compiler.mjs";
 import { HM3_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 import { templateFlags } from "./template-priority.mjs";
 
+/**
+ * HM3's Item compile pass.
+ *
+ * Declares HM3's note-type → document-subtype map, which decides the notes this
+ * pass claims and what each becomes, the one `system` key HM3 writes from prose,
+ * and the template-priority flag HM3's data model has no field for. Everything
+ * else is {@link module:engine/item-compiler}'s.
+ */
 export class Hm3Items extends SystemItemCompiler {
     /**
      * HM3's note-type → document-subtype map — the one declaration that says

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "20.4.0",
+    "version": "20.6.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/release.mjs

@@ -57,10 +57,17 @@ import { ZipArchive } from "archiver";
  *   Determines both asset names.
  * @param {string} [opts.metadataDir] - Where the build writes its content
  *   index, consulted when the advertised file was not staged.
+ * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
+ *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   bytes: number, version: string}>} The paths written, the archive's size,
- *   and the version the manifest declares. `metadata` is absent when the
- *   manifest advertises no content index.
+ *   pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   bytes: number, version: string}>} The paths written, what the book build
+ *   found, the archive's size, and the version the manifest declares.
+ *   `metadata` is absent when the manifest advertises no content index, and
+ *   `pdf` is absent when no book was written. `pdfSkipped` is `null` when a
+ *   book was built, and otherwise the reason none was — itself `null` when the
+ *   book builder could not be loaded, which is reported through
+ *   `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -69,6 +76,7 @@ export async function packRelease({
     outDir = "build/dist",
     artifact = "system",
     metadataDir = "build/content-index",
+    pdf = true,
 } = {}) {
     const stage = path.resolve(stageDir);
     const out = path.resolve(outDir);
@@ -112,15 +120,67 @@ export async function packRelease({
 
     const metadata = await publishMetadataIndex({ manifest, stage, out, metadataDir });
 
+    // Last, and never fatal: the archive and the manifest are the release, and
+    // a book that failed to set is a reported problem rather than a reason to
+    // publish neither.
+    const book =
+        pdf ?
+            await packReleasePdf({ out, version: manifest.version })
+        :   { pdf: null, findings: [], reason: "the release was asked not to build one" };
+
     return {
         zip: zipPath,
         manifest: path.join(out, manifestName),
         ...(metadata ? { metadata } : {}),
+        ...(book.pdf ? { pdf: book.pdf } : {}),
+        pdfFindings: book.findings,
+        pdfSkipped: book.pdf ? null : book.reason,
         bytes: archive.pointer(),
         version: manifest.version,
     };
 }
 
+/**
+ * Build the book that ships beside the archive.
+ *
+ * **Imported when it is used, not when this module is.** The book build pulls
+ * in a markdown parser, DuckDB and the whole content engine; `release.mjs`
+ * otherwise exists to zip a directory, and every consumer that publishes no
+ * book would pay for that graph on `import`. A dynamic import inside the one
+ * function that needs it keeps the cost where the benefit is.
+ *
+ * **Not building is the normal case and never an error.** A package publishing
+ * only a homepage, one with no `pdf:` block and one with no content tree have
+ * each said they publish no book. Four of the six packages that install this
+ * toolchain are in exactly that position, so a release that failed for the
+ * absence of a PDF would break more releases than it helped.
+ *
+ * @param {object} opts - Options.
+ * @param {string} opts.out - The release directory.
+ * @param {string} opts.version - The version the manifest declares.
+ * @returns {Promise<{pdf: string|null, findings: object[], reason: string|null}>}
+ *   What was built, and what was found on the way.
+ */
+async function packReleasePdf({ out, version }) {
+    let buildPdf;
+    try {
+        ({ buildPdf } = await import("./engine/pdf-build.mjs"));
+    } catch (err) {
+        return {
+            pdf: null,
+            findings: [
+                {
+                    severity: "warning",
+                    message: `the book builder could not be loaded: ${err.message}`,
+                },
+            ],
+            reason: null,
+        };
+    }
+    const result = await buildPdf({ out, version });
+    return { pdf: result.pdf, findings: result.findings, reason: result.reason };
+}
+
 /**
  * Place the content index the manifest advertises beside the archive.
  *

package/sohl/actors.mjs

@@ -190,6 +190,14 @@ function extractBodyAndMovement(fm) {
     };
 }
 
+/**
+ * SoHL's Actor compile pass.
+ *
+ * Declares SoHL's note-type → document-subtype map and builds a `being` note's
+ * document: the body structure and its movement profiles, the embedded
+ * attribute and item documents the frontmatter names, and the `system` block.
+ * Everything else is {@link module:engine/actor-compiler}'s.
+ */
 export class Actors extends SystemActorCompiler {
     /**
      * SoHL's note-type → document-subtype map — the one declaration that says

package/sohl/items.mjs

@@ -41,6 +41,14 @@ import { systemTemplatePriority } from "../engine/helpers.mjs";
 import { SystemItemCompiler } from "../engine/item-compiler.mjs";
 import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 
+/**
+ * SoHL's Item compile pass.
+ *
+ * Declares SoHL's note-type → document-subtype map, which decides the notes
+ * this pass claims and what each becomes, and the `system` keys SoHL writes on
+ * every item whatever its type. Everything else is
+ * {@link module:engine/item-compiler}'s.
+ */
 export class Items extends SystemItemCompiler {
     /**
      * SoHL's note-type → document-subtype map — the one declaration that says

package/sohl/note-schemas.mjs

@@ -82,11 +82,6 @@ const MACRO_FIELDS = Object.freeze([
     },
 ]);
 
-/**
- * A `being` note — an actor, with its body, movement and embedded items.
- *
- * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
- */
 /**
  * A `vehicle` note — a conveyance that carries goods and people.
  *
@@ -103,6 +98,11 @@ const MACRO_FIELDS = Object.freeze([
  */
 const VEHICLE_FIELDS = Object.freeze([]);
 
+/**
+ * A `being` note — an actor, with its body, movement and embedded items.
+ *
+ * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
+ */
 const BEING_FIELDS = Object.freeze([
     {
         name: "body",

package/types/content-config.d.mts

@@ -1,3 +1,16 @@
+/**
+ * Whether this package compiles Foundry documents at all.
+ *
+ * The one question every Foundry-side reader asks — the manifest writer, to
+ * decide whether there is a package for Foundry to install, and the pack
+ * compilers, to decide whether there is anything to compile.
+ *
+ * @param {{packageKind: string}} config - A resolved configuration.
+ * @returns {boolean} Whether the package compiles Foundry documents.
+ */
+export function compilesFoundryDocuments(config: {
+    packageKind: string;
+}): boolean;
 /**
  * Whether this package publishes the pages its content tree compiles to.
  *
@@ -30,13 +43,27 @@ export function publishesContentPages(config: {
  */
 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.
+ * What kind of package this is.
+ *
+ * `systems` and `modules` are the two Foundry answers, and the value is also
+ * the directory Foundry installs the package under, which is why they are
+ * plural. `documentation` is the answer "not a Foundry package at all": it
+ * publishes a site and a book from its notes, installs into no Foundry data
+ * directory and compiles no compendium.
  *
  * @satisfies {readonly PackageKind[]}
  */
-export const PACKAGE_KINDS: readonly ["systems", "modules"];
+export const PACKAGE_KINDS: readonly ["systems", "modules", "documentation"];
+/**
+ * The kind that compiles no Foundry documents.
+ *
+ * Spelled once and read wherever a pass asks whether it applies, so the
+ * validator, the CLI and the compile passes cannot come to disagree about what
+ * the value means.
+ *
+ * @type {string}
+ */
+export const DOCUMENTATION_KIND: string;
 export namespace DEFAULT_PATHS {
     let content: "assets/content";
     let contentIndex: "build/content-index";
@@ -179,7 +206,7 @@ export const DERIVED_SYSTEM_VERSION: symbol;
  * means what it said.
  */
 export type SiteMode = "homepage" | "content";
-export type PackageKind = "systems" | "modules";
+export type PackageKind = "systems" | "modules" | "documentation";
 export type PackDocumentType = "Actor" | "Adventure" | "Item" | "JournalEntry" | "Macro" | "Scene";
 /**
  * One compendium pack the build compiles, named exactly as it is declared in
@@ -542,17 +569,27 @@ export type ContentBuildConfigInput = {
     contentPackage: string;
     /**
      * Foundry package id, as it appears in
-     * `system.json` / `module.json`.
+     *       `system.json` / `module.json`.
+     *       Refused by a `documentation`
+     *       package, which ships no Foundry
+     *       package.
      */
-    foundryPackage: string;
+    foundryPackage?: string | undefined;
     /**
-     * Whether the package is a system or a module.
+     * Whether the package is a system, a
+     * module, or documentation — the kind
+     * that publishes a site and a book
+     * while compiling nothing.
      */
     packageKind: PackageKind;
     /**
-     * Identity stamped into every document's `_stats`.
+     * Identity stamped into every
+     *             document's `_stats`. Required of a
+     *             package that compiles documents, and
+     *             refused by a `documentation` one,
+     *             which compiles none.
      */
-    stats: StatsSpec;
+    stats?: StatsSpec | undefined;
     /**
      * The consumer's
      * item-type registry: each content `type`
@@ -626,15 +663,29 @@ export type ContentBuildConfigInput = {
 export type ContentBuildConfig = {
     rootDir: string;
     contentPackage: string;
-    foundryPackage: string;
+    /**
+     * `null` for a `documentation`
+     * package, which ships no Foundry package.
+     */
+    foundryPackage: string | null;
     packageKind: PackageKind;
     /**
-     * Derived: the served Foundry asset root,
-     * `<packageKind>/<foundryPackage>/assets`.
+     * Derived, and **conditional**: the served
+     * Foundry asset root,
+     * `<packageKind>/<foundryPackage>/assets`,
+     * for a package Foundry installs — and
+     * `null` for a `documentation` package,
+     * which Foundry serves no files for. See
+     * {@link module :engine/helpers.resolveImg},
+     * the one reader of it.
      */
-    assetRoot: string;
+    assetRoot: string | null;
     paths: Readonly<ResolvedPaths>;
-    stats: Readonly<StatsSpec>;
+    /**
+     * `null` for a `documentation`
+     * package, which stamps no `_stats`.
+     */
+    stats: Readonly<StatsSpec> | null;
     /**
      * Derived: the
      * `system` builder of each entry, whichever

package/types/engine/actor-compiler.d.mts

@@ -224,33 +224,6 @@ export class SystemActorCompiler extends BasePackCompiler {
      *   subtype, or why the reference names none.
      */
     embeddedSubtype(type: string): import("./document-subtypes.mjs").ReferencedSubtype;
-    /**
-     * 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, subType, shortcode, indexKey)` so re-exports are stable —
-     * from the **document subtype**, so that renaming a note type leaves
-     * every embedded id exactly where it was.
-     * Returns null if the descriptor cannot be resolved.
-     *
-     * @param {Map<string, object>} itemsMap - The predefined items, by address.
-     * @param {string} actorId - The owning actor's id, seeding embedded ids.
-     * @param {string} type - The **note** type the reference names.
-     * @param {string|null} shortcode - The referenced item's shortcode, or
-     *   `null` for a stand-alone entry.
-     * @param {object} [overlay] - The entry's remaining properties.
-     * @param {string} indexKey - Where the reference sits, for a diagnostic.
-     *   It no longer reaches the id — it names the entry in a message.
-     * @param {string} ctx - Diagnostic context (the actor's label).
-     * @param {object} [at] - Where to locate a finding.
-     * @param {string} [at.fmKey] - The frontmatter key the reference sits
-     *   under, so an unresolved one is reported at the reference rather than
-     *   at the note.
-     * @returns {object|null} The embedded item, or null when it resolved to
-     *   nothing — always with a finding emitted.
-     */
     /**
      * Read an entry's `model:` — the address of the item it is a copy of.
      *
@@ -276,9 +249,40 @@ export class SystemActorCompiler extends BasePackCompiler {
         shortcode: string;
         package: string | null;
     } | null;
-    resolveEmbedded(itemsMap: any, actorId: any, type: any, shortcode: any, overlay: any, indexKey: any, ctx: any, { fmKey, modelPackage }?: {
-        modelPackage?: null | undefined;
-    }): any;
+    /**
+     * 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, subType, shortcode, indexKey)` so re-exports are stable —
+     * from the **document subtype**, so that renaming a note type leaves
+     * every embedded id exactly where it was.
+     * Returns null if the descriptor cannot be resolved.
+     *
+     * @param {Map<string, object>} itemsMap - The predefined items, by address.
+     * @param {string} actorId - The owning actor's id, seeding embedded ids.
+     * @param {string} type - The **note** type the reference names.
+     * @param {string|null} shortcode - The referenced item's shortcode, or
+     *   `null` for a stand-alone entry.
+     * @param {object} overlay - The entry's remaining properties.
+     * @param {string} indexKey - Where the reference sits, for a diagnostic.
+     *   It names the entry in a message and does not reach the id.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     * @param {object} [at] - Where to locate a finding.
+     * @param {string} [at.fmKey] - The frontmatter key the reference sits
+     *   under, so an unresolved one is reported at the reference rather than
+     *   at the note.
+     * @param {string|null} [at.modelPackage] - The package a `model:` names,
+     *   where the template comes from another package's catalogue. Given one,
+     *   the packaged address is what resolves and nothing local shadows it.
+     * @returns {object|null} The embedded item, or null when it resolved to
+     *   nothing — always with a finding emitted.
+     */
+    resolveEmbedded(itemsMap: Map<string, object>, actorId: string, type: string, shortcode: string | null, overlay: object, indexKey: string, ctx: string, { fmKey, modelPackage }?: {
+        fmKey?: string | undefined;
+        modelPackage?: string | null | undefined;
+    }): object | null;
     #private;
 }
 import { BasePackCompiler } from "./base-compiler.mjs";

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

@@ -39,9 +39,60 @@ export function readItemAddresses(dirs: readonly string[]): Map<string, {
     shortcode: string;
     file: string;
 }>;
-export function declaredPredecessors(contentBase: any, { skipDirectories, maps, config, records, problems }?: {
-    maps?: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[] | undefined;
-}): Map<any, any>;
+/**
+ * Every rename the tree's notes **declare**, as old address → where it went.
+ *
+ * Read from the content tree rather than from compiled output, because a
+ * declaration is authored and the compiled document does not carry it: nothing
+ * downstream consumes `renamedFrom:`, so emitting it into every pack to let one
+ * diagnostic read it back would put a build-time note in shipped data forever.
+ * The tree is already read by this module for the same reason
+ * ({@link noteFilesById}) — to place a finding where its author can fix it.
+ *
+ * **A declaration is keyed by document subtype, not by note type.** The address
+ * space is the one consumers resolve against, and it is spelled in compiled
+ * documents: `hm3` compiles a `projectile` note into a `missilegear` item,
+ * so that is the address a rename of it moves. {@link referencedSubtype} is the
+ * function that already answers this for a being's embedded `(type, shortcode)`
+ * references, so both sides read the same rule rather than a second copy of it.
+ *
+ * **An entry is emitted for every system that maps the type**, whether or not
+ * the note declares that system's block. Over-emitting is inert — the diff uses
+ * an entry only when the baseline published the old address *and* this build
+ * publishes the new one, and a system the note does not compile for satisfies
+ * neither — while asking which blocks a note declares would put a second,
+ * subtly different answer to that question in a third place.
+ *
+ * **First claim wins on a collision.** Two notes naming one predecessor is a
+ * contradiction — an address has one successor — and it is reported as an error
+ * by `engine/content-lint.mjs`, where both notes are in hand and can both be
+ * named. Picking one here keeps this a map; it is not a resolution, and nothing
+ * rests on which one it picked.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} opts
+ * @param {readonly string[]} [opts.skipDirectories] - The corpus scope. Stated
+ *   by the caller, never defaulted — see {@link addressCorpus}.
+ * @param {readonly object[]} [opts.maps] - The document-subtype maps.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {readonly object[]} [opts.records] - Index records the caller already
+ *   derived, shared with {@link noteFilesById} so one command reads one corpus.
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, so one of them does not abort the diff before it reports.
+ * @returns {Map<string, {to: string, file: string, shortcode: string}>} Old
+ *   address → the address the declaring note publishes at now, and that note.
+ */
+export function declaredPredecessors(contentBase: string, { skipDirectories, maps, config, records, problems }?: {
+    skipDirectories?: readonly string[] | undefined;
+    maps?: readonly object[] | undefined;
+    config?: object | undefined;
+    records?: readonly object[] | undefined;
+    problems?: object[] | undefined;
+}): Map<string, {
+    to: string;
+    file: string;
+    shortcode: string;
+}>;
 /**
  * Every address the baseline published that this build does not.
  *
@@ -85,12 +136,15 @@ export function diffItemAddresses(baseline: Map<string, object>, current: Map<st
  *   id is derived against. See {@link addressCorpus} for why that matters.
  * @param {readonly object[]} [opts.records] - Index records the caller already
  *   derived, shared with {@link declaredPredecessors}.
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, so one of them does not abort the diff before it reports.
  * @returns {Map<string, string>} Document id → the note's absolute path.
  */
 export function noteFilesById(contentBase: string, { skipDirectories, config, records, problems }?: {
     skipDirectories?: readonly string[] | undefined;
     config?: object | undefined;
     records?: readonly object[] | undefined;
+    problems?: object[] | undefined;
 }): Map<string, string>;
 /**
  * Where to send the reader for one finding.

package/types/engine/base-compiler.d.mts

@@ -136,11 +136,17 @@ export class BasePackCompiler {
      *   Resolves a `packFolder` — a folder note's address — to the Foundry
      *   folder id it materialises as in this pack.
      * @param {string} [options.packName] - The pack this pass writes.
+     * @param {string|null} [options.packSystem] - The system that pack declares,
+     *   which decides the `_stats` it stamps and the system block a note must
+     *   carry to reach it. `null` for a pack that declares none.
      * @param {string} [options.docType] - The Foundry document type it holds.
      * @param {{resolve: Function}} [options.router] - The pack router. Omit it
      *   — as the unit suite does — and every claimed note is compiled here.
      * @param {boolean} [options.routingReporter] - Whether this pass reports a
      *   note of its type that routes nowhere.
+     * @param {object} [options.corpus] - The corpus this compile is running
+     *   over, derived once and shared by every pass. A pass handed none derives
+     *   its own in `prepare`, and reports that corpus's problems itself.
      */
     constructor({ contentBase, dest, skipDirectories, folderResolver, packName, packSystem, docType, router, routingReporter, corpus, }?: {
         contentBase: string;
@@ -148,11 +154,13 @@ export class BasePackCompiler {
         skipDirectories: readonly string[];
         folderResolver?: ((address: string | null) => string | null) | undefined;
         packName?: string | undefined;
+        packSystem?: string | null | undefined;
         docType?: string | undefined;
         router?: {
             resolve: Function;
         } | undefined;
         routingReporter?: boolean | undefined;
+        corpus?: object | undefined;
     });
     /** @type {string} */
     contentBase: string;
@@ -219,8 +227,8 @@ export class BasePackCompiler {
      * @type {number}
      */
     unresolvedLinks: number;
-    packSystem: any;
-    corpus: any;
+    packSystem: string | null;
+    corpus: object | undefined;
     /**
      * The `_stats` block every entry this pass emits is stamped with.
      *

package/types/engine/bundles.d.mts

@@ -20,6 +20,15 @@
  *   pack, which reordering cannot fix.
  */
 export function loadBundleSources(sourceDirs: Readonly<Record<string, readonly string[]>>): Map<string, object>;
+/**
+ * Adventure pack compiler.
+ *
+ * Walks the content tree and compiles every `type: bundle` note into one
+ * Adventure per system, holding **copies** of the compiled documents its
+ * `contents` addresses name. Reading other passes' output is what
+ * {@link Bundles.readsPackOutputOf} declares, and what the generator orders the
+ * compile by.
+ */
 export class Bundles extends BasePackCompiler {
     /**
      * @param {object} options - As {@link BasePackCompiler}, plus:

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

@@ -14,11 +14,11 @@
  * consumer deriving a `path` from a key drops the *package and the system*, not
  * the package alone.
  *
- * The hyphen is a separator and never occurs inside a segment: a shortcode is
- * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced by `content-lint.mjs`)
- * and a type is a bare word. That is the same charset guarantee positional key
- * parsing rests on, so the address and the key cannot disagree about where one
- * ends and the other begins.
+ * The hyphen is a separator and never occurs inside a segment: a shortcode
+ * matches `ADDRESS_SEGMENT_PATTERN` (`engine/address-charset.mjs`, enforced by
+ * `content-lint.mjs`) and a type is a bare word. That is the same charset
+ * guarantee positional key parsing rests on, so the address and the key
+ * cannot disagree about where one ends and the other begins.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string} The address segment, e.g. `weapongear-dagger`.
@@ -182,10 +182,10 @@ export function expandAddress(read: {
  *
  * 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 charset rule is what makes that sound** — every segment matches
+ * `ADDRESS_SEGMENT_PATTERN` (`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`, `contentPackage` by
  * `defineConfig`, 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

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

@@ -91,21 +91,65 @@ export function asciiName(name: unknown): string | null;
  *   a consumer iterating it should not have to check first.
  */
 export function asciiAliases(aliases: unknown): Array<string>;
+/**
+ * Build one index record from a note's frontmatter and its place in the tree.
+ *
+ * The frontmatter as authored, plus what the index derives from it: the package
+ * it compiles as, its address, ASCII folds of its name and aliases, the anchors
+ * of its body, its Foundry block, the address of its documentation journal, and
+ * where the file sits within the tree.
+ *
+ * @param {object} options - Options.
+ * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
+ * @param {string} options.relPath - Its path below the content root, POSIX-separated.
+ * @param {string} [options.absPath] - The file, read only on the failing path to
+ *   locate the offending key.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {string} [options.body] - The note's markdown body, for its anchors.
+ * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
+ * @param {object} [options.manifest] - The package manifest, which the Foundry
+ *   entries are derived against.
+ * @returns {Record<string, any>} The record, keys sorted at every depth.
+ * @throws {Error} When the note carries a key this module derives, which would
+ *   otherwise be overwritten without a word. `file` and, where the file was
+ *   read, `position` ride on the error.
+ */
 export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, }: {
-    frontmatter: any;
-    relPath: any;
-    absPath: any;
-    contentPackage: any;
-    body: any;
-    bodyLine: any;
-    manifest: any;
+    frontmatter: Record<string, any>;
+    relPath: string;
+    absPath?: string | undefined;
+    contentPackage: string;
+    body?: string | undefined;
+    bodyLine?: number | undefined;
+    manifest?: object | undefined;
 }): Record<string, any>;
-export function collectContentIndex(contentBase: any, { contentPackage, skipDirectories, manifest, problems }: {
-    contentPackage: any;
-    skipDirectories: any;
-    manifest: any;
-    problems: any;
-}): Record<string, any>[];
+/**
+ * Read a content tree into index records, in the order they will be written.
+ *
+ * An item note yields two records — the item, and the documentation journal
+ * that is a document in its own right.
+ *
+ * @param {string} contentBase - The content tree to walk.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {readonly string[]} options.skipDirectories - The walk's scope, stated
+ *   by the caller. An absent one is the caller's omission, and
+ *   {@link module:engine/helpers.walkMarkdownTree} throws on it.
+ * @param {object} [options.manifest] - The package manifest, which the Foundry
+ *   entries are derived against.
+ * @param {object[]} [options.problems] - Supplied by a **reader**: a note that
+ *   cannot be recorded is pushed here as a diagnostic and skipped. Omitted, the
+ *   note throws — the contract the emitter needs, since an index missing a note
+ *   asserts that it does not exist.
+ * @returns {Array<Record<string, any>>} The records, in a total order that does
+ *   not depend on directory-read order.
+ */
+export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, manifest, problems }: {
+    contentPackage: string;
+    skipDirectories: readonly string[];
+    manifest?: object | undefined;
+    problems?: object[] | undefined;
+}): Array<Record<string, any>>;
 /**
  * Serialize records as JSON Lines.
  *