@heroiclands/package-build 22.4.6 → 22.5.0

package/engine/stub-lint.mjs

@@ -0,0 +1,237 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * An empty body must be deliberate.
+ *
+ * An empty body is what makes a note a **stub**, and the whole scheme turns on
+ * that being on purpose rather than something somebody forgot. So four rules
+ * hold the state honest, and two more report what the rules cannot decide:
+ *
+ * 1. **A stub states what it is.** With nothing in the body, the `description`
+ *    is the only sentence a reader gets and it is what every table and index
+ *    prints. An **error**.
+ * 2. **A stub is not tagged `draft`.** A thing not started is not a thing in
+ *    progress. An **error**.
+ * 3. **A body that renders to nothing is an abandoned draft, not a stub.** This
+ *    is what keeps the empty-body rule's severity honest: the softer cases are
+ *    *reported* rather than silently treated as one state or the other. An
+ *    **error**.
+ * 4. **A short unmarked body may be a draft that forgot its marker.** A
+ *    **warning**, never an error — a note reading `See [[affiliation-meivor|Mëivōr]]`
+ *    says everything it has to say, and a corpus holds many of them.
+ * 5. **A long-standing draft is a report, not a finding.** It is unfinished,
+ *    which the tag already says, so the oldest are listed and nobody is asked
+ *    to dismiss a warning they cannot clear.
+ * 6. **The counts are reported**, per package and per type, so the ratio of
+ *    written to unwritten is visible on every run rather than discovered in a
+ *    year.
+ *
+ * **What this does not decide is what earns a body.** Whether a given village
+ * deserves prose is a question about a setting, and it belongs in the
+ * repository that ships it. The toolchain's job is to make promotion free.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { authoredFrontmatter, isNoteRecord, isStub, noteFile } from "./index-records.mjs";
+import { positionInFrontmatter, positionOfLiteral } from "./diagnostics.mjs";
+import { parseMarkdownFile } from "./helpers.mjs";
+import { bodyWordCount, isStubNote, placeholderBody } from "./note-state.mjs";
+import { isDraftNote } from "./note-vocabulary.mjs";
+
+/**
+ * The word count below which an unmarked body is asked whether it is a draft.
+ *
+ * A threshold, so it is a value the rule *is* rather than a census: twenty-five
+ * words is about two sentences, which is where a note stops reading as a
+ * statement and starts reading as a beginning.
+ *
+ * @type {number}
+ */
+export const SHORT_BODY_WORDS = 25;
+
+/** How many of the oldest drafts the report names. */
+const OLDEST_DRAFTS = 10;
+
+/**
+ * Whether a note states a description.
+ *
+ * @param {Record<string, any>} fm - The note's authored frontmatter.
+ * @returns {boolean} Whether `description` carries a sentence.
+ */
+function hasDescription(fm) {
+    return String(fm?.description ?? "").trim() !== "";
+}
+
+/**
+ * Check one note's state, and say where the fault is.
+ *
+ * @param {object} note - `{ fm, body, file, raw }`.
+ * @returns {object[]} The findings.
+ */
+function checkNote({ fm, body, file, raw }) {
+    const findings = [];
+    const at = (key, value) => positionInFrontmatter(raw, key, value, { topLevel: true });
+
+    if (isStubNote(fm, body)) {
+        if (!hasDescription(fm)) {
+            findings.push({
+                file,
+                ...at("type", fm.type),
+                severity: "error",
+                message:
+                    "this note has no body, so it is a stub — and a stub carries " +
+                    "a `description`, which is the only sentence a reader gets " +
+                    "and what every table listing it prints",
+            });
+        }
+        if (isDraftNote(fm)) {
+            findings.push({
+                file,
+                ...at("type", fm.type),
+                severity: "error",
+                message:
+                    "this note has no body and is tagged `draft`, and a thing " +
+                    "not started is not a thing in progress — remove the tag, " +
+                    "or write a body",
+            });
+        }
+        return findings;
+    }
+
+    const placeholders = placeholderBody(body);
+    if (placeholders.length) {
+        const [{ phrase }] = placeholders;
+        findings.push({
+            file,
+            ...positionOfLiteral(raw, phrase),
+            severity: "error",
+            message:
+                `this note's body says only "${phrase}", so it publishes a page ` +
+                `that tells a reader nothing — empty the body to make this a ` +
+                `stub, or write it`,
+        });
+        return findings;
+    }
+
+    if (!isDraftNote(fm)) {
+        const words = bodyWordCount(body);
+        if (words > 0 && words < SHORT_BODY_WORDS) {
+            findings.push({
+                file,
+                ...at("type", fm.type),
+                severity: "warning",
+                message:
+                    `this note's body is ${words} word(s) and carries no \`draft\` ` +
+                    `tag — tag it if it is a beginning, and leave it alone if it ` +
+                    `says everything it has to say`,
+            });
+        }
+    }
+    return findings;
+}
+
+/**
+ * The state of every note in a tree, checked and counted.
+ *
+ * Read from the content index rather than from a walk of this pass's own, like
+ * every other lint: the command derives the corpus once and hands it to each
+ * pass, so no two findings are drawn from different ideas of which files the
+ * content is. The **body** is read from the file, because the index carries
+ * what is *about* a note and never the note's text.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} opts
+ * @param {readonly object[]} opts.records - Index records the caller derived.
+ * @param {string} [opts.contentPackage] - Named in the counts line.
+ * @returns {{findings: object[], counts: {full: number, draft: number,
+ *   stub: number}, byType: Array<{type: string, full: number, draft: number,
+ *   stub: number}>, oldestDrafts: Array<{file: string, modified: Date}>,
+ *   summary: string[]}} The findings, the ladder's counts, and the lines a
+ *   reader is shown as prose rather than as findings.
+ */
+export function lintNoteStates(contentBase, { records, contentPackage } = {}) {
+    const findings = [];
+    const counts = { full: 0, draft: 0, stub: 0 };
+    /** @type {Map<string, {full: number, draft: number, stub: number}>} */
+    const byType = new Map();
+    /** @type {Array<{file: string, modified: Date}>} */
+    const drafts = [];
+
+    for (const record of records ?? []) {
+        // A documentation journal and an asset are documents rather than notes,
+        // so neither has a state. A note with no `type` — vault scaffolding, a
+        // README — does: it publishes no page, which is what a stub is, and
+        // counting it here is what keeps this line and the index's own agreeing
+        // with `SELECT state, count(*) FROM entries`. What it has no frontmatter
+        // for is the **rules**, which are skipped below.
+        if (!isNoteRecord(record)) continue;
+        const absPath = noteFile(contentBase, record);
+        const file = path.relative(process.cwd(), absPath);
+        const fm = authoredFrontmatter(record);
+        const { body } = parseMarkdownFile(absPath);
+        const raw = fs.readFileSync(absPath, "utf8");
+
+        // The ladder, read exactly as the `entries` view reads it: the absent
+        // address is the state, not a second body test beside it. A note with
+        // no `type` and no `shortcode` has no address whatever its body says,
+        // and calling it anything else here would make this line disagree with
+        // `SELECT state, count(*) FROM entries` — two ladders, one corpus.
+        const state =
+            isStub(record) ? "stub"
+            : isDraftNote(fm) ? "draft"
+            : "full";
+        counts[state] += 1;
+        // Vault scaffolding is counted under a name rather than under
+        // "undefined", so the per-type table reads as a sentence.
+        const type = record.type ? String(record.type) : "(no type)";
+        if (!byType.has(type)) byType.set(type, { full: 0, draft: 0, stub: 0 });
+        byType.get(type)[state] += 1;
+        if (state === "draft") drafts.push({ file, modified: fs.statSync(absPath).mtime });
+
+        // Held to the rules only where there is a note to hold: a file that
+        // declares no type declares nothing for them to read, and asking it for
+        // a `description` would report vault scaffolding as content.
+        if (record.type) findings.push(...checkNote({ fm, body, file, raw }));
+    }
+
+    const oldestDrafts = drafts
+        .sort((a, b) => a.modified.getTime() - b.modified.getTime())
+        .slice(0, OLDEST_DRAFTS);
+
+    const total = counts.full + counts.draft + counts.stub;
+    const summary = [
+        `${contentPackage ?? "this package"}: ${total} notes — ` +
+            `${counts.full} full, ${counts.draft} draft, ${counts.stub} stub.`,
+    ];
+    if (oldestDrafts.length) {
+        summary.push(
+            `The drafts nothing has touched in longest: ` +
+                `${oldestDrafts.map((d) => d.file).join(", ")}.`,
+        );
+    }
+
+    return {
+        findings,
+        counts,
+        byType: [...byType]
+            .map(([type, c]) => ({ type, ...c }))
+            .sort((a, b) => b.full + b.draft + b.stub - (a.full + a.draft + a.stub)),
+        oldestDrafts,
+        summary,
+    };
+}

package/engine/wikilink-syntax.mjs

@@ -182,6 +182,8 @@ export function unlabelledLinkMessage(target) {
  * - `unknown-type` — definitely qualified, but names no type this build knows.
  * - `not-an-asset` — a real address, embedded where only a file can be drawn.
  * - `unresolved` — parses as an address, and nothing publishes it.
+ * - `stub` — the address names a note this tree holds whose body is empty, so
+ *   it publishes no page for the link to reach.
  * - `ambiguous` — more than one package publishes the short address.
  * - `unknown-anchor` — the address resolved, the `#section` it names did not.
  * - `no-content-index` — the address names a package declared
@@ -198,6 +200,7 @@ export const LINK_FINDING_REASONS = Object.freeze(
         "unknown-type",
         "not-an-asset",
         "unresolved",
+        "stub",
         "ambiguous",
         "unknown-anchor",
         "no-content-index",
@@ -231,6 +234,26 @@ export function unresolvedAddressMessage(target) {
     );
 }
 
+/**
+ * What an author linking to a **stub** is told.
+ *
+ * Strictly better than "resolves to no note", and available only because a stub
+ * is in the index: the note exists, its file can be named, and the reason the
+ * link cannot land is a fact about that file rather than a guess about a
+ * shortcode. So the message names the file to open and offers both corrections
+ * — the link was either premature or the note is owed a body.
+ *
+ * @param {string} target - The address as authored.
+ * @param {string} [file] - Where the stub is, relative to the content root.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function stubAddressMessage(target, file) {
+    return (
+        `address [[${target}]] names a stub${file ? ` at ${file}` : ""}, which has ` +
+        `no body and therefore no page — name it in prose, or write the note`
+    );
+}
+
 /**
  * What an author writing a short address more than one package publishes is
  * told.
@@ -278,11 +301,12 @@ export function ambiguousAddressMessage(target, packages = []) {
  * @param {string} [finding.anchor] - For `unknown-anchor`, the section named.
  * @param {string} [finding.type] - For `not-an-asset`, the type the address
  *   named.
+ * @param {string} [finding.stub] - For `stub`, where the stub is.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor, type }) {
+export function linkFindingMessage({ reason, target, packages, anchor, type, stub }) {
     switch (reason) {
         case "unlabelled":
             return unlabelledLinkMessage(target);
@@ -316,6 +340,8 @@ export function linkFindingMessage({ reason, target, packages, anchor, type }) {
             );
         case "unresolved":
             return unresolvedAddressMessage(target);
+        case "stub":
+            return stubAddressMessage(target, stub);
         case "no-content-index":
             return (
                 `address [[${target}]] names a package declared \`contentIndex: false\` — ` +

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.6",
+    "version": "22.5.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/types/engine/content-index.d.mts

@@ -95,11 +95,18 @@ export function asciiAliases(aliases: unknown): Array<string>;
  * @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 {string} [options.body] - The note's markdown body, for its anchors
+ *   and for the one question that decides whether the note publishes a page. A
+ *   caller that states no body is stating an empty one, and the note is a stub.
  * @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.
+ * @returns {Record<string, any>} The record, keys sorted at every depth. A
+ *   **stub** — a note with an empty body, on a type an empty body suppresses —
+ *   carries `address` and `anchors` as `null`: it publishes no page, so it
+ *   holds no address and offers no anchor. It keeps everything else, its `id`
+ *   and its `foundry` block included, because the document it compiles is
+ *   derived from `data:` rather than from prose.
  * @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.
@@ -205,8 +212,11 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
  *   `paths.contentIndex`.
  * @param {object} [options.config] - A resolved configuration; loaded when omitted.
  * @returns {{file: string, notes: number, assets: number, records: number,
- *   bytes: number}} Where it was written, how many notes and how many assets it
- *   holds, how many records that is in all, and its size.
+ *   bytes: number, full: number, draft: number, stub: number}} Where it was
+ *   written, how many notes and how many assets it holds, how many records that
+ *   is in all, its size, and the ladder those notes sit on — so the ratio of
+ *   written to unwritten is visible on every build rather than discovered in a
+ *   year.
  * @throws {Error} When the content tree is absent, or when it yields no note at
  *   all — an empty index is indistinguishable from a mis-pointed tree, and a
  *   reader would take it as the authoritative statement that this package has
@@ -222,13 +232,17 @@ export function emitContentIndex({ contentBase, outDir, config }?: {
     assets: number;
     records: number;
     bytes: number;
+    full: number;
+    draft: number;
+    stub: number;
 };
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
 import { DERIVED_KEYS } from "./index-records.mjs";
 import { isAssetRecord } from "./index-records.mjs";
 import { isNoteRecord } from "./index-records.mjs";
+import { isStub } from "./index-records.mjs";
 import { noteFile } from "./index-records.mjs";
 import { recordPath } from "./index-records.mjs";
 import { sortKeysDeep } from "./index-records.mjs";
-export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, noteFile, recordPath, sortKeysDeep };
+export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, isStub, noteFile, recordPath, sortKeysDeep };

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

@@ -133,9 +133,9 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *   which addresses a foreign manifest answered. Each `deadAddresses` entry
  *   carries a `reason` from {@link LINK_FINDING_REASONS} —
  *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
- *   `packages`), `"no-content-index"`, or `"unresolved"` — and every one of
- *   them is an **error**: the three resolvers agree on severity for every
- *   class.
+ *   `packages`), `"no-content-index"`, `"stub"` (with the stub's path) or
+ *   `"unresolved"` — and every one of them is an **error**: the three
+ *   resolvers agree on severity for every class.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];

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

@@ -105,7 +105,8 @@ export function renderContentTable(spec: object, rows: Array<ContentTableDoc>, l
  *   each came from, so a diagnostic about the expanded body can name an
  *   authored position. An `errors` entry carries the 0-based line of the
  *   directive that failed, for the same reason. `warnings` holds one entry per
- *   `dataview` directive the body still authors.
+ *   `dataview` directive the body still authors, and one per `sql` directive
+ *   that leaves out stubs it would otherwise list.
  */
 export function expandContentTables(markdown: string, { docs, linkable, source, self, sqlTables, }?: {
     docs: Array<ContentTableDoc>;

package/types/engine/holdings.d.mts

@@ -0,0 +1,157 @@
+/**
+ * A `parents` or `domains` value as the shortcodes it names, in order,
+ * empties dropped and repeats collapsed.
+ *
+ * @param {unknown} value - The authored value — a list, or a lone entry.
+ * @returns {string[]} The shortcodes.
+ */
+export function shortcodesOf(value: unknown): string[];
+/**
+ * Read a local note into a node, or `null` for a note that takes no part.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} page - The page it publishes as.
+ * @param {string} page.title - Its published title.
+ * @param {string} page.url - Its URL.
+ * @returns {HoldingsNode|null} The node, or `null` for a note that is neither
+ *   a place nor an affiliation, or that declares no shortcode.
+ */
+export function holdingsNode(fm: object, { title, url }: {
+    title: string;
+    url: string;
+}): HoldingsNode | null;
+/**
+ * Read a fetched index's places and affiliations as nodes.
+ *
+ * An entry carries what the producer's record stated — its name, `subType`,
+ * `parents` and `domains` — and its page URL where the package publishes one.
+ *
+ * @param {Map<string, object>|undefined} foreignIndex - As
+ *   {@link module:engine/metadata-index.loadForeignIndexes} returns it.
+ * @returns {HoldingsNode[]} The nodes, in index order.
+ */
+export function foreignHoldingsNodes(foreignIndex: Map<string, object> | undefined): HoldingsNode[];
+/**
+ * Invert `parents` and `domains` into each page's lists.
+ *
+ * A shortcode is declared once per type: the first node declaring it wins,
+ * so local nodes handed in ahead of fetched ones shadow a dependency's, the
+ * way the link resolver answers. A node with no URL carries no lists of its
+ * own, since there is no page to write them on — and is still an entry on
+ * everybody else's, rendered as plain text. A name no node declares is
+ * dropped: a `parents` naming nowhere is the map's finding, a `domains`
+ * naming nowhere the reference check's.
+ *
+ * The result holds only pages with at least one entry on at least one list,
+ * and a page's block carries only the keys it has entries for — the theme's
+ * silent-disappear convention, kept at the source.
+ *
+ * @param {Iterable<HoldingsNode|null>} nodes - Every place and affiliation,
+ *   local first. `parents` and `domains` are read as written, so a node
+ *   built by hand may carry them as the note spells them.
+ * @returns {Map<string, Holdings>} URL → the page's lists, sorted.
+ */
+export function holdingsPages(nodes: Iterable<HoldingsNode | null>): Map<string, Holdings>;
+/**
+ * Check a place note's tenure: a settlement, a site or a structure that no
+ * affiliation's `domains` names is unheld land, reported as a warning at the
+ * note's `type:` line.
+ *
+ * Declared on the `place` vocabulary as its type-level check, so the lint
+ * runs it beside the field checks with the same index. Without an index the
+ * question cannot be asked and nothing is reported.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, holding every affiliation.
+ * @returns {object[]} Findings.
+ */
+export function checkHeld(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];
+/**
+ * The keys this module writes, and which a note cannot author: `contains`
+ * and `held_by` on a place, `holdings` on an affiliation.
+ *
+ * @type {readonly string[]}
+ */
+export const HOLDINGS_KEYS: readonly string[];
+/**
+ * The place subTypes tenure is checked on. A region is held through its
+ * polity's `domains`, a world by nobody, a feature by nobody — a river has no
+ * lord — so the rest are the kinds of place a body holds directly.
+ *
+ * @type {readonly string[]}
+ */
+export const HELD_SUBTYPES: readonly string[];
+/**
+ * One entry of a holdings list — a page a reader is pointed at.
+ */
+export type HoldingsEntry = {
+    /**
+     * The page's published title.
+     */
+    title: string;
+    /**
+     * `<base><slug>/` — the page's address as every
+     *    href this build renders composes it. **Absent
+     *    for a stub**, which has no page: an entry with no
+     *    `url` renders as plain text.
+     */
+    url?: string | undefined;
+    /**
+     * The note's `type` — `place` or `affiliation`.
+     */
+    type: string;
+    /**
+     * The note's `subType`, where it declares one.
+     */
+    subType?: string | undefined;
+};
+/**
+ * One place or affiliation, as the derivation reads it — a local page or a
+ * fetched index entry through one shape.
+ */
+export type HoldingsNode = {
+    /**
+     * Lower case.
+     */
+    shortcode: string;
+    type: "place" | "affiliation";
+    subType?: string | undefined;
+    /**
+     * The page's published title.
+     */
+    title: string;
+    /**
+     * The page's URL; absent where the package
+     *      publishes no page for it.
+     */
+    url?: string | undefined;
+    /**
+     * What a place sits within, as written.
+     */
+    parents: string[];
+    /**
+     * What an affiliation holds, as written.
+     */
+    domains: string[];
+};
+/**
+ * The lists one page carries. Every key is optional, and a key present holds
+ * at least one entry.
+ */
+export type Holdings = {
+    /**
+     * Places whose `parents` name this one.
+     */
+    contains?: HoldingsEntry[] | undefined;
+    /**
+     * Affiliations whose `domains` name this one.
+     */
+    held_by?: HoldingsEntry[] | undefined;
+    /**
+     * Places this affiliation's `domains` name.
+     */
+    holdings?: HoldingsEntry[] | undefined;
+};

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

@@ -77,6 +77,28 @@ export function isAssetRecord(record: Record<string, any>): boolean;
  * @returns {boolean} True for a note's own record.
  */
 export function isNoteRecord(record: Record<string, any>): boolean;
+/**
+ * Whether a record is a **stub**: a note with an empty body.
+ *
+ * Asked of the **absent address**, not of a marker block, because the absent
+ * address is the whole signal. A note's body is not in the index — the index
+ * carries what is *about* a note — so there is nothing else to ask, and nothing
+ * else needs to be: an address is emitted if and only if the body is non-empty
+ * on a type an empty body suppresses (see
+ * {@link module:engine/note-state.isStubNote}).
+ *
+ * A stub keeps its file, its `id` and, where its type compiles one, its Foundry
+ * document. What the empty body suppresses is the **page**, and the address and
+ * the link target that go with it.
+ *
+ * Asked only of a note's own record. A documentation journal and an asset are
+ * documents rather than notes, and both are addressed whatever the note they
+ * belong to says.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {boolean} True for a stub's record.
+ */
+export function isStub(record: Record<string, any>): boolean;
 /**
  * The path a record names inside its package, whichever shape it is.
  *

package/types/engine/index.d.mts

@@ -15,12 +15,18 @@ export * as derivedFields from "./derived-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
+export * as noteState from "./note-state.mjs";
+export * as stubLint from "./stub-lint.mjs";
 export * as placeRelations from "./place-relations.mjs";
+export * as holdings from "./holdings.mjs";
+export * as populations from "./populations.mjs";
+export * as marketClass from "./market-class.mjs";
 export * as mapPlaces from "./map-places.mjs";
 export * as mapLayout from "./map-layout.mjs";
 export * as mapDot from "./map-dot.mjs";
 export * as mapGraphviz from "./map-graphviz.mjs";
 export * as mapBuild from "./map-build.mjs";
+export * as siteMaps from "./site-maps.mjs";
 export * as systems from "./systems.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";

package/types/engine/map-graphviz.d.mts

@@ -21,7 +21,7 @@ export function findGraphviz(engine: string, { env, fallbacks }?: {
 }): string | undefined;
 /**
  * What to say when an engine is not installed: the name, and what installs
- * it on the two platforms a contributor is likely to be on.
+ * it.
  *
  * @param {string} engine - The engine that was wanted.
  * @returns {string} The message.
@@ -59,3 +59,10 @@ export function renderDot(dotPath: string, outPath: string, { binary, format, ar
  * @type {readonly string[]}
  */
 export const GRAPHVIZ_ENGINES: readonly string[];
+/**
+ * What installs GraphViz on the two platforms a contributor is likely to be
+ * on, as the clause every "not installed" message ends with.
+ *
+ * @type {string}
+ */
+export const GRAPHVIZ_INSTALL: string;

package/types/engine/map-places.d.mts

@@ -34,6 +34,32 @@ export function loadMapWorld({ config, contentBase, base, problems }: {
     base?: string | undefined;
     problems?: object[] | undefined;
 }): MapWorld;
+/**
+ * The world a map is drawn from, out of records and indexes a caller already
+ * holds: this package's places from its index records, and every
+ * dependency's from the fetched indexes. The site build reads its corpus and
+ * its foreign indexes once for every surface it publishes, and hands them
+ * here rather than walking the tree a second time.
+ *
+ * @param {object} opts
+ * @param {Array<Record<string, any>>} opts.records - Index records, as
+ *   {@link module:engine/content-index.indexRecordsFor} returns them.
+ * @param {Map<string, object>} opts.foreignIndex - The fetched indexes, as
+ *   {@link module:engine/metadata-index.loadForeignIndexes} returns `index`.
+ * @param {string} opts.contentBase - The content root the records were read from.
+ * @param {string} [opts.base] - The site base this package's pages are served
+ *   under. Absent, no local place carries a URL.
+ * @param {object} opts.config - The resolved configuration.
+ * @returns {MapWorld} The world, with nothing stale: the caller has already
+ *   judged its indexes usable.
+ */
+export function mapWorld({ records, foreignIndex, contentBase, base, config }: {
+    records: Array<Record<string, any>>;
+    foreignIndex: Map<string, object>;
+    contentBase: string;
+    base?: string | undefined;
+    config: object;
+}): MapWorld;
 /**
  * Analyse the containment tree.
  *