@heroiclands/package-build 23.12.8 → 24.0.0

package/engine/web-wikilinks.mjs

@@ -1,594 +0,0 @@
-/*
- * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
- * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
- *
- * This work is licensed under the GNU General Public License v3.0 (GPLv3).
- * You may copy, modify, and distribute it under the terms of that license.
- *
- * For full terms, see the LICENSE.md file in the project root or visit:
- * https://www.gnu.org/licenses/gpl-3.0.html
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- */
-
-/**
- * Wikilink resolution for the knowledgebase build.
- *
- * The same authored links the pack compilers turn into Foundry `@UUID` enrichers
- * (see `./wikilinks.mjs`) become site-local hrefs here:
- *
- *   `[[type-shortcode|Text]]`       → `[Text](/section/slug/)`
- *   `[[type-shortcode|]]`           → the same, showing the target's own name
- *   `[[type-shortcode#slug|Text]]`  → `[Text](/section/slug/#slug)`
- *   `[[#slug|Text]]`                → `[Text](#slug)`
- *
- * **Every link is an address and carries a label**. One written without
- * a label addresses nothing and is reported — see
- * {@link unlabelledLinkMessage}, which states the rule for this build and the
- * pack build together.
- *
- * The KB *section* is not always the type: prose pages (`type: doc`) route by
- * their `category`, so `doc/quickstart` lands on `/userguide/sohl-quickstart/`.
- * The caller supplies that mapping already resolved, in the index it builds.
- *
- * Lives here rather than in a consumer so every package resolves a link the
- * same way. `sohl-thalorna` carried a forked copy of this as
- * `utils/site-wikilinks.mjs`, already 3 KB adrift from the original, which is
- * exactly the drift one rule with two implementations produces.
- */
-
-// How an address *parses* is the pack build's own rule, so the two builds
-// cannot drift apart on it: they disagreed once over the unlabelled hyphen
-// form, which the packs showed as a raw shortcode and the knowledgebase as a
-// name.
-import { collectAnchors } from "./anchors.mjs";
-import { presentWikilink, readWikilink } from "./wikilink-syntax.mjs";
-import { readQualifier } from "./wikilinks.mjs";
-import { replaceOutsideCode } from "./code-fences.mjs";
-// The canonical `package-system-type-shortcode` key, so a package-qualified
-// address is matched the way a vendored manifest publishes it — by the
-// segments the target supplies, with the system wildcarded unless stated.
-import { canonicalKey, expandAddress, readCanonicalKey } from "./content-address.mjs";
-import { NOTE_SYSTEM } from "./systems.mjs";
-// The one rule about a link's shape both builds share: it carries a label, and
-// {@link unlabelledLinkMessage} is the one place that says so.
-import { unlabelledLinkMessage } from "./wikilink-syntax.mjs";
-// One slug rule for the whole build — see `./content-slug.mjs`. This module
-// carried a copy that dropped non-ASCII letters rather than transliterating
-// them, so a link to a heading named `Kûrbúl Helm` pointed at `#k-rb-l-helm`.
-import { slugify } from "./content-slug.mjs";
-
-// Re-exported so a site build keeps one import path for the whole of link
-// resolution: the same rule that names a page also names an anchor within it.
-/** KB heading/anchor slug: lowercase, non-alphanumerics to single hyphens. */
-export { slugify };
-import {
-    authoredLabel,
-    WIKILINK,
-    isEventAnchor,
-    isSamePage,
-    parseWikilink,
-} from "./wikilink-syntax.mjs";
-import { resolveEmbeds } from "./content-embeds.mjs";
-
-/**
- * Whether a page's declared anchors include the slug a link names.
- *
- * A local page carries a `Set` built by {@link module:engine/site-index}.
- * A foreign page declares prose anchors in its note metadata, independently
- * of whether it has a Foundry target map. An empty collection declares none.
- * An absent collection leaves the target unchecked.
- *
- * @param {Set<string>|Record<string, string>|Array<{slug: string, kind: string}>|undefined} anchors - The page's
- *   declared anchors, or `undefined` where none were recorded.
- * @param {string} slug - The anchor a link names.
- * @returns {boolean} Whether the anchor is declared, or `true` when `anchors`
- *   is `undefined` — which reads as "nothing to check against" rather than
- *   "declares none".
- */
-function hasAnchor(anchors, slug) {
-    if (!anchors) return true;
-    if (Array.isArray(anchors))
-        return anchors.some((anchor) => anchor.kind === "prose" && anchor.slug === slug);
-    return anchors instanceof Set ? anchors.has(slug) : Object.hasOwn(anchors, slug);
-}
-
-/**
- * The index key a **piped** target resolves to, or `null` when it does not
- * parse as an address at all.
- *
- * The KB index is keyed by the canonical `type/shortcode`, so a target written
- * in the hyphen separator — which is what the content tree authors —
- * has to be rewritten to it before lookup. The target is read by the pack
- * build's own {@link readQualifier}, so recognising an address and resolving
- * one can never disagree: the two separators and the optional leading package
- * segment are stated once, there.
- *
- * It takes the **parsed** qualifier rather than the raw target because the
- * caller needs the parse for a second purpose: `unknown-type` and
- * `not-an-address` are different findings with different fixes, and only the
- * `reason` tells them apart. Reading the target twice would let the two
- * readings drift.
- *
- * The build indexes an item note under both `skill/climb` and `docskill/climb`,
- * and `contentTypes` carries both qualifiers, so either form finds the page.
- *
- * @param {Map<string, object>} index - The page index to look in.
- * @param {object|null} read - From {@link readQualifier}.
- * @param {string} contentPackage - The citing package, which an omitted package
- *   segment defaults from.
- * @returns {object|undefined} The indexed page, or `undefined` when the target
- *   is not an address or nothing publishes it.
- */
-function lookupRead(index, read, contentPackage) {
-    if (!read || read.reason) return undefined;
-    // Every omitted segment defaults from where the link is written —
-    // package from the citing package, system from the block, which on a page
-    // body is `none` — so the target expands to exactly one canonical address
-    // and this is a plain lookup. No filter, no single-hit rule, and no
-    // ambiguity: one key names one entry.
-    //
-    // It replaced a system-blind short key for the unqualified form, which
-    // could be silently overwritten by a second note of the same
-    // `(type, shortcode)` under another system.
-    const key = expandAddress(read, { package: contentPackage, system: NOTE_SYSTEM });
-    const found = index.get(key);
-    if (found || read.package) return found;
-
-    // A local target may also be keyed by its short form. On the KB that is not
-    // a second answer: an item note renders as **one page** which is its own
-    // documentation, so `skill/climb`, `docskill/climb` and both canonical
-    // addresses are all the same value — the fallback cannot pick
-    // differently, only earlier. It stays because an index built before the
-    // canonical documentation key was added still carries the short one, and
-    // because a page collision here is caught by the site index's own
-    // `ambiguous` set rather than by silent overwrite as in the pack index.
-    return (
-        index.get(`${read.itemDoc ? "doc" : ""}${read.type}/${read.shortcode}`.toLowerCase()) ??
-        undefined
-    );
-}
-
-/**
- * How an **unresolved** link renders.
- *
- * The author's text remains readable. The website uses an HTML span matching
- * the pack compiler's cue; the book uses text that Typst can print.
- *
- * The knowledgebase renders with `unsafe = true` (`kb/hugo.toml`), so raw HTML
- * in generated markdown reaches the page. That makes escaping obligatory: this
- * is the one path where *authored* text becomes markup rather than content.
- *
- * @param {string} text - The text to show, from the link's label or target.
- * @param {string} target - The address that resolved nowhere, for the tooltip.
- * @param {"html"|"book"} output - The destination format.
- * @returns {string} A visible cue in the destination's Markdown.
- */
-function unresolvedLink(text, target, output) {
-    if (output === "book") return `${text} (unresolved link)`;
-    const esc = (v) =>
-        String(v)
-            .replace(/&/g, "&amp;")
-            .replace(/</g, "&lt;")
-            .replace(/>/g, "&gt;")
-            .replace(/"/g, "&quot;");
-    return (
-        `<span class="sohl-unresolved-link" title="Unresolved link: ` +
-        `${esc(target)}">${esc(text)}</span>`
-    );
-}
-
-/**
- * How the website marks a link to a **draft** note.
- *
- * A note tagged `draft` exists so a link into it is not dead, and nothing more.
- * Unmarked, a reader follows a promising link into an empty page and an author
- * cannot see which of their links still owe content.
- *
- * The link itself remains intact inside the HTML span.
- *
- * The appearance lives in the Hugo theme for the website and in
- * `scss/components/_draft-link.scss` for Foundry, not here.
- *
- * The website span matches the pack compiler's copy in `wikilinks.mjs`.
- *
- * The argument is already-built markup and is deliberately not escaped; the
- * *authored* text inside it was escaped, or made into a link, by the caller.
- *
- * @param {string} inner - The resolved link, as this build emits it.
- * @returns {string} An inline HTML span wrapping it.
- */
-function draftLink(inner) {
-    return `<span class="sohl-draft-link" title="Draft — not yet written">${inner}</span>`;
-}
-
-/**
- * A wikilink, as it is written, anywhere in a value that is not markdown.
- *
- * Deliberately its own pattern rather than the body resolver's: nothing here is
- * markdown, so there is no fence or code span to step around, and a frontmatter
- * value is a single line by construction (`[^\]\n]` keeps a runaway match from
- * swallowing the rest of a folded scalar).
- */
-// The same syntax the body scan reads — see `./wikilink-syntax.mjs`.
-const FRONTMATTER_WIKILINK = new RegExp(WIKILINK.source, "g");
-
-/**
- * Every wikilink authored inside a frontmatter value.
- *
- * Wikilinks are resolved in a note's **body** — by {@link resolveWebWikilinks}
- * here, and by the pack compilers' `convertWikilinks` for Foundry. Frontmatter
- * is not markdown and is never walked by either, so a link written in one is
- * copied through verbatim and reaches the reader as literal `[[…]]` text, in
- * whatever the theme renders that field as (an infobox row, a description, a
- * card subtitle). Nothing downstream notices: the value is a valid string, the
- * page builds, and the defect is visible only to someone who looks at it.
- *
- * So the form is refused rather than resolved. Resolving it would mean choosing
- * an output syntax for a field whose renderer is unknown to this build — a
- * markdown link is inert in a Hugo template that prints the value as text, and
- * an `<a>` is unusable in one that escapes it — and would quietly bless an
- * authoring habit that the pack build has no way to honour at all. Frontmatter
- * carries data; a link belongs in prose.
- *
- * Values are read from the *parsed* frontmatter, so a `[[` inside a YAML comment
- * is not a hit, and every hit can be named by the path a reader would look at.
- *
- * @param {unknown} fm - Parsed frontmatter, as `gray-matter` returns it.
- * @returns {Array<{path: string, link: string}>} In reading order; `path` is the
- *   dotted key path of the offending value (`government.summary`, `aliases.1`).
- */
-export function frontmatterWikilinks(fm) {
-    const hits = [];
-    const visit = (value, trail) => {
-        if (typeof value === "string") {
-            for (const m of value.matchAll(FRONTMATTER_WIKILINK)) {
-                hits.push({ path: trail, link: m[0] });
-            }
-        } else if (Array.isArray(value)) {
-            value.forEach((v, i) => visit(v, `${trail}.${i}`));
-        } else if (isPlainMap(value)) {
-            for (const [k, v] of Object.entries(value)) {
-                visit(v, trail ? `${trail}.${k}` : k);
-            }
-        }
-    };
-    if (!isPlainMap(fm)) return hits;
-    visit(fm, "");
-    return hits;
-}
-
-/**
- * Whether a value is a YAML mapping rather than a scalar the parser built into
- * an object of its own (a `Date`, which is what an unquoted date becomes).
- *
- * @param {unknown} value
- * @returns {boolean}
- */
-function isPlainMap(value) {
-    return (
-        typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        !(value instanceof Date)
-    );
-}
-
-/**
- * Rewrites the wikilinks in a markdown body as KB-local markdown links.
- *
- * **Every target is an address**, parsed by {@link readQualifier} and looked up
- * case-insensitively in the KB-wide `ctx.index` (the canonical
- * `package-system-type-shortcode`, `type/shortcode`, and the site's own
- * `section/slug`), then in the vendored `ctx.foreign` manifests. A target is a
- * *partial* address: an omitted package means this package, an omitted system
- * is a wildcard, and exactly one match resolves — two are `ambiguous`. A link written
- * without a label addresses nothing at all and is reported as such —
- * there is no second namespace left for it to name.
- *
- * Only a slash-qualified target reaches the raw key, which is what keeps
- * `section/slug` addressable without a page's own slug answering for it.
- *
- * **Every target that resolves nowhere fails the build**, and is
- * classified into the vocabulary all three resolvers share — `unlabelled`,
- * `not-an-address`, `unknown-type`, `ambiguous`, `unresolved`,
- * `no-content-index`. Failures are collected in `ctx.errors`, each carrying
- * the authored `link` and its `occurrence` so a caller can report the line and
- * column it sits on.
- *
- * There is deliberately no exception letting a hyphen-form address through while
- * any linkable package had no vendored manifest, since a real cross-package
- * reference and a typo look identical from here. The pack compilers and the
- * link checker never made that allowance, so its only surviving effect was to
- * give one authored link two verdicts. The advice moved into the message
- * instead.
- *
- * A target that resolves nowhere still renders through {@link unresolvedLink}
- * rather than as bare prose: the author's text is kept, marked so a
- * reader can see a link was intended. The marking and the failure are separate
- * jobs and always were — the mark is for whoever reads the page a *previous*
- * build emitted, the failure is for the author of this one.
- *
- * A target that **resolved** to an entry with no page is not this case and is
- * not marked: a pack-only package publishes Foundry addresses and no
- * web pages, so the author wrote a real address and there is simply nothing to
- * link to.
- *
- * ## Embeds first, and they are not links
- *
- * `![[address|label]]` names a file rather than a note, so it is resolved into
- * an ordinary markdown image before anything looks for a link — which is what
- * stops the link pass reading an embed's interior as a link to a note nobody
- * wrote. The image the rewrite leaves behind is what
- * {@link module:engine/content-images.renderImageFigures} turns into a figure
- * for the website, and what the book reads its staging list out of.
- *
- * ## Every hit is recorded, so the page's edges come out of one pass
- *
- * A caller that hands in `ctx.resolved` is given every index entry a link on
- * the page resolved to, in body order, repeats included. That is the link
- * graph, read at the one point where it exists: the build never has to walk a
- * page a second time to learn what it links to. Nothing is recorded for a
- * same-page anchor or for a target that resolved nowhere.
- *
- * @param {string} body - The markdown body.
- * @param {object} ctx - `{ index, assets, collide, contentTypes,
- *   packages, noIndexPackages, foreign, type, errors, src, file, resolved,
- *   output }`. `output` is `"book"` for PDF Markdown and defaults to HTML.
- *   `packages` is every package an address may name, without which the leading
- *   package segment of a canonical address reads as an unknown type;
- *   `noIndexPackages` is every package declared `contentIndex: false`, so a
- *   qualified address naming one fails with `no-content-index` rather than
- *   `not-an-address`; `foreign`
- *   is the cross-package manifest index; `assets` is the address space an embed
- *   resolves against. `src` is the page's display
- *   path and `file` the source file a diagnostic should name — absent, `src`
- *   stands in. `resolved`, when supplied, is the array every resolved
- *   target's index entry is appended to. `anchors` is the `{#slug}` set
- *   *this* page declares, which a `[[#slug]]` self-link is checked against;
- *   absent, a self-link is not checked, exactly as before this existed.
- * @returns {string} The body with embeds and wikilinks rewritten.
- */
-export function resolveWebWikilinks(body, ctx) {
-    // How many times each authored link has been seen, so two identical links
-    // on one page are located at their own positions in the source file — the
-    // same counting the checker does, and what turns a finding into a
-    // `file:line:column:` diagnostic rather than a note-wide one.
-    const seen = new Map();
-    let ownAnchors = ctx.noteAnchors;
-    /**
-     * Records a finding against one authored literal.
-     *
-     * @param {string} all - The literal, exactly as authored.
-     * @param {object} finding - The finding's own fields.
-     * @returns {void}
-     */
-    const record = (all, finding) => {
-        const occurrence = (seen.get(all) ?? 0) + 1;
-        seen.set(all, occurrence);
-        ctx.errors.push({
-            // Absolute where the caller supplied one, so a diagnostic locates
-            // the file an editor opens; the display path otherwise.
-            file: ctx.file ?? ctx.src,
-            src: ctx.src,
-            link: all,
-            occurrence,
-            ...finding,
-        });
-    };
-
-    /**
-     * Records a finding, and returns the marked-up link it renders as.
-     *
-     * @param {string} all - The authored link, brackets and all.
-     * @param {object} finding - `{ target, reason }`, plus any extras the class
-     *   carries.
-     * @param {string} text - What the link renders as.
-     * @returns {string} The marked span.
-     */
-    const report = (all, finding, text) => {
-        record(all, finding);
-        return unresolvedLink(text, finding.target, ctx.output ?? "html");
-    };
-
-    // An embed names a file, so it resolves before anything looks for a link.
-    // Its findings are recorded rather than rendered: the rewrite already
-    // leaves an embed it cannot resolve exactly as authored, which is the
-    // visible degradation an unresolved link gets from `unresolvedLink`.
-    const embedded = resolveEmbeds(body, { index: ctx.assets });
-    for (const u of embedded.unresolved) {
-        record(u.link, { target: u.target, reason: u.reason, ...(u.type ? { type: u.type } : {}) });
-    }
-    for (const problem of embedded.problems) {
-        record(problem.link, { target: problem.link, message: problem.message });
-    }
-
-    // Code is verbatim: a `[[…]]` inside a code fence, an indented block or an
-    // inline span is source text, not a link.
-    return replaceOutsideCode(embedded.markdown, WIKILINK, (all, rawInner) => {
-        const parsed = readWikilink(
-            rawInner,
-            {
-                package: ctx.contentPackage,
-                system: "note",
-                types: ctx.contentTypes ?? new Set(),
-                packages: ctx.packages,
-                noIndexPackages: ctx.noIndexPackages,
-            },
-            all,
-        );
-        const { rawTarget: target, anchor, display } = parsed;
-        // An empty label is not a label: `[[x|]]` addresses the target and
-        // shows its name, so `""` falls through to the same place `null` does.
-        // One reading, from {@link authoredLabel}.
-        const label = authoredLabel({ display });
-        if (parsed.attributes?.problems.length)
-            return report(
-                all,
-                { target, reason: "invalid-attributes", problems: parsed.attributes.problems },
-                label ?? target,
-            );
-
-        // **Every link carries a label**. Without one there is nothing
-        // to resolve against, and nothing to show either, a shortcode being an
-        // address rather than prose. Reported before the same-page form, because the
-        // rule is about how the link is *written*: `[[#slug]]` needs the pipe
-        // exactly as `[[skill-clmb]]` does.
-        if (!parsed.labelled) {
-            return report(all, { target: parsed.inner, reason: "unlabelled" }, parsed.inner);
-        }
-
-        // `[[#section-slug|Text]]` — a section of this same page.
-        if (isSamePage({ target, anchor })) {
-            // Checked against this page's own anchors, exactly as a link into
-            // another page is: a self-link naming a section the page does not
-            // declare is as dead as one naming a section nowhere does.
-            if (isEventAnchor(ctx, anchor)) {
-                return report(
-                    all,
-                    { target, reason: "event-anchor", anchor, addressed: true },
-                    label ?? anchor,
-                );
-            }
-            if (!hasAnchor(ctx.anchors, anchor)) {
-                return report(
-                    all,
-                    { target, reason: "unknown-anchor", anchor, addressed: true },
-                    label ?? anchor,
-                );
-            }
-            return presentWikilink(
-                `[${label ?? ctx.captionLabels?.get(anchor) ?? anchor}](#${slugify(anchor)})`,
-                parsed,
-                { noteAnchors: (ownAnchors ??= collectAnchors(body)) },
-            );
-        }
-
-        // The canonical separator has to be resolved, not merely
-        // recognised. `null` here means the target is not an address at all,
-        // which is a defect: there is no other namespace to try.
-        const read = parsed.problem ?? parsed.target;
-        const rawKey = target.toLowerCase();
-        const hit =
-            lookupRead(ctx.index, read, ctx.contentPackage) ??
-            // A manifest entry carries the same `{ url, name }` shape as a
-            // local one, so a cross-package hit needs no special case
-            // below. Local wins: a live build is authoritative and a vendored
-            // manifest can only be staler.
-            // A short form names *this* package, so it never reaches a
-            // vendored manifest; only a fully qualified address does.
-            (ctx.foreign && read?.package ?
-                lookupRead(ctx.foreign, read, ctx.contentPackage)
-            :   undefined);
-        if (hit) {
-            // A `#section` the target declares no heading for. Checked only
-            // where there is a page to check against — a pack-only hit has no
-            // `url` and therefore nothing for the anchor to address, which is
-            // the asset-like case this must not touch. `anchorPageId` on the
-            // pack build and the KB manifest's own `{slug: uuid}` map both
-            // hash any slug into something that resolves, so an undeclared
-            // one otherwise joins onto the URL unchecked and dead-ends for
-            // the reader.
-            if (anchor && isEventAnchor(hit, anchor)) {
-                return report(
-                    all,
-                    { target, reason: "event-anchor", anchor, addressed: true },
-                    label ?? hit.name ?? target,
-                );
-            }
-            if (anchor && !hasAnchor(hit.noteAnchors ?? hit.anchors, anchor)) {
-                return report(
-                    all,
-                    { target, reason: "unknown-anchor", anchor, addressed: true },
-                    label ?? hit.name ?? target,
-                );
-            }
-            // The edge, for a caller reading the link graph off this pass.
-            ctx.resolved?.push(hit);
-            // An address with an *empty* label has no prose to show (a
-            // shortcode is not display text), so the document's **current**
-            // name stands in and a rename shows at every citation.
-            const text = label ?? hit.name;
-            // A pack-only package publishes Foundry addresses and no pages,
-            // so its entries carry no `path` and resolve to no URL.
-            // The address is real — this is not a typo and must not fail the
-            // build — but there is nothing on the web to point at, so the
-            // reader gets the text and no href. Emitting the href anyway is
-            // what the manifest exists to prevent: `[Name](undefined)` renders
-            // as a link and goes nowhere.
-            const link =
-                hit.url ? `[${text}](${anchor ? `${hit.url}#${slugify(anchor)}` : hit.url})` : text;
-            // A link into a note that exists but is not written renders marked.
-            // Presentation only — the href above is unchanged, and a
-            // `[[#anchor]]` self-link is not marked because the reader is
-            // already on the page it would be telling them about.
-            return presentWikilink(
-                !hit.draft ? link
-                : ctx.output === "book" ? `${link} (draft)`
-                : draftLink(link),
-                parsed,
-                hit,
-            );
-        }
-
-        // **An address resolving nowhere is a failure, unconditionally**.
-        //
-        // It was gated on a manifest-completeness check — while any linkable package was
-        // invisible here, `Rules/Bestiary.md` addressing `being-grkrahk` in the
-        // `thalorna` package was indistinguishable from a typo, so the form
-        // stayed unguarded rather than fail correct content. The gate has
-        // outlived that: every linkable package publishes a manifest now, and
-        // more to the point the *other two* resolvers never had it. The pack
-        // compilers fail the note and the link checker reports an error, so the
-        // gate's only remaining effect was to give one authored link two
-        // verdicts depending on which build read it. The advice a missing
-        // manifest calls for is in the message instead — {@link
-        // unresolvedAddressMessage} names both corrections — which informs the
-        // author without excusing the link.
-        // The bucket an ambiguity is recorded under is the *short* address —
-        // the only form two packages can collide on, since a qualified one
-        // names its package. A qualified target that matched more than one
-        // document is reported by the matcher instead, not by this set.
-        const collideKey =
-            read && !read.reason && read.package === ctx.contentPackage ?
-                `${read.type}/${read.shortcode}`.toLowerCase()
-            :   rawKey;
-        // A capital in the shortcode is refused, never lowercased. The
-        // lowercase spelling is looked up only to name it in the finding.
-        if (read?.reason === "shortcode-not-lowercase") {
-            const lower = read.lowercase;
-            const declared =
-                lookupRead(ctx.index, lower, ctx.contentPackage) ??
-                (ctx.foreign && lower.package ?
-                    lookupRead(ctx.foreign, lower, ctx.contentPackage)
-                :   undefined);
-            return report(
-                all,
-                {
-                    target,
-                    reason: "shortcode-not-lowercase",
-                    shortcode: read.shortcode,
-                    ...(declared ? { declared: lower.shortcode } : {}),
-                },
-                label ?? target,
-            );
-        }
-        const reason =
-            ctx.collide?.has(collideKey) ? "ambiguous"
-                // "It parsed as an address" is a property of the parse, not of
-                // a key: a partial address has no single key to be non-null.
-            : read && !read.reason ? "unresolved"
-            : read?.reason === "unknown-type" ? "unknown-type"
-            : read?.reason === "no-content-index" ? "no-content-index"
-            : read?.reason === "not-lowercase" ? "not-lowercase"
-                // Every link is an address, and this is not one. Distinct from
-                // a dead address, because the fix is different: a name has to
-                // become an address, not be corrected.
-            : "not-an-address";
-
-        // Whether or not it failed the build, the link renders marked: the
-        // author's text is kept so the sentence still reads, and a reader can
-        // see that something was meant to be a link.
-        return report(all, { target, reason }, label ?? target);
-    });
-}

package/hugo-theme/layouts/404.html

@@ -1,85 +0,0 @@
-{{- /*
-  "Page not found" page.
-
-  Hugo renders this template to `public/404.html`, and a static host such as
-  Cloudflare Pages serves that file — with a genuine HTTP 404 — for any path
-  the deployment does not publish. Without it, Pages falls back to the site
-  root, so an unknown path answers 200 with the landing page: a soft-404 that
-  makes every "does this URL resolve?" check report success, and lets search
-  engines index withdrawn content as live.
-
-  Every consumer needs exactly this, so it lives here rather than being copied
-  into each one (issue #1454). The theme carries layout, not addresses, so the
-  wording and the routes back are supplied by the consuming site:
-
-    [params.notfound]
-      heroimage = "images/banner.webp"   # CDN-relative or absolute
-      tagline   = "This site has no page at"
-      sitenoun  = "site"                 # used in the body prose
-      [[params.notfound.links]]
-        title = "Home"
-        url   = "/"                      # relURL'd unless already absolute
-        text  = "Everything, from the top."
-
-  Each is guarded: a consumer supplying none still builds, and simply gets the
-  generic wording with no list of routes back.
-*/ -}}
-{{ define "main" }}
-{{- $nf := .Site.Params.notfound | default dict -}}
-{{- $img := $nf.heroimage | default "images/banners/default.webp" -}}
-{{- $heroURL := partial "cdn-url.html" (dict "site" .Site "path" $img) -}}
-{{- $tagline := $nf.tagline | default "This site has no page at" -}}
-{{- $noun := $nf.sitenoun | default "site" -}}
-<section class="hero hero-with-image" style="background-image: url('{{ $heroURL }}');">
-  <div class="hero-inner" data-pagefind-ignore>
-    <h1>Page not found</h1>
-    <p class="hero-tagline">{{ $tagline }} <code id="missing-path">the address you followed</code>.</p>
-  </div>
-</section>
-
-<article class="single">
-  <div class="single-content">
-    <div class="single-body">
-      <p>
-        The page may have been moved to another part of the
-        {{ $noun }}, or withdrawn along with the concept it described. Links
-        from older discussions, issues, and search results can outlive the
-        pages they point at.
-      </p>
-      {{- with $nf.links }}
-      <p>Start again from one of these:</p>
-      <ul class="page-list">
-        {{- range . }}
-        {{- $url := .url -}}
-        {{- if not (or (hasPrefix $url "http://") (hasPrefix $url "https://") (hasPrefix $url "//")) -}}
-          {{- /* relURL only mounts a path under the site's base when it is
-                 given relative: a leading slash means "from the origin", and
-                 the base path is left off. Trim it, so a consumer writing the
-                 obvious "/section/" gets a link inside its own site even when
-                 that site is served under a prefix. */ -}}
-          {{- $url = strings.TrimPrefix "/" $url | relURL -}}
-        {{- end }}
-        <li class="page-list-item">
-          <a class="page-list-title" href="{{ $url }}">{{ .title }}</a>
-          {{- with .text }}
-          <span class="page-list-desc">{{ . }}</span>
-          {{- end }}
-        </li>
-        {{- end }}
-      </ul>
-      {{- end }}
-    </div>
-  </div>
-</article>
-
-{{/* Name the address that failed, so a reader can see what they followed and
-     quote it in a bug report. Static hosting cannot template it — Pages serves
-     this one file for every unmatched path — so it is filled in client-side,
-     and the markup above reads sensibly without scripting. */}}
-<script>
-  (function () {
-    var el = document.getElementById("missing-path");
-    if (el) el.textContent = window.location.pathname;
-  })();
-</script>
-{{ end }}