@heroiclands/package-build 22.1.1 → 22.3.0

package/engine/site-index.mjs

@@ -65,20 +65,14 @@ import { isDraftNote } from "./note-vocabulary.mjs";
  *
  * @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.
+ *                           tree. Only content entries take part in
+ *                           type-scoped indexing; anything else is carried
+ *                           through unindexed.
  * @property {object} fm     The note's frontmatter.
  * @property {string} name   Display name.
  * @property {string} slug   URL segment.
- * @property {string} [sec]  The Hugo section a **tree** page is filed under, and
- *                           the first segment of the `<sec>/<slug>` address it
- *                           is reachable by. A content page has none: it is
- *                           addressed by `(type, shortcode)` and emitted flat.
  * @property {string} base   Source file's basename, e.g. `Climbing.md`.
  * @property {string} url    The page's published address.
- * @property {boolean} [isReadme]  Whether a tree page is its directory's
- *                           landing.
  */
 
 /**
@@ -94,23 +88,18 @@ import { isDraftNote } from "./note-vocabulary.mjs";
  *                                       from `index`.
  * @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, subType?: 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.
  */
 
 /**
  * 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.
+ * in — one map, one lookup, no precedence rule. It runs before the local pass
+ * writes a single key, so a local page always ends up owning its own address.
  *
  * 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
@@ -122,22 +111,15 @@ import { isDraftNote } from "./note-vocabulary.mjs";
  *
  * @param {Map<string, object>} index - The local index, mutated.
  * @param {Map<string, {package: string, type?: string}>} foreignIndex - Merged in.
- * @returns {{conflicts: {key: string, package: string}[],
- *   ambiguous: Set<string>}} The addresses two packages both claim outright,
- *   and the short `type/shortcode` forms two foreign packages claim — those are
- *   left out of the index, so a resolver can say *ambiguous* rather than
- *   *nothing answers*.
+ * @returns {{ambiguous: Set<string>}} The short `type/shortcode` forms two
+ *   foreign packages claim — those are left out of the index, so a resolver
+ *   can say *ambiguous* rather than *nothing answers*.
  */
 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);
@@ -154,7 +136,7 @@ function mergeForeign(index, foreignIndex) {
     for (const [key, value] of short) {
         if (!index.has(key)) index.set(key, value);
     }
-    return { conflicts, ambiguous };
+    return { ambiguous };
 }
 
 /**
@@ -178,7 +160,6 @@ export function buildSiteIndex(
 ) {
     const index = new Map();
     const contentTypes = new Set();
-    const sections = new Set();
     const refIndex = new Map();
     // Every package an address may name: this build's own, plus every one a
     // vendored manifest speaks for. Without it `readQualifier` cannot see the
@@ -187,30 +168,12 @@ export function buildSiteIndex(
     const ownPackage = contentPackage();
     const packages = new Set(ownPackage ? [ownPackage] : []);
 
-    // `section/slug` is unique by construction, and is now a **tree** page's
-    // address: a `trees` entry keeps its source layout below a named section,
-    // so `dev-docs/testing` is how one is cited. A content page carries no
-    // section at all and is addressed by `(type, shortcode)` below —
-    // indexing it here as well would have written `weapongear/weapongear-dagger`,
-    // a key no author could reasonably write.
-    //
-    // A page's name, filename and bare slug were indexed here too, as
-    // collision-aware fallbacks the bare `[[Name]]` form looked up; that form is
-    // retired and nothing consults them, so they are gone and with them the rule
-    // that two pages of a type may not share a name.
-    for (const e of entries) {
-        if (typeof e.sec !== "string" || !e.sec) continue;
-        sections.add(e.sec.toLowerCase());
-        // `draft` rides on every key a page is addressable by, because a link
-        // into a draft note renders marked whichever of them the author wrote.
-        // It decides nothing about resolution: the page is indexed and
-        // published as any other.
-        index.set(`${e.sec}/${e.slug}`.toLowerCase(), {
-            url: e.url,
-            name: e.name,
-            draft: isDraftNote(e.fm),
-        });
-    }
+    // A page is addressed by `(type, shortcode)` and nothing else. Its name,
+    // filename and bare slug are not keys: the bare `[[Name]]` form that
+    // looked them up is retired, and with it the rule that two pages of a
+    // type may not share a name. A page carries no section either — a
+    // section is a listing the configuration declares, not part of any
+    // address.
 
     // 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 —
@@ -226,15 +189,11 @@ export function buildSiteIndex(
     // 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, ambiguous } = mergeForeign(index, foreignIndex);
+    const { ambiguous } = 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.
+        // Only a content note is addressable; anything else is carried
+        // through and takes no part in type-scoped indexing.
         if (e.kind !== "content") continue;
         const type = String(e.fm.type).toLowerCase();
         contentTypes.add(type);
@@ -303,11 +262,9 @@ export function buildSiteIndex(
         index,
         ambiguous,
         contentTypes,
-        sections,
         packages,
         noIndexPackages,
         refIndex,
-        conflicts,
     };
 }
 
@@ -352,7 +309,6 @@ export function wikiContext(
         // a URL and a name, an asset's carries the path to a file.
         assets,
         collide: built.ambiguous,
-        sections: built.sections,
         contentTypes: built.contentTypes,
         packages: built.packages,
         noIndexPackages: built.noIndexPackages,

package/engine/web-wikilinks.mjs

@@ -312,7 +312,7 @@ function isPlainMap(value) {
  * for the website, and what the book reads its staging list out of.
  *
  * @param {string} body - The markdown body.
- * @param {object} ctx - `{ index, assets, collide, sections, contentTypes,
+ * @param {object} ctx - `{ index, assets, collide, contentTypes,
  *   packages, noIndexPackages, foreign, type, errors, src, file }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type;
@@ -415,10 +415,6 @@ export function resolveWebWikilinks(body, ctx) {
         const rawKey = target.toLowerCase();
         const hit =
             lookupRead(ctx.index, read, ctx.contentPackage) ??
-            // `section/slug` is the site's own address for a page, and it is in
-            // the same map. Admitted only when the target carries a slash, so
-            // a page's bare slug cannot answer for an address.
-            (rawKey.includes("/") ? ctx.index.get(rawKey) : undefined) ??
             // 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
@@ -449,16 +445,6 @@ export function resolveWebWikilinks(body, ctx) {
             return hit.draft ? draftLink(link) : link;
         }
 
-        const slash = target.indexOf("/");
-        const prefix = slash === -1 ? null : target.slice(0, slash).toLowerCase();
-        // A slash-qualified target whose prefix is a real KB **section** is an
-        // address in the site's own `section/slug` space, which the lookup
-        // above already consulted. It parses as no `type/shortcode`, but it did
-        // address something and nothing answered — so it is unresolved, not
-        // unaddressable. (A prefix that is a content *type* never reaches here:
-        // it parses as an address.)
-        const siteAddress = prefix !== null && ctx.sections.has(prefix);
-
         // **An address resolving nowhere is a failure, unconditionally**.
         //
         // It was gated on a manifest-completeness check — while any linkable package was
@@ -485,7 +471,7 @@ export function resolveWebWikilinks(body, ctx) {
             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) || siteAddress ? "unresolved"
+            : read && !read.reason ? "unresolved"
             : read?.reason === "unknown-type" ? "unknown-type"
             : read?.reason === "no-content-index" ? "no-content-index"
                 // Every link is an address, and this is not one. Distinct from

package/engine/wikilinks.mjs

@@ -353,12 +353,14 @@ export function anchorPageId(noteId, anchorSlug) {
  * Builds the link-resolution tables for a content tree.
  *
  * @param {Array<{type: string, id: string, shortcode?: string|null,
- *   name?: string, pack?: string, docPack?: string,
+ *   name?: string, pack?: string, docPack?: string, none?: boolean,
  *   draft?: boolean}>} docs -
  *   One entry per content note. `pack` / `docPack` name the packs the note's
  *   document and its documentation entry landed in; omitted, the conventional
- *   one-pack-per-type names stand in. `draft` says the note carries the `draft`
- *   tag, which marks links *into* it and changes nothing else.
+ *   one-pack-per-type names stand in. `none` says the note declares
+ *   `pack: none` and compiles into no document, so it has no UUID to link to.
+ *   `draft` says the note carries the `draft` tag, which marks links *into* it
+ *   and changes nothing else.
  * @param {string} packageId - The Foundry package shipping the packs; the first
  *   segment of every emitted UUID.
  * @param {Map<string, object>} [foreign] - Canonically keyed entries from
@@ -408,17 +410,29 @@ export function buildWikilinkIndex(
         if (!d.id || !d.type) continue;
         types.add(norm(d.type));
 
-        uuidByDoc.set(d, {
-            // `d.pack` is where this note's document actually landed, resolved
-            // by the pack router when the index was collected. A repository may
-            // ship several packs of one type and a UUID carries the
-            // pack name, so the address cannot be derived from the type alone.
-            uuid: compendiumUuid(packageId, d.type, d.id, d.pack),
-            // An item's prose compiles into a separate JournalEntry, addressed
-            // by the virtual `doc<type>` qualifier. Its id is derived from the
-            // item's, so its address is knowable here too.
-            docUuid: compendiumUuid(packageId, "doc", itemDocEntryId(d.id), d.docPack),
-        });
+        uuidByDoc.set(
+            d,
+            // A note declaring `pack: none` compiles into no document, so it
+            // has no address in any compendium: a link to it is a page on the
+            // web and prose in a journal. Recorded as an entry with no UUIDs
+            // rather than left out, so the address still resolves and a link
+            // to it is never reported as dead.
+            d.none ?
+                { uuid: undefined, docUuid: undefined }
+            :   {
+                    // `d.pack` is where this note's document actually landed,
+                    // resolved by the pack router when the index was
+                    // collected. A repository may ship several packs of one
+                    // type and a UUID carries the pack name, so the address
+                    // cannot be derived from the type alone.
+                    uuid: compendiumUuid(packageId, d.type, d.id, d.pack),
+                    // An item's prose compiles into a separate JournalEntry,
+                    // addressed by the virtual `doc<type>` qualifier. Its id
+                    // is derived from the item's, so its address is knowable
+                    // here too.
+                    docUuid: compendiumUuid(packageId, "doc", itemDocEntryId(d.id), d.docPack),
+                },
+        );
 
         if (d.shortcode) byShortcode.set(`${norm(d.type)}/${norm(d.shortcode)}`, d);
     }
@@ -783,6 +797,13 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
             docUuid: compendiumUuid(index.packageId, "doc", itemDocEntryId(doc.id), doc.docPack),
         };
         const entryUuid = itemDoc ? addresses.docUuid : addresses.uuid;
+        // The target is a note that compiles into no document — `pack: none`.
+        // The address is real and the page exists on the web, so this is not
+        // a dead link and must not fail the build; but a compendium has
+        // nothing to open, so the reader gets the prose and no `@UUID`. The
+        // mirror of what the website does for an address that publishes a
+        // document and no page.
+        if (entryUuid === undefined) return text;
         const entryId = itemDoc ? itemDocEntryId(doc.id) : doc.id;
         const isJournal = itemDoc || packForType(doc.type).docType === "JournalEntry";
         // A JournalEntry link opens a journal — at its first page, or at the

package/manifest.mjs

@@ -28,10 +28,12 @@
  *
  * - **Declared** — the `packageBuild.manifest` block, emitted unchanged, so a
  *   key Foundry adds in a later version needs no release of this package.
- * - **Derived** — the identity, the description, the version, the release
- *   addresses, the compatibility ranges and the pack list. Declaring one of
- *   these is an error rather than an override: the authored copy would be
- *   silently overwritten.
+ *   `descriptionHtml` is the one exception, folded into the derived
+ *   `description` below rather than surviving under its own name.
+ * - **Derived** — the identity, the description (from `descriptionHtml`), the
+ *   version, the release addresses, the compatibility ranges and the pack
+ *   list. Declaring `description` directly is an error rather than an
+ *   override: the authored copy would be silently overwritten.
  * - **Computed** — namespaced `flags` a repository works out for itself.
  *
  * **Nothing here invents an address.** The repository URL is read from
@@ -459,11 +461,13 @@ function withoutBuildKeys(entry) {
  * Three kinds of key end up in the result:
  *
  * - **Declared** — everything in `packageBuild.manifest`, emitted unchanged, so
- *   a key Foundry adds later needs no release of this package.
+ *   a key Foundry adds later needs no release of this package. The one
+ *   exception is `descriptionHtml`, folded into the description below rather
+ *   than surviving under its own name.
  * - **Derived** — the identity, the description, the release addresses, the
  *   version, the Foundry and system compatibility ranges, and the pack list.
- *   These are refused if also declared: an authored copy would be overwritten
- *   and the two would disagree with nothing to say so.
+ *   These are refused if also declared (`description` directly; `descriptionHtml`
+ *   is how it is authored) and the two would disagree with nothing to say so.
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *
@@ -479,7 +483,9 @@ function withoutBuildKeys(entry) {
  * @returns {object} The manifest, ready to serialise.
  */
 export function buildManifest({ config, packageJson, artifact, flags }) {
-    const declared = config.packageBuild?.manifest ?? {};
+    // `descriptionHtml` is the authored source of `description` — pulled out
+    // so it never survives the spread below under its own name.
+    const { descriptionHtml, ...declared } = config.packageBuild?.manifest ?? {};
     const repoUrl = normalizeRepoUrl(packageJson.repository);
 
     const derived = {
@@ -495,8 +501,8 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     };
     // Own-property presence, not just value, decides whether a key survives
     // into `ordered` below — an explicit `undefined` would still occupy a slot
-    // in it. Set only when `package.json` actually declares one.
-    if (packageJson.description !== undefined) derived.description = packageJson.description;
+    // in it. Set only when the repository actually declares one.
+    if (descriptionHtml !== undefined) derived.description = descriptionHtml;
     if (config.compatibility) derived.compatibility = config.compatibility;
 
     // `requiresSystem` is the gate half of the declare/require split. It

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.1.1",
+    "version": "22.3.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/release.mjs

@@ -13,7 +13,7 @@
 
 /**
  * The release archive — the two files a Foundry package's GitHub Release
- * carries.
+ * carries, plus the optional siblings a repository opts into.
  *
  * Foundry installs a package by fetching the `download` URL its manifest
  * advertises, so a release publishes `<artifact>.zip`, the whole staged tree,
@@ -21,7 +21,10 @@
  * re-fetches to notice a new version. A package that ships content publishes a
  * third: the content index other packages resolve its addresses through,
  * named by the `flags.metadataUrl` the manifest advertises. Every name is fixed
- * by what the manifest says, not chosen here — see `manifest.mjs`.
+ * by what the manifest says, not chosen here — see `manifest.mjs`. A package
+ * that publishes a DataModel schema (`packageBuild.schema`, staged through
+ * `packageBuild.assets`) gets a fourth: `schema.json`, published whenever the
+ * stage carries one and silently skipped otherwise.
  *
  * Kept apart from `stage.mjs` because this is the only part of assembling a
  * package that needs a dependency. A repository that never cuts a release from
@@ -40,6 +43,8 @@ import path from "node:path";
 // release job came to fail before a single byte was written.
 import { ZipArchive } from "archiver";
 
+import { SCHEMA_ARTIFACT_FILE } from "./engine/foreign-catalog.mjs";
+
 /**
  * Zip the staged tree and place the manifest beside the archive.
  *
@@ -60,14 +65,14 @@ import { ZipArchive } from "archiver";
  * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
  *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   schema?: string, pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
  *   bytes: number, version: string}>} The paths written, what the book build
  *   found, the archive's size, and the version the manifest declares.
- *   `metadata` is absent when the manifest advertises no content index, and
- *   `pdf` is absent when no book was written. `pdfSkipped` is `null` when a
- *   book was built, and otherwise the reason none was — itself `null` when the
- *   book builder could not be loaded, which is reported through
- *   `pdfFindings`.
+ *   `metadata` is absent when the manifest advertises no content index,
+ *   `schema` is absent when the stage carries no `schema.json`, and `pdf` is
+ *   absent when no book was written. `pdfSkipped` is `null` when a book was
+ *   built, and otherwise the reason none was — itself `null` when the book
+ *   builder could not be loaded, which is reported through `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -119,6 +124,7 @@ export async function packRelease({
     await fsp.copyFile(stagedManifest, path.join(out, manifestName));
 
     const metadata = await publishMetadataIndex({ manifest, stage, out, metadataDir });
+    const schema = await publishSchemaAsset({ stage, out });
 
     // Last, and never fatal: the archive and the manifest are the release, and
     // a book that failed to set is a reported problem rather than a reason to
@@ -132,6 +138,7 @@ export async function packRelease({
         zip: zipPath,
         manifest: path.join(out, manifestName),
         ...(metadata ? { metadata } : {}),
+        ...(schema ? { schema } : {}),
         ...(book.pdf ? { pdf: book.pdf } : {}),
         pdfFindings: book.findings,
         pdfSkipped: book.pdf ? null : book.reason,
@@ -226,3 +233,29 @@ async function publishMetadataIndex({ manifest, stage, out, metadataDir }) {
     await fsp.copyFile(found, dest);
     return dest;
 }
+
+/**
+ * Place the published DataModel schema beside the archive, when the stage
+ * carries one.
+ *
+ * **The stage is the one place this looks.** `package-build schema` writes
+ * `build/schema.json`, and a repository that wants it released names it in
+ * `packageBuild.assets` (`from: build/schema.json`) the way every other
+ * staged file is declared — so a schema at the stage root is a repository
+ * that opted in, and its absence is a repository that has not, which is
+ * exactly as releasable as one that never adopted the artifact at all.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage - The staged tree.
+ * @param {string} opts.out - Where release assets are written.
+ * @returns {Promise<string|undefined>} The published path, or nothing when
+ *   the stage carries no `schema.json`.
+ */
+async function publishSchemaAsset({ stage, out }) {
+    const src = path.join(stage, SCHEMA_ARTIFACT_FILE);
+    if (!fs.existsSync(src)) return undefined;
+
+    const dest = path.join(out, SCHEMA_ARTIFACT_FILE);
+    await fsp.copyFile(src, dest);
+    return dest;
+}

package/sohl/kb-passes.mjs

@@ -12,25 +12,23 @@
  */
 
 /**
- * The `sohl` knowledgebase's own body passes.
+ * The `sohl` knowledgebase's own body pass.
  *
  * `content-build site` publishes a content tree as a website, and almost all of
- * that job is the same for every package. These two rewrites are not: they are
- * driven by a TypeDoc symbol map and a repository layout only this package has,
- * and they are ruled explicitly per-consumer.
+ * that job is the same for every package. This rewrite is not: it is driven by
+ * a TypeDoc symbol map only this package has, and it is ruled explicitly
+ * per-consumer.
  *
- * They live here rather than in a script in the consuming repository for the
+ * It lives here rather than in a script in the consuming repository for the
  * same reason `sohl/item-builders.mjs` and `sohl/being-info.mjs` do: a
  * configuration is data and cannot hold a function, so a package-specific table
  * of code is **named** from configuration and resolved from a registry. What is
  * package-specific is the code; what is repository-specific — where the symbol
- * map sits, what the API is served at, which GitHub tree to link into — is
- * options, supplied beside the name.
+ * map sits, what the API is served at — is options, supplied beside the name.
  *
- * Neither *rewrite* ever fails a build. A `{@link}` the map does not know
- * degrades to a code span, and a relative link that resolves outside the
- * documentation tree becomes a GitHub blob URL. Both are legible to a reader; a
- * broken link or a failed build for a syntax example in prose would not be.
+ * The *rewrite* never fails a build. A `{@link}` the map does not know
+ * degrades to a code span, which is legible to a reader; a failed build for a
+ * syntax example in prose would not be.
  *
  * Building the bundle is a different matter: a `symbolMap` that is configured
  * and cannot be used fails, loudly, before a page is rendered. Degrading
@@ -168,80 +166,21 @@ export function resolveApiLinks(body, symbols, apiBase) {
     });
 }
 
-/**
- * Rewrites the relative links in a developer-doc body so they resolve on the
- * published site.
- *
- * Developer docs are authored to link one another and the source tree with
- * repository-relative paths, and neither target exists at the same path once
- * rendered. Each link is resolved against the doc's own location:
- *
- * - a `*.md` link landing inside the documentation tree becomes the published
- *   route, preserving any `#anchor`; a `README` is its directory's landing, so
- *   that segment is dropped.
- * - anything else — source, templates, a repository-root `*.md` — becomes its
- *   GitHub blob URL.
- *
- * Absolute URLs, anchor-only links, `mailto:` and site-root links are untouched.
- *
- * @param {string} body - The markdown body.
- * @param {string} docRel - The doc's path relative to the documentation tree.
- * @param {object} options - `{ repoRoot, docsSrc, docsRel, route, blob }`.
- * @returns {string} The body with every relative link rewritten.
- */
-export function rewriteRepoLinks(body, docRel, options) {
-    const { repoRoot, docsSrc, docsRel, route, blob } = options;
-    const docDir = path.dirname(docRel);
-    return body.replace(/\]\(([^)]+)\)/g, (whole, raw) => {
-        // Peel an optional link title: [text](url "title").
-        const sp = raw.search(/\s/);
-        const href = sp === -1 ? raw : raw.slice(0, sp);
-        const title = sp === -1 ? "" : raw.slice(sp);
-        if (/^(https?:|mailto:|tel:|#|\/)/.test(href)) return whole;
-
-        const hash = href.indexOf("#");
-        const filePart = hash === -1 ? href : href.slice(0, hash);
-        const anchor = hash === -1 ? "" : href.slice(hash);
-        if (!filePart) return whole;
-
-        const repoRel = path
-            .relative(repoRoot, path.resolve(docsSrc, docDir, filePart))
-            .replace(/\\/g, "/");
-
-        let out;
-        if (repoRel.startsWith(`${docsRel}/`) && repoRel.endsWith(".md")) {
-            const rel2 = repoRel.slice(docsRel.length + 1, -3).toLowerCase();
-            const devPath = path.basename(rel2) === "readme" ? path.posix.dirname(rel2) : rel2;
-            out = `${route}${devPath === "." ? "" : `${devPath}/`}${anchor}`;
-        } else {
-            out = `${blob}${repoRel}${anchor}`;
-        }
-        return `](${out}${title})`;
-    });
-}
-
 /**
  * The `sohl` knowledgebase pass bundle, built from its options.
  *
- * A pass bundle is two optional hooks the page renderer calls around wikilink
- * resolution, and the order matters:
- *
- * - `beforeLinks` runs on every page, before wikilinks resolve, because a
- *   `{@link}` tag may sit inside prose a wikilink also touches.
- * - `afterLinks` runs only on pages from an **extra tree** — the documentation
- *   tree — because repository-relative links are a property of how those pages
- *   are authored, not of content notes.
- *
- * Both run inside code-fence protection, so neither can rewrite a fenced example.
+ * A pass bundle is the hook the page renderer calls before wikilink
+ * resolution: `beforeLinks` runs on every page, before wikilinks resolve,
+ * because a `{@link}` tag may sit inside prose a wikilink also touches. It
+ * runs inside code-fence protection, so it cannot rewrite a fenced example.
  *
  * @param {object} options - Resolved from `site.passOptions`.
  * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map,
  *   relative to `repoRoot`. Absent means no API links; present and unusable is
  *   a build failure.
  * @param {string} [options.apiBase] - Where the API documentation is served.
- * @param {string} [options.blob] - GitHub blob base for repository files.
  * @param {string} options.repoRoot - The repository root, for relative paths.
- * @returns {{beforeLinks: Function, afterLinks: Function}} The bundle.
+ * @returns {{beforeLinks: Function}} The bundle.
  * @throws {Error} When a configured `symbolMap` cannot be resolved, read,
  *   parsed, or is not a name → page object.
  */
@@ -250,15 +189,5 @@ export function sohlKbPass(options) {
     const apiBase = options.apiBase ?? "";
     return {
         beforeLinks: (text) => resolveApiLinks(text, symbols, apiBase),
-        afterLinks: (text, page) =>
-            page.tree ?
-                rewriteRepoLinks(text, page.rel, {
-                    repoRoot: options.repoRoot,
-                    docsSrc: page.tree.from,
-                    docsRel: page.tree.rel,
-                    route: page.tree.route,
-                    blob: options.blob ?? "",
-                })
-            :   text,
     };
 }

package/types/config.d.mts

@@ -1,3 +1,20 @@
+/**
+ * Reject a configured value, naming the key it was written under.
+ *
+ * The dotted path rides on the error as `field` as well as appearing in the
+ * message, so {@link loadPackageBuildConfig} — the half that knows which file
+ * was read — can resolve it to a line and column. This half stays pure.
+ *
+ * Exported so a sibling module composing a configuration value this module
+ * does not itself validate — {@link module:engine/site-config}'s
+ * `hugoConfig`, checking `site.assets` — reports through the one helper
+ * rather than a second copy.
+ *
+ * @param {string} where - Dotted path of the offending key.
+ * @param {string} problem - What is wrong with it.
+ * @returns {never}
+ */
+export function fail(where: string, problem: string): never;
 /**
  * Where a declared `assetTransform` is loaded from.
  *

package/types/content-config.d.mts

@@ -133,10 +133,10 @@ 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.trees` / `site.landing`
- *   emit nothing, and nothing serves a page for its addresses.
+ *   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, the extra trees, the section landings.
+ *   knowledgebase and the section landings.
  *
  * **Homepage-only is a first-class mode, not an accommodation.**
  * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
@@ -200,10 +200,10 @@ 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.trees` / `site.landing`
- *   emit nothing, and nothing serves a page for its addresses.
+ *   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, the extra trees, the section landings.
+ *   knowledgebase and the section landings.
  *
  * **Homepage-only is a first-class mode, not an accommodation.**
  * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'