@heroiclands/package-build 6.0.0 → 6.1.0

package/engine/homepage.mjs

@@ -49,14 +49,18 @@
  *
  * **Its address is the package's, not the note's.** A homepage publishes at
  * `/<contentPackage>/` because that is where the package is, so `name.full`,
- * `shortcode` and `id` decide nothing on it (#53 refuses them outright; this
- * module simply never reads them). It compiles into no document, so it carries
+ * `shortcode` and `id` decide nothing on it — nothing here reads them, and
+ * {@link HOMEPAGE_REFUSED_FIELDS} refuses them outright rather than leaving an
+ * author to believe they worked (#53). It compiles into no document, so it carries
  * no compendium UUID and appears in no pack and in no link-manifest entry.
  *
  * @module
  */
 
+import fs from "node:fs";
+
 import { matchAllOutsideCode } from "./code-fences.mjs";
+import { formatLocator, positionInFrontmatter } from "./diagnostics.mjs";
 
 /**
  * The note type that compiles to the package homepage.
@@ -98,6 +102,206 @@ export function isHomepage(fm) {
     return Boolean(fm) && fm.type === HOMEPAGE_TYPE;
 }
 
+/**
+ * The top-level fields a homepage refuses, and what each one would decide (#53).
+ *
+ * A note's URL derives from `name.full` and its identity from
+ * `(type, shortcode)`. The homepage is the one page for which neither holds: it
+ * publishes at `/<package>/`, fixed by the package id. An author fluent in the
+ * conventions writes them here expecting exactly what they do everywhere else,
+ * and gets none of it.
+ *
+ * **They were never inert, which is why ignoring them was the wrong answer.** A
+ * `shortcode` puts the note in the address index and in the `dataview` link
+ * universe, so `[[homepage-<shortcode>]]` resolves *green* — to
+ * `homepage/<slug>/`, an address derived from `name.full` and published by
+ * nothing, because a homepage is written to {@link HOMEPAGE_DESTINATION} at the
+ * package root. A build that reports a live link to a 404 is worse than one
+ * that says nothing. It also inflates `content-build lint`'s address tally, so
+ * the lint and the link manifest disagree about what the package publishes.
+ *
+ * **A named class, not an allow-list, and that boundary is the decision.** The
+ * documented envelope is `type` plus an optional `title`, and `landing`,
+ * `description` and `banner` are legitimate beside them — but a homepage's
+ * frontmatter is *emitted into the published page*
+ * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
+ * parameter this build has never heard of and has no standing to refuse.
+ * Rejecting unknown keys would make every new theme parameter wait on a
+ * package-build release. What is refused is the specific class that makes a
+ * false claim about *where this page is*.
+ *
+ * `aliases` is deliberately not in the class: {@link homepageFrontmatter}
+ * already drops it from every emitted page, with a reason of its own, so
+ * authoring one is the same no-op it is on any other page rather than a wrong
+ * belief about this one's address.
+ *
+ * @type {ReadonlyMap<string, string>}
+ */
+export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
+    new Map([
+        [
+            "name",
+            "`name` decides nothing on a `type: homepage` note: a page's slug " +
+                "derives from `name.full`, and a homepage's destination is " +
+                `fixed — it is written to \`${HOMEPAGE_DESTINATION}\` at the ` +
+                "package's own address, `/<package>/`. Write `title:` for what " +
+                "the page is called, and delete `name`",
+        ],
+        [
+            "shortcode",
+            "`shortcode` decides nothing on a `type: homepage` note: this " +
+                "page's address is the package's own, `/<package>/`, fixed by " +
+                "the package id. It is not ignored either — it puts the note " +
+                "in the address index, so `[[homepage-<shortcode>]]` resolves " +
+                "to a page the site build never writes. Delete it",
+        ],
+        [
+            "id",
+            "`id` decides nothing on a `type: homepage` note: it is the " +
+                "Foundry document id a compendium UUID is built from, and a " +
+                "homepage compiles into no document — it appears in no pack " +
+                "and in no link manifest. Delete it",
+        ],
+    ]),
+);
+
+/**
+ * The address-bearing fields one note authors, in the order it authored them.
+ *
+ * Authoring order rather than declaration order, so a caller emitting one
+ * diagnostic per finding emits them top to bottom down the file — the order a
+ * reader and a compiler-output parser both expect.
+ *
+ * Presence is the whole test: `shortcode:` authored empty still says "this page
+ * has an address of its own", and a value cannot make the claim true.
+ *
+ * Returned without a locator, because the two things that would supply one —
+ * the raw note text and the position helper — belong to the caller. This
+ * mirrors {@link module:engine/retired-fields}, whose retired-field messages
+ * are likewise positioned by whoever reports them.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {Array<{key: string, message: string}>} One entry per field the note
+ *   authored, empty for any note that is not a homepage.
+ */
+export function checkHomepageAddressFields(fm) {
+    if (!isHomepage(fm)) return [];
+    const out = [];
+    for (const key of Object.keys(fm)) {
+        const message = HOMEPAGE_REFUSED_FIELDS.get(key);
+        if (message) out.push({ key, message });
+    }
+    return out;
+}
+
+/**
+ * Require exactly one homepage note in a content tree (#52).
+ *
+ * "Exactly one" is two rules, and they are **one severity** because they are
+ * one defect: a package whose front page is not the page a person chose.
+ *
+ * - _None_ and the package serves nothing at `/<package>/`. That is the failure
+ *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
+ *   homepage(s)` and exits 0.
+ * - _Two_ and it serves a page nobody chose. Every homepage is written to the
+ *   same {@link HOMEPAGE_DESTINATION}, so the second overwrites the first and
+ *   the package's front page is decided by the order the walk happened to reach
+ *   the files in — by *filename*, on a type whose whole point is that it is
+ *   routed by frontmatter. There is no "first wins" convention to fall back on,
+ *   so nothing here can pick the right one.
+ *
+ * Neither has a safe default, so neither is a warning. A warning is the right
+ * severity for something a build can proceed past correctly, and a build that
+ * proceeds past either of these publishes the wrong front page while reporting
+ * success — which is the exact outcome a warning would be tolerating.
+ *
+ * **Two is reported once per note, not once for the tree.** Each note is a
+ * place an author has to open and edit, and a single finding saying "there are
+ * two" sends them hunting for the second.
+ *
+ * **None is located at the tree, honestly.** There is no file to name, so the
+ * locator is the content root — the directory the note is missing from, which
+ * is a real path and the one the author adds it to. No line and no column are
+ * invented for it, per the diagnostic rules in
+ * {@link module:engine/diagnostics}. {@link lintContentTree} already reports an
+ * empty walk against the same locator.
+ *
+ * The rule reads no `site:` configuration and does not vary by
+ * `publish.site`: that setting chooses whether the *content* surfaces are
+ * published, and the homepage is the floor underneath both modes.
+ *
+ * @param {ReadonlyArray<{file: string}>} found - The homepage notes, in walk
+ *   order. Paths may be absolute or relative to the working directory.
+ * @param {object} options - Options.
+ * @param {string} options.contentBase - Root of the content tree, for the
+ *   locator when there is no file to name.
+ * @param {string} [options.contentPackage] - The package this tree builds.
+ *   Dropped from the message when unknown rather than guessed.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string}>} The findings, one per offending note.
+ */
+export function checkHomepageCount(found, { contentBase, contentPackage }) {
+    const pages = found ?? [];
+    const named = contentPackage ? ` "${contentPackage}"` : "";
+    const address = contentPackage ? ` /${contentPackage}/` : "";
+
+    if (pages.length === 0) {
+        return [
+            {
+                file: contentBase,
+                severity: "error",
+                message:
+                    `holds no \`type: homepage\` note, so ` +
+                    `${contentPackage ? `package${named}` : "this package"} ` +
+                    `publishes nothing at its own address${address} — a ` +
+                    `package's front page is one authored note in this tree, ` +
+                    `routed by \`type:\` rather than by filename`,
+            },
+        ];
+    }
+    if (pages.length === 1) return [];
+
+    return pages.map((page) => {
+        const others = pages
+            .filter((p) => p !== page)
+            .map((p) => formatLocator({ file: p.file }));
+        return {
+            file: page.file,
+            ...positionOfType(page.file),
+            severity: "error",
+            message:
+                `duplicate \`type: homepage\` note, also declared by ` +
+                `${others.join(", ")}; a package has one front page` +
+                `${contentPackage ? `, at${address},` : ""} and every ` +
+                `homepage is written to the same \`${HOMEPAGE_DESTINATION}\` — ` +
+                `so the one the walk reaches last silently overwrites the rest`,
+        };
+    });
+}
+
+/**
+ * Where a note declares `type: homepage`, when the file can still be read.
+ *
+ * A separate read rather than a raw text threaded through every caller: the
+ * two call sites hold different shapes (a lint note, a collected page) and this
+ * runs only on a tree that is already failing.
+ *
+ * @param {string} file - Path to the note.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when the file cannot be read — dropped rather than guessed.
+ */
+function positionOfType(file) {
+    try {
+        return positionInFrontmatter(
+            fs.readFileSync(file, "utf8"),
+            "type",
+            HOMEPAGE_TYPE,
+        );
+    } catch {
+        return {};
+    }
+}
+
 /**
  * The title a homepage publishes under.
  *

package/engine/site-build.mjs

@@ -65,6 +65,7 @@ import { loadPackConfig } from "./pack-config.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 import {
     HOMEPAGE_DESTINATION,
+    checkHomepageCount,
     homepageFrontmatter,
     homepageTitle,
     isHomepage,
@@ -269,9 +270,9 @@ export function collectTreePages(tree, ctx) {
  * packages ship under is a property of the code path rather than of a
  * configuration that happens to be empty (#55).
  *
- * Returned as a list rather than as the one note there should be. Requiring
- * exactly one is #52's, and it is a separate decision — this reports what it
- * found so a count is visible either way.
+ * Returned as a list rather than as the one note there should be, because the
+ * count is what {@link checkHomepageCount} judges (#52) — this walk reports
+ * what it found, and {@link buildSite} decides whether that is one.
  *
  * @param {string} contentBase - Absolute path to the content tree.
  * @param {object} ctx - `{ skipDirectories }`.
@@ -345,6 +346,10 @@ export function writeHomepages(outRoot, pages, config) {
  */
 export function siteGates(pages, findings, { manifestDir }) {
     const out = {
+        // Always empty here: the homepage count is decided in `buildSite`
+        // before the content walk, and a failing count returns without ever
+        // reaching these gates (#52). Present so every caller reads one shape.
+        homepages: [],
         frontmatterLinks: findings.fmLinkFindings ?? [],
         slugErrors: findings.slugFindings ?? [],
         collisions: [],
@@ -403,6 +408,7 @@ export function siteGates(pages, findings, { manifestDir }) {
  */
 export function emptyGates() {
     return {
+        homepages: [],
         frontmatterLinks: [],
         slugErrors: [],
         collisions: [],
@@ -418,6 +424,7 @@ export function emptyGates() {
 /** Whether any gate produced a finding. */
 export function gatesFailed(gates) {
     return Boolean(
+        gates.homepages.length ||
         gates.frontmatterLinks.length ||
         gates.slugErrors.length ||
         gates.collisions.length ||
@@ -455,6 +462,39 @@ export function tableUniverse(pages) {
     return byPackage;
 }
 
+/**
+ * The front matter a section's landing states about itself.
+ *
+ * The section metadata a configuration resolved, ready to be written or merged
+ * onto a page. Two things happen here and nothing else does:
+ *
+ * - **`title` leads.** It is the one key every landing has carried since the
+ *   first one, and a landing whose block opened with `banner:` would be a
+ *   gratuitous diff on every consumer's tree.
+ * - **An absent value is left off**, not written as `undefined` — which is not
+ *   a value YAML can carry, and would abort the serializer.
+ *
+ * Everything else the section declared is passed through. That is the point of
+ * the function: before #91 both writers transcribed `title` and `banner` by
+ * name, so the vocabulary lived in three places — the schema that admits a key
+ * and the two writers that copy it — and a key added to the schema alone
+ * validated cleanly and then reached no page. The *schema* is the bound worth
+ * keeping (see `normalizeSectionMeta`, which refuses a key it does not know and
+ * names it); a second, silent bound in the writers is not.
+ *
+ * @param {object} meta - A resolved `site.sections` / `site.readmeSections`
+ *   entry.
+ * @returns {object} Its front matter, `title` first.
+ */
+export function sectionFrontmatter(meta) {
+    const data = { title: meta.title };
+    for (const [key, value] of Object.entries(meta)) {
+        if (key === "title" || value === undefined) continue;
+        data[key] = value;
+    }
+    return data;
+}
+
 /**
  * The frontmatter a page publishes with.
  *
@@ -494,12 +534,11 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
         if (decorate) decorate(data, page);
         if (isReadme) {
             const meta = readmeSections[sec];
-            if (meta) {
-                data.title = meta.title;
-                // Guarded: a title-only entry would otherwise emit
-                // `banner: undefined`, which the YAML serializer rejects.
-                if (meta.banner) data.banner = meta.banner;
-            }
+            // What the section says about itself wins over what its README
+            // happens to carry — the landing has to match the card linking to
+            // it. Assigned rather than transcribed key by key, so a section's
+            // vocabulary is decided in one place (#91).
+            if (meta) Object.assign(data, sectionFrontmatter(meta));
         }
     } else {
         // A tree's own landing describes the *mount*, and nothing beneath it. A
@@ -509,7 +548,7 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
         const isSectionRoot = path.posix.dirname(page.rel) === ".";
         const meta = isReadme && isSectionRoot ? readmeSections[sec] : null;
         data = { ...fm, title: meta?.title ?? fm.title ?? name };
-        if (meta?.banner) data.banner = meta.banner;
+        if (meta) Object.assign(data, sectionFrontmatter(meta));
     }
     delete data.aliases;
     return data;
@@ -660,15 +699,11 @@ export function writeSectionLandings(
     for (const [sec, meta] of Object.entries(sections)) {
         const dir = path.join(outRoot, sec);
         fs.mkdirSync(dir, { recursive: true });
-        // A section may have no hero: the images are CDN assets and not every
-        // section has one. An explicit `banner: undefined` is not a value YAML
-        // can carry, so the key is left off entirely.
+        // Whatever the section declared, not a list of keys named here — see
+        // {@link sectionFrontmatter} for why the two lists were one too many.
         fs.writeFileSync(
             path.join(dir, "_index.md"),
-            matter.stringify("", {
-                title: meta.title,
-                ...(meta.banner ? { banner: meta.banner } : {}),
-            }),
+            matter.stringify("", sectionFrontmatter(meta)),
         );
         written += 1;
     }
@@ -848,12 +883,32 @@ export function buildSite({ config, outRoot } = {}) {
         scheme,
     };
 
+    const homepages = collectHomepages(resolved.paths.content, ctx).pages;
+
+    // Exactly one homepage, and checked here — before the output tree is
+    // cleared and before either mode branches (#52). Before the clear, because
+    // a gate that fired after it would have destroyed a good site to report a
+    // bad tree. Before the branch, because the requirement does not vary by
+    // mode: `publish.site` chooses whether the *content* surfaces are
+    // published, and the homepage is the floor beneath both.
+    const homepageFindings = checkHomepageCount(homepages, {
+        contentBase: resolved.paths.content,
+        contentPackage: resolved.contentPackage,
+    });
+    if (homepageFindings.length) {
+        return {
+            gates: { ...emptyGates(), homepages: homepageFindings },
+            manifests: null,
+            tableErrors: [],
+            wikiErrors: [],
+            stats: null,
+        };
+    }
+
     // The whole tree is a build artifact, regenerated every run: a page whose
     // note was deleted or renamed would otherwise linger and keep publishing.
     fs.rmSync(outBase, { recursive: true, force: true });
 
-    const homepages = collectHomepages(resolved.paths.content, ctx).pages;
-
     // Homepage-only stops here, and stopping is the point: nothing below reads
     // the content tree for pages, so `sohl-kethira-basic` and `harn-adventures`
     // cannot publish one whatever else their `site:` block declares (#55).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "6.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/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/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;

package/types/engine/homepage.d.mts

@@ -5,6 +5,87 @@
  * @returns {boolean} Whether it is a homepage note.
  */
 export function isHomepage(fm: object | null | undefined): boolean;
+/**
+ * The address-bearing fields one note authors, in the order it authored them.
+ *
+ * Authoring order rather than declaration order, so a caller emitting one
+ * diagnostic per finding emits them top to bottom down the file — the order a
+ * reader and a compiler-output parser both expect.
+ *
+ * Presence is the whole test: `shortcode:` authored empty still says "this page
+ * has an address of its own", and a value cannot make the claim true.
+ *
+ * Returned without a locator, because the two things that would supply one —
+ * the raw note text and the position helper — belong to the caller. This
+ * mirrors {@link module:engine/retired-fields}, whose retired-field messages
+ * are likewise positioned by whoever reports them.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {Array<{key: string, message: string}>} One entry per field the note
+ *   authored, empty for any note that is not a homepage.
+ */
+export function checkHomepageAddressFields(fm: object | null | undefined): Array<{
+    key: string;
+    message: string;
+}>;
+/**
+ * Require exactly one homepage note in a content tree (#52).
+ *
+ * "Exactly one" is two rules, and they are **one severity** because they are
+ * one defect: a package whose front page is not the page a person chose.
+ *
+ * - _None_ and the package serves nothing at `/<package>/`. That is the failure
+ *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
+ *   homepage(s)` and exits 0.
+ * - _Two_ and it serves a page nobody chose. Every homepage is written to the
+ *   same {@link HOMEPAGE_DESTINATION}, so the second overwrites the first and
+ *   the package's front page is decided by the order the walk happened to reach
+ *   the files in — by *filename*, on a type whose whole point is that it is
+ *   routed by frontmatter. There is no "first wins" convention to fall back on,
+ *   so nothing here can pick the right one.
+ *
+ * Neither has a safe default, so neither is a warning. A warning is the right
+ * severity for something a build can proceed past correctly, and a build that
+ * proceeds past either of these publishes the wrong front page while reporting
+ * success — which is the exact outcome a warning would be tolerating.
+ *
+ * **Two is reported once per note, not once for the tree.** Each note is a
+ * place an author has to open and edit, and a single finding saying "there are
+ * two" sends them hunting for the second.
+ *
+ * **None is located at the tree, honestly.** There is no file to name, so the
+ * locator is the content root — the directory the note is missing from, which
+ * is a real path and the one the author adds it to. No line and no column are
+ * invented for it, per the diagnostic rules in
+ * {@link module:engine/diagnostics}. {@link lintContentTree} already reports an
+ * empty walk against the same locator.
+ *
+ * The rule reads no `site:` configuration and does not vary by
+ * `publish.site`: that setting chooses whether the *content* surfaces are
+ * published, and the homepage is the floor underneath both modes.
+ *
+ * @param {ReadonlyArray<{file: string}>} found - The homepage notes, in walk
+ *   order. Paths may be absolute or relative to the working directory.
+ * @param {object} options - Options.
+ * @param {string} options.contentBase - Root of the content tree, for the
+ *   locator when there is no file to name.
+ * @param {string} [options.contentPackage] - The package this tree builds.
+ *   Dropped from the message when unknown rather than guessed.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string}>} The findings, one per offending note.
+ */
+export function checkHomepageCount(found: ReadonlyArray<{
+    file: string;
+}>, { contentBase, contentPackage }: {
+    contentBase: string;
+    contentPackage?: string | undefined;
+}): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "error";
+    message: string;
+}>;
 /**
  * The title a homepage publishes under.
  *
@@ -107,6 +188,42 @@ export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
  * @type {string}
  */
 export const HOMEPAGE_DESTINATION: string;
+/**
+ * The top-level fields a homepage refuses, and what each one would decide (#53).
+ *
+ * A note's URL derives from `name.full` and its identity from
+ * `(type, shortcode)`. The homepage is the one page for which neither holds: it
+ * publishes at `/<package>/`, fixed by the package id. An author fluent in the
+ * conventions writes them here expecting exactly what they do everywhere else,
+ * and gets none of it.
+ *
+ * **They were never inert, which is why ignoring them was the wrong answer.** A
+ * `shortcode` puts the note in the address index and in the `dataview` link
+ * universe, so `[[homepage-<shortcode>]]` resolves *green* — to
+ * `homepage/<slug>/`, an address derived from `name.full` and published by
+ * nothing, because a homepage is written to {@link HOMEPAGE_DESTINATION} at the
+ * package root. A build that reports a live link to a 404 is worse than one
+ * that says nothing. It also inflates `content-build lint`'s address tally, so
+ * the lint and the link manifest disagree about what the package publishes.
+ *
+ * **A named class, not an allow-list, and that boundary is the decision.** The
+ * documented envelope is `type` plus an optional `title`, and `landing`,
+ * `description` and `banner` are legitimate beside them — but a homepage's
+ * frontmatter is *emitted into the published page*
+ * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
+ * parameter this build has never heard of and has no standing to refuse.
+ * Rejecting unknown keys would make every new theme parameter wait on a
+ * package-build release. What is refused is the specific class that makes a
+ * false claim about *where this page is*.
+ *
+ * `aliases` is deliberately not in the class: {@link homepageFrontmatter}
+ * already drops it from every emitted page, with a reason of its own, so
+ * authoring one is the same no-op it is on any other page rather than a wrong
+ * belief about this one's address.
+ *
+ * @type {ReadonlyMap<string, string>}
+ */
+export const HOMEPAGE_REFUSED_FIELDS: ReadonlyMap<string, string>;
 /**
  * The two frontmatter keys that hold an address, and what each one means.
  *