@heroiclands/package-build 22.3.0 → 22.4.0

package/engine/content-links.mjs

@@ -621,21 +621,18 @@ export function buildLinkIndex(
 const SITE_HOST = /^(?:[a-z0-9-]+\.)*heroiclands\.org$/i;
 
 /**
- * Every package landing this build can name, as `package` → base.
+ * Every package front page this build can name, as `package` → base.
  *
- * **A landing needs no manifest, and that is what makes it work.** The link
- * manifest indexes content notes, and a homepage is deliberately not one — it
- * compiles to no document and is entered in no manifest. The reading that
- * follows from this, and that left a hardcoded URL as the only authored form,
- * is that a landing therefore cannot be addressed. It does not follow: a
- * landing's address is not a *note's* address but the **package's**, and
- * {@link PACKAGE_BASE} already records where each package is served. That is a
- * frozen constant compiled into every build, so consulting it walks no
- * tree, reads no manifest and builds no index — which is precisely why the
- * mechanism survives `homepage` mode, where the licensing fence means none of
- * those exist.
+ * **A front page needs no manifest, and that is what makes it work.** A
+ * homepage compiles to no document and is entered in no manifest, but its
+ * address is not a *note's* address but the **package's** — it is the mount's
+ * `_index.md`, published at `/<package>/` — and {@link PACKAGE_BASE} already
+ * records where each package is served. That is a frozen constant compiled
+ * into every build, so consulting it walks no tree, reads no manifest and
+ * builds no index — which is precisely why the mechanism survives `homepage`
+ * mode, where the licensing fence means none of those exist.
  *
- * The roster is consulted **for landings only**. Widening the package set the
+ * The roster is consulted **for front pages only**. Widening the package set the
  * other rules read would make them offer manifest-based advice about packages
  * no index has been fetched for.
  *
@@ -738,41 +735,30 @@ function readAddress(url, packages) {
  * 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,
@@ -814,7 +800,7 @@ export function auditHomepageLinks(index) {
             );
         }
 
-        for (const { field, url, kind } of homepageAddresses(note.fm, note.body)) {
+        for (const { field, url } of homepageAddresses(note.body)) {
             // Counted for every address, checked or not, so the count is
             // the literal's nth appearance in the file rather than the nth
             // *finding* about it — two rules can fire on one address.
@@ -853,34 +839,13 @@ export function auditHomepageLinks(index) {
                     prefix === index.contentPackage ?
                         `hardcoded absolute URL into this package's own ` +
                             `address — write the package-relative ` +
-                            `"${rest}/", which the landing resolves ` +
-                            `against the site so the page follows the mount`
+                            `"${rest}/", which a browser resolves against ` +
+                            `the homepage's own address, the package root`
                     :   `hardcoded absolute URL into package "${prefix}" ` +
                             `— resolve it through that package's link ` +
                             `manifest, whose entries carry the address, so a ` +
                             `relocation does not leave this page behind`,
                 );
-            } else if (shape === "rooted" && kind === "url") {
-                const rest = prefix ? segments.slice(1).join("/") : segments.join("/");
-                report(
-                    field,
-                    url,
-                    url,
-                    occurrence,
-                    // A `url:` is package-relative by construction, so it
-                    // cannot address anything outside this package at all —
-                    // there is no relative spelling of another package's root.
-                    // `href:` is the field for an address already resolved.
-                    !rest ?
-                        `url "${url}" addresses ` +
-                            (prefix ? `package "${prefix}"'s landing` : `the site root`) +
-                            `, but a landing's url: is package-relative and ` +
-                            `cannot leave this package — write ` +
-                            `href: "${url}", which is used verbatim`
-                    :   `url "${url}" is root-relative, but a landing's url: ` +
-                            `is resolved against the site — write "${rest}/", ` +
-                            `or href: for an address that is already resolved`,
-                );
             }
 
             // The retired-type rule reads the path *inside* the package, so an

package/engine/diagnostics.mjs

@@ -297,7 +297,7 @@ export function positionOfLiteral(text, needle, occurrence = 1) {
  *
  * **`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
@@ -347,7 +347,7 @@ export function positionOfYamlPath(text, keyPath, { key = false } = {}) {
  * 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/engine/field-reference.mjs

@@ -34,6 +34,9 @@
  * @module
  */
 
+import path from "node:path";
+import matter from "gray-matter";
+
 import { authoredFields, runtimeOnlyFields } from "./field-spec.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 
@@ -309,3 +312,141 @@ export function renderItemFieldReference({
     // and then reported stale by `--check` forever after.
     return lines.join("\n").replace(/\n+$/, "");
 }
+
+/**
+ * @param {unknown} value - Anything.
+ * @returns {boolean} Whether it is a mapping a field may be read out of.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Recursively merge `overlay` onto `base`. Plain objects merge key-by-key;
+ * everything else (arrays, primitives, `null`) replaces. Inputs are not
+ * mutated.
+ *
+ * @param {any} base - The generated envelope.
+ * @param {any} overlay - The consumer's declared `frontmatter`.
+ * @returns {any} The merged value.
+ */
+function deepMerge(base, overlay) {
+    if (overlay === undefined) return base;
+    if (!isPlainObject(base) || !isPlainObject(overlay)) return overlay;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        out[key] = key in base ? deepMerge(base[key], value) : value;
+    }
+    return out;
+}
+
+/**
+ * Whether a destination file sits under a content tree.
+ *
+ * The one question that decides whether `docs item-fields` writes a note
+ * envelope: `assets/content/` walks every file under it for its `type:`, so a
+ * generated page filed there needs one to publish at all, while a page filed
+ * anywhere else — a repository's own `docs/` — is read by nobody but Hugo's
+ * `--check` guard and the reader following a link, neither of which wants
+ * frontmatter.
+ *
+ * @param {string} destination - Absolute path of the file being written.
+ * @param {string} contentRoot - Absolute path of the content tree root
+ *   (`config.paths.content`).
+ * @returns {boolean} Whether `destination` resolves inside `contentRoot`.
+ */
+export function isUnderContentTree(destination, contentRoot) {
+    const relative = path.relative(contentRoot, destination);
+    return (
+        relative !== "" &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative)
+    );
+}
+
+/**
+ * A note's `shortcode`, derived from the basename of its destination file.
+ *
+ * Lowercase alphanumerics only — the address charset every other shortcode in
+ * the tree is held to — so `item-frontmatter.md` derives `itemfrontmatter`
+ * rather than carrying a hyphen no address segment permits.
+ *
+ * @param {string} destination - Where the note is written.
+ * @returns {string} The derived shortcode.
+ */
+export function shortcodeFromBasename(destination) {
+    return path
+        .basename(destination, path.extname(destination))
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, "");
+}
+
+/**
+ * The note envelope `docs item-fields` writes when its page lives in the
+ * content tree.
+ *
+ * The universal keys every note in the format carries: `type: doc`,
+ * `subType: reference` — this page is out-of-world lookup material, the same
+ * genre as every other generated reference — a `shortcode`, `name.full` from
+ * the page's title, and `pack: none`, since the page publishes to the website
+ * and compiles into no compendium document. A consumer's own
+ * `docs.itemFields.frontmatter` is deep-merged over it, so it may add keys or
+ * override any of the derived ones, `shortcode` included.
+ *
+ * @param {object} options
+ * @param {string} options.title - The page's H1, and `name.full`'s default.
+ * @param {string} options.shortcode - The derived shortcode, from
+ *   {@link shortcodeFromBasename}.
+ * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
+ *   declared `docs.itemFields.frontmatter`.
+ * @returns {Record<string, unknown>} The envelope, ready for `matter.stringify`.
+ */
+export function itemFieldsEnvelope({ title, shortcode, frontmatter }) {
+    return deepMerge(
+        {
+            type: "doc",
+            subType: "reference",
+            shortcode,
+            name: { full: title },
+            pack: "none",
+        },
+        frontmatter,
+    );
+}
+
+/**
+ * Wrap the rendered item-fields page in the note envelope, when its
+ * destination is under the content tree.
+ *
+ * `--check` compares the **whole** file this returns, envelope included — a
+ * page committed with its old envelope by hand, or with none at all, is
+ * exactly the staleness the guard exists to catch.
+ *
+ * @param {string} body - The page {@link renderItemFieldReference} rendered.
+ * @param {object} options
+ * @param {string} options.title - The page's H1, threaded through to
+ *   `name.full`.
+ * @param {string} options.destination - Absolute path the page is written to.
+ * @param {string} options.contentRoot - Absolute path of the content tree
+ *   root (`config.paths.content`).
+ * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
+ *   declared `docs.itemFields.frontmatter`.
+ * @returns {string} `body`, unchanged when `destination` is outside the
+ *   content tree; otherwise `body` with the note envelope stringified above it.
+ */
+export function renderItemFieldsPage(body, { title, destination, contentRoot, frontmatter }) {
+    if (!isUnderContentTree(destination, contentRoot)) return body;
+    const envelope = itemFieldsEnvelope({
+        title,
+        shortcode: shortcodeFromBasename(destination),
+        frontmatter,
+    });
+    const page = matter.stringify(body, envelope);
+    // `matter.stringify` closes the frontmatter fence directly onto the
+    // body's first line; Prettier's markdown printer requires a blank line
+    // between them, so a page written without one fails a consumer's
+    // `lint:format` the moment it is committed. Insert it here rather than
+    // let the generator and the formatter rewrite the file back and forth.
+    return page.replace(/^(---\n[\s\S]*?\n---\n)/, "$1\n");
+}