@heroiclands/package-build 5.0.0 → 6.1.0

package/manifest.mjs

@@ -49,8 +49,11 @@
  */
 
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import path from "node:path";
 
+import { emitDiagnostic, positionOfYamlPath } from "./engine/diagnostics.mjs";
+
 /**
  * The two package kinds Foundry defines, as the artifact name each one's
  * manifest and release archive are called.
@@ -197,6 +200,130 @@ export function manifestPacks(config) {
     });
 }
 
+/**
+ * Where a `packFolders` declaration lives in the configuration file.
+ *
+ * @type {readonly string[]}
+ */
+const PACK_FOLDERS_PATH = Object.freeze([
+    "packageBuild",
+    "manifest",
+    "packFolders",
+]);
+
+/**
+ * Every pack name a folder tree names, with the folder that named it.
+ *
+ * Foundry nests pack folders three deep — `PackageCompendiumFolder` re-declares
+ * itself while `depth < 4` — so a rule reading only the top level would miss
+ * every nested name in both directions: a broken one it never checked, and a
+ * working one it would then report as ungrouped.
+ *
+ * @param {unknown} folders - A `packFolders` list, or a nested `folders` list.
+ * @param {Array<string|number>} at - Config key path of `folders`.
+ * @returns {Array<{pack: string, folder: string, keyPath: Array<string|number>}>}
+ *   One entry per named pack, in declaration order, depth first.
+ */
+function namedPacks(folders, at) {
+    if (!Array.isArray(folders)) return [];
+    const found = [];
+    folders.forEach((folder, index) => {
+        if (folder === null || typeof folder !== "object") return;
+        const name = String(folder.name ?? "");
+        const packs = Array.isArray(folder.packs) ? folder.packs : [];
+        packs.forEach((pack, position) => {
+            found.push({
+                pack: String(pack),
+                folder: name,
+                keyPath: [...at, index, "packs", position],
+            });
+        });
+        found.push(...namedPacks(folder.folders, [...at, index, "folders"]));
+    });
+    return found;
+}
+
+/**
+ * What `packFolders` and the derived `packs[]` disagree about.
+ *
+ * `packFolders` is the one **declared** manifest key that names something the
+ * build **derives**: every other declared key states a fact about the package
+ * (`title`, `socket`, `grid`) or addresses a staged file (`esmodules`,
+ * `styles`, `languages`), and a staged file is a different relation, checked
+ * against the stage rather than against configuration. So this is the one place
+ * a declaration can go stale against a value the build already computed — and
+ * until now nothing compared them (#81).
+ *
+ * `HarnMaster-3-FoundryVTT` shipped the consequence: its folder named four
+ * packs, three of which had not existed since the compendium was consolidated,
+ * and omitted `items` — 1,577 of 1,597 documents, loose in Foundry's compendium
+ * browser, with the build reporting nothing (HM3#420).
+ *
+ * **The two findings are not the same finding**, and giving them one severity
+ * gets one of them wrong:
+ *
+ * - _A folder names a pack that does not exist_ is an **error**. Foundry
+ *   resolves the name against the package's own packs and silently skips what
+ *   it cannot find, so the declaration does nothing at all; there is no
+ *   arrangement in which it is intended, and the fix is unambiguous.
+ * - _A pack no folder names_ is a **warning**. It is legal and can be
+ *   deliberate — a package may want one pack at the root — so failing on it
+ *   would break working packages for a matter of taste. But a package that
+ *   bothered to declare a folder rarely meant to leave one out, which is
+ *   exactly how HM3's `items` went unnoticed.
+ * - _A package declaring no folders_ says **nothing**. Everything at the root
+ *   is the majority arrangement, not an omission.
+ *
+ * Errors come first, in declaration order, then warnings in pack order: the
+ * unresolvable names are what a reader fixes, and a folder gaining a name often
+ * settles a warning too.
+ *
+ * @param {object} options
+ * @param {unknown} [options.packFolders] - The declared `packFolders`.
+ * @param {ReadonlyArray<{name: string}>} [options.packs] - The derived packs,
+ *   as {@link manifestPacks} returns them.
+ * @returns {Array<{severity: "error"|"warning", message: string, pack: string,
+ *   folder?: string, keyPath: Array<string|number>}>} The findings, ordered.
+ */
+export function packFolderFindings({ packFolders, packs = [] }) {
+    if (!Array.isArray(packFolders) || packFolders.length === 0) return [];
+
+    const shipped = packs.map((pack) => pack?.name).filter(Boolean);
+    const known = new Set(shipped);
+    const named = namedPacks(packFolders, PACK_FOLDERS_PATH);
+    const grouped = new Set(named.map((entry) => entry.pack));
+
+    const findings = named
+        .filter((entry) => !known.has(entry.pack))
+        .map((entry) => ({
+            severity: /** @type {const} */ ("error"),
+            pack: entry.pack,
+            folder: entry.folder,
+            keyPath: entry.keyPath,
+            message:
+                `packFolders: folder "${entry.folder}" names pack ` +
+                `"${entry.pack}", which this package does not ship ` +
+                `(packs: ${shipped.join(", ")})`,
+        }));
+
+    for (const name of shipped) {
+        if (grouped.has(name)) continue;
+        findings.push({
+            severity: /** @type {const} */ ("warning"),
+            pack: name,
+            // No folder omitted it in particular — every one of them did — so
+            // the position is the declaration a reader edits, not one entry
+            // inside it. Each warning names its own pack, so they stay
+            // distinguishable despite sharing a line.
+            keyPath: [...PACK_FOLDERS_PATH],
+            message:
+                `packFolders: pack "${name}" is named by no folder, so it ` +
+                `ships outside every folder this package declares`,
+        });
+    }
+    return findings;
+}
+
 /**
  * Relationship keys that direct the **build**, rather than describe the
  * package.
@@ -330,16 +457,66 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     return ordered;
 }
 
+/**
+ * Report what {@link packFolderFindings} found, and say whether it was fatal.
+ *
+ * The position comes from the configuration file, when one was named and can be
+ * read: a `packFolders` finding is about a line of YAML, and the file is the
+ * only place a line exists. Anything that cannot be established — an `.mjs`
+ * configuration, an unreadable file, a path that resolves to nothing — is
+ * dropped rather than guessed, so the diagnostic degrades from
+ * `file:line:column:` to `file:` to no locator at all.
+ *
+ * @param {ReturnType<typeof packFolderFindings>} findings - What was found.
+ * @param {string} [configFile] - Absolute path of the configuration file.
+ * @returns {number} How many of them were errors.
+ */
+function reportPackFolders(findings, configFile) {
+    if (!findings.length) return 0;
+
+    let text;
+    if (configFile) {
+        try {
+            text = fsSync.readFileSync(configFile, "utf8");
+        } catch {
+            text = undefined;
+        }
+    }
+
+    let errors = 0;
+    for (const finding of findings) {
+        if (finding.severity === "error") errors += 1;
+        emitDiagnostic({
+            ...(configFile ? { file: configFile } : {}),
+            ...(text ? positionOfYamlPath(text, finding.keyPath) : {}),
+            severity: finding.severity,
+            message: finding.message,
+        });
+    }
+    return errors;
+}
+
 /**
  * Write the generated manifest into the staged package.
  *
+ * The declared `packFolders` is checked against the derived `packs[]` first,
+ * and an unresolvable name **stops the write**: a manifest already known to
+ * describe packs the package does not ship should not reach the stage, where
+ * the next command would deploy it (#81). See {@link packFolderFindings} for
+ * the rule and why its two findings carry different severities.
+ *
  * @param {object} options - As {@link buildManifest}, plus where to write.
  * @param {object} options.config - The resolved content configuration.
  * @param {object} options.packageJson - The repository's `package.json`.
  * @param {string} options.artifact - `system` or `module`.
  * @param {string} options.outDir - Directory to write into.
  * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
+ * @param {string} [options.configFile] - Absolute path of the configuration
+ *   file the manifest was resolved from, so a finding about it can be located.
+ *   Omitting it costs the position, not the finding.
  * @returns {Promise<{path: string, manifest: object}>} Where it went, and what.
+ * @throws {Error} When a `packFolders` entry names a pack the package does not
+ *   ship. Nothing is written in that case.
  */
 export async function writeManifest({
     config,
@@ -347,8 +524,26 @@ export async function writeManifest({
     artifact,
     outDir,
     flags,
+    configFile,
 }) {
     const manifest = buildManifest({ config, packageJson, artifact, flags });
+
+    const errors = reportPackFolders(
+        packFolderFindings({
+            packFolders: manifest.packFolders,
+            packs: manifest.packs,
+        }),
+        configFile,
+    );
+    if (errors) {
+        throw new Error(
+            `packFolders names ${errors} pack${errors === 1 ? "" : "s"} this ` +
+                `package does not ship (reported above). Foundry skips a name ` +
+                `it cannot resolve, so the folder would ship missing those ` +
+                `packs — correct \`packageBuild.manifest.packFolders\`.`,
+        );
+    }
+
     await fs.mkdir(outDir, { recursive: true });
     const outPath = path.join(outDir, `${artifact}.json`);
     // Trailing newline: the file is committed to a release archive and read by

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "5.0.0",
+    "version": "6.1.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/sohl/actors.mjs

@@ -186,8 +186,16 @@ function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
     const shadowed = [];
     for (const itemsSourceDir of itemsSourceDirs) {
         if (!fs.existsSync(itemsSourceDir)) {
+            // The generator orders the actors pass after every Item pass (#73),
+            // so a whole-package build cannot reach this. What can is a run
+            // restricted to this one pack, or a caller constructing the
+            // compiler itself — neither of which reordering a pack list fixes,
+            // so the message no longer suggests it.
             throw new Error(
-                `Items source directory ${itemsSourceDir} does not exist — actors must be generated after items`,
+                `Items source directory ${itemsSourceDir} does not exist — ` +
+                    `a being resolves its embedded items against the Item ` +
+                    `packs' compiled output, so those packs must be compiled ` +
+                    `before this one`,
             );
         }
         for (const name of fs.readdirSync(itemsSourceDir)) {
@@ -310,6 +318,11 @@ export class Actors extends BasePackCompiler {
     static id = "actors";
     static label = "actor";
 
+    // A being's embedded items are resolved against the *output* of the item
+    // passes, so every Item pack compiles before this one. Declared rather than
+    // left to the order `packs:` happens to list (#73).
+    static readsPackOutputOf = Object.freeze(["Item"]);
+
     /** @type {readonly string[]} */
     itemsSourceDirs;
     foreignSourceDirs;

package/sohl/item-fields.mjs

@@ -231,11 +231,6 @@ const GEAR_COMMON = Object.freeze([
         value: true,
         describe: "Whether it is being carried. Possession state.",
     },
-    {
-        to: "isEquipped",
-        value: false,
-        describe: "Whether it is equipped. Possession state.",
-    },
 ]);
 
 /* --------------------------------------------------------------------- */

package/sohl/kb-passes.mjs

@@ -27,35 +27,98 @@
  * map sits, what the API is served at, which GitHub tree to link into — is
  * options, supplied beside the name.
  *
- * Neither pass ever fails a build. A `{@link}` the map does not know degrades to
- * a code span, and a relative link that resolves outside the documentation tree
- * becomes a GitHub blob URL. Both are legible to a reader; a broken link or a
- * failed build for a syntax example in prose would not be.
+ * Neither *rewrite* ever fails a build. A `{@link}` the map does not know
+ * degrades to a code span, and a relative link that resolves outside the
+ * documentation tree becomes a GitHub blob URL. Both are legible to a reader; a
+ * broken link or a failed build for a syntax example in prose would not be.
+ *
+ * Building the bundle is a different matter: a `symbolMap` that is configured
+ * and cannot be used fails, loudly, before a page is rendered (#75). Degrading
+ * a tag the map does not know is a judgement about *prose*; degrading every tag
+ * on the site because the map was never read is a build that lied.
  *
  * @module
  */
 
 import fs from "node:fs";
 import path from "node:path";
+import log from "loglevel";
 
 /**
  * Reads the TypeDoc symbol map, or an empty one.
  *
- * Absent is not an error: the map is generated by `npm run docs`, and a
- * knowledgebase build that runs before it — or in a checkout that has never run
- * it — should publish prose with `{@link}` tags degraded to code spans rather
- * than refuse to build.
+ * **Not configuring a map is the empty case, and it is silent.** The map is
+ * generated by `npm run docs`, and a knowledgebase build in a repository that
+ * has no API documentation should publish prose with `{@link}` tags degraded to
+ * code spans rather than refuse to build.
+ *
+ * **Configuring one that cannot be used is a defect, and it fails the build.**
+ * A missing file, a malformed one, a permissions error and a path typo used to
+ * be indistinguishable from each other *and* from a correctly configured build
+ * with no symbols: a bare `catch` returned `{}` for all five. Nothing then
+ * compares an emitted page against what its source asked for, so the first
+ * observer of a broken map was a reader who clicked nothing, because every
+ * `{@link}` on the published site had quietly become a code span (#75).
+ *
+ * The path is resolved against the **repository root**, never the process cwd.
+ * `site.passOptions.symbolMap` is authored repo-relative, so a cwd-relative
+ * read misses the moment `content-build site` is driven from anywhere but the
+ * repository root — which is exactly how #51's end-to-end verification, running
+ * through `PACKAGE_BUILD_CONFIG` from outside the tree, found this.
  *
  * @param {string|undefined} file - Path to the map, if configured.
+ * @param {string|undefined} repoRoot - The repository root to resolve against.
  * @returns {Record<string, string>} Qualified name → API page path.
+ * @throws {Error} When a configured map cannot be resolved, read, parsed, or is
+ *   not a name → page object.
  */
-function readSymbolMap(file) {
+function readSymbolMap(file, repoRoot) {
     if (!file) return {};
+
+    // Refused rather than quietly resolved against the cwd, which is the
+    // defect this function was fixed for: a fallback would let it return.
+    if (!path.isAbsolute(file) && !repoRoot) {
+        throw new Error(
+            `site.passOptions.symbolMap ${JSON.stringify(file)} is relative ` +
+                `and no repoRoot was supplied to resolve it against`,
+        );
+    }
+    const resolved = path.resolve(repoRoot ?? "", file);
+
+    let raw;
     try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    } catch {
-        return {};
+        raw = fs.readFileSync(resolved, "utf8");
+    } catch (err) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} cannot be read: ` +
+                `${err.message}`,
+        );
     }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} is not valid JSON: ` +
+                `${err.message}`,
+        );
+    }
+
+    // `[]`, `"x"` and `null` all parse, and then every lookup misses — the same
+    // silent degradation reached a different way.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} is not an object mapping ` +
+                `qualified names to API page paths`,
+        );
+    }
+
+    // Reported because a map that loaded and a map that loaded empty are
+    // otherwise indistinguishable without reading the emitted HTML — and an
+    // empty one degrades every tag exactly as a missing one used to.
+    log.info(`resolved ${Object.keys(parsed).length} API symbols from ${file}`);
+    return parsed;
 }
 
 /**
@@ -182,14 +245,18 @@ export function rewriteRepoLinks(body, docRel, options) {
  * Both run inside code-fence protection, so neither can rewrite a fenced example.
  *
  * @param {object} options - Resolved from `site.passOptions`.
- * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map.
+ * @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.
+ * @throws {Error} When a configured `symbolMap` cannot be resolved, read,
+ *   parsed, or is not a name → page object.
  */
 export function sohlKbPass(options) {
-    const symbols = readSymbolMap(options.symbolMap);
+    const symbols = readSymbolMap(options.symbolMap, options.repoRoot);
     const apiBase = options.apiBase ?? "";
     return {
         beforeLinks: (text) => resolveApiLinks(text, symbols, apiBase),

package/types/engine/address-diff.d.mts

@@ -0,0 +1,108 @@
+/**
+ * The address space a set of compiled Item pack directories publishes.
+ *
+ * The directories are read as one space for the same reason the actors pass
+ * reads them as one: a being names an item by `(type, shortcode)` and never by
+ * the pack it happens to ship in. Both sides of a diff are built by this one
+ * function, so a released catalogue extracted by `deps fetch` and a freshly
+ * compiled pack are indexed identically and a difference between them is a real
+ * one rather than an artefact of two readers.
+ *
+ * A missing directory throws rather than reading as an empty space: an empty
+ * baseline would report every address in the package as withdrawn, and an empty
+ * current side would report every address as gone — the loudest possible
+ * output from the quietest possible mistake.
+ *
+ * @param {readonly string[]} dirs - Directories of item JSON.
+ * @returns {Map<string, {id: string, name: string, type: string, shortcode: string, file: string}>}
+ *   Every item, keyed `type:shortcode`.
+ */
+export function readItemAddresses(dirs: readonly string[]): Map<string, {
+    id: string;
+    name: string;
+    type: string;
+    shortcode: string;
+    file: string;
+}>;
+/**
+ * Every address the baseline published that this build does not.
+ *
+ * An address that merely *arrived* is not a finding: adding one breaks nobody.
+ * The arrivals are read only to answer the one question that matters about a
+ * departure — is the document still here under another name?
+ *
+ * @param {Map<string, object>} baseline - The released address space.
+ * @param {Map<string, object>} current - This build's address space.
+ * @param {object} opts
+ * @param {string} opts.baseline - What the baseline is, for the message —
+ *   conventionally `<package>@<version>`.
+ * @returns {Array<object>} One finding per departed address, in address order
+ *   so two runs read the same. `kind` is `"renamed"` (with `to`) or
+ *   `"withdrawn"`.
+ */
+export function diffItemAddresses(baseline: Map<string, object>, current: Map<string, object>, { baseline: label }: {
+    baseline: string;
+}): Array<object>;
+/**
+ * Every content note in a tree, indexed by the document id it authors.
+ *
+ * The address space is read from compiled output because that is what actually
+ * ships; the tree is read only to place a finding somewhere a reader can open
+ * and fix it. Each source answers the question it is good at, and the id is the
+ * exact key that joins them.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Passed to the walk.
+ * @returns {Map<string, string>} Document id → the note's absolute path.
+ */
+export function noteFilesById(contentBase: string, { skipDirectories }?: {
+    skipDirectories?: readonly string[] | undefined;
+}): Map<string, string>;
+/**
+ * Where to send the reader for one finding.
+ *
+ * A rename is fixed in the note that made it, so a finding whose id is still in
+ * this tree is reported at that note's `shortcode:` line — the line the author
+ * just edited. A withdrawal has no such note by definition, so it degrades to
+ * the baseline document, which is the only artefact left that records the
+ * address existing. When neither is readable the position is **dropped**, never
+ * defaulted to `1:1`.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @param {Map<string, string>} noteFiles - From {@link noteFilesById}.
+ * @returns {{file?: string, line?: number, column?: number}} Spreadable
+ *   position fields for {@link formatDiagnostic}.
+ */
+export function locateAddressFinding(finding: object, noteFiles: Map<string, string>): {
+    file?: string;
+    line?: number;
+    column?: number;
+};
+/**
+ * What one finding says, without a locator or a severity.
+ *
+ * The rename message names the identity it matched on, because that is what
+ * separates this from a spelling suggestion: the reader can check the id in
+ * both artefacts. The withdrawal message names no successor, because none is
+ * known — and says so, rather than leaving the reader to wonder whether one was
+ * looked for.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @returns {string} The message.
+ */
+export function addressFindingMessage(finding: object): string;
+/**
+ * One finding, in the standard `file:line:column: severity: message` form.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @param {{file?: string, line?: number, column?: number}} at - From
+ *   {@link locateAddressFinding}.
+ * @param {"warning"|"error"} [severity] - `error` when the caller is gating.
+ * @returns {string} The formatted diagnostic, path first on the line.
+ */
+export function formatAddressFinding(finding: object, at: {
+    file?: string;
+    line?: number;
+    column?: number;
+}, severity?: "warning" | "error"): string;

package/types/engine/base-compiler.d.mts

@@ -57,6 +57,28 @@ export class BasePackCompiler {
      * @type {boolean}
      */
     static convertsWikilinks: boolean;
+    /**
+     * The document types whose **compiled output** this pass reads.
+     *
+     * Empty for every pass that reads only the content tree. The actors pass
+     * is the exception: a being names its embedded items by
+     * `(type, shortcode)`, and it resolves them against the JSON the item
+     * passes wrote — so an Actor pass must run after every Item pass, and it
+     * says so here.
+     *
+     * The generator derives the compile order from this (#73), so the order
+     * `packs:` declares is presentation only — it is the manifest's `packs`
+     * array as well, and a consumer orders that for a reader. A pass that
+     * reads another's output states the dependency once, in the class that
+     * does the reading, instead of every consuming repository having to know
+     * it when writing its pack list.
+     *
+     * A consumer registering a compiler of its own declares its dependencies
+     * the same way; a type no pack declares is simply not waited for.
+     *
+     * @type {readonly string[]}
+     */
+    static readsPackOutputOf: readonly string[];
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.

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

@@ -26,18 +26,69 @@ export function buildLinkIndex(contentBase: string, { manifestDir, skipDirectori
     manifestDir?: string | undefined;
     skipDirectories?: readonly string[] | undefined;
 }): object;
+/**
+ * Every defect in the addresses a package homepage carries.
+ *
+ * **Why the homepage needs its own audit at all.** Every other note addresses
+ * the corpus with wikilinks, which {@link auditLinks} resolves. A homepage does
+ * not and cannot: it is published *verbatim* by every publishing mode, including
+ * the homepage-only mode two fan-licensed packages ship under, where the content
+ * tree is never walked and there is no index for a wikilink to resolve against.
+ * So a landing addresses the web the way the web does — markdown links and
+ * `url:` fields — and nothing was looking at those. SoHL's landing pointed at
+ * `kb/creature/` and `kb/character/` from the day those types merged into
+ * `being`: two 404s on the package's front page, through every build.
+ *
+ * **What is checkable, stated plainly.** Only an address into this site is, and
+ * only against facts this build already holds:
+ *
+ * - A **retired content type** in the path. The engine knows what used to exist
+ *   and what replaced it, so this is a fact rather than a guess — and it is
+ *   exactly the SoHL defect.
+ * - A **hardcoded absolute URL** into this package's own prefix, or into one a
+ *   vendored manifest names. Both have a better form to write, which is why they
+ *   are reported; a bare `/<package>/` is left alone, because a package
+ *   homepage is in no manifest and there is nothing better to write.
+ * - A **root-relative `url:`**, which the theme's `relURL` prefixes a second
+ *   time. `href:` means "already resolved, use verbatim", so the same leading
+ *   slash is correct there and is not reported.
+ * - A **wikilink**, which nothing on this page will ever resolve.
+ *
+ * **What is not checkable, and is not attempted.** Whether an external URL
+ * answers — there is no network at build time, and a build must not fail because
+ * a third party is down. And whether a live in-site address names a page that
+ * exists: several of the surfaces a landing routes to are produced by other
+ * tools entirely (generated API documentation, hand-authored Hugo sections), so
+ * this build does not hold the set of published pages and would report a working
+ * link as dead.
+ *
+ * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
+ * @returns {Array<{note: object, field: string, url: string, text: string,
+ *   occurrence: number, message: string}>} One finding per defect, `text` and
+ *   `occurrence` locating it in the note's raw source.
+ */
+export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Array<{
+    note: object;
+    field: string;
+    url: string;
+    text: string;
+    occurrence: number;
+    message: string;
+}>;
 /**
  * Every link in a tree that lands nowhere.
  *
  * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
  * @returns {{deadAnchors: object[], deadAddresses: object[],
- *   frontmatterLinks: object[], usedManifest: Set<string>}} The findings, and
- *   which addresses a foreign manifest answered.
+ *   frontmatterLinks: object[], homepageLinks: object[],
+ *   usedManifest: Set<string>}} The findings, and which addresses a foreign
+ *   manifest answered.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];
     deadAddresses: object[];
     frontmatterLinks: object[];
+    homepageLinks: object[];
     usedManifest: Set<string>;
 };
 /**

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

@@ -16,12 +16,15 @@ export function isValidShortcode(value: unknown): boolean;
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names the walk
  *   ignores. Defaults to the configured list.
+ * @param {string} [opts.contentPackage] - The package this tree builds, for the
+ *   homepage rule. Dropped from that finding when unknown rather than guessed.
  * @returns {{findings: Array<{file: string, line?: number, column?: number,
  *   severity: "error"|"warning", message: string}>, notes: number,
  *   keys: number}} The findings, and what was inspected to produce them.
  */
-export function lintContentTree(contentBase: string, { skipDirectories }?: {
+export function lintContentTree(contentBase: string, { skipDirectories, contentPackage }?: {
     skipDirectories?: readonly string[] | undefined;
+    contentPackage?: string | undefined;
 }): {
     findings: Array<{
         file: string;