@heroiclands/package-build 5.0.0 → 6.1.0

package/engine/homepage.mjs

@@ -49,13 +49,19 @@
  *
  * **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.
  *
@@ -96,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.
  *
@@ -148,3 +354,110 @@ export function homepageFrontmatter(fm, { contentPackage, title }) {
     delete data.aliases;
     return data;
 }
+
+/**
+ * An inline markdown link — `[text](target)`, but not an image.
+ *
+ * Reference-style links are deliberately not matched: a landing's prose fields
+ * are single YAML scalars with nowhere to put a link definition, so a `[x][y]`
+ * in one could never resolve and is not an address anybody wrote.
+ *
+ * @type {RegExp}
+ */
+const MARKDOWN_LINK = /(?<!!)\[[^\]]*\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g;
+
+/**
+ * The two frontmatter keys that hold an address, and what each one means.
+ *
+ * They are **not** interchangeable, and a check that treated them as one would
+ * be wrong about both. The theme resolves a `url` against the site with
+ * `relURL`, so a package writes `kb/rules/` and is served `/sohl/kb/rules/`
+ * without ever naming its own prefix. An `href` is an address that is *already*
+ * resolved and is used verbatim — which is what `cards.source: sections` fills
+ * in, since a section's permalink already carries the prefix.
+ *
+ * So a leading `/` is a defect in a `url` (it is prefixed a second time) and
+ * correct in an `href`.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const HOMEPAGE_ADDRESS_KEYS = Object.freeze(new Set(["url", "href"]));
+
+/**
+ * Collect the markdown links in one prose value.
+ *
+ * @param {string} text - The value.
+ * @param {string} field - Where it came from.
+ * @param {string} kind - The address kind to record.
+ * @param {object[]} out - Accumulator.
+ * @param {boolean} [skipCode] - Whether to ignore links inside code.
+ */
+function collectProse(text, field, kind, out, skipCode = false) {
+    const pattern = new RegExp(MARKDOWN_LINK.source, "g");
+    const matches =
+        skipCode ?
+            matchAllOutsideCode(text, pattern)
+        :   [...text.matchAll(pattern)];
+    for (const m of matches) out.push({ field, url: m[1], kind });
+}
+
+/**
+ * Every address a homepage carries, wherever it is written.
+ *
+ * **Both halves of the page are in scope, and that is the finding rather than
+ * the assumption.** Of the six homepages authored today, four carry every link
+ * in the body as ordinary markdown and two carry them in `landing:` — and the
+ * one whose dead links prompted the check has an *empty body*, so a body-only
+ * reading would have found nothing at all on it. A dead link in a card is
+ * exactly as broken as one in a paragraph.
+ *
+ * Three shapes are gathered, and the caller needs to tell them apart because
+ * the rules differ:
+ *
+ * - **`url`** — package-relative, resolved against the site by the theme.
+ * - **`href`** — already resolved, used verbatim.
+ * - **prose and body markdown links** — emitted as written and resolved by the
+ *   browser against the landing's own address, which *is* the package root, so
+ *   a relative one means the same thing a `url` does.
+ *
+ * `banner:` is not an address: it is an image path resolved through the CDN
+ * base, and `banner: none` is a sentinel rather than a target. Top-level
+ * `title` and `description` are not walked either — they are set as text, never
+ * rendered as markdown.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {string} [body] - The note's markdown body.
+ * @returns {Array<{field: string, url: string, kind: string}>} Every address,
+ *   frontmatter first and then the body, each with the dotted path it was
+ *   written at.
+ */
+export function homepageAddresses(fm, body = "") {
+    const out = [];
+
+    const walk = (value, field) => {
+        if (typeof value === "string") {
+            collectProse(value, field, "prose", out);
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((v, i) => walk(v, `${field}[${i}]`));
+            return;
+        }
+        if (!value || typeof value !== "object") return;
+        for (const [key, v] of Object.entries(value)) {
+            const child = `${field}.${key}`;
+            // An address field holds an address, not prose: reading it for
+            // markdown links as well would report the same target twice
+            // whenever one happened to look like a link.
+            if (HOMEPAGE_ADDRESS_KEYS.has(key) && typeof v === "string") {
+                out.push({ field: child, url: v, kind: key });
+                continue;
+            }
+            walk(v, child);
+        }
+    };
+
+    walk(fm?.landing, "landing");
+    collectProse(String(body ?? ""), "body", "body", out, true);
+    return out;
+}

package/engine/pack-config.mjs

@@ -453,6 +453,9 @@ function loadCodeConfig(configPath) {
 /** The loaded configuration, memoised — the file is read at most once. */
 let loaded;
 
+/** The file {@link loadPackConfig} read, alongside the memoised result. */
+let loadedFrom;
+
 /**
  * The consuming repository's resolved, frozen configuration.
  *
@@ -492,5 +495,23 @@ export function loadPackConfig() {
                 YAML.parse(fs.readFileSync(configPath, "utf8")),
                 configPath,
             );
+    loadedFrom = configPath;
     return loaded;
 }
+
+/**
+ * The file {@link loadPackConfig} resolved the configuration from.
+ *
+ * A diagnostic about a *configured* value has to name the file it was declared
+ * in, and re-deriving that path at the point of the finding would be a second
+ * resolution free to disagree with the first — the `PACKAGE_BUILD_CONFIG`
+ * override, the upward walk and the one-file-per-directory rule all have to
+ * come out the same way. This reports the path actually read.
+ *
+ * @returns {string} Its absolute path.
+ * @throws {Error} As {@link loadPackConfig}, when there is no configuration.
+ */
+export function packConfigPath() {
+    loadPackConfig();
+    return /** @type {string} */ (loadedFrom);
+}

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 }`.
@@ -291,10 +292,16 @@ export function collectHomepages(contentBase, ctx) {
  * Writes each homepage at the package's own root.
  *
  * Its own writer, deliberately small. A homepage is authored markdown published
- * verbatim — no table expansion, no section landing, and (until #54) no link
- * resolution — so routing it through {@link renderPages} would buy it a pipeline
- * it has no input for, and would make homepage-only mode depend on the index,
- * the foreign manifests and the table universe that mode exists to not build.
+ * verbatim — no table expansion, no section landing and no link resolution — so
+ * routing it through {@link renderPages} would buy it a pipeline it has no input
+ * for, and would make homepage-only mode depend on the index, the foreign
+ * manifests and the table universe that mode exists to not build.
+ *
+ * **Verbatim is the answer to #54, not a gap left by it.** A landing's links
+ * could not be *resolved* here without giving `homepage` mode the index its
+ * licensing fence exists to not build, so they are **checked** instead:
+ * {@link auditHomepageLinks} reads the `landing:` addresses and the body's
+ * markdown links, and reports a wikilink on the page rather than resolving one.
  *
  * @param {string} outRoot - The package's site root — the configured `site.out`,
  *   one level above the content mount.
@@ -339,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: [],
@@ -397,6 +408,7 @@ export function siteGates(pages, findings, { manifestDir }) {
  */
 export function emptyGates() {
     return {
+        homepages: [],
         frontmatterLinks: [],
         slugErrors: [],
         collisions: [],
@@ -412,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 ||
@@ -449,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.
  *
@@ -488,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
@@ -503,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;
@@ -654,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;
     }
@@ -842,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).