@heroiclands/package-build 0.6.0 → 3.0.0

package/engine/site-index.mjs

@@ -0,0 +1,332 @@
+/*
+ * 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
+ */
+
+/**
+ * **The address index a site build resolves its wikilinks against.**
+ *
+ * Every consumer that publishes a content tree as a website has to answer the
+ * same question — given `[[Something]]`, which page? — and every one of them
+ * answered it with its own copy of the same 150 lines. `sohl`'s and
+ * `sohl-thalorna`'s site builds still share 147 identical lines of it, comments
+ * and indentation aside. This is that shared half, lifted out whole.
+ *
+ * **What stays with the consumer: how a page gets its address.** The URL
+ * scheme, the section a note is filed under, whether developer docs are part of
+ * the site at all — those genuinely differ, and the two builds differ on all
+ * three. So this takes *entries that already know their own URL* and does the
+ * part that is the same everywhere: index them, index their aliases, merge the
+ * foreign packages in, and report what cannot be addressed unambiguously.
+ *
+ * **Three key spaces, one map.**
+ *
+ * - `section/slug` and `type/shortcode` are unique by construction, so they
+ *   always resolve. `type/shortcode` is the authored form; the canonical
+ *   `package-type-shortcode` is set alongside it, which is what a cross-package
+ *   link and every merged foreign entry use (#1499).
+ * - A bare name, filename, or slug is a **collision-aware fallback**: a key
+ *   that would map to two different pages is dropped and remembered, so
+ *   `[[Name]]` on it fails the build rather than silently picking one. The
+ *   author disambiguates with `[[section/slug|Label]]`.
+ * - Aliases are indexed **scoped to their type**, which is what makes a bare
+ *   `[[Shock]]` resolvable when "Shock" is both a rules page and a trauma item.
+ *   Two notes *of the same type* sharing a name poison it, and the author
+ *   writes `[[type/shortcode|Text]]`.
+ *
+ * **It reports rather than exits.** A build script owns its diagnostics and its
+ * exit code; this returns what it found. That is the same rule the rest of the
+ * engine follows, and it is what lets these cases be tested at all.
+ *
+ * @module
+ */
+
+import path from "node:path";
+
+import { canonicalKey, readCanonicalKey } from "./kb-manifest.mjs";
+import { hasDocEntry } from "./item-docs.mjs";
+
+/**
+ * One page the site will publish, as the index needs to see it.
+ *
+ * @typedef {object} SiteEntry
+ * @property {string} kind   `"content"` for a note compiled from the content
+ *                           tree, anything else for a page that carries no
+ *                           `type`/`shortcode` (a developer doc, say). Only
+ *                           content entries take part in type-scoped indexing.
+ * @property {object} fm     The note's frontmatter.
+ * @property {string} name   Display name.
+ * @property {string} slug   URL segment.
+ * @property {string} sec    Section the page is filed under.
+ * @property {string} base   Source file's basename, e.g. `Climbing.md`.
+ * @property {string} url    The page's published address.
+ * @property {boolean} isReadme  Whether the page is its section's landing.
+ */
+
+/**
+ * The resolved index and everything a wikilink resolver reads beside it.
+ *
+ * @typedef {object} SiteIndex
+ * @property {Map<string, {url: string, name?: string}>} index  Address → page.
+ * @property {Set<string>} ambiguous     Keys claimed by two pages, and so
+ *                                       deliberately absent from `index`.
+ * @property {Map<string, {url: string, name?: string}>} typeAlias  `type|alias`.
+ * @property {Set<string>} typeCollide   Type-scoped aliases claimed twice.
+ * @property {Set<string>} contentTypes  Every type the resolver should read as
+ *                                       an address qualifier, local and foreign.
+ * @property {Set<string>} sections      Section names, lowercased.
+ * @property {Map<string, {name: string, url: string}>} refIndex  `type:shortcode`
+ *                                       → page, for callers resolving embedded
+ *                                       references (a being's items, say).
+ * @property {{key: string, package: string}[]} conflicts  Addresses claimed by
+ *                                       more than one package. Non-empty is a
+ *                                       build failure; the caller reports it.
+ */
+
+/**
+ * Add a collision-aware fallback key.
+ *
+ * First writer wins *until* a second, different page claims the key — at which
+ * point the key is removed and blacklisted, so neither page answers to it. That
+ * is deliberate: resolving to whichever note happened to be walked first is a
+ * silently wrong link, and a failed build is not.
+ *
+ * @param {Map<string, object>} index - The index being built.
+ * @param {Set<string>} collide - Keys already found ambiguous.
+ * @param {string} key - The candidate key, in any case.
+ * @param {{url: string}} value - The page it would resolve to.
+ */
+function addFallback(index, collide, key, value) {
+    const k = String(key).toLowerCase();
+    if (collide.has(k)) return;
+    const cur = index.get(k);
+    if (cur && cur.url !== value.url) {
+        index.delete(k);
+        collide.add(k);
+    } else if (!cur) {
+        index.set(k, value);
+    }
+}
+
+/**
+ * Merge the packages this build does not publish into the local index.
+ *
+ * Every canonical key is globally unique, so a foreign manifest merges straight
+ * in — one map, one lookup, no precedence rule. A key already present is a
+ * genuine conflict: two packages claiming one address, which is the case the
+ * canonical form exists to make detectable.
+ *
+ * The short `type/shortcode` form is merged too, because a bare `[[doc-xyz]]`
+ * carries no package and must still find a foreign note when exactly one
+ * package publishes that address. Claimed by two, it is genuinely ambiguous and
+ * the author writes the qualified form — the same rule the type-scoped aliases
+ * use, one level out. **Local wins**: a live build is authoritative and a
+ * vendored manifest can only be staler, so a short key the local tree already
+ * claims is left alone.
+ *
+ * @param {Map<string, object>} index - The local index, mutated.
+ * @param {Map<string, {package: string, type?: string}>} foreignIndex - Merged in.
+ * @returns {{key: string, package: string}[]} Addresses claimed twice.
+ */
+function mergeForeign(index, foreignIndex) {
+    const conflicts = [];
+    const short = new Map();
+    const ambiguous = new Set();
+
+    for (const [key, value] of foreignIndex) {
+        if (index.has(key)) {
+            conflicts.push({ key, package: value.package });
+            continue;
+        }
+        index.set(key, value);
+
+        const parts = readCanonicalKey(key);
+        if (!parts) continue;
+        const shortKey = `${parts.type}/${parts.shortcode}`;
+        if (
+            short.has(shortKey) &&
+            short.get(shortKey).package !== value.package
+        ) {
+            ambiguous.add(shortKey);
+        } else {
+            short.set(shortKey, value);
+        }
+    }
+
+    for (const key of ambiguous) short.delete(key);
+    for (const [key, value] of short) {
+        if (!index.has(key)) index.set(key, value);
+    }
+    return conflicts;
+}
+
+/**
+ * Build the address index a site's wikilink resolver reads.
+ *
+ * @param {readonly SiteEntry[]} entries - Every page the site will publish,
+ *   each already knowing its own `url`.
+ * @param {object} [options] - Cross-package inputs.
+ * @param {Map<string, {package: string, type?: string}>} [options.foreignIndex]
+ *   The merged index from `loadForeignManifests`. Omit when the build publishes
+ *   no cross-package links.
+ * @returns {SiteIndex} The index, and what could not be addressed unambiguously.
+ */
+export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
+    const index = new Map();
+    const ambiguous = new Set();
+    const typeAlias = new Map();
+    const typeCollide = new Set();
+    const contentTypes = new Set();
+    const sections = new Set();
+    const refIndex = new Map();
+
+    // `section/slug` is unique by construction; the rest are fallbacks.
+    for (const e of entries) {
+        sections.add(String(e.sec).toLowerCase());
+        const value = { url: e.url, name: e.name };
+        index.set(`${e.sec}/${e.slug}`.toLowerCase(), value);
+        addFallback(index, ambiguous, e.name, value);
+        if (!e.isReadme) {
+            addFallback(index, ambiguous, path.basename(e.base, ".md"), value);
+        }
+        addFallback(index, ambiguous, e.slug, value);
+    }
+
+    // A foreign package may use a type this build has never seen. Seeding those
+    // is what lets the resolver recognise `polity-xyz` as an address at all —
+    // without it the link reads as prose and silently loses its href.
+    for (const value of foreignIndex.values()) {
+        if (value.type) contentTypes.add(value.type);
+    }
+
+    // Merged *before* the local type-scoped pass below, so a local page always
+    // ends up owning its own canonical `package-type-shortcode` address: the
+    // local write lands last and wins. `loadForeignManifests` already excludes
+    // the local packages, so a manifest should never carry one — this is what
+    // makes that a belt-and-braces rather than the only thing standing between
+    // a stale vendored manifest and a shadowed local page.
+    //
+    // The corollary is that a conflict can only be reported against the keys
+    // that exist at this point — the addressing ones, `section/slug` and the
+    // bare fallbacks — which is precisely the overlap worth refusing.
+    const conflicts = mergeForeign(index, foreignIndex);
+
+    for (const e of entries) {
+        // A page with no type or shortcode — a developer doc — is addressable
+        // by section and name, and takes no part in type-scoped indexing.
+        if (e.kind !== "content") continue;
+        const type = String(e.fm.type).toLowerCase();
+        contentTypes.add(type);
+        const value = { url: e.url, name: e.name };
+
+        const shortcode = e.fm.shortcode;
+        if (typeof shortcode === "string" && shortcode) {
+            refIndex.set(`${e.fm.type}:${shortcode}`, {
+                name: e.name,
+                url: e.url,
+            });
+            index.set(`${type}/${shortcode}`.toLowerCase(), value);
+            // The canonical address alongside the short one. The short form
+            // stays because a bare `[[skill-lang]]` defaults to the citing
+            // note's own package and must keep resolving unchanged; the
+            // canonical form is what cross-package links use (#1499).
+            index.set(canonicalKey(e.fm.package, type, shortcode), value);
+            // In Foundry an item and its documentation are two documents, so
+            // `skill/wpnc` and `docskill/wpnc` are two UUIDs (#1362). Here the
+            // item note renders as one page which *is* its documentation, so
+            // the two qualifiers alias one URL and an anchor on either is an
+            // ordinary in-page anchor. One authored link, correct in both
+            // builds — restricted to the types that actually have an item doc,
+            // so a qualifier the packs would reject is reported broken here too.
+            if (hasDocEntry(type)) {
+                contentTypes.add(`doc${type}`);
+                index.set(`doc${type}/${shortcode}`.toLowerCase(), value);
+            }
+        }
+
+        const aliases = [
+            ...(Array.isArray(e.fm.aliases) ? e.fm.aliases : []),
+            ...(Array.isArray(e.fm.name?.aliases) ? e.fm.name.aliases : []),
+            e.name,
+            path.basename(e.base, ".md").replace(/_/g, " "),
+        ].filter((a) => typeof a === "string" && a);
+
+        for (const alias of aliases) {
+            const key = `${type}|${alias}`.toLowerCase();
+            if (typeCollide.has(key)) continue;
+            const cur = typeAlias.get(key);
+            if (cur && cur.url !== value.url) {
+                typeAlias.delete(key);
+                typeCollide.add(key);
+            } else if (!cur) {
+                typeAlias.set(key, value);
+            }
+        }
+    }
+
+    return {
+        index,
+        ambiguous,
+        typeAlias,
+        typeCollide,
+        contentTypes,
+        sections,
+        refIndex,
+        conflicts,
+    };
+}
+
+/**
+ * The per-page context a wikilink resolver takes.
+ *
+ * Assembled here so a consumer spells out only what is genuinely its own — the
+ * source path, the citing note's type, and where errors collect — instead of
+ * restating the whole index every call. Both site builds wrote this object by
+ * hand, identically.
+ *
+ * @param {SiteIndex} built - The result of {@link buildSiteIndex}.
+ * @param {object} options - Per-page inputs.
+ * @param {string} options.src - Source path of the page being resolved, for
+ *   diagnostics.
+ * @param {string|null} [options.type] - The citing note's type, which scopes a
+ *   bare alias lookup.
+ * @param {object[]} options.errors - Collector the resolver appends to.
+ * @param {Map<string, object>} [options.foreignIndex] - The foreign index, for
+ *   resolvers that distinguish a foreign hit from a local one.
+ * @param {boolean} [options.manifestsComplete] - Whether every package this
+ *   build links into supplied a manifest. When false, a resolver may soften an
+ *   unresolved cross-package link rather than fail.
+ * @returns {object} The resolver context.
+ */
+export function wikiContext(
+    built,
+    {
+        src,
+        type = null,
+        errors,
+        foreignIndex = new Map(),
+        manifestsComplete = true,
+    },
+) {
+    return {
+        index: built.index,
+        foreign: foreignIndex,
+        manifestsComplete,
+        collide: built.ambiguous,
+        sections: built.sections,
+        typeAlias: built.typeAlias,
+        typeCollide: built.typeCollide,
+        contentTypes: built.contentTypes,
+        type,
+        errors,
+        src,
+    };
+}

package/engine/web-wikilinks.mjs

@@ -0,0 +1,330 @@
+/*
+ * 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/)`
+ *   `[[Text]]`                      → the same, via a type-scoped alias
+ *   `[[type/shortcode#slug|Text]]`   → `[Text](/section/slug/#slug)`
+ *   `[[#slug|Text]]`                 → `[Text](#slug)`
+ *
+ * The KB *section* is not always the type: prose pages (`type: doc`) route by
+ * their `category`, so `doc/quickstart` lands on `/user-guide/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 (#20).
+ */
+
+// Whether a target is an *address* rather than prose is read with 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 (#1409).
+import { readQualifier } from "./wikilinks.mjs";
+import { replaceOutsideCode } from "./code-fences.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.
+export { slugify };
+import { WIKILINK, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
+
+/** KB heading/anchor slug: lowercase, non-alphanumerics to single hyphens. */
+
+/**
+ * Whether a link target addresses a document as `type-shortcode` (or the legacy
+ * `type/shortcode`) rather than naming it in prose.
+ *
+ * Delegates to the pack build's {@link readQualifier} so one rule serves both
+ * builds. A `reason` is as much an address as a resolved qualifier is — the
+ * target is qualified either way, it just names no known type — and the caller
+ * only ever asks this of a target that already resolved.
+ *
+ * @param {string} target - The link target, anchor already removed.
+ * @param {Set<string>} [contentTypes] - Every content type the KB build saw.
+ * @returns {boolean} `true` when the target is an address.
+ */
+function isAddress(target, contentTypes) {
+    return readQualifier(target, contentTypes ?? new Set()) !== null;
+}
+
+/**
+ * The `type/shortcode` index key a qualified target resolves to, or `null`.
+ *
+ * The KB index is keyed by the canonical `type/shortcode`, so a target written
+ * in the hyphen separator — which is what the vault authors (#1398) — has to be
+ * rewritten to it before lookup. Uses the same {@link readQualifier} as
+ * {@link isAddress}, so recognising an address and resolving one can never
+ * disagree: the first-hyphen split and the known-type condition that keeps
+ * `[[Grukar-ahk]]` an alias are stated once, in the pack build.
+ *
+ * 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 {string} target - The link target, anchor already removed.
+ * @param {Set<string>} [contentTypes] - Every content type the KB build saw.
+ * @returns {string | null} The index key, or `null` when not qualified.
+ */
+function qualifiedKey(target, contentTypes) {
+    const read = readQualifier(target, contentTypes ?? new Set());
+    if (!read || read.reason) return null;
+    return `${read.type}/${read.shortcode}`.toLowerCase();
+}
+
+/**
+ * How an **unresolved** link renders.
+ *
+ * The author's text is kept, so the sentence still reads — dropping it would
+ * silently rewrite the prose. It is marked so a reader can tell that something
+ * was meant to be a link, and an author can find it: the appearance lives in
+ * `scss/components/_unresolved-link.scss` for Foundry and in the Hugo theme for
+ * the website, not here.
+ *
+ * This is deliberately identical to the pack compiler's own `unresolvedLink`,
+ * down to the class name and the `title` wording. One authored link renders on
+ * two surfaces, and the two builds have drifted before over exactly this kind
+ * of detail (#1409) — matching markup is what keeps a reader's cue the same in
+ * a journal and on the page. Duplicated rather than imported only because the
+ * function is not exported from `@heroiclands/package-build`; hoisting it there
+ * is HeroicLands/content-build#13.
+ *
+ * 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.
+ * @returns {string} An inline HTML span, safe to sit in a markdown table cell.
+ */
+function unresolvedLink(text, target) {
+    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>`
+    );
+}
+
+/**
+ * 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 (#1428).
+ *
+ * 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.
+ *
+ * A target is looked up case-insensitively: first as an alias scoped to the
+ * source's own **type** (`ctx.typeAlias`, keyed `type|alias`) — a note's
+ * directory and `category` play no part — then in the KB-wide `ctx.index` (keyed
+ * by the unambiguous `section/slug` and `type/shortcode`, plus name/filename/slug
+ * fallbacks).
+ *
+ * An unresolved target fails the build only when it is a genuine intra-KB
+ * problem — an ambiguous alias, or a qualified `prefix/key` whose prefix is a
+ * real KB section or content directory. Anything else is treated as an external
+ * reference — until every package's manifest is present, after which any
+ * `type-shortcode` address resolving nowhere fails too. Failures are collected
+ * in `ctx.errors`.
+ *
+ * Whether or not it fails the build, a target that resolves nowhere renders
+ * through {@link unresolvedLink} rather than as bare prose (#1665): the author's
+ * text is kept, marked so a reader can see a link was intended. Not failing the
+ * build is a statement that the link *may* be legitimate prose — it was never a
+ * reason to make a dead link indistinguishable from the sentence around it.
+ *
+ * A target that **resolved** to an entry with no page is not this case and is
+ * not marked: a pack-only package (#1516) publishes Foundry addresses and no
+ * web pages, so the author wrote a real address and there is simply nothing to
+ * link to.
+ *
+ * @param {string} body - The markdown body.
+ * @param {object} ctx - `{ index, typeAlias, collide, typeCollide, sections,
+ *   contentTypes, foreign, manifestsComplete, type, errors, src }`. `foreign`
+ *   is the cross-package manifest index (#1446); `manifestsComplete` says
+ *   whether every linkable package is accounted for. Together they decide
+ *   whether an unresolved address is a typo or a package merely absent.
+ * @returns {string} The body with wikilinks rewritten.
+ */
+export function resolveWebWikilinks(body, ctx) {
+    // Code is verbatim: a `[[…]]` inside a code fence, an indented block or an
+    // inline span is source text, not a link (#1505).
+    return replaceOutsideCode(body, WIKILINK, (_m, rawInner) => {
+        const { target, anchor, display } = parseWikilink(rawInner);
+
+        // `[[#section-slug|Text]]` — a section of this same page.
+        if (isSamePage({ target, anchor })) {
+            return `[${display ?? anchor}](#${slugify(anchor)})`;
+        }
+
+        const key = target.toLowerCase();
+        const typeKey = ctx.type ? `${ctx.type}|${key}`.toLowerCase() : null;
+        // The canonical separator (#1398) has to be resolved, not merely
+        // recognised. Without this the form resolved only when source and
+        // target shared a type, by way of the seeded alias below; every
+        // *cross-type* link written in it silently lost its href.
+        const hyphenKey = qualifiedKey(target, ctx.contentTypes);
+        const hit =
+            (typeKey ? ctx.typeAlias.get(typeKey) : undefined) ??
+            ctx.index.get(key) ??
+            (hyphenKey ? ctx.index.get(hyphenKey) : undefined) ??
+            // A manifest entry carries the same `{ url, name }` shape as a
+            // local one (#1446), 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.
+            (hyphenKey ? ctx.foreign?.get(hyphenKey) : undefined);
+        if (hit) {
+            // With no explicit label, a *qualified* target has no prose to show
+            // (a shortcode is not display text), so fall back to the document's
+            // name. A bare `[[Text]]` is already the prose the author wrote —
+            // substituting the canonical name there would rewrite the sentence
+            // ("worsens the [[Shock State]]" must not render as "Shock").
+            // Both separators qualify: `type-shortcode` is the canonical form
+            // (#1398), and a hyphen inside a note *name* ("Grukar-ahk") is not
+            // one, which is why the rule is the packs' own (#1409).
+            const text =
+                display ??
+                (isAddress(target, ctx.contentTypes) ? hit.name : target);
+            // A pack-only package publishes Foundry addresses and no pages
+            // (#1516), 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.
+            if (!hit.url) return text;
+            return `[${text}](${anchor ? `${hit.url}#${slugify(anchor)}` : hit.url})`;
+        }
+
+        const slash = target.indexOf("/");
+        const prefix =
+            slash === -1 ? null : target.slice(0, slash).toLowerCase();
+        // Deliberately *not* extended to the hyphen form, which is also how a
+        // note addresses content in a package this build does not publish
+        // (`Rules/Bestiary.md` → `being-grkrahk`, a real note in the `thalorna`
+        // package). Nothing in the syntax separates that from a typo,
+        // so failing here would break the build on correct content.
+        //
+        // A dead address is caught instead by `lint:content-links` (#1414),
+        // which holds the reviewed list of cross-package exceptions — and which,
+        // unlike this build, runs as part of `npm run lint` on every change.
+        const badQualified =
+            prefix !== null &&
+            (ctx.sections.has(prefix) || ctx.contentTypes.has(prefix));
+        // The hyphen form is the canonical address (#1398) and is what the
+        // authored content writes. It could not be guarded while some packages
+        // were invisible here: `Rules/Bestiary.md` addresses `being-grkrahk`,
+        // a real note in the `thalorna` package, and nothing in the syntax
+        // separated that legitimate cross-package reference from a typo — so
+        // treating the form as definitely-local would have failed the build on
+        // correct content.
+        //
+        // The link manifest settles it (#1446). Once every linkable package is
+        // accounted for — built here or vendored as a manifest — an address
+        // resolving in none of them is a typo and nothing else. Until then
+        // `manifestsComplete` is false and the form stays unguarded, so the
+        // check returns exactly when it becomes decidable rather than on a date
+        // someone has to remember.
+        const badAddress = ctx.manifestsComplete === true && hyphenKey !== null;
+
+        if ((typeKey && ctx.typeCollide.has(typeKey)) || ctx.collide.has(key)) {
+            ctx.errors.push({ file: ctx.src, target, reason: "ambiguous" });
+        } else if (badQualified || badAddress) {
+            ctx.errors.push({
+                file: ctx.src,
+                target,
+                reason: "broken type/shortcode",
+            });
+        }
+        return unresolvedLink(display ?? target, target);
+    });
+}