@heroiclands/package-build 20.3.1 → 20.5.0

package/types/engine/note-vocabulary.d.mts

@@ -24,7 +24,7 @@ export function declaredTags(type: string, groups?: object): readonly string[];
  */
 export function hasTag(fm: object | null | undefined, tag: string): boolean;
 /**
- * Whether a note is tagged as an unfinished **draft** (#183).
+ * Whether a note is tagged as an unfinished **draft**.
  *
  * The one reader of {@link DRAFT_TAG}, so both builds ask the same question of
  * the same field. Presentation only: a draft note is in the packs, in the
@@ -38,10 +38,11 @@ export function isDraftNote(fm: object | null | undefined): boolean;
 /**
  * What a note carrying a subType outside the address charset is told.
  *
- * **Why the charset holds for a subType, which reaches no address.** #206 said
+ * **Why the charset holds for a subType, which reaches no address.** The rule
+ * said
  * "the hyphen separates the segments of an address", and that was true of a
  * subType when it shipped: `sectionOf` returned a `doc`'s subType, so the value
- * was a URL path segment. #204 retired sections and it is not one now. The rule
+ * was a URL path segment. Sections are retired and it is not one. The rule
  * stays, on its own footing: a subType is a vocabulary term the whole toolchain
  * keys on, and it is one closed set away from being an address segment again —
  * so the reason to spell it in the address charset is that a charset holding
@@ -72,8 +73,8 @@ export function typeCharsetMessage(type: string): string;
  *
  * The message states the reason **per key**, as {@link typeCharsetMessage} and
  * {@link subTypeCharsetMessage} do: a type is an address segment, and a subType
- * has not been one since #204 retired sections, so a single claim covering both
- * would be half wrong (#210).
+ * is not one, since sections are retired, so a single claim covering both
+ * would be half wrong.
  *
  * @param {Readonly<Record<string, TypeVocabulary>>} vocabulary - The registry.
  * @param {string} [where] - What declares it, for the message.
@@ -104,19 +105,21 @@ export function dataFields(type: string, vocabulary?: Readonly<Record<string, Ty
  */
 export function subTypes(type: string, vocabulary?: Readonly<Record<string, TypeVocabulary>>): readonly string[] | null | undefined;
 /**
- * Every note type this toolchain compiles, and the closed vocabulary it
- * declares.
+ * The declared tag that marks a note as **unfinished**.
  *
- * Taken from the content-format specification, one `### type:` section per
- * entry. Where the specification and the shape notes are authored in today
- * disagree, the specification wins on the **name** — that is what a `data:`
- * key will be called — and the disagreement is recorded on the field rather
- * than resolved silently.
+ * Named once and referenced from the declaration below, because a second
+ * spelling is how the two come apart: rename the tag in `DECLARED_TAGS` and a
+ * private copy elsewhere keeps matching the old word, silently.
  *
- * @type {Readonly<Record<string, TypeVocabulary>>}
+ * It is a **presentation** fact and nothing more. A draft note compiles,
+ * validates, publishes and resolves like any other; only a link *into* it
+ * renders marked. What it emphatically is not is the retired `draft:` field,
+ * whose entire effect was to move a note from published to unresolvable — see
+ * {@link draftRetiredMessage}.
  */
+export const DRAFT_TAG: "draft";
 /**
- * The tags that **classify** a note, grouped by what they classify (#172).
+ * The tags that **classify** a note, grouped by what they classify.
  *
  * `tags:` lives at the open top level and most tags belong there: a theme, a
  * region, a working state is the author's own and this build has no opinion
@@ -141,20 +144,6 @@ export function subTypes(type: string, vocabulary?: Readonly<Record<string, Type
  * fishing village is a `village` that is `fishing`, and the single-valued field
  * this replaced had to spell it `Fishing Village` as a value of its own.
  */
-/**
- * The declared tag that marks a note as **unfinished** (#183).
- *
- * Named once and referenced from the declaration below, because a second
- * spelling is how the two come apart: rename the tag in `DECLARED_TAGS` and a
- * private copy elsewhere keeps matching the old word, silently.
- *
- * It is a **presentation** fact and nothing more. A draft note compiles,
- * validates, publishes and resolves like any other; only a link *into* it
- * renders marked. What it emphatically is not is the retired `draft:` field,
- * whose entire effect was to move a note from published to unresolvable — see
- * {@link draftRetiredMessage}.
- */
-export const DRAFT_TAG: "draft";
 export const DECLARED_TAGS: Readonly<{
     /** What a place *is*. */
     placeKind: Readonly<{
@@ -182,186 +171,25 @@ export const DECLARED_TAGS: Readonly<{
         tags: readonly string[];
     }>;
 }>;
-export const NOTE_VOCABULARY: Readonly<{
-    being: Readonly<{
-        subTypes: null;
-        data: readonly DataFieldSpec[];
-    }>;
-    vehicle: Readonly<{
-        subTypes: null;
-        data: readonly DataFieldSpec[];
-    }>;
-    affiliation: Readonly<{
-        subTypes: readonly string[];
-        data: readonly DataFieldSpec[];
-    }>;
-    affliction: Readonly<{
-        subTypes: readonly string[];
-        data: readonly DataFieldSpec[];
-    }>;
-    armorgear: Readonly<{
-        data: readonly DataFieldSpec[];
-    }>;
-    armorlocation: Readonly<{
-        subTypes: null;
-        data: readonly DataFieldSpec[];
-    }>;
-    attribute: Readonly<{
-        data: readonly DataFieldSpec[];
-    }>;
-    concoctiongear: Readonly<{
-        subTypes: readonly string[];
-        data: readonly (DataFieldSpec | Readonly<{
-            describe: "How many of the thing there are; one when unstated.";
-            shape: "number";
-            kind: "number";
-            name: "quantity";
-        }>)[];
-    }>;
-    containergear: Readonly<{
-        data: readonly DataFieldSpec[];
-    }>;
-    miscgear: Readonly<{
-        data: readonly (DataFieldSpec | Readonly<{
-            describe: "How many of the thing there are; one when unstated.";
-            shape: "number";
-            kind: "number";
-            name: "quantity";
-        }>)[];
-    }>;
-    mystery: Readonly<{
-        subTypes: readonly string[];
-        data: readonly DataFieldSpec[];
-    }>;
-    mysticalability: Readonly<{
-        subTypes: readonly string[];
-        data: readonly DataFieldSpec[];
-    }>;
-    projectilegear: Readonly<{
-        subTypes: readonly string[];
-        data: readonly (DataFieldSpec | Readonly<{
-            describe: "How many of the thing there are; one when unstated.";
-            shape: "number";
-            kind: "number";
-            name: "quantity";
-        }>)[];
-    }>;
-    skill: Readonly<{
-        subTypes: readonly string[];
-        data: readonly DataFieldSpec[];
-    }>;
-    trauma: Readonly<{
-        subTypes: readonly string[];
-        data: readonly DataFieldSpec[];
-    }>;
-    weapongear: Readonly<{
-        data: readonly DataFieldSpec[];
-    }>;
-    doc: Readonly<{
-        subTypes: readonly string[];
-        data: readonly never[];
-    }>;
-    macro: Readonly<{
-        data: readonly never[];
-    }>;
-    folder: Readonly<{
-        data: readonly ({
-            describe: string;
-            shape: "a wikilink, or a map of wikilinks keyed by pack";
-            kind: "scalar-or-map";
-            entryShape: "a wikilink";
-            keys: "pack";
-            name: string;
-        } | {
-            describe: string;
-            shape: "string";
-            kind: "string";
-            name: string;
-        })[];
-    }>;
-    bundle: Readonly<{
-        data: readonly {
-            describe: string;
-            shape: "list of wikilinks";
-            kind: "list";
-            name: string;
-        }[];
-    }>;
-    lore: Readonly<{
-        subTypes: readonly string[];
-        data: readonly never[];
-    }>;
-    place: Readonly<{
-        subTypes: readonly string[];
-        data: readonly ({
-            describe: string;
-            shape: "string";
-            kind: "string";
-            name: string;
-        } | {
-            describe: string;
-            shape: "list of wikilinks";
-            kind: "list";
-            name: string;
-        } | {
-            describe: string;
-            shape: "number";
-            kind: "number";
-            name: string;
-        })[];
-    }>;
-    scenario: Readonly<{
-        subTypes: readonly string[];
-        data: readonly ({
-            describe: string;
-            shape: "list of wikilinks";
-            kind: "list";
-            name: string;
-        } | {
-            describe: string;
-            shape: "string";
-            kind: "string";
-            name: string;
-        } | {
-            describe: string;
-            shape: "list";
-            kind: "list";
-            name: string;
-        })[];
-    }>;
-    homepage: Readonly<{
-        data: readonly never[];
-    }>;
-    map: Readonly<{
-        subTypes: readonly string[];
-        data: readonly ({
-            describe: string;
-            shape: "string";
-            kind: "string";
-            name: string;
-        } | {
-            describe: string;
-            shape: "list";
-            kind: "list";
-            name: string;
-        } | {
-            describe: string;
-            shape: "number";
-            kind: "number";
-            name: string;
-        } | {
-            describe: string;
-            shape: "as authored";
-            name: string;
-        })[];
-    }>;
-}>;
+/**
+ * Every note type this toolchain compiles, and the closed vocabulary it
+ * declares.
+ *
+ * Taken from the content-format specification, one `### type:` section per
+ * entry. Where the specification and the shape notes are authored in today
+ * disagree, the specification wins on the **name** — that is what a `data:`
+ * key will be called — and the disagreement is recorded on the field rather
+ * than resolved silently.
+ *
+ * @type {Readonly<Record<string, TypeVocabulary>>}
+ */
+export const NOTE_VOCABULARY: Readonly<Record<string, TypeVocabulary>>;
 /**
  * One `data:` key a note type may carry.
  *
  * A deliberate subset of {@link import ("./field-spec.mjs").FieldSpec}: no `to`,
  * because nothing here builds anything yet. Reading `data.*` through into a
- * document's `system` block is the passthrough slice (#126), and claiming an
+ * document's `system` block is the passthrough slice, and claiming an
  * emitted path this does not produce would be a lie in the one place a reader
  * would trust it.
  */

package/types/engine/pack-config.d.mts

@@ -20,7 +20,7 @@ export function findConfigFile(from: string): string | undefined;
  *
  * Kept separate from {@link loadPackConfig} because the *choice* is worth being
  * able to ask about without loading anything: the two walks disagreeing is the
- * observable form of #364, and a caller that wants to report it — or a test
+ * observable form of that, and a caller that wants to report it — or a test
  * that wants to describe it — should not have to reproduce the resolution and
  * risk disagreeing with the loader about it. It performs I/O, and is named for
  * it, like the {@link findConfigFile} it calls twice.
@@ -58,7 +58,7 @@ export function resolveConfigFile({ cwd, moduleDir }?: {
  * worse than locating none — a reader would learn that some configuration
  * errors carry a position and could not predict which — so the path rides on
  * the error and every one of them is located here, at the boundary that knows
- * which file was read (#95).
+ * which file was read.
  *
  * The message keeps its body and gains the `file:line:column: error: ` prefix
  * every other finding in this build already uses, so nothing a reader has today
@@ -82,7 +82,7 @@ export function locateConfigError(err: unknown, configPath?: string): unknown;
  *   cannot write `import.meta.dirname`, and any absolute path it wrote instead
  *   would be one machine's — so authoring it is rejected rather than honoured.
  * - **`itemBuilders`** is a *name* (`sohl`) — or a list of names, for a tree
- *   feeding more than one system (#58) — resolved against the built-in
+ *   feeding more than one system — resolved against the built-in
  *   registries. A registry's name is the system it belongs to. A registry of a
  *   consumer's own is code, and code goes in an `.mjs` configuration.
  * - **`stats.systemVersion`** is derived from the adjacent `package.json` when
@@ -95,11 +95,11 @@ export function locateConfigError(err: unknown, configPath?: string): unknown;
  *
  * @param {unknown} data - The parsed configuration document.
  * @param {string} configPath - Absolute path of the file it was parsed from.
- * @returns {import("../config.mjs").ContentBuildConfig} The frozen configuration.
+ * @returns {import("../content-config.mjs").ContentBuildConfig} The frozen configuration.
  * @throws {Error} When the document is not a mapping, declares `rootDir`, or
  *   names an item-builder registry this package does not ship.
  */
-export function configFromData(data: unknown, configPath: string): import("../config.mjs").ContentBuildConfig;
+export function configFromData(data: unknown, configPath: string): import("../content-config.mjs").ContentBuildConfig;
 /**
  * The consuming repository's resolved, frozen configuration.
  *
@@ -108,12 +108,12 @@ export function configFromData(data: unknown, configPath: string): import("../co
  * configuration (#2). The result is memoised, so calling it in a default
  * parameter — the usual spelling here — costs one property read per call.
  *
- * @returns {import("../config.mjs").ContentBuildConfig} The frozen configuration.
+ * @returns {import("../content-config.mjs").ContentBuildConfig} The frozen configuration.
  * @throws {Error} When no configuration file can be found, or the one named
  *   cannot be loaded. Absence is a defect, not a fallback: without it the
  *   compilers know neither what to compile nor where to put it.
  */
-export function loadPackConfig(): import("../config.mjs").ContentBuildConfig;
+export function loadPackConfig(): import("../content-config.mjs").ContentBuildConfig;
 /**
  * The file {@link loadPackConfig} resolved the configuration from.
  *

package/types/engine/pack-router.d.mts

@@ -48,7 +48,7 @@ export class PackRoutingError extends Error {
  *
  * Deliberately close to the retired `package:` and deliberately not the same
  * word: `package:` said which *distribution* owned a note — now the
- * repository's `contentPackage`, and no longer authorable (#56) — while `pack:`
+ * repository's `contentPackage`, and no longer authorable — while `pack:`
  * says which *compendium* receives its document.
  */
 export const PACK_FIELD: "pack";

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

@@ -0,0 +1,42 @@
+/**
+ * The file name a downloaded book identifies itself by.
+ *
+ * The zip and the manifest take their names from the manifest, so an asset's
+ * name and its advertised URL cannot disagree. A PDF has no advertised URL, so
+ * its name is a free choice — which is exactly why it is fixed here rather than
+ * left for each of six consumers to invent.
+ *
+ * @param {string} artifact - The package's artifact name.
+ * @param {string} version - The version being released.
+ * @returns {string} `<artifact>-<version>.pdf`, or `<artifact>.pdf` unversioned.
+ */
+export function pdfFileName(artifact: string, version: string): string;
+/**
+ * Build the book.
+ *
+ * @param {object} [opts] - Options.
+ * @param {object} [opts.config] - A resolved configuration; loaded when absent.
+ * @param {string} [opts.out] - Where to write, overriding `pdf.out`.
+ * @param {string} [opts.version] - Stamped on the title page and the file name.
+ * @param {boolean} [opts.compile] - Whether to run Typst. False leaves the
+ *   `.typ` source, which is what the unit tests read.
+ * @returns {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.
+ */
+export function buildPdf({ config, out, version, compile }?: {
+    config?: object | undefined;
+    out?: string | undefined;
+    version?: string | undefined;
+    compile?: boolean | undefined;
+}): Promise<object>;
+/**
+ * Run Typst over the emitted source.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string} pdfPath - Where the PDF goes.
+ * @param {object} pdf - The resolved `pdf:` block.
+ * @returns {{ok: boolean, message: string}} What happened.
+ */
+export function compileTypst(typPath: string, pdfPath: string, pdf?: object): {
+    ok: boolean;
+    message: string;
+};

package/types/engine/pdf-fonts.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Every glyph name a font carries, with the codepoint that reaches it.
+ *
+ * @param {string} file - Path to a `.ttf`/`.otf`.
+ * @returns {Map<string, number>} Name → codepoint.
+ */
+export function glyphTable(file: string): Map<string, number>;
+/**
+ * The family name a font file announces, for Typst's `text(font: …)`.
+ *
+ * Read from the `name` table rather than from the file name, because the file
+ * is what a consumer happened to call it and the family is what the font stack
+ * will match on.
+ *
+ * @param {string} file - Path to a `.ttf`/`.otf`.
+ * @returns {string} The family name, or "" when the table cannot be read.
+ */
+export function familyName(file: string): string;
+/**
+ * Resolve every icon in a registry against the fonts a consumer named.
+ *
+ * @param {object} registry - The resolved `icons:` registry.
+ * @param {Record<string, string>} iconFonts - Family name → font file.
+ * @param {object[]} [findings] - Collected here rather than thrown.
+ * @returns {Map<string, {font: string, codepoint: number}>} Icon name → glyph.
+ */
+export function resolveIconGlyphs(registry: object, iconFonts?: Record<string, string>, findings?: object[]): Map<string, {
+    font: string;
+    codepoint: number;
+}>;

package/types/engine/pdf-render.d.mts

@@ -0,0 +1,144 @@
+/**
+ * Escape literal text for Typst markup.
+ *
+ * @param {string} text - Text as the author wrote it.
+ * @returns {string} The same text, inert.
+ */
+export function escapeTypst(text: string): string;
+/**
+ * Escape a string going inside Typst string quotes, as a `#link` URL does.
+ *
+ * @param {string} text - The raw value.
+ * @returns {string} The same value, quotable.
+ */
+export function escapeTypstString(text: string): string;
+/**
+ * A Typst label, from a plan anchor.
+ *
+ * Typst labels admit a narrower charset than an anchor does, so anything else
+ * folds to a hyphen. The plan already guarantees anchors are unique, and a fold
+ * that merged two of them would silently give one destination two meanings —
+ * so the fold is injective by construction: only characters Typst rejects move,
+ * and they move to a character the slugifier never emits twice in a row.
+ *
+ * @param {string} anchor - The plan's anchor.
+ * @returns {string} A Typst label name.
+ */
+export function labelFor(anchor: string): string;
+/**
+ * A markdown-it configured to parse, not to render.
+ *
+ * `html: false` is the load-bearing setting: raw HTML in a note has no route to
+ * Typst at all, which is why {@link module:engine/content-html} reports it. With
+ * HTML disabled markdown-it emits the tag as text, so it arrives in the book
+ * visibly wrong rather than invisibly missing.
+ *
+ * @param {object} [registry] - The icon registry.
+ * @returns {object} A markdown-it instance.
+ */
+export function createParser(registry?: object): object;
+/**
+ * Render markdown as Typst content.
+ *
+ * @param {string} markdown - The note's body, tables expanded and links resolved.
+ * @param {object} [opts] - Options.
+ * @param {object} [opts.md] - A parser from {@link createParser}, reused across
+ *   a whole book rather than rebuilt for each of 2,500 notes.
+ * @param {object} [opts.registry] - The icon registry, when no parser is passed.
+ * @param {Map<string, string>} [opts.links] - Address slug → plan anchor.
+ * @param {Map<string, string>} [opts.glyphs] - Icon name → `{font, char}`.
+ * @param {number} [opts.headingOffset] - Added to every heading level, so a
+ *   note's own `##` nests beneath the entry heading the book gave it.
+ * @param {string} [opts.anchorPrefix] - The entry's anchor, which namespaces
+ *   every `{#slug}` the body declares.
+ * @returns {string} Typst markup.
+ */
+export function markdownToTypst(markdown: string, opts?: {
+    md?: object | undefined;
+    registry?: object | undefined;
+    links?: Map<string, string> | undefined;
+    glyphs?: Map<string, string> | undefined;
+    headingOffset?: number | undefined;
+    anchorPrefix?: string | undefined;
+}): string;
+/**
+ * The whole book, as one Typst document.
+ *
+ * **Pure, and that is the point.** Everything a reviewer of #316 has to check
+ * about structure — the outline's shape, the anchors, which links went inward,
+ * the order entries print in — is decided here from a plan and a map of bodies,
+ * with no filesystem and no compiler. {@link module:engine/pdf-build} supplies
+ * both and runs Typst over the result.
+ *
+ * ## Two outlines, and why they are not the same outline
+ *
+ * A roster of 2,500 entries wants every entry reachable from a viewer's
+ * sidebar, and emphatically does not want all 2,500 printed in the front
+ * matter: that is forty pages of contents before the book starts.
+ *
+ * Typst separates the two for us. **The PDF bookmark outline is built from
+ * every heading**, so each entry gets its own node at its own depth for free
+ * and the sidebar is the navigational interface the issue asks for.
+ * **`#outline()` prints only to `tocDepth`**, so the paper table of contents
+ * stays the sections. Both are page-numbered and both are links.
+ *
+ * ## Headings carry the structure, so nothing else has to
+ *
+ * Every section, every prose file and every entry is a real Typst heading at
+ * its plan depth. That single decision supplies the bookmarks, the printed
+ * contents, the running heads and the page breaks at once — where drawing
+ * titles as styled text would have meant building all four by hand and keeping
+ * them agreeing with each other.
+ *
+ * @param {object} opts - Options.
+ * @param {object} opts.plan - From {@link module:engine/pdf-toc.planDocument}.
+ * @param {Map<string, string>} opts.bodies - Anchor → the entry's rendered
+ *   Typst body. An entry with no body prints its heading alone.
+ * @param {string} opts.title - The document's title.
+ * @param {string} [opts.subtitle] - Shown under it on the title page.
+ * @param {string[]} [opts.front] - Rendered Typst for each front-matter file.
+ * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names.
+ * @param {number} [opts.tocDepth] - How deep the *printed* contents go.
+ * @param {string} [opts.version] - Stamped on the title page when given.
+ * @returns {string} A complete `.typ` document.
+ */
+export function renderBook({ plan, bodies, title, subtitle, front, fonts, tocDepth, version, }?: {
+    plan: object;
+    bodies: Map<string, string>;
+    title: string;
+    subtitle?: string | undefined;
+    front?: string[] | undefined;
+    fonts?: object | undefined;
+    tocDepth?: number | undefined;
+    version?: string | undefined;
+}): string;
+/**
+ * Point every internal link at a label the document actually declares.
+ *
+ * **Typst refuses to compile a reference to a label that is not there.** That
+ * makes one mistyped `[[note#appearance]]`, or an anchor written inside a code
+ * fence where no heading is emitted, fatal to a 1,200-page book — and fatal at
+ * the very end, after everything else has succeeded. A reference book cannot
+ * have that failure mode: the link is the least important thing on the page and
+ * would be taking the other two thousand entries down with it.
+ *
+ * So references are reconciled against declarations before the source is
+ * written. A link to a section that does not exist falls back to the **entry**
+ * that would have contained it, which is where a reader wants to end up anyway;
+ * a link with no entry to fall back to becomes plain text. Both are reported.
+ *
+ * A declaration is a label not preceded by `#link(` — the only two places a
+ * label appears are the heading that declares one and the link that uses one.
+ *
+ * @param {string} source - The assembled Typst document.
+ * @param {object[]} [findings] - Collected here rather than thrown.
+ * @returns {string} The same document, with no reference left dangling.
+ */
+export function resolveDanglingLabels(source: string, findings?: object[]): string;
+/**
+ * Every icon name a body uses, so a build can resolve them once.
+ *
+ * @param {string} markdown - A note body.
+ * @returns {string[]} The names, in order of appearance, with repeats.
+ */
+export function iconNamesIn(markdown: string): string[];