@heroiclands/package-build 22.3.1 → 22.4.0

package/engine/site-root.mjs

@@ -15,12 +15,16 @@
  * inside the prefix is published as a text file and never applied. Hugo owns
  * everything under the prefix; this owns what sits beside it.
  *
- * **One implementation, because it is one policy.** What is indexable, where
- * the prefix root sends a reader, and how long that answer is cached are
- * decisions about the hosting rather than about any one package. Held in each
- * consumer they are the same file with one constant changed, which is a file
- * that drifts — and the drift is invisible, because nobody reads all of the
- * copies at once.
+ * **One file, `_headers`.** The prefix root is the homepage — the site build
+ * writes it as the mount's `_index.md` — so nothing redirects, and no
+ * `_redirects` is written. One left beside the site by an earlier build is
+ * removed rather than left to send every reader somewhere nothing publishes.
+ *
+ * **One implementation, because it is one policy.** What is indexable is a
+ * decision about the hosting rather than about any one package. Held in each
+ * consumer it is the same file with one constant changed, which is a file that
+ * drifts — and the drift is invisible, because nobody reads all of the copies
+ * at once.
  *
  * @module
  */
@@ -39,19 +43,6 @@ import path from "node:path";
  */
 export const ORIGIN_SUFFIX = "pkg.heroiclands.org";
 
-/**
- * Where a package's landing is served, now that it is an addressed page.
- *
- * The site build emits the homepage at its own address rather than as the
- * site root's `_index.md`, so the prefix root is a redirect to it.
- *
- * @param {string} pkg - The content package name.
- * @returns {string} The landing's path.
- */
-export function landingPath(pkg) {
-    return `/${pkg}/homepage-root/`;
-}
-
 /**
  * Suppress indexing of every address a deployment answers on but nobody
  * advertises.
@@ -85,54 +76,25 @@ export function noindexHeaders() {
 }
 
 /**
- * The lifetime pinned on the prefix-root redirect, and why it is pinned.
+ * The `_headers` file's contents: the `noindex` rules, and nothing else.
  *
- * Cloudflare Pages sets no `Cache-Control` on a redirect it generates — those
- * responses carry `location` and nothing else — and a 301 with no lifetime is
- * cached by a browser indefinitely, on the most-linked URL there is. An hour
- * keeps the 301's canonical signal without the permanence.
+ * No `Cache-Control` is pinned on the prefix root. It is the homepage, and a
+ * lifetime on it would hold a stale copy at the most-linked address after a
+ * deploy; Pages' own defaults for a page apply.
  *
- * @param {string} pkg - The content package name.
- * @returns {string[]} The header block's lines.
- */
-export function cacheHeaders(pkg) {
-    return [
-        `/${pkg}/`,
-        "  Cache-Control: max-age=3600",
-        "",
-        `/${pkg}`,
-        "  Cache-Control: max-age=3600",
-        "",
-    ];
-}
-
-/**
- * Both forms of the prefix root, because Pages matches the raw path.
- *
- * Redirect matching runs before any trailing-slash or `index.html` handling, so
- * `/<pkg>` and `/<pkg>/` are distinct keys and a rule on one does not catch the
- * other.
- *
- * @param {string} pkg - The content package name.
- * @returns {string} The `_redirects` file's contents.
- */
-export function redirects(pkg) {
-    const to = landingPath(pkg);
-    return [`/${pkg}/   ${to}   301`, `/${pkg}    ${to}   301`, ""].join("\n");
-}
-
-/**
- * The `_headers` file's contents.
- *
- * @param {string} pkg - The content package name.
  * @returns {string} The file's contents.
  */
-export function headers(pkg) {
-    return [...noindexHeaders(), ...cacheHeaders(pkg)].join("\n");
+export function headers() {
+    return noindexHeaders().join("\n");
 }
 
 /**
- * Write `_headers` and `_redirects` beside the rendered site.
+ * Write `_headers` beside the rendered site, and remove any `_redirects`.
+ *
+ * The removal is part of owning the root: a `_redirects` this build did not
+ * write is one an earlier build left, and Cloudflare Pages applies whatever
+ * sits there. Left in place it would redirect the prefix root — the homepage —
+ * to an address nothing publishes.
  *
  * @param {object} options - Options.
  * @param {string} options.pkg - The content package name, which is also the
@@ -152,14 +114,8 @@ export function writeSiteRoot({ pkg, out }) {
         );
     }
 
-    const written = [];
-    for (const [name, body] of [
-        ["_headers", headers(pkg)],
-        ["_redirects", redirects(pkg)],
-    ]) {
-        const file = path.join(root, name);
-        fs.writeFileSync(file, body);
-        written.push(file);
-    }
-    return { files: written };
+    const file = path.join(root, "_headers");
+    fs.writeFileSync(file, headers());
+    fs.rmSync(path.join(root, "_redirects"), { force: true });
+    return { files: [file] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.3.1",
+    "version": "22.4.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/content-config.d.mts

@@ -133,10 +133,9 @@ export const DEFAULT_ADDRESS_SCHEME: Readonly<{
  * and the default.
  *
  * - `homepage` — the authored homepage, and **no other page**. The content tree
- *   is not walked for pages, `site.sections` / `site.landing` emit nothing,
- *   and nothing serves a page for its addresses.
- * - `content` — the homepage *plus* every page the content tree publishes: the
- *   knowledgebase and the section landings.
+ *   is not walked for pages, and nothing serves a page for its addresses.
+ * - `content` — the homepage *plus* every page the content tree publishes, one
+ *   per note.
  *
  * **Homepage-only is a first-class mode, not an accommodation.**
  * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
@@ -200,10 +199,9 @@ export const DERIVED_HUGO_KEYS: Readonly<Record<string, string>>;
  * and the default.
  *
  * - `homepage` — the authored homepage, and **no other page**. The content tree
- *   is not walked for pages, `site.sections` / `site.landing` emit nothing,
- *   and nothing serves a page for its addresses.
- * - `content` — the homepage *plus* every page the content tree publishes: the
- *   knowledgebase and the section landings.
+ *   is not walked for pages, and nothing serves a page for its addresses.
+ * - `content` — the homepage *plus* every page the content tree publishes, one
+ *   per note.
  *
  * **Homepage-only is a first-class mode, not an accommodation.**
  * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'

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

@@ -79,41 +79,30 @@ export function buildLinkIndex(contentBase: string, { config, skipDirectories, s
  * 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.
+ * So a homepage addresses the web the way the web does — markdown links in its
+ * body — and this is what looks at those. A dead link on the page a reader
+ * arrives at is the one nothing else would report.
  *
  * **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 the retired names
- *   and what replaced it, so this is a fact rather than a guess — and it is
- *   exactly the SoHL defect.
+ *   and what replaced it, so this is a fact rather than a guess.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
- *   a fetched index names. Every one of them has a better form to write, which
+ *   fetched index names. Every one of them has a better form to write, which
  *   is why every one is reported — including a bare `/<package>/`, which names
- *   another package's landing.
- *
- *   That last case was exempt until the better form was identified, on the
- *   reasoning that a landing is in no link manifest so nothing could resolve it.
- *   True, and beside the point: it does not need resolving. A landing's address
- *   *is* its package prefix, so `/<package>/` is the absolute URL with the host
- *   struck off — host-free, emitted verbatim, and needing no index, which is
- *   what lets it hold in homepage-only mode where the tree is never walked. The
- *   form was already accepted here; nothing had ever named it as the one to use.
- * - 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.
+ *   another package's front page. A front page's address *is* its package
+ *   prefix, so `/<package>/` is the absolute URL with the host struck off —
+ *   host-free, emitted verbatim, and needing no index, which is what lets it
+ *   hold in homepage-only mode where the tree is never walked.
  * - 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.
+ * exists: several of the surfaces a homepage routes to are produced by other
+ * tools entirely (generated API documentation, say), 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,

package/types/engine/diagnostics.d.mts

@@ -184,7 +184,7 @@ export function positionOfLiteral(text: string, needle: string, occurrence?: num
  *
  * **`key: true` addresses the declaration rather than the value.** A finding
  * about a *value* — this pack name is not in `packs[]` — belongs on the value,
- * which is the default. A finding that names a **field** — `\`site.sections.x\`
+ * which is the default. A finding that names a **field** — `\`site.notfound.x\`
  * is not a recognized option` — sends the reader to look for that field, so the
  * position should be the field's own, and in a flow mapping
  * (`{ title: X, banner: Y }`) the two are different columns on one line. The
@@ -210,7 +210,7 @@ export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string |
  * The YAML key path a **dotted field path** addresses.
  *
  * Configuration checks report the offending key as the path a reader would
- * write it — `packs[1].name`, `site.sections.affliction.title` — because that
+ * write it — `packs[1].name`, `site.notfound.links[0].url` — because that
  * is what the message has to say. {@link positionOfYamlPath} addresses a node
  * by segments instead, so this is the one translation between them: `.`
  * separates map keys, and a bracketed suffix is a sequence index.

package/types/engine/homepage.d.mts

@@ -1,18 +1,3 @@
-/**
- * The file a homepage is written to, relative to the package's site root.
- *
- * Its **address**, flat at the package root, and stated in the page's own `url`
- * — the same separation every other page has, where the directory
- * decides the Hugo section and the front matter decides the URL. Flat rather
- * than inside a `homepage/` section directory, because a homepage is not one of
- * a kind: a section holding exactly one page would publish a landing at
- * `/<package>/kb/homepage/` that nothing links to and nobody wrote.
- *
- * @param {object} fm - Parsed frontmatter.
- * @returns {string} The destination filename, e.g. `homepage-root.md`.
- * @throws {Error} When the note declares no shortcode, and so has no address.
- */
-export function homepageDestination(fm: object): string;
 /**
  * Whether a note's frontmatter declares the homepage type.
  *
@@ -24,7 +9,7 @@ export function isHomepage(fm: object | null | undefined): boolean;
  * What the address rule says about one note's top-level fields.
  *
  * Two statements about the same thing, so they are made together: the field a
- * homepage **owes** and the field it may **not** write.
+ * homepage **owes** and the fields it may **not** write.
  *
  * The missing `shortcode` comes first, and is located at `type:` rather than at
  * a key that is not there — the `homepage` value is what makes the field
@@ -34,8 +19,9 @@ export function isHomepage(fm: object | null | undefined): boolean;
  * diagnostic per finding walks down the file.
  *
  * Presence is the whole test for a refused field, and absence-or-blank for the
- * required one: `shortcode:` authored empty is no address, and a value cannot
- * make `id` mean something on a page that compiles to no document.
+ * required one: `shortcode:` authored empty is no address, and no value can
+ * make `id` or `landing` mean something on a page that compiles to no document
+ * and renders as its body.
  *
  * Each finding carries the `locator` key to position it at, because the two
  * things that would resolve one — the raw note text and the position helper —
@@ -79,13 +65,11 @@ export function checkHomepageAddressFields(fm: object | null | undefined, { isAu
  *   this 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. **This is a cardinality rule, and
- *   only that.** A homepage is written at its own address, so two of them
- *   publish two pages and collide over nothing; the
- *   duplicate-address check catches only the pair that happen to share a
- *   shortcode, and says nothing at all about a `homepage-root` beside a
- *   `homepage-front`. Which of the two the redirect at `/<package>/` should
- *   name is a question nothing here can answer, and both being reachable is
- *   not an answer to it.
+ *   only that.** Both are written to the mount's `_index.md`, so the second
+ *   silently overwrites the first; the duplicate-address check catches only
+ *   the pair that happen to share a shortcode, and says nothing at all about
+ *   a `homepage-root` beside a `homepage-front`. Which of the two should be
+ *   the front page is a question nothing here can answer.
  *
  * 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
@@ -149,24 +133,15 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
 /**
  * The frontmatter a homepage publishes with.
  *
- * The note's own, plus the derived values every emitted page carries: the
- * resolved `title`, the package the build derived — no note declares one
+ * The note's own, plus the two derived values every emitted page carries: the
+ * resolved `title`, and the package the build derived — no note declares one
  * (`package:` is retired) and the theme's breadcrumb partial reads
- * `.Params.package` — and its **address**.
- *
- * The address is stated as `url` for the same reason every other page states
- * one: Hugo publishes a page where its file sits unless told otherwise,
- * and a homepage's file sits at the package's site root. `slug` is written
- * beside it because it is the last segment of that address and Hugo's own key
- * for one; it decides nothing while `url` is present, but a page carrying only
- * `url` would report a slug Hugo had inferred from the filename.
- *
- * **Site-root relative, and so carrying no package base**, exactly as
- * `pageFrontmatter` states a content page's: Hugo resolves a `url`
- * against `baseURL`, whose path is already where the package is served, so a
- * stated base was written twice and published the landing at
- * `/<package>/<package>/homepage-root/`. Where the package is served is what
- * every *href* is composed from and it reaches this page's address not at all.
+ * `.Params.package`.
+ *
+ * **No `url` and no `slug`.** Hugo publishes the `home` kind at `baseURL`,
+ * whose path is already where the package is served, so the page has no
+ * address to state; a content page states one because its file sits under the
+ * mount and its address does not.
  *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
@@ -178,43 +153,33 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
  * @returns {object} The frontmatter to write.
- * @throws {Error} When the note declares no shortcode, and so has no address.
  */
 export function homepageFrontmatter(fm: object, { contentPackage, title }: {
     contentPackage: string;
     title: string;
 }): object;
 /**
- * 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.
+ * Every address a homepage carries: the markdown links in its body.
  *
- * Three shapes are gathered, and the caller needs to tell them apart because
- * the rules differ:
+ * Nowhere else: the frontmatter holds no address, because a homepage is a
+ * page with a body and the card block that once carried links is refused.
+ * Top-level `title` and `description` are not walked — they are set as text,
+ * never rendered as markdown — and `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.
  *
- * - **`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.
+ * A body link is emitted as written and resolved by the browser against the
+ * homepage's own address, which *is* the package root, so a package-relative
+ * one (`kb/rules/`) lands where a reader expects.
  *
- * `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.
+ * Links inside code are ignored, so an example in a fenced block is not
+ * reported as a dead address.
  *
- * @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.
+ *   in body order, each recorded at `field: "body"` with `kind: "body"`.
  */
-export function homepageAddresses(fm: object | null | undefined, body?: string): Array<{
+export function homepageAddresses(body?: string): Array<{
     field: string;
     url: string;
     kind: string;
@@ -250,17 +215,28 @@ export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
  */
 export const HOMEPAGE_SHORTCODE: string;
 /**
- * The top-level field a homepage refuses, and what it would decide.
+ * The file a homepage is written to, relative to the package's site root.
  *
- * **One field rather than three.** `name` and `shortcode` are
- * refused because a page's URL derived from `name.full` while a homepage's
- * destination was fixed, so the address a `shortcode` computed named a page the
- * site build never wrote. A page's URL is its address now and a homepage
- * publishes at its own, so both fields decide exactly what they decide
- * everywhere else and are permitted.
+ * The mount's own `_index.md`: Hugo renders it as the `home` kind, at
+ * `baseURL` — which is `/<package>/`, the package's own address. One fixed
+ * destination rather than one derived from the note's address, because the
+ * homepage's address *is* the package root; the note's `shortcode` names the
+ * page in links and decides no file.
  *
- * `id` is untouched by that, and stays: it is the Foundry document id a
- * compendium UUID is built from, and a homepage compiles into no document.
+ * @type {string}
+ */
+export const HOMEPAGE_DESTINATION: string;
+/**
+ * The top-level fields a homepage refuses, and what each would decide.
+ *
+ * `id` is the Foundry document id a compendium UUID is built from, and a
+ * homepage compiles into no document. `landing` is a card block; the homepage
+ * is a page with a body, rendered as one, so nothing reads it — and an index
+ * of what the package publishes is a `doc` note carrying a content table,
+ * authored where every other page is.
+ *
+ * `name` and `shortcode` are permitted: the shortcode is what a link is
+ * written with, and `name` titles the page like every other note's.
  *
  * **A named class, not an allow-list, and that boundary is the decision.** A
  * homepage's frontmatter is *emitted into the published page*
@@ -276,19 +252,3 @@ export const HOMEPAGE_SHORTCODE: string;
  * @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.
- *
- * 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: ReadonlySet<string>;

package/types/engine/note-vocabulary.d.mts

@@ -50,18 +50,6 @@ export function exclusiveTagGroups(type: string, groups?: object): {
  * @returns {boolean} Whether the note carries it.
  */
 export function hasTag(fm: object | null | undefined, tag: string): boolean;
-/**
- * Whether a note carries any `tags:` at all, however authored.
- *
- * The one question the site build asks of tags in aggregate — whether the
- * tree publishes taxonomy pages — rather than about a particular tag. Reads
- * `tags` and `tag` exactly as {@link hasTag} does, and treats an empty list
- * or a blank string as carrying none.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {boolean} Whether the note carries at least one tag.
- */
-export function hasAnyTag(fm: object | null | undefined): boolean;
 /**
  * Whether a note is tagged as an unfinished **draft**.
  *