@heroiclands/package-build 22.1.1 → 22.3.0

package/types/engine/ids.d.mts

@@ -148,6 +148,17 @@ export const MAP_SUBTYPES: readonly string[];
  * @type {ReadonlySet<string>}
  */
 export const JOURNAL_TYPES: ReadonlySet<string>;
+/**
+ * The `pack:` value that routes a note's document into no compendium.
+ *
+ * One reading, on the key that already decides which compendium receives a
+ * note: the note publishes to the site and compiles into nothing. Declared
+ * here, beside the pack table, so the configuration can refuse a pack of this
+ * name and the router can read the value from one spelling.
+ *
+ * @type {string}
+ */
+export const NO_PACK: string;
 /**
  * Content type → the pack its documents compile into, and the document type
  * that pack holds.

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

@@ -1,3 +1,19 @@
+/**
+ * Whether a note declares `pack: none` for one system's document.
+ *
+ * The same reading {@link createPackRouter}'s `resolve` applies: the system's
+ * block wins where it declares a pack, and the shared top-level value stands
+ * otherwise. Asked with no system, it reads the shared value alone, which is
+ * what every single-system build and the content index read.
+ *
+ * Pure, so the readers that never route — the Foundry-address pass, the link
+ * index, the unclaimed-type check — can ask it without a router.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} [system] - The system whose document is asked about.
+ * @returns {boolean} True when the answer for that document is `none`.
+ */
+export function declaresNoPack(fm: object, system?: string): boolean;
 /**
  * Build the router for one configured pack list.
  *
@@ -6,13 +22,13 @@
  *
  * @param {readonly object[]} packs - The resolved `packs` list from
  *   `defineConfig`.
- * @returns {{resolve: (fm: object, docType: string, system?: string) => string,
+ * @returns {{resolve: (fm: object, docType: string, system?: string) => string|undefined,
  *   resolveOrNull: (fm: object, docType: string, system?: string) => string|undefined,
  *   packsOfType: (docType: string) => string[],
  *   defaultOf: (docType: string) => string|undefined}} The router.
  */
 export function createPackRouter(packs: readonly object[]): {
-    resolve: (fm: object, docType: string, system?: string) => string;
+    resolve: (fm: object, docType: string, system?: string) => string | undefined;
     resolveOrNull: (fm: object, docType: string, system?: string) => string | undefined;
     packsOfType: (docType: string) => string[];
     defaultOf: (docType: string) => string | undefined;
@@ -52,3 +68,5 @@ export class PackRoutingError extends Error {
  * says which *compendium* receives its document.
  */
 export const PACK_FIELD: "pack";
+export { NO_PACK };
+import { NO_PACK } from "./ids.mjs";

package/types/engine/schema-check.d.mts

@@ -157,8 +157,8 @@ export function compareEmittedSystem({ system, artifact, documentType, subtype,
  * Two places to find it, because a system checks itself against source it owns
  * while a module checks against a dependency it fetched:
  *
- * - **A system**: its own `schema.json`, generated from its `src/` and
- *   committed beside it.
+ * - **A system**: its own `schema.json`, generated from its `src/` into
+ *   `build/` by `package-build schema`.
  * - **A module**: the copy cached by `content-build deps fetch`, from the
  *   archive of the version it pins — which is what makes the comparison happen
  *   at `verified` rather than against whatever the system's `main` holds today.
@@ -282,9 +282,9 @@ export function checkAuthoredSystemData(fm: object, { block, documentType, subTy
  * subtype declares.
  *
  * The build-time face of {@link compareEmittedSystem}: it resolves the schema
- * the way every other check here does — the system's own committed artifact, or
- * the cached one from the release a module pins — and attaches the message a
- * reader sees.
+ * the way every other check here does — the system's own published artifact,
+ * or the cached one from the release a module pins — and attaches the message
+ * a reader sees.
  *
  * **Silent where there is nothing to check against**, exactly as its two
  * siblings are: a module pinning a system version released before the artifact

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

@@ -1,19 +1,3 @@
-/**
- * Every `.md` file under `dir`, depth-first in directory order.
- *
- * Deliberately *not* {@link walkMarkdownTree}, whose stack-based walk yields a
- * tree in reverse. Order was load-bearing here when the address index carried
- * first-writer-wins fallbacks for a page's name, filename and slug — reversing
- * the walk silently changed which page an ambiguous name resolved to. Those
- * fallbacks are gone with the bare `[[Name]]` form, so this is now
- * ordinary reading order rather than a dependency; it is kept because a site's
- * emitted pages should not reorder for no reason.
- *
- * @param {string} dir - Directory to walk.
- * @param {readonly string[]} skip - Directory names to ignore at any depth.
- * @returns {string[]} Absolute paths.
- */
-export function walkSiteTree(dir: string, skip?: readonly string[]): string[];
 /**
  * The content tree's pages, and what could not be addressed.
  *
@@ -29,29 +13,6 @@ export function collectContentPages(contentBase: string, ctx: object): {
     addressFindings: object[];
     fmLinkFindings: object[];
 };
-/**
- * An extra tree's pages — a documentation tree published alongside the content.
- *
- * These preserve their **source layout** below the section rather than being
- * addressed by type and slug: they are a book with chapters, and a reader
- * follows their paths. A `README` is its directory's landing.
- *
- * **The section is the tree's, never the note's.** `tree.section` is the
- * mount point a `trees` entry configures — fixed, physical, and the same
- * value `site-index.mjs` indexes a tree page's address under. A note's own
- * `subType` is a genre and reaches no address, the same contract
- * `packageAddress()` holds for a content page: reading it here would move a
- * page's URL, its file destination (`pageDestination`) and the address a
- * wikilink cites it by, every time an author classified it.
- *
- * @param {object} tree - `{ from, rel, section, route }`.
- * @param {object} ctx - `{ mount }`.
- * @returns {{pages: object[], fmLinkFindings: object[]}}
- */
-export function collectTreePages(tree: object, ctx: object): {
-    pages: object[];
-    fmLinkFindings: object[];
-};
 /**
  * The package's homepage notes — the authored page at `/<contentPackage>/`.
  *
@@ -226,15 +187,8 @@ export function sectionFrontmatter(meta: object): object;
  * self-describing and makes sweeping the field out of a content tree
  * output-preserving for a site as it already is for the packs.
  *
- * A **tree** page is the one that still reads `readmeSections`: a `trees` entry
- * keeps its source layout below a named section, so its own `README` is that
- * section's landing and takes the title and hero the section declares.
- *
  * @param {object} page - The page.
  * @param {object} options
- * @param {Record<string, object>} [options.readmeSections] - The sections a
- *   published tree declares, which a tree page's own `README` is the landing
- *   for.
  * @param {(data: object, page: object) => void} [options.decorate] - Called
  *   with each page's frontmatter, for whatever a consumer's own pass adds.
  * @param {(value: unknown, type: string) => string|null} [options.artSrc] -
@@ -246,8 +200,7 @@ export function sectionFrontmatter(meta: object): object;
  *   same way.
  * @returns {object} The frontmatter to write.
  */
-export function pageFrontmatter(page: object, { readmeSections, decorate, webSrc, artSrc }: {
-    readmeSections?: Record<string, object> | undefined;
+export function pageFrontmatter(page: object, { decorate, webSrc, artSrc }: {
     decorate?: ((data: object, page: object) => void) | undefined;
     artSrc?: ((value: unknown, type: string) => string | null) | undefined;
     webSrc?: ((src: string) => string) | undefined;
@@ -267,12 +220,10 @@ export function pageFrontmatter(page: object, { readmeSections, decorate, webSrc
  * the same as another note's `type`, and `doc-gear.md` and `weapongear-gear.md`
  * are distinct whatever the sections.
  *
- * **A `trees` entry is the exception, and always was.** Those pages preserve
- * their source layout below a named section — they are a book with chapters,
- * addressed by their path — so a `README` there is still its directory's
- * `_index.md`.
+ * @param {object} page - The page.
+ * @returns {string} The file, relative to the mount.
  */
-export function pageDestination(page: any): string;
+export function pageDestination(page: object): string;
 /**
  * Renders and writes every page.
  *
@@ -283,10 +234,10 @@ export function pageDestination(page: any): string;
  *    authored as a fenced `dataview` block, which `protectCode` would otherwise
  *    stash away before the expander saw it. Expanding first leaves an ordinary
  *    markdown table to walk, with every other fence still protected.
- * 2. **Then, inside protection**: the consumer's `beforeLinks` pass, wikilink
- *    resolution, and the consumer's `afterLinks` pass. A `{@link}` tag may sit
- *    in prose a wikilink also touches, so the repository's own rewrites bracket
- *    the shared one rather than replacing it.
+ * 2. **Then, inside protection**: the consumer's `beforeLinks` pass, then
+ *    wikilink resolution. A `{@link}` tag may sit in prose a wikilink also
+ *    touches, so the repository's own rewrite runs before the shared one
+ *    rather than replacing it.
  *
  * @param {object[]} pages - Every page.
  * @param {object} options - Everything the render needs.
@@ -324,9 +275,9 @@ export function renderPages(pages: object[], options: object): {
  *   or its own address publishes nothing. Hugo generates a section page
  *   automatically only for a *top-level* content directory; below that, a
  *   directory without an `_index.md` is not a section, so its URL 404s while its
- *   children publish normally. With content pages flat, what that reaches is a
- *   `trees` entry's directory — the one thing left below the mount that a note
- *   creates.
+ *   children publish normally. With content pages flat, no note creates a
+ *   directory below the mount, so this reaches only what something else
+ *   placed there.
  *
  * **A section listing is not a page listing any more.** A layout that reads
  * `.Pages` off a section it declares here will find nothing, because no file is
@@ -373,11 +324,10 @@ export function pluralTitle(name: string): string;
  *
  * @param {string|undefined} name - The configured name.
  * @param {object} options - The configured options, plus `repoRoot`.
- * @returns {{beforeLinks?: Function, afterLinks?: Function}} The bundle.
+ * @returns {{beforeLinks?: Function}} The bundle.
  */
 export function resolveSitePass(name: string | undefined, options: object): {
     beforeLinks?: Function;
-    afterLinks?: Function;
 };
 /**
  * Builds a Hugo content tree from a content tree, and reports what it found.

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

@@ -89,7 +89,6 @@ export function resolveThemesDir(rootDir: string): string;
  *
  * @param {object} options - The sources.
  * @param {object} options.config - The resolved build configuration.
- * @param {string} [options.description] - `package.json`'s `description`.
  * @param {readonly NavigationEntry[]} options.navigation - The navigation.
  * @param {string} options.themesDir - From {@link resolveThemesDir}.
  * @param {boolean} [options.hasTags] - Whether any note the site build walked
@@ -97,11 +96,11 @@ export function resolveThemesDir(rootDir: string): string;
  *   `hasTags`. Defaults to `false` — no tagged note, no taxonomy pages.
  * @returns {Record<string, any>} The configuration Hugo reads.
  * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
- *   configuration declares no `packageBuild.manifest.title`.
+ *   configuration declares no `packageBuild.manifest.title`, no
+ *   `site.description`, or no `site.assets`.
  */
-export function hugoConfig({ config, description, navigation, themesDir, hasTags }: {
+export function hugoConfig({ config, navigation, themesDir, hasTags }: {
     config: object;
-    description?: string | undefined;
     navigation: readonly NavigationEntry[];
     themesDir: string;
     hasTags?: boolean | undefined;
@@ -116,10 +115,9 @@ export function hugoToml(generated: Record<string, unknown>): string;
 /**
  * The Hugo configuration, every source read from the repository.
  *
- * Reads `package.json`, the cached navigation and the installed theme's
- * location, and composes them with {@link hugoConfig}. Nothing is written, so
- * a caller can run this before touching the output tree and fail with it
- * intact.
+ * Reads the cached navigation and the installed theme's location, and
+ * composes them with {@link hugoConfig}. Nothing is written, so a caller can
+ * run this before touching the output tree and fail with it intact.
  *
  * @param {object} config - The resolved build configuration.
  * @param {object} [options] - Options.

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

@@ -94,9 +94,9 @@ export function resolveInfoboxRef(siteIndex: SiteIndex, ref: unknown, hint?: obj
 export type SiteEntry = {
     /**
      * `"content"` for a note compiled from the content
-     * tree, anything else for a page that carries no
-     * `type`/`shortcode` (a developer doc, say). Only
-     * content entries take part in type-scoped indexing.
+     * tree. Only content entries take part in
+     * type-scoped indexing; anything else is carried
+     * through unindexed.
      */
     kind: string;
     /**
@@ -111,13 +111,6 @@ export type SiteEntry = {
      * URL segment.
      */
     slug: string;
-    /**
-     * The Hugo section a **tree** page is filed under, and
-     *   the first segment of the `<sec>/<slug>` address it
-     *   is reachable by. A content page has none: it is
-     *   addressed by `(type, shortcode)` and emitted flat.
-     */
-    sec?: string | undefined;
     /**
      * Source file's basename, e.g. `Climbing.md`.
      */
@@ -126,11 +119,6 @@ export type SiteEntry = {
      * The page's published address.
      */
     url: string;
-    /**
-     * Whether a tree page is its directory's
-     * landing.
-     */
-    isReadme?: boolean | undefined;
 };
 /**
  * The resolved index and everything a wikilink resolver reads beside it.
@@ -157,10 +145,6 @@ export type SiteIndex = {
      * an address qualifier, local and foreign.
      */
     contentTypes: Set<string>;
-    /**
-     * Section names, lowercased.
-     */
-    sections: Set<string>;
     /**
      *                                       `type:shortcode` → page, for callers
      *                                       resolving embedded references (a
@@ -171,13 +155,4 @@ export type SiteIndex = {
         url: string;
         subType?: string;
     }>;
-    /**
-     * Addresses claimed by
-     * more than one package. Non-empty is a
-     * build failure; the caller reports it.
-     */
-    conflicts: {
-        key: string;
-        package: string;
-    }[];
 };

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

@@ -77,7 +77,7 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  * for the website, and what the book reads its staging list out of.
  *
  * @param {string} body - The markdown body.
- * @param {object} ctx - `{ index, assets, collide, sections, contentTypes,
+ * @param {object} ctx - `{ index, assets, collide, contentTypes,
  *   packages, noIndexPackages, foreign, type, errors, src, file }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type;

package/types/engine/wikilinks.d.mts

@@ -122,12 +122,14 @@ 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,
- *   name?: string, pack?: string, docPack?: string,
+ *   name?: string, pack?: string, docPack?: string, none?: boolean,
  *   draft?: boolean}>} 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. `draft` says the note carries the `draft`
- *   tag, which marks links *into* it and changes nothing else.
+ *   one-pack-per-type names stand in. `none` says the note declares
+ *   `pack: none` and compiles into no document, so it has no UUID to link to.
+ *   `draft` says the note carries the `draft` tag, which marks links *into* it
+ *   and changes nothing else.
  * @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
@@ -153,6 +155,7 @@ export function buildWikilinkIndex(docs: Array<{
     name?: string;
     pack?: string;
     docPack?: string;
+    none?: boolean;
     draft?: boolean;
 }>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets, noIndexPackages }?: {
     assets?: Map<string, object> | undefined;

package/types/manifest.d.mts

@@ -187,11 +187,13 @@ export function publishedRelationships(relationships: Record<string, unknown>):
  * Three kinds of key end up in the result:
  *
  * - **Declared** — everything in `packageBuild.manifest`, emitted unchanged, so
- *   a key Foundry adds later needs no release of this package.
+ *   a key Foundry adds later needs no release of this package. The one
+ *   exception is `descriptionHtml`, folded into the description below rather
+ *   than surviving under its own name.
  * - **Derived** — the identity, the description, the release addresses, the
  *   version, the Foundry and system compatibility ranges, and the pack list.
- *   These are refused if also declared: an authored copy would be overwritten
- *   and the two would disagree with nothing to say so.
+ *   These are refused if also declared (`description` directly; `descriptionHtml`
+ *   is how it is authored) and the two would disagree with nothing to say so.
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *

package/types/release.d.mts

@@ -18,14 +18,14 @@
  * @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,
- *   pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   schema?: string, 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`.
+ *   `metadata` is absent when the manifest advertises no content index,
+ *   `schema` is absent when the stage carries no `schema.json`, 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.
  */
@@ -39,6 +39,7 @@ export function packRelease({ stageDir, outDir, artifact, metadataDir, pdf, }?:
     zip: string;
     manifest: string;
     metadata?: string;
+    schema?: string;
     pdf?: string;
     pdfFindings: object[];
     pdfSkipped: string | null;

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

@@ -17,59 +17,28 @@
  * @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.
+ * A pass bundle is the hook the page renderer calls before wikilink
+ * resolution: `beforeLinks` runs on every page, before wikilinks resolve,
+ * because a `{@link}` tag may sit inside prose a wikilink also touches. It
+ * runs inside code-fence protection, so it cannot rewrite a fenced example.
  *
  * @param {object} options - Resolved from `site.passOptions`.
  * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map,
  *   relative to `repoRoot`. Absent means no API links; present and unusable is
  *   a build failure.
  * @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.
+ * @returns {{beforeLinks: Function}} The bundle.
  * @throws {Error} When a configured `symbolMap` cannot be resolved, read,
  *   parsed, or is not a name → page object.
  */
 export function sohlKbPass(options: {
     symbolMap?: string | undefined;
     apiBase?: string | undefined;
-    blob?: string | undefined;
     repoRoot: string;
 }): {
     beforeLinks: Function;
-    afterLinks: Function;
 };