@heroiclands/package-build 20.4.0 → 20.6.0

package/engine/helpers.mjs

@@ -130,24 +130,6 @@ export function parseMarkdownFile(filePath) {
     return { frontmatter, body, description, bodyLine, bodyColumn };
 }
 
-/**
- * Recursively yields every `.md` file under `rootDir`, parsed.
- * Yields `{ frontmatter, body, description, file, absPath, bodyLine,
- * bodyColumn }` for each match — the last two from
- * {@link parseMarkdownFile}, so a caller can report a position inside the
- * body as a position in the file.
- * Silently skips directories that don't exist.
- *
- * Directory names in `skipDirectories` are ignored wherever they appear. The
- * walk itself knows nothing about what they mean: `Templates/` is an Obsidian
- * templater convention this repository's vault happens to use, not a property
- * of a content tree, so it is configured rather than hard-coded.
- *
- * @param {string} rootDir - Root of the tree to walk.
- * @param {object} [opts]
- * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
- *   Defaults to the configured list.
- */
 /**
  * Refuse a corpus read whose scope its caller did not state.
  *
@@ -203,6 +185,31 @@ export function assertSuppliedCorpus(records, who) {
     }
 }
 
+/**
+ * Recursively yields every `.md` file under `rootDir`, parsed.
+ *
+ * Yields `{ frontmatter, body, description, file, absPath, bodyLine,
+ * bodyColumn }` for each match — the last from {@link parseMarkdownFile}, so a
+ * caller can report a position inside the body as a position in the file. A
+ * root that does not exist yields nothing, and a directory that cannot be read
+ * is warned about and skipped.
+ *
+ * Directory names in `skipDirectories` are ignored wherever they appear. The
+ * walk itself knows nothing about what they mean: `Templates/` is an Obsidian
+ * templater convention this repository's vault happens to use, not a property
+ * of a content tree, so it is stated by the caller rather than hard-coded.
+ *
+ * @param {string} rootDir - Root of the tree to walk.
+ * @param {object} opts
+ * @param {readonly string[]} opts.skipDirectories - Directory names to ignore.
+ *   Required: the scope is the caller's to state, so two passes cannot
+ *   disagree about which files are the corpus.
+ * @yields {{frontmatter: object|null, body: string, description: string,
+ *   file: string, absPath: string, bodyLine?: number, bodyColumn?: number}}
+ *   One entry per `.md` file found.
+ * @throws {Error} When `skipDirectories` is not stated — see
+ *   {@link assertStatedScope}.
+ */
 export function* walkMarkdownTree(rootDir, { skipDirectories } = {}) {
     // Stated by the caller, never resolved here. A default here
     // — `loadPackConfig().skipDirectories` — read whichever configuration
@@ -415,11 +422,6 @@ export function makeFilename(name, id) {
     return `${unidecode(name)}_${id}`.replace(/[^0-9a-zA-Z]+/g, "_") + ".json";
 }
 
-/**
- * Standardize a name into a slug: lowercase, apostrophes removed,
- * non-alphanumerics collapsed to single hyphens.
- */
-
 /**
  * The path prefixes that name a package other than the one being compiled.
  *
@@ -537,11 +539,19 @@ function addressesAnotherPackage(s) {
  * `itemArt()`, which runs the path back through this function so a registry
  * entry and a note's `img:` are spelled the same way (#7).
  *
+ * **A package with no asset root cannot answer at all.** `assetRoot` is derived
+ * from the package kind, and a `documentation` package has none: Foundry serves
+ * no files for it. Only a compiling pass reaches here, and a documentation
+ * package runs none, so a path arriving with no root to put it under is a pass
+ * running where it should not — reported as that, rather than emitted as
+ * `null/icons/relic.svg` into a document nobody would check.
+ *
  * @param {string | null | undefined} raw - content-relative path from frontmatter.
- * @param {{assetRoot: string}} [config] - The resolved build configuration.
+ * @param {{assetRoot: string|null}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
  * @returns {string | null} the Foundry-relative path; `""` for a deliberate
  *   blank, and `null` when the note names no art at all.
+ * @throws {Error} When the configuration has no asset root.
  */
 export function resolveImg(raw, config = loadPackConfig()) {
     // Unset — the caller's default applies. An absent key arrives as
@@ -552,6 +562,14 @@ export function resolveImg(raw, config = loadPackConfig()) {
     if (s === "") return "";
     // Somebody else's to serve — emit it exactly as authored.
     if (addressesAnotherPackage(s)) return s;
+    if (!config.assetRoot) {
+        throw new Error(
+            `package-build: \`${s}\` names a file this package serves, and a ` +
+                `\`documentation\` package has no asset root to serve it from — ` +
+                `Foundry installs no such package. Address the owning package ` +
+                `(\`systems/…\`, \`modules/…\`) or a URL.`,
+        );
+    }
     // Ours, so root it where Foundry serves this package's files from.
     return `${config.assetRoot}/${s}`;
 }
@@ -689,6 +707,13 @@ export function defaultStats() {
     return cachedDefaultStats;
 }
 
+// The one slug rule, re-exported so callers keep a single import path.
+/**
+ * Standardize a name into a slug: lowercase, apostrophes removed,
+ * non-alphanumerics collapsed to single hyphens.
+ */
+export { slugify } from "./content-slug.mjs";
+
 /**
  * Stable 16-char hex id derived from `${namespace}:${value}`.
  *
@@ -696,9 +721,6 @@ export function defaultStats() {
  * resolver this one imports can derive ids too — and re-exported here for the
  * passes that have always reached it through `helpers`.
  */
-// The one slug rule, re-exported so callers keep a single import path.
-export { slugify } from "./content-slug.mjs";
-
 export { makeId } from "./ids.mjs";
 
 // The content-type → document-type map, which decides *which* pack list a
@@ -730,6 +752,15 @@ import { collectAnchors } from "./anchors.mjs";
  * @param {object} [router] - The pack router. Supplied by the calling pass so
  *   the index and the compile agree about where each note landed; defaults to
  *   this repository's own.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Part of the options bag
+ *   every corpus reader takes; the scope is already settled by `records`.
+ * @param {object} [opts.config] - The resolved build configuration; loaded when
+ *   omitted.
+ * @param {readonly object[]} [opts.records] - The corpus, derived once per
+ *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
+ * @param {object[]} [opts.problems] - Part of the same options bag; the notes
+ *   the index cannot record are collected where the corpus is derived.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
 export function buildContentLinkIndex(
@@ -827,11 +858,21 @@ export function buildContentLinkIndex(
  * inventing a position.
  *
  * @param {string} body - The note's markdown body, tables already expanded.
- * @param {object} ctx - `{ type, id, pack, docPack, index, name }` — `name` is
- *   used in the message, and the two pack names address a `[[#slug]]`
- *   self-link, whose target is the source note itself and so has no index
- *   entry. Position is carried by `{ file, bodyLine, bodyColumn, lineMap }`,
- *   the last from {@link expandNoteTables}.
+ * @param {object} ctx
+ * @param {string} ctx.type - The source note's content type.
+ * @param {string} ctx.id - The source note's document id.
+ * @param {string} ctx.pack - The pack the note's own document lands in, which
+ *   addresses a `[[#slug]]` self-link: its target is the source note itself, so
+ *   it has no index entry.
+ * @param {string} ctx.docPack - The pack the note's documentation journal lands
+ *   in, addressing a self-link the same way.
+ * @param {object} ctx.index - The address index every link resolves through.
+ * @param {string} ctx.name - The note, for the message.
+ * @param {string} [ctx.file] - The note's file, so a report names it.
+ * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line.
+ * @param {number} [ctx.bodyColumn] - 1-based file column of the same character.
+ * @param {Array<{line: number, generated: boolean}>} [ctx.lineMap] - Which
+ *   authored line each body line came from, from {@link expandNoteTables}.
  * @returns {{markdown: string, unresolved: Array<object>}}
  * @throws {Error} On any link that does not resolve — an unlabelled one, a
  *   target that is not an address, or an address nothing publishes. The error
@@ -908,6 +949,15 @@ export function convertNoteWikilinks(
  * a table that leaves rows tied still emits identically on every build.
  *
  * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Part of the options bag
+ *   every corpus reader takes; the scope is already settled by `records`.
+ * @param {object} [opts.config] - The resolved build configuration; loaded when
+ *   omitted.
+ * @param {readonly object[]} [opts.records] - The corpus, derived once per
+ *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
+ * @param {object[]} [opts.problems] - Part of the same options bag; the notes
+ *   the walk cannot read are collected where the corpus is derived.
  * @returns {Array<{fm: object, path: string, tld: string, folder: string,
  *   absPath: string}>}
  */
@@ -972,6 +1022,10 @@ const packLinkable = (doc) => Boolean(doc.fm?.shortcode) && Boolean(doc.fm?.type
  *   query's `this` reads. Its entry in `docs` supplies the path as well.
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line,
  *   so a failing directive can be reported at its position in the file.
+ * @param {object[]} [ctx.sqlTables] - This note's prepared `sql` results, in
+ *   document order, from
+ *   {@link module:engine/sql-tables.prepareSqlTables}. An `sql` directive with
+ *   no prepared result fails the note: nothing here runs a query.
  * @returns {{markdown: string, lineMap: Array<{line: number,
  *   generated: boolean}>}} The body with every table expanded, and where each
  *   emitted line came from — which is what lets a diagnostic about the

package/engine/index.mjs

@@ -87,8 +87,6 @@ export * as noteVocabulary from "./note-vocabulary.mjs";
 /** The closed registry of system ids, and the `none` that stands for no system. */
 export * as systems from "./systems.mjs";
 
-/** The shipped Foundry manifest: locating it, reading it, guarding its id. */
-
 /** The one normalisation this build makes: prose to a URL-safe token. */
 export * as contentSlug from "./content-slug.mjs";
 
@@ -158,6 +156,18 @@ export * as wikilinkSyntax from "./wikilink-syntax.mjs";
 /** The address index a site build resolves its wikilinks against. */
 export * as siteIndex from "./site-index.mjs";
 
+/** The document tree a book selects, and the plan it resolves to. */
+export * as pdfToc from "./pdf-toc.mjs";
+
+/** Markdown and a plan, rendered as Typst source. Pure. */
+export * as pdfRender from "./pdf-render.mjs";
+
+/** Which glyph an icon name resolves to, read from the font that carries it. */
+export * as pdfFonts from "./pdf-fonts.mjs";
+
+/** The content tree, built into a book. Reads the tree; runs the compiler. */
+export * as pdfBuild from "./pdf-build.mjs";
+
 /** The shape every pack compiler shares. */
 export * as baseCompiler from "./base-compiler.mjs";
 

package/engine/journals.mjs

@@ -303,6 +303,15 @@ export function buildJournalEntry({
     };
 }
 
+/**
+ * Journals pack compiler.
+ *
+ * Walks the content tree and compiles every `type: doc` note, and every note of
+ * a doc-carrying type, into one JournalEntry document: the body split into
+ * pages on its top-level H1 headings, each rendered to HTML. A doc-carrying
+ * note's entry is that document's documentation, filed in the document's own
+ * folder.
+ */
 export class Journals extends BasePackCompiler {
     static id = "journals";
     static label = "journal";

package/engine/note-claims.mjs

@@ -111,6 +111,23 @@ import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
  */
 export const NEVER_PACKED_TYPES = Object.freeze(new Set([HOMEPAGE_TYPE]));
 
+/**
+ * The whole note vocabulary of a package that compiles no Foundry documents.
+ *
+ * Every other type in the vocabulary exists to *become* a document: a `skill` is
+ * an Item, a `being` an Actor, a `place` a JournalEntry, a `folder` the Folder
+ * they are filed under. In a `documentation` package none of them has a
+ * destination, so a note carrying one would be authored, validated, walked and
+ * then published as a page of something that was meant to be a compendium
+ * entry — the plausible-looking result that reads as success.
+ *
+ * `doc` is prose whose single document *is* the prose, and `homepage` is the
+ * authored front page every package publishes. Both are already pages first.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const DOCUMENTATION_NOTE_TYPES = Object.freeze(new Set(["doc", HOMEPAGE_TYPE]));
+
 /**
  * Content types the specification states and this toolchain does not yet
  * compile.
@@ -229,10 +246,7 @@ function mappingSystems(maps, type) {
  * pack from appearing to answer for any note.
  *
  * @param {string} docType - The Foundry document type a pack holds.
- * @param {ClaimSources} [sources] - What to answer from.
- * @param {object} [opts] - Options.
- * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above. Defaults to the
+ * @param {ClaimSources} [sources] - What to answer from. Defaults to the
  *   configured registries and the systems this toolchain ships.
  * @returns {ReadonlySet<string>} The note types such a pass would claim.
  */
@@ -403,9 +417,6 @@ function noteHasProse(absPath) {
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
  * @param {ClaimSources} [sources] - What to answer from.
- * @param {object} [opts] - Options.
- * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above.
  * @returns {ReadonlySet<string>} The claimed note types.
  */
 export function claimedNoteTypes(config = loadPackConfig(), sources) {
@@ -427,9 +438,6 @@ export function claimedNoteTypes(config = loadPackConfig(), sources) {
  * declare on top.
  *
  * @param {ClaimSources} [sources] - What to answer from.
- * @param {object} [opts] - Options.
- * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above.
  * @returns {ReadonlySet<string>} The vocabulary.
  */
 export function noteTypeVocabulary(sources) {

package/engine/note-schemas.mjs

@@ -34,11 +34,6 @@
 
 import { HOMEPAGE_FIELDS, HOMEPAGE_TYPE } from "./homepage.mjs";
 
-/**
- * Every engine-level content type, and what a note of that type may write.
- *
- * @type {Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>}
- */
 /**
  * A note that compiles to a JournalEntry and nothing else.
  *

package/engine/note-vocabulary.mjs

@@ -53,8 +53,8 @@
  * have swept.
  *
  * **A type name and a subType value are held to the address charset**, so
- * both are `^[A-Za-z0-9]+$` — the charset `engine/address-charset.mjs` states
- * and the shortcode is already held to. For a type that is literal: it is a
+ * both match `ADDRESS_SEGMENT_PATTERN` — the charset `engine/address-charset.mjs`
+ * states and the shortcode is already held to. For a type that is literal: it is a
  * segment of every address — the first of the short form an author writes
  * (`type-shortcode`), the third of the canonical
  * `package-system-type-shortcode` — the hyphen is the separator between
@@ -223,17 +223,20 @@ const CHARGES = Object.freeze([
 /* --------------------------------------------------------------------- */
 
 /**
- * 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.
  *
@@ -260,21 +263,6 @@ const CHARGES = Object.freeze([
  * 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**.
- *
- * 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 = Object.freeze({
     /** What a place *is*. */
     placeKind: Object.freeze({
@@ -413,6 +401,18 @@ export function isDraftNote(fm) {
     return hasTag(fm, DRAFT_TAG);
 }
 
+/**
+ * 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 = Object.freeze({
     /* ----- actors --------------------------------------------------- */
 
@@ -793,12 +793,13 @@ export const NOTE_VOCABULARY = Object.freeze({
     /* ----- core documents ------------------------------------------- */
 
     doc: Object.freeze({
-        // `userguide`, not `user-guide`: a subType is held to the address
-        // charset, and a segment carries no hyphen. The old spelling was
-        // accepted transitionally for one release so the consumer trees could
-        // sweep; they have, so it is refused by the charset check now, with no
-        // retirement-specific code left over.
-        subTypes: Object.freeze(["rules", "userguide", "reference"]),
+        // Five genres, and a genre is all this field carries: what kind of page
+        // it is, never who reads it. An audience term alongside them would give
+        // a developer how-to two valid values and no rule for choosing.
+        //
+        // `userguide` and `howto`, not `user-guide` and `how-to`: a subType is
+        // held to the address charset, and a segment carries no hyphen.
+        subTypes: Object.freeze(["rules", "userguide", "reference", "howto", "concept"]),
         data: Object.freeze([]),
     }),
 

package/engine/pack-config.mjs

@@ -104,7 +104,7 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import YAML from "yaml";
 
-import { defineConfig, DERIVED_SYSTEM_VERSION } from "../content-config.mjs";
+import { defineConfig, DERIVED_SYSTEM_VERSION, DOCUMENTATION_KIND } from "../content-config.mjs";
 import {
     emitDiagnostic,
     formatDiagnostic,
@@ -513,7 +513,7 @@ export function locateConfigError(err, configPath) {
  *
  * @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.
  */
@@ -541,14 +541,19 @@ export function configFromData(data, configPath) {
     // Every consumer's copy matched exactly, which is what a transcription
     // looks like right up until it does not (a transcribed one freezes
     // four releases while nothing said so).
-    if (input.foundryPackage !== undefined) {
-        throw new Error(
-            `package-build: ${configPath} declares \`foundryPackage\`, which ` +
-                `a data configuration may not: it is the \`name\` of the ` +
-                `\`package.json\` beside it. Remove the key.`,
-        );
+    // A documentation package has no Foundry package, so there is no id to
+    // derive: the validator refuses the key by name, with a locator, and
+    // deriving one here would hand it the very key it is about to refuse.
+    if (input.packageKind !== DOCUMENTATION_KIND) {
+        if (input.foundryPackage !== undefined) {
+            throw new Error(
+                `package-build: ${configPath} declares \`foundryPackage\`, which ` +
+                    `a data configuration may not: it is the \`name\` of the ` +
+                    `\`package.json\` beside it. Remove the key.`,
+            );
+        }
+        input.foundryPackage = foundryPackageId(rootDir);
     }
-    input.foundryPackage = foundryPackageId(rootDir);
 
     if (input.itemBuilders !== undefined) {
         const declared = input.itemBuilders;
@@ -590,7 +595,16 @@ export function configFromData(data, configPath) {
     }
 
     const stats = input.stats;
-    if (stats !== null && typeof stats === "object" && !Array.isArray(stats)) {
+    // Skipped for a documentation package, which stamps no `_stats` and
+    // declares no system to take a version from: the derivation would throw a
+    // bare error about a missing system relationship, burying the located
+    // refusal of the `stats:` key that is the finding an author needs.
+    if (
+        input.packageKind !== DOCUMENTATION_KIND &&
+        stats !== null &&
+        typeof stats === "object" &&
+        !Array.isArray(stats)
+    ) {
         const declared = /** @type {Record<string, unknown>} */ (stats);
         // `stats.systemId` and `stats.systemVersion` are both refused by
         // `defineConfig`, which reports them with a locator — so nothing is
@@ -620,7 +634,7 @@ export function configFromData(data, configPath) {
  * Load an `.mjs` configuration — one that called `defineConfig` itself.
  *
  * @param {string} configPath - Absolute path of the file.
- * @returns {import("../config.mjs").ContentBuildConfig} What it exported.
+ * @returns {import("../content-config.mjs").ContentBuildConfig} What it exported.
  * @throws {Error} When its module graph uses top-level `await`, which a
  *   synchronously-read configuration cannot.
  */
@@ -662,7 +676,7 @@ let loadedFrom;
  * 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.