@heroiclands/package-build 22.0.3 → 22.1.1

package/content-config.mjs

@@ -175,6 +175,10 @@ export const DEFAULT_PATHS = /** @type {const} */ ({
     // dependency — so nesting one under the other would imply a containment
     // that does not hold.
     metadataCache: "build/cache/metadata",
+    // Where the site navigation heroiclands.org publishes is fetched to.
+    // Beside the other two: it is fetched by the same command and read under
+    // the same complete-marker rule.
+    navigationCache: "build/cache/navigation",
 });
 
 /**
@@ -387,6 +391,8 @@ export function publishesContentPages(config) {
  *                                       index is fetched to. Inbound,
  *                                       for *every* declared dependency, not
  *                                       only those supplying a catalogue.
+ * @property {string} [navigationCache]  Where the site navigation is fetched
+ *                                       to, for the generated Hugo menu.
  */
 
 /**
@@ -401,6 +407,7 @@ export function publishesContentPages(config) {
  * @property {string} unpack
  * @property {string} foreignCache
  * @property {string} metadataCache
+ * @property {string} navigationCache
  */
 
 /**
@@ -496,6 +503,14 @@ export function publishesContentPages(config) {
  *                                   package this one targets — for a system
  *                                   relationship, `verified` is what
  *                                   `_stats.systemVersion` is stamped from.
+ * @property {boolean} [contentIndex]  Whether `deps fetch` fetches this
+ *                                   dependency's content index. Default
+ *                                   `true`. `false` declares the dependency
+ *                                   for the Foundry manifest only — nothing
+ *                                   this tree cites by wikilink — and refuses
+ *                                   `itemCatalog: true` on the same entry,
+ *                                   since a catalogue is fetched from the same
+ *                                   index.
  */
 
 /**
@@ -578,6 +593,13 @@ export function publishesContentPages(config) {
  *                                          Refused by a `documentation`
  *                                          package, which ships no Foundry
  *                                          package.
+ * @property {string} [homepage]            `package.json`'s own `homepage` —
+ *                                          the site build's `baseURL`. Checked
+ *                                          by `checkHomepage` in
+ *                                          `config.mjs`.
+ * @property {string|{name: string, email?: string, url?: string}} [author]
+ *                                          `package.json`'s own `author`, in
+ *                                          either of npm's forms.
  * @property {PackageKind} packageKind      Whether the package is a system, a
  *                                          module, or documentation — the kind
  *                                          that publishes a site and a book
@@ -637,6 +659,13 @@ export function publishesContentPages(config) {
  * @property {string} contentPackage
  * @property {string|null} foundryPackage  `null` for a `documentation`
  *                                     package, which ships no Foundry package.
+ * @property {string|null} homepage    `package.json`'s own `homepage`,
+ *                                     checked by `checkHomepage` in
+ *                                     `config.mjs`.
+ * @property {Readonly<{name: string, email?: string, url?: string}>|null} author
+ *                                     `package.json`'s own `author`, normalised
+ *                                     from either of npm's forms; `null` when
+ *                                     the package declares none.
  * @property {PackageKind} packageKind
  * @property {string|null} assetRoot   Derived, and **conditional**: the served
  *                                     Foundry asset root,
@@ -705,6 +734,8 @@ const CONFIG_KEYS = [
     "rootDir",
     "contentPackage",
     "foundryPackage",
+    "homepage",
+    "author",
     "packageKind",
     "stats",
     "itemBuilders",
@@ -726,7 +757,6 @@ const SYSTEM_KEYS = ["manifest", "compatibility"];
 const COMPATIBILITY_KEYS = ["minimum", "verified"];
 const DOCS_KEYS = ["itemFields"];
 const SITE_KEYS = [
-    "out",
     "base",
     "assets",
     "packages",
@@ -737,8 +767,14 @@ const SITE_KEYS = [
     "pass",
     "passOptions",
     "backfillSections",
+    "list",
+    "notfound",
+    "hugo",
 ];
 const SITE_TREE_KEYS = ["from", "section"];
+const SITE_LIST_KEYS = ["shortcodes"];
+const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
+const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
 const PDF_KEYS = ["title", "subtitle", "document", "out", "front", "fonts", "iconFonts", "binary"];
 const PDF_FONT_KEYS = ["serif", "sans", "mono", "path"];
 const EMPTY_PDF_FONTS = Object.freeze({ serif: "", sans: "", mono: "", path: "" });
@@ -752,7 +788,9 @@ const RELATIONSHIP_KEYS = [
     "manifest",
     "compatibility",
     "itemCatalog",
+    "contentIndex",
 ];
+const AUTHOR_KEYS = ["name", "email", "url"];
 const ITEM_BUILDER_KEYS = ["system", "img", "fields"];
 const ITEM_REGISTRY_KEYS = ["system", "builders"];
 const PACK_KEYS = [
@@ -964,6 +1002,56 @@ function optionalString(value, field) {
     return value;
 }
 
+/**
+ * npm's `author` field, in either of its two forms.
+ *
+ * `package.json` accepts a single string — `"Name <email> (url)"`, with the
+ * email and the URL both optional — or an object carrying the same three
+ * parts. Both normalise to one shape, so the site build reads one field
+ * instead of branching on which form a repository happened to write.
+ *
+ * @type {RegExp}
+ */
+const AUTHOR_STRING = /^([^<(]*?)\s*(?:<([^>]*)>)?\s*(?:\(([^)]*)\))?\s*$/;
+
+/**
+ * @param {unknown} value - The declared `author`, or `undefined`.
+ * @returns {Readonly<{name: string, email?: string, url?: string}>|null}
+ *   `null` when the package declares none.
+ */
+function normalizeAuthor(value) {
+    if (value === undefined) return null;
+    if (typeof value === "string") {
+        const match = AUTHOR_STRING.exec(value.trim());
+        const name = match?.[1]?.trim();
+        if (!match || !name) {
+            fail(
+                "author",
+                'must be `"Name"`, `"Name <email>"`, `"Name (url)"` or ' +
+                    '`"Name <email> (url)"` — npm\'s own `author` forms',
+            );
+        }
+        return Object.freeze({
+            name: /** @type {string} */ (name),
+            ...(match[2] ? { email: match[2] } : {}),
+            ...(match[3] ? { url: match[3] } : {}),
+        });
+    }
+    if (!isPlainObject(value)) {
+        fail("author", "must be a string or an object with `name`, `email` and `url`");
+    }
+    const author = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(author, AUTHOR_KEYS, "author.");
+    const name = requireNonEmptyString(author.name, "author.name");
+    return Object.freeze({
+        name,
+        ...(author.email !== undefined ?
+            { email: optionalString(author.email, "author.email") }
+        :   {}),
+        ...(author.url !== undefined ? { url: optionalString(author.url, "author.url") } : {}),
+    });
+}
+
 /**
  * @param {unknown} value
  * @param {string} where       Field path used in error messages.
@@ -1504,21 +1592,151 @@ function normalizeSectionMap(value, where) {
     return Object.freeze(out);
 }
 
+/**
+ * Hugo keys a repository may **not** declare under `site.hugo`, because the
+ * site build generates them and would only overwrite what was written.
+ *
+ * The same rule `DERIVED_MANIFEST_KEYS` states for the manifest, for the same
+ * reason: an authored `baseURL` would look authoritative, sit there unread,
+ * and disagree with the site forever. Each key names where its value comes
+ * from. A dotted key names a nested one, and covers everything beneath it —
+ * `params.brand` refuses `params.brand.logo` too — so `site.hugo` reaches only
+ * what the generator does not write.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DERIVED_HUGO_KEYS = Object.freeze({
+    baseURL: "package.json `homepage`",
+    title: "`packageBuild.manifest.title`",
+    locale: "the organisation's locale, in `engine/site-config.mjs`",
+    publishDir: "`contentPackage`, under the deployment root `build/site`",
+    contentDir: "the fixed content mount, `build/hugo/content`",
+    themesDir: "where `@heroiclands/hugo-theme` is installed",
+    theme: "the installed `@heroiclands/hugo-theme`",
+    disableKinds: "whether any note in the tree carries `tags:`, which the site walk discovers",
+    taxonomies: "whether any note in the tree carries `tags:`, which the site walk discovers",
+    outputs: "whether any note in the tree carries `tags:`, which the site walk discovers",
+    "params.description": "package.json `description`",
+    "params.author": "package.json `author`",
+    "params.cdnBaseURL": "`site.assets`",
+    "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
+    "params.list": "`site.list`",
+    "params.notfound": "`site.notfound`",
+    "markup.goldmark.renderer.unsafe": "the toolchain, whose pages carry raw HTML",
+    menu: "the navigation `content-build deps fetch` caches from heroiclands.org",
+});
+
+/**
+ * The `site.list` block — how a listing page renders.
+ *
+ * @param {unknown} value - The block, or `undefined`.
+ * @returns {Readonly<{shortcodes: boolean}>} It, frozen, with every default filled.
+ */
+function normalizeSiteList(value) {
+    if (value === undefined) return Object.freeze({ shortcodes: false });
+    if (!isPlainObject(value)) fail("site.list", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(input, SITE_LIST_KEYS, "site.list.");
+    return Object.freeze({
+        shortcodes: optionalBoolean(input.shortcodes, "site.list.shortcodes", false),
+    });
+}
+
+/**
+ * The `site.notfound` block — the wording of the "page not found" page.
+ *
+ * The theme renders the page for every site; what a repository supplies is
+ * the tagline, the noun the body prose calls the site, and the routes back.
+ * `tagline` and `sitenoun` are required once the block is present: a block
+ * declaring only links would render the theme's generic wording above a list
+ * of this site's routes, which reads as two sites.
+ *
+ * @param {unknown} value - The block, or `undefined`.
+ * @returns {Readonly<object>|null} It, frozen; `null` when absent.
+ */
+function normalizeSiteNotfound(value) {
+    if (value === undefined) return null;
+    if (!isPlainObject(value)) fail("site.notfound", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(input, SITE_NOTFOUND_KEYS, "site.notfound.");
+    const out = {
+        tagline: requireNonEmptyString(input.tagline, "site.notfound.tagline"),
+        sitenoun: requireNonEmptyString(input.sitenoun, "site.notfound.sitenoun"),
+    };
+    if (input.heroimage !== undefined) {
+        out.heroimage = requireNonEmptyString(input.heroimage, "site.notfound.heroimage");
+    }
+    if (input.links !== undefined) {
+        if (!Array.isArray(input.links)) fail("site.notfound.links", "must be a list");
+        out.links = Object.freeze(
+            input.links.map((link, i) => {
+                const where = `site.notfound.links[${i}]`;
+                if (!isPlainObject(link)) fail(where, "must be a mapping");
+                const entry = /** @type {Record<string, unknown>} */ (link);
+                rejectUnknownKeys(entry, SITE_NOTFOUND_LINK_KEYS, `${where}.`);
+                return Object.freeze({
+                    title: requireNonEmptyString(entry.title, `${where}.title`),
+                    url: requireNonEmptyString(entry.url, `${where}.url`),
+                    text: requireNonEmptyString(entry.text, `${where}.text`),
+                });
+            }),
+        );
+    }
+    return Object.freeze(out);
+}
+
+/**
+ * The `site.hugo` block — a mapping deep-merged over the generated Hugo
+ * configuration, last.
+ *
+ * The escape hatch for the key nobody anticipated. Every key the generator
+ * writes is refused here by {@link DERIVED_HUGO_KEYS}, naming its source, so
+ * the block cannot grow into a second configuration file.
+ *
+ * @param {unknown} value - The block, or `undefined`.
+ * @returns {Readonly<Record<string, unknown>>} It, frozen; `{}` when absent.
+ */
+function normalizeSiteHugo(value) {
+    if (value === undefined) return Object.freeze({});
+    if (!isPlainObject(value)) fail("site.hugo", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    for (const [dotted, source] of Object.entries(DERIVED_HUGO_KEYS)) {
+        /** @type {unknown} */
+        let at = input;
+        for (const part of dotted.split(".")) {
+            at = isPlainObject(at) ? /** @type {Record<string, unknown>} */ (at)[part] : undefined;
+            if (at === undefined) break;
+        }
+        if (at !== undefined) {
+            fail(
+                `site.hugo.${dotted}`,
+                `is derived from ${source} and must not be declared — it ` +
+                    `would be overwritten, and the two would disagree with ` +
+                    `nothing to say so`,
+            );
+        }
+    }
+    return Object.freeze(structuredClone(input));
+}
+
 /**
  * The `site` section — how this repository frames the website it publishes.
  *
- * Everything here is *framing*: where the Hugo tree is written, what a section
- * is called, which extra trees are published beside the content, and which
- * named pass bundle supplies the repository's own body rewrites. How a page gets
- * its **address** is deliberately not here — that is `publish.address`, shared
- * with the link manifest so the two cannot disagree about where a page is.
+ * Everything here is *framing*: what a section is called, which extra trees
+ * are published beside the content, which named pass bundle supplies the
+ * repository's own body rewrites, and the residue of the generated Hugo
+ * configuration that is genuinely this repository's own. Where the Hugo tree
+ * is written is not a choice: `content-build site` writes it under
+ * `build/hugo/`, and a `site.out` is refused by name. How a page gets its
+ * **address** is deliberately not here either — that is `publish.address`,
+ * shared with the link manifest so the two cannot disagree about where a
+ * page is.
  *
  * @param {unknown} value - The `site` block, or `undefined`.
  * @returns {Readonly<object>} It, frozen, with every default filled.
  */
 function normalizeSite(value) {
     const empty = Object.freeze({
-        out: "",
         base: "",
         assets: "",
         packages: Object.freeze([]),
@@ -1529,10 +1747,23 @@ function normalizeSite(value) {
         pass: "",
         passOptions: Object.freeze({}),
         backfillSections: false,
+        list: Object.freeze({ shortcodes: false }),
+        notfound: null,
+        hugo: Object.freeze({}),
     });
     if (value === undefined) return empty;
     if (!isPlainObject(value)) fail("site", "must be a mapping");
     const input = /** @type {Record<string, unknown>} */ (value);
+    // Refused by name, ahead of the vocabulary check: the useful thing to say
+    // is not "no such key" but that the location is fixed.
+    if (input.out !== undefined) {
+        fail(
+            "site.out",
+            "is retired — the site build writes its content mount at " +
+                "`build/hugo/content`, beside the generated `hugo.toml`, and " +
+                "the location is not configurable. Remove the key",
+        );
+    }
     rejectUnknownKeys(input, SITE_KEYS, "site.");
 
     const trees = [];
@@ -1574,7 +1805,6 @@ function normalizeSite(value) {
     }
 
     return Object.freeze({
-        out: input.out === undefined ? "" : requireNonEmptyString(input.out, "site.out"),
         base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
         assets: normalizeSiteAssets(input.assets),
         packages: Object.freeze(packages),
@@ -1588,6 +1818,9 @@ function normalizeSite(value) {
                 Object.freeze({})
             :   Object.freeze({ ...input.passOptions }),
         backfillSections: optionalBoolean(input.backfillSections, "site.backfillSections", false),
+        list: normalizeSiteList(input.list),
+        notfound: normalizeSiteNotfound(input.notfound),
+        hugo: normalizeSiteHugo(input.hugo),
     });
 }
 
@@ -1925,6 +2158,24 @@ function normalizeRelationships(value) {
                     }
                     spec.itemCatalog = rel.itemCatalog;
                 }
+                // Opt-out: declares the dependency for the Foundry manifest
+                // only, so `deps fetch` fetches no content index for it and a
+                // wikilink into it is refused rather than silently dead. A
+                // catalogue is fetched from the same index, so it cannot be
+                // declared alongside `itemCatalog: true`.
+                if (rel.contentIndex !== undefined) {
+                    if (typeof rel.contentIndex !== "boolean") {
+                        fail(`${at}.contentIndex`, "must be true or false");
+                    }
+                    if (rel.contentIndex === false && spec.itemCatalog) {
+                        fail(
+                            `${at}.contentIndex`,
+                            "cannot be false together with `itemCatalog: true` — a catalogue is " +
+                                "fetched from the same index",
+                        );
+                    }
+                    spec.contentIndex = rel.contentIndex;
+                }
                 return Object.freeze(spec);
             }),
         );
@@ -2493,6 +2744,11 @@ export function defineConfig(config) {
         rootDir,
         contentPackage: requireContentPackage(input.contentPackage, docEntryTypes),
         foundryPackage,
+        // `package.json`'s own address and byline. `homepage` is checked by
+        // `checkHomepage` in `config.mjs`.
+        homepage:
+            input.homepage === undefined ? null : requireNonEmptyString(input.homepage, "homepage"),
+        author: normalizeAuthor(input.author),
         packageKind: /** @type {PackageKind} */ (packageKind),
         // Foundry serves a package's files from `<kind>/<id>/`, so this is the
         // one place `systems/sohl` (or `modules/sohl-thalorna`) is spelled.

package/docs/api.md

@@ -342,6 +342,7 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | `applicableTagGroups`     | `applicableTagGroups(type, groups)`          | `object[]`                               | reading the declared tag groups that apply to a note type                                    |
 | `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading the single-valued tag slots a note type has, such as a being's kind                  |
 | `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in |
+| `hasAnyTag`               | `hasAnyTag(fm)`                              | `boolean`                                | checking whether a note carries any `tags:` at all, for the site build's taxonomy decision   |
 | `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                | checking whether a note is tagged as an unfinished draft                                     |
 | `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                 | building the message for a `subType` outside the address charset                             |
 | `typeCharsetMessage`      | `typeCharsetMessage(type)`                   | `string`                                 | building the message for a `type` outside the address charset                                |
@@ -491,21 +492,22 @@ The shortcodes a note declares it used to be published under. A package's `(type
 
 The published content index — the artifact packages exchange addresses through. **A package publishes its own index; a consumer fetches the ones it depends on.** That is the whole mechanism, and it replaces a vendored link manifest that each repository committed a copy of every other repository's file into. Vendoring failed three ways, and only the last is about staleness:
 
-| Export                         | Signature                                                  | Returns                                                                                                                                                                                | Use it when                                                                   |
-| ------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `METADATA_RELATIONSHIP_KINDS`  | `const METADATA_RELATIONSHIP_KINDS`                        | —                                                                                                                                                                                      | The relationship kinds that are dependencies, and therefore citable.          |
-| `metadataFileName`             | `function metadataFileName(pkg)`                           | {string} The file name, e.g.                                                                                                                                                           | What a package's content index is called, wherever it is written or fetched.  |
-| `metadataRelationships`        | `function metadataRelationships(config)`                   | {Array<{id: string, manifest: string, kind: string, verified: string\|undefined}>} The dependencies, in declaration order.                                                             | Every dependency whose published index this build resolves addresses through. |
-| `metadataCacheDir`             | `function metadataCacheDir(config, id, version)`           | {string} The directory.                                                                                                                                                                | The cache directory for one dependency's index at one version.                |
-| `isComplete`                   | `const isComplete`                                         | {boolean} True when it was fetched to completion.                                                                                                                                      | Whether a dependency's cache is present and complete.                         |
-| `markComplete`                 | `function markComplete(dir)`                               | {void}                                                                                                                                                                                 | Mark a dependency's cache complete.                                           |
-| `cachedMetadataFiles`          | `function cachedMetadataFiles(config)`                     | {string[]} One index file per declared dependency.                                                                                                                                     | The fetched index files this build resolves foreign addresses against.        |
-| `cachedMetadataIndexes`        | `function cachedMetadataIndexes(config)`                   | {Array<{id: string, file: string}>} One entry per declared dependency.                                                                                                                 | The same fetched indexes, each paired with the package that published it.     |
-| `newestVersionDir`             | `function newestVersionDir(dirs)`                          | {string} The newest one.                                                                                                                                                               | The newest cached version among several version-keyed cache directories.      |
-| `loadForeignIndexes`           | `function loadForeignIndexes(config, localPackages, bases` | {{index: Map<string, object>, packages: Set<string>, stale: Array<{package: string, reason: string}>}} The resolved addresses, which packages contributed, and what could not be read. | Resolve every foreign address this build can cite, from the fetched indexes.  |
-| `cachedIndexPath`              | `function cachedIndexPath(config, pkg)`                    | {string} A path to name in a diagnostic.                                                                                                                                               | Where a dependency's fetched index sits, for naming it in a diagnostic.       |
-| `unaddressableForeignPackages` | `function unaddressableForeignPackages(foreignIndex)`      | {Array<{package: string, entries: number, sampleKey: string}>} One finding per drifted package, in the order the index first names each.                                               | Whether a fetched index can still be _addressed_, as distinct from read.      |
-| `formatUnaddressableFinding`   | `function formatUnaddressableFinding(finding, config)`     | {string} The formatted diagnostic, path first on the line.                                                                                                                             | One finding, in the standard `file:line:column: severity: message` form.      |
+| Export                         | Signature                                                  | Returns                                                                                                                                                                                | Use it when                                                                                                                 |
+| ------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `METADATA_RELATIONSHIP_KINDS`  | `const METADATA_RELATIONSHIP_KINDS`                        | —                                                                                                                                                                                      | The relationship kinds that are dependencies, and therefore citable.                                                        |
+| `metadataFileName`             | `function metadataFileName(pkg)`                           | {string} The file name, e.g.                                                                                                                                                           | What a package's content index is called, wherever it is written or fetched.                                                |
+| `metadataRelationships`        | `function metadataRelationships(config)`                   | {Array<{id: string, manifest: string, kind: string, verified: string\|undefined}>} The dependencies, in declaration order.                                                             | Every dependency whose published index this build resolves addresses through.                                               |
+| `noContentIndexPackages`       | `function noContentIndexPackages(config)`                  | {ReadonlySet<string>} The content package names.                                                                                                                                       | Every package a relationship declares `contentIndex: false` on, keyed by the content package name a link into it would use. |
+| `metadataCacheDir`             | `function metadataCacheDir(config, id, version)`           | {string} The directory.                                                                                                                                                                | The cache directory for one dependency's index at one version.                                                              |
+| `isComplete`                   | `const isComplete`                                         | {boolean} True when it was fetched to completion.                                                                                                                                      | Whether a dependency's cache is present and complete.                                                                       |
+| `markComplete`                 | `function markComplete(dir)`                               | {void}                                                                                                                                                                                 | Mark a dependency's cache complete.                                                                                         |
+| `cachedMetadataFiles`          | `function cachedMetadataFiles(config)`                     | {string[]} One index file per declared dependency.                                                                                                                                     | The fetched index files this build resolves foreign addresses against.                                                      |
+| `cachedMetadataIndexes`        | `function cachedMetadataIndexes(config)`                   | {Array<{id: string, file: string}>} One entry per declared dependency.                                                                                                                 | The same fetched indexes, each paired with the package that published it.                                                   |
+| `newestVersionDir`             | `function newestVersionDir(dirs)`                          | {string} The newest one.                                                                                                                                                               | The newest cached version among several version-keyed cache directories.                                                    |
+| `loadForeignIndexes`           | `function loadForeignIndexes(config, localPackages, bases` | {{index: Map<string, object>, packages: Set<string>, stale: Array<{package: string, reason: string}>}} The resolved addresses, which packages contributed, and what could not be read. | Resolve every foreign address this build can cite, from the fetched indexes.                                                |
+| `cachedIndexPath`              | `function cachedIndexPath(config, pkg)`                    | {string} A path to name in a diagnostic.                                                                                                                                               | Where a dependency's fetched index sits, for naming it in a diagnostic.                                                     |
+| `unaddressableForeignPackages` | `function unaddressableForeignPackages(foreignIndex)`      | {Array<{package: string, entries: number, sampleKey: string}>} One finding per drifted package, in the order the index first names each.                                               | Whether a fetched index can still be _addressed_, as distinct from read.                                                    |
+| `formatUnaddressableFinding`   | `function formatUnaddressableFinding(finding, config)`     | {string} The formatted diagnostic, path first on the line.                                                                                                                             | One finding, in the standard `file:line:column: severity: message` form.                                                    |
 
 ### `engine.foundryEntries`
 
@@ -621,8 +623,7 @@ Publishing a content tree as a website. Compiling a content tree into compendium
 | `writeSectionLandings` | `function writeSectionLandings(outRoot,`          | {number} How many landings were written.                                                                                               | Writes the Hugo sections a published tree declares.                           |
 | `pluralTitle`          | `function pluralTitle(name)`                      | {string} The display title.                                                                                                            | A section landing's title, from its directory name — `macro` → `Macros`.      |
 | `resolveSitePass`      | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function, afterLinks?: Function}} The bundle.                                                                          | Resolves `site.pass` to its bundle.                                           |
-| `resolveOutputRoot`    | `function resolveOutputRoot(rootDir, out)`        | {string} The absolute output root.                                                                                                     | The output root, having established that it is safe to delete.                |
-| `buildSite`            | `buildSite({ config, outRoot, sqlTables })`       | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], manifests: object\|null}}                           | Builds a Hugo content tree from a content tree, and reports what it found.    |
+| `buildSite`            | `buildSite({ config, sqlTables })`                | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], manifests: object\|null}}                           | Builds a Hugo content tree from a content tree, and reports what it found.    |
 
 ### `engine.contentLint`
 
@@ -835,14 +836,14 @@ Shared helpers for the pack compilers in `packages/content-build/`. The HeroicLa
 
 Wikilink resolution for the pack compilers. Content notes link to one another with wikilinks rather than file paths:
 
-| Export               | Signature                                                               | Returns                                                                                                                                                                                                                                                                                                                               | Use it when                                                                                                                                                                |
-| -------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveItemDocType` | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                       | Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is not one.                                                                                      |
-| `readQualifier`      | `function readQualifier(target, types, packages)`                       | {{type: string, shortcode: string, itemDoc: boolean, package?: string, system?: string, reason?: undefined} \| {reason: "unknown-type"} \| null} The resolved qualifier; a `reason` when the target is definitely qualified but names no known type; or `null` when it is not an address at all.                                      | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
-| `anchorPageId`       | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                              | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
-| `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | {{byShortcode: Map<string, object>, types: Set<string>}} `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                | Builds the link-resolution tables for a content tree.                                                                                                                      |
-| `resolveReference`   | `function resolveReference(index, ref, hint)`                           | {{name?: string, uuid?: string, address?: string, subType?: string}\|undefined} The target, or `undefined` where nothing answers.                                                                                                                                                                                                     | Resolve one reference — a bare shortcode, a short address or a canonical one — to what a compendium can use.                                                               |
-| `convertWikilinks`   | `function convertWikilinks(markdown,`                                   | {{markdown: string, unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}} Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all three resolvers share — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named. | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
+| Export               | Signature                                                               | Returns                                                                                                                                                                                                                                                                                                                                                    | Use it when                                                                                                                                                                |
+| -------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `resolveItemDocType` | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                                            | Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is not one.                                                                                      |
+| `readQualifier`      | `function readQualifier(target, types, packages, noIndexPackages)`      | {{type: string, shortcode: string, itemDoc: boolean, package?: string, system?: string, reason?: undefined} \| {reason: "unknown-type"\|"no-content-index", package?: string} \| null} The resolved qualifier; a `reason` when the target is definitely qualified but names no known type or no fetched index; or `null` when it is not an address at all. | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
+| `anchorPageId`       | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                                                   | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
+| `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | {{byShortcode: Map<string, object>, types: Set<string>}} `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                                     | Builds the link-resolution tables for a content tree.                                                                                                                      |
+| `resolveReference`   | `function resolveReference(index, ref, hint)`                           | {{name?: string, uuid?: string, address?: string, subType?: string}\|undefined} The target, or `undefined` where nothing answers.                                                                                                                                                                                                                          | Resolve one reference — a bare shortcode, a short address or a canonical one — to what a compendium can use.                                                               |
+| `convertWikilinks`   | `function convertWikilinks(markdown,`                                   | {{markdown: string, unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}} Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all three resolvers share — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named.                      | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
 
 ### `engine.wikilinkSyntax`
 
@@ -1269,6 +1270,7 @@ const config = defineConfig({
 | `SITE_MODES`               | `const SITE_MODES`                 | —                                                          | reading the publishing modes `publish.site` may name, weakest first                                                                                                                                                                      |
 | `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`     | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                              |
 | `publishesContentPages`    | `publishesContentPages(config)`    | `boolean`                                                  | checking whether a resolved configuration publishes the pages its content tree compiles to — the one question the site build and the content index both need answered identically                                                        |
+| `DERIVED_HUGO_KEYS`        | `const DERIVED_HUGO_KEYS`          | —                                                          | reading which Hugo keys `site.hugo` may not declare because the site build generates them, each naming its source (declaring one is an error naming the key); a dotted key covers everything beneath it                                  |
 
 ## `./config`
 
@@ -1282,11 +1284,12 @@ const config = loadPackageBuildConfig();
 console.log(config.stageDir);
 ```
 
-| Export                      | Signature                           | Returns                        | Use it when                                                                                                                                  |
-| --------------------------- | ----------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DERIVED_MANIFEST_KEYS`     | `const DERIVED_MANIFEST_KEYS`       | —                              | reading which manifest keys a repository may not declare because the build derives them (declaring one is an error naming the key)           |
-| `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)` | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk             |
-| `loadPackageBuildConfig`    | `loadPackageBuildConfig()`          | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import |
+| Export                      | Signature                                 | Returns                        | Use it when                                                                                                                                                                     |
+| --------------------------- | ----------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DERIVED_MANIFEST_KEYS`     | `const DERIVED_MANIFEST_KEYS`             | —                              | reading which manifest keys a repository may not declare because the build derives them (declaring one is an error naming the key)                                              |
+| `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)`       | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk                                                |
+| `loadPackageBuildConfig`    | `loadPackageBuildConfig()`                | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import                                    |
+| `checkHomepage`             | `checkHomepage(homepage, contentPackage)` | `void`                         | validating a resolved `homepage` against `contentPackage` — called by `content-build site` before the generated `baseURL` is written, not by `resolvePackageBuildConfig` itself |
 
 ## `./prettier`