@heroiclands/package-build 20.7.0 → 21.1.0

package/engine/dependency-bump.mjs

@@ -0,0 +1,218 @@
+/*
+ * 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
+ */
+
+/**
+ * Taking a newer version of a dependency, without reformatting the lockfile.
+ *
+ * npm resolves the bump; this module's whole job is what npm does badly here.
+ * Every repository in the constellation indents `package-lock.json` with four
+ * spaces and prettier-ignores it, and npm rewrites it with two — so a
+ * three-line version change arrives as a seventeen-thousand-line diff that no
+ * reviewer can read past.
+ *
+ * The alternative — editing the three `version` / `resolved` / `integrity`
+ * lines by hand — is only correct while the new version's dependency set is
+ * identical to the old one's, and nothing tells the author when it is not. npm
+ * is what knows; so npm does the resolution and the indentation is restored
+ * afterwards.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+/** Dependency sections a bump may read a package's declared range from. */
+const DEPENDENCY_SECTIONS = ["dependencies", "devDependencies", "optionalDependencies"];
+
+/**
+ * The indentation a JSON file already uses, as the literal string to indent
+ * with.
+ *
+ * Read from the first indented line rather than assumed, because the two-space
+ * default is right for some consumers and wrong for most of them. A file whose
+ * second line is not indented — a one-line document — reports the npm default,
+ * which is what rewriting it would produce anyway.
+ *
+ * @param {string} text - The file's contents.
+ * @returns {string} The indent string, e.g. `"    "` or `"  "`.
+ */
+export function detectJsonIndent(text) {
+    const match = /\n([ \t]+)\S/.exec(text);
+    return match ? match[1] : "  ";
+}
+
+/**
+ * Rewrite a JSON file with a given indent, leaving its content untouched.
+ *
+ * @param {string} file - Absolute path to the JSON file.
+ * @param {string} indent - The indent string to write with.
+ * @returns {boolean} Whether the file's bytes changed.
+ */
+export function reindentJsonFile(file, indent) {
+    if (!fs.existsSync(file)) return false;
+    const before = fs.readFileSync(file, "utf8");
+    const trailingNewline = before.endsWith("\n") ? "\n" : "";
+    const after = JSON.stringify(JSON.parse(before), null, indent) + trailingNewline;
+    if (after === before) return false;
+    fs.writeFileSync(file, after);
+    return true;
+}
+
+/**
+ * Every package name a manifest declares a range for, in declaration order.
+ *
+ * @param {object} manifest - The parsed `package.json`.
+ * @returns {string[]} The declared package names.
+ */
+export function declaredDependencies(manifest) {
+    const names = [];
+    for (const section of DEPENDENCY_SECTIONS) {
+        for (const name of Object.keys(manifest?.[section] ?? {})) {
+            if (!names.includes(name)) names.push(name);
+        }
+    }
+    return names;
+}
+
+/**
+ * The packages a bump targets when the caller names none.
+ *
+ * The first-party scope, because that is the bump a consumer runs by hand: a
+ * third-party one arrives from Dependabot on its own schedule, while a
+ * first-party release is taken the moment it publishes, usually to unblock the
+ * very change that prompted it.
+ *
+ * @param {object} manifest - The parsed `package.json`.
+ * @param {string} [scope] - The scope prefix to match.
+ * @returns {string[]} The package names to bump.
+ */
+export function firstPartyDependencies(manifest, scope = "@heroiclands/") {
+    return declaredDependencies(manifest).filter((name) => name.startsWith(scope));
+}
+
+/**
+ * The version the lockfile currently resolves a package to.
+ *
+ * Read from the lockfile rather than the manifest, because the manifest states
+ * a *range* and the lockfile states what `npm ci` will actually install — which
+ * is the thing a bump moves. A caret range that already admits the new version
+ * needs no manifest change at all, and reporting the range would then show a
+ * bump as changing nothing.
+ *
+ * @param {object} lock - The parsed `package-lock.json`.
+ * @param {string} name - The package name.
+ * @returns {string|undefined} The locked version, if the lockfile holds one.
+ */
+export function lockedVersion(lock, name) {
+    return lock?.packages?.[`node_modules/${name}`]?.version;
+}
+
+/**
+ * Take the newest published version of one or more dependencies.
+ *
+ * npm performs the resolution — so a bump that changes the dependency set is
+ * as correct as one that moves three lines — and both JSON files are restored
+ * to the indentation they already used.
+ *
+ * @param {object} options - Options.
+ * @param {string} options.rootDir - The repository root holding `package.json`.
+ * @param {string[]} [options.packages] - Packages to bump. Defaults to every
+ *   first-party dependency the manifest declares.
+ * @param {string} [options.tag] - The dist-tag to take. Defaults to `latest`.
+ * @param {boolean} [options.check] - Report what would change and write nothing.
+ * @param {(command: string, args: string[], cwd: string) => void} [options.run] -
+ *   How to invoke npm. Injected by the tests, which have no registry.
+ * @returns {{changes: Array<{name: string, from: string|undefined, to: string|undefined}>,
+ *   unchanged: string[], reindented: string[], checked: boolean}} What moved.
+ */
+export function bumpDependencies({ rootDir, packages, tag = "latest", check = false, run }) {
+    const manifestPath = path.join(rootDir, "package.json");
+    const lockPath = path.join(rootDir, "package-lock.json");
+
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`no package.json at ${rootDir}`);
+    }
+    if (!fs.existsSync(lockPath)) {
+        throw new Error(
+            `no package-lock.json at ${rootDir}: this bump moves the lockfile, ` +
+                `which is what \`npm ci\` resolves from`,
+        );
+    }
+
+    const manifestText = fs.readFileSync(manifestPath, "utf8");
+    const lockText = fs.readFileSync(lockPath, "utf8");
+    const manifest = JSON.parse(manifestText);
+    const lockBefore = JSON.parse(lockText);
+
+    const declared = declaredDependencies(manifest);
+    const targets = packages?.length ? packages : firstPartyDependencies(manifest);
+
+    if (targets.length === 0) {
+        return { changes: [], unchanged: [], reindented: [], checked: check };
+    }
+
+    const unknown = targets.filter((name) => !declared.includes(name));
+    if (unknown.length > 0) {
+        throw new Error(
+            `not a declared dependency: ${unknown.join(", ")} — ` +
+                `a bump takes a newer version of something already depended on`,
+        );
+    }
+
+    const before = new Map(targets.map((name) => [name, lockedVersion(lockBefore, name)]));
+
+    if (check) {
+        const latest = (name) =>
+            execFileSync("npm", ["view", `${name}@${tag}`, "version"], {
+                cwd: rootDir,
+                encoding: "utf8",
+            }).trim();
+        const changes = [];
+        const unchanged = [];
+        for (const name of targets) {
+            const to = latest(name);
+            if (to && to !== before.get(name)) changes.push({ name, from: before.get(name), to });
+            else unchanged.push(name);
+        }
+        return { changes, unchanged, reindented: [], checked: true };
+    }
+
+    const invoke =
+        run ?? ((command, args, cwd) => execFileSync(command, args, { cwd, stdio: "pipe" }));
+
+    invoke(
+        "npm",
+        ["install", "--package-lock-only", ...targets.map((name) => `${name}@${tag}`)],
+        rootDir,
+    );
+
+    // Restore what npm reformatted. Both files, because npm rewrites the
+    // manifest too when a range has to move — which below 1.0 it always does,
+    // a caret there being locked to the minor.
+    const reindented = [];
+    if (reindentJsonFile(lockPath, detectJsonIndent(lockText))) reindented.push(lockPath);
+    if (reindentJsonFile(manifestPath, detectJsonIndent(manifestText))) {
+        reindented.push(manifestPath);
+    }
+
+    const lockAfter = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    const changes = [];
+    const unchanged = [];
+    for (const name of targets) {
+        const to = lockedVersion(lockAfter, name);
+        if (to !== before.get(name)) changes.push({ name, from: before.get(name), to });
+        else unchanged.push(name);
+    }
+
+    return { changes, unchanged, reindented, checked: false };
+}

package/engine/frontmatter-lint.mjs

@@ -63,6 +63,7 @@ import {
     unknownBlockKeys,
 } from "./system-block.mjs";
 import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { pathnameProblem } from "./pathnames.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES, RENAMED_TYPES, currentType, renamedTypeMessage } from "./ids.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
@@ -70,7 +71,12 @@ import { isAddressSegment } from "./address-charset.mjs";
 // than repeated, because a linter holding its own copy of what the compiler
 // reads is exactly the disagreement to avoid.
 import { DEFAULT_PARENT } from "./folder-notes.mjs";
-import { declaredTags, subTypeCharsetMessage, typeCharsetMessage } from "./note-vocabulary.mjs";
+import {
+    declaredTags,
+    exclusiveTagGroups,
+    subTypeCharsetMessage,
+    typeCharsetMessage,
+} from "./note-vocabulary.mjs";
 import {
     RETIRED_FIELD_ALIASES,
     declaresRetiredAlias,
@@ -672,6 +678,14 @@ function checkSubType(note, { type, entry }) {
  * findings above become none while a settlement tagged `vilage` is still
  * caught.
  *
+ * **A group declared as a slot is checked twice over.** Its tags are the
+ * alternative answers to one question — a being is a `character` or a
+ * `creature` — so two of them on one note is refused outright, by
+ * {@link checkExclusiveTags}, on top of the near miss every group gets. An
+ * *unfilled* slot is not a finding: the kind is authored deliberately, and
+ * nothing can tell a being nobody has classified yet from one the author means
+ * to leave unclassified.
+ *
  * @param {object} note - The note.
  * @param {object} opts
  * @param {string} opts.type - The note's declared `type`, which scopes the
@@ -706,6 +720,55 @@ function checkTags(note, { type }) {
     return findings;
 }
 
+/**
+ * Refuse a note that fills one single-valued tag slot twice.
+ *
+ * This is the whole of what "a closed tag vocabulary" can mean while `tags:`
+ * stays open. A slot's values are alternatives, not attributes: a being is a
+ * `character` or a `creature`, so a note carrying both has answered the
+ * question twice and every reader of the tag — an index, a query, a renderer —
+ * gets to pick. That is the same silent wrongness a misspelt classifying tag
+ * is, and it gets the same answer.
+ *
+ * **An error, not a warning**, because a warning does not change the build's
+ * exit code and a contradiction that still ships is a contradiction nobody
+ * fixes.
+ *
+ * **Located on the `tags` key**, because the fault is the list rather than
+ * either entry in it — both values are correctly spelt, and pointing at one of
+ * them would say the wrong one is the wrong one.
+ *
+ * @param {object} note - The note.
+ * @param {object} opts
+ * @param {string} opts.type - The note's declared `type`, which scopes the
+ *   slots checked.
+ * @returns {object[]} Findings.
+ */
+function checkExclusiveTags(note, { type }) {
+    const authored = (note.fm ?? {}).tags;
+    if (!Array.isArray(authored)) return [];
+
+    const carried = new Set(
+        authored.filter((t) => typeof t === "string" && t.trim()).map((t) => t.trim()),
+    );
+    const findings = [];
+    for (const { slot, tags } of exclusiveTagGroups(type)) {
+        const filled = tags.filter((t) => carried.has(t));
+        if (filled.length < 2) continue;
+        findings.push({
+            file: note.file,
+            ...positionInFrontmatter(note.raw ?? "", "tags"),
+            severity: "error",
+            message:
+                `a ${type}'s ${slot} is one tag, and this note carries ` +
+                `${filled.map((t) => `"${t}"`).join(" and ")}. Those are the alternative ` +
+                `answers to one question (${tags.join(", ")}), so carrying two of them ` +
+                `states no ${slot} at all. Keep the one that is true, or neither`,
+        });
+    }
+    return findings;
+}
+
 /**
  * The frontmatter fields that name artwork, and so resolve through
  * {@link module:engine/helpers.resolveImg}.
@@ -725,7 +788,7 @@ function checkTags(note, { type }) {
  *
  * @type {readonly {key: string, inData: boolean}[]}
  */
-const ART_FIELDS = Object.freeze([
+export const ART_FIELDS = Object.freeze([
     Object.freeze({ key: "img", inData: false }),
     Object.freeze({ key: "portrait", inData: true }),
 ]);
@@ -1120,6 +1183,29 @@ export function lintNote(
         });
     }
 
+    // A pathname written in Foundry's own spelling. It resolves for Foundry and
+    // for neither of the other two surfaces, which have no such directory — so
+    // the website serves a 404 and the book prints a caption with no picture,
+    // and nothing in either build has any reason to look twice at a string that
+    // parses. An **error**: the replacement is mechanical and named in the
+    // message, and a tree that has not been swept should stop rather than
+    // publish two broken surfaces out of three.
+    for (const { key, inData } of ART_FIELDS) {
+        const authored = authoredValue(fm, key, {
+            inData,
+            blockCollides: blockCollisions.has(key),
+        });
+        if (typeof authored !== "string") continue;
+        const problem = pathnameProblem(authored);
+        if (!problem) continue;
+        findings.push({
+            file: note.file,
+            ...at(key, authored),
+            severity: "error",
+            message: problem,
+        });
+    }
+
     for (const { key, inData } of ART_FIELDS) {
         // Reported above, and the distinction this draws does not exist there:
         // where nothing is emitted, `""` and `null` are equally inert and the
@@ -1219,6 +1305,7 @@ export function lintNote(
     // type's property — `draft` belongs to any note and `village` to a place —
     // so the finding must survive the early returns below.
     findings.push(...checkTags(note, { type }));
+    findings.push(...checkExclusiveTags(note, { type }));
 
     // A refused field must be one the note *wrote*: `resolveNoteId` fills
     // `fm.id` in place, so the parsed frontmatter carries a derived id the

package/engine/helpers.mjs

@@ -32,6 +32,8 @@ import yaml from "yaml";
 import unidecode from "unidecode";
 import markdownit from "markdown-it";
 import { iconPlugin } from "./content-icons.mjs";
+import { imagePlugin } from "./content-images.mjs";
+import { resolvePathname } from "./pathnames.mjs";
 import log from "loglevel";
 
 import { loadPackConfig } from "./pack-config.mjs";
@@ -77,19 +79,41 @@ export {
  * instruction to write `<i class="fa-solid …">` by hand: that would render on
  * the two HTML surfaces and be silently dropped by the third.
  */
-export const md = markdownit({ html: true }).use(
-    // Resolved per render, not at import: this constant is built before any
-    // configuration is read, and a package's own icons live in the
-    // configuration. A tree with none — or a caller with no configuration to
-    // find — falls back to the shipped table.
-    iconPlugin(() => {
-        try {
-            return loadPackConfig().icons;
-        } catch {
-            return undefined;
-        }
-    }),
-);
+export const md = markdownit({ html: true })
+    .use(
+        // Resolved per render, not at import: this constant is built before any
+        // configuration is read, and a package's own icons live in the
+        // configuration. A tree with none — or a caller with no configuration to
+        // find — falls back to the shipped table.
+        iconPlugin(() => {
+            try {
+                return loadPackConfig().icons;
+            } catch {
+                return undefined;
+            }
+        }),
+    )
+    // The width and position an image states, honoured as a figure. The
+    // vocabularies are closed and need no configuration; the address does, and
+    // is resolved per render for the reason the icon registry is — Foundry
+    // serves a file from inside the install, so a body image's address is
+    // translated by the same rule `img:` follows.
+    .use(
+        imagePlugin((src) => {
+            // **Reported elsewhere, never here.** A renderer has no channel to
+            // report through, and this one runs inside the very passes whose
+            // job is to collect findings — a throw would take the whole lint
+            // down and lose every other finding in the tree. A pathname this
+            // rule refuses is a Foundry address, so emitting it unchanged is
+            // right on the one surface this renderer serves, and the passes
+            // that own the other three refuse it with a line and a column.
+            try {
+                return resolveImg(src, loadPackConfig()) ?? src;
+            } catch {
+                return src;
+            }
+        }),
+    );
 
 /**
  * Parses a markdown file with YAML frontmatter.
@@ -423,155 +447,66 @@ export function makeFilename(name, id) {
 }
 
 /**
- * The path prefixes that name a package other than the one being compiled.
- *
- * Foundry serves every installed package from a root named for its kind, so a
- * path opening with one of these is already a served address and belongs to
- * somebody else — most often `systems/sohl/assets/…`, where every default this
- * toolchain ships lives, and which a module's content cites as readily as the
- * system's own does.
- *
- * **Two, not "the ones we happen to use".** `worlds/` is left out on purpose: a
- * package may not ship art out of a world, so a note that writes one has made a
- * mistake, and prefixing it yields a plainly broken path rather than a
- * plausible one that fails silently much later.
- *
- * @type {readonly string[]}
- */
-const FOREIGN_PACKAGE_ROOTS = Object.freeze(["systems/", "modules/"]);
-
-/**
- * Whether a path already addresses something this package does not own, and so
- * must be emitted exactly as authored.
- *
- * Three shapes qualify, each a different kind of "not mine":
- *
- * - **Another package** — `systems/…` or `modules/…`, per
- *   {@link FOREIGN_PACKAGE_ROOTS}.
- * - **Somewhere off this install** — a URI scheme (`https:`, `data:`) or a
- *   protocol-relative `//cdn…`.
- * - **The data root itself** — a leading `/`, which Foundry serves from the
- *   install rather than from any package.
- *
- * @param {string} s - A non-empty authored path.
- * @returns {boolean} Whether it passes through untranslated.
- */
-function addressesAnotherPackage(s) {
-    if (FOREIGN_PACKAGE_ROOTS.some((root) => s.startsWith(root))) return true;
-    // `//host/x.png` — protocol-relative, so it leaves this origin entirely.
-    // Checked before the single-slash case, which would otherwise claim it.
-    if (s.startsWith("//")) return true;
-    // `/x.png` — rooted at the Foundry data root, not at any package.
-    if (s.startsWith("/")) return true;
-    // `https://…`, `data:…`, `file:…` — a scheme, so not a path at all.
-    return /^[a-z][a-z0-9+.-]*:/i.test(s);
-}
-
-/**
- * Translate a content-relative image path into its Foundry-relative form.
- *
- * Content frontmatter (`img` / `portrait`) authors a single path that has to
- * work for Foundry, the knowledgebase, and the website. **Its first segment
- * says which package owns the file**, and there are exactly three
- * answers:
- *
- * | Authored path starts with | Owner                 | Emitted              |
- * | ------------------------- | --------------------- | -------------------- |
- * | `systems/`                | a separate **system** | unchanged            |
- * | `modules/`                | a separate **module** | unchanged            |
- * | anything else             | **this package**      | `<assetRoot>/<path>` |
- *
- * So `icons/relic.svg` compiles to `systems/sohl/assets/icons/relic.svg` here
- * and to `modules/sohl-thalorna/assets/icons/relic.svg` in a module — the asset
- * root is derived from the configuration, and is the one place `systems/sohl`
- * is ever spelled. An authored
- * `systems/sohl/assets/icons/noun/shield.svg` is left exactly as written,
- * whichever package is compiling it.
- *
- * **This is a rule about ownership, not an allowlist of directories.** It used
- * to prefix `icons/…` and `images/…` and pass everything else through — the
- * same answer for every path any tree authors today, and the wrong one for the
- * next directory a package ships. `sohl-kethira-basic` keeps art under
- * `assets/artwork/`, so an authored `artwork/deity.webp` would have shipped
- * unprefixed: a 404 in Foundry, reported by nothing. That a package owns its
- * own tree is the fact; the directory names inside it are that package's
- * business.
- *
- * **Off-install addresses pass through too**, which is the same rule rather
- * than a fourth: a URL, a `data:` URI, or a `/`-rooted path names something no
- * package owns. See {@link addressesAnotherPackage}.
- *
- * **`banner:` does not follow this rule, deliberately.** It is not an
- * asset path inside a Foundry install at all: it reaches no compiled document,
- * and its only consumer is the Hugo theme, which prefixes a relative value with
- * `images/` and joins it onto `params.cdnBaseURL`. The two fields look alike
- * and address different places — `img:` a file Foundry serves, `banner:` a file
- * the CDN serves — so they are documented apart rather than reconciled into one
- * rule that would be true of neither.
- *
- * **Two empties, and they mean opposite things.** `null` — or an absent
- * key, which reaches here as `undefined` — means _unset_: the note names no art
- * and the caller's default applies. `""` means _blank on purpose_: the note
- * names no art **and wants none**, so no default may replace it. Both come back
+ * Translate an authored pathname into the address a Foundry install serves.
+ *
+ * The Foundry half of {@link module:engine/pathnames.resolvePathname}, which
+ * states the rule and derives the other three surfaces from the same
+ * statement. Kept as its own function because the compilers want one address
+ * and nothing else, and because the default a caller applies to an unset one is
+ * domain-specific — actors default differently from items, and gear differently
+ * again — so each compiler owns its default and applies it with **nullish**
+ * coalescing: `resolveImg(fm.img) ?? <default>`. Not `||`, which would collapse
+ * a deliberate blank back into the default.
+ *
+ * **Two empties, and they mean opposite things.** `null` — or an absent key,
+ * which reaches here as `undefined` — means _unset_: the note names no art and
+ * the caller's default applies. `""` means _blank on purpose_: the note names
+ * no art **and wants none**, so no default may replace it. Both come back
  * distinguishable, `null` and `""` respectively, and neither is invented from
  * the other.
  *
- * This used to open `if (!raw) return ""`, which made the two one case: every
- * caller then applied its default with `||`, so a deliberate blank was
- * unspellable and an unset key and an empty string compiled identically. That
- * is the convention the project already rejects for an optional "not specified"
- * DataModel string, where `nullable, initial: null` keeps "unset" a single
- * honest value rather than two.
- *
  * **`title` does not follow this rule**, and must not be made to. On a
  * `type: affiliation` note `title` is *also* a declared item field whose default
  * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
  * key the site emitter reads as the page title — so `title: null` stringifies
  * into the compiled document as the literal `"null"`. One key, two destinations
- * that disagree about what empty means; see.
+ * that disagree about what empty means.
  *
- * This is translation only: the default for an unset path is domain-specific
- * (actors default differently from items, and gear differently again), so each
- * compiler owns its own default and applies it to the result with **nullish**
- * coalescing — `resolveImg(fm.img) ?? <default>`. Not `||`: that would collapse
- * a deliberate blank back into the default and undo the distinction. For items
- * that default is the art paired with the type's builder, reached through
- * `itemArt()`, which runs the path back through this function so a registry
- * entry and a note's `img:` are spelled the same way (#7).
+ * **`banner:` does not follow it either, deliberately.** It is not a file
+ * inside a Foundry install: it reaches no compiled document and no book, its
+ * only consumer is the Hugo theme, and the theme resolves it against the site's
+ * own asset root. See `docs/content-format.md`.
  *
- * **A package with no asset root cannot answer at all.** `assetRoot` is derived
- * from the package kind, and a `documentation` package has none: Foundry serves
- * no files for it. Only a compiling pass reaches here, and a documentation
- * package runs none, so a path arriving with no root to put it under is a pass
- * running where it should not — reported as that, rather than emitted as
- * `null/icons/relic.svg` into a document nobody would check.
+ * For items, the default is the art paired with the type's builder, reached
+ * through `itemArt()`, which runs the pathname back through this function so a
+ * registry entry and a note's `img:` are spelled the same way.
  *
- * @param {string | null | undefined} raw - content-relative path from frontmatter.
+ * @param {string | null | undefined} raw - The pathname from frontmatter.
  * @param {{assetRoot: string|null}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
  * @returns {string | null} the Foundry-relative path; `""` for a deliberate
  *   blank, and `null` when the note names no art at all.
- * @throws {Error} When the configuration has no asset root.
+ * @throws {Error} When no Foundry address can be derived — a `documentation`
+ *   package, which Foundry installs nothing of, or a pathname naming a package
+ *   this build declares no relationship with.
  */
 export function resolveImg(raw, config = loadPackConfig()) {
-    // Unset — the caller's default applies. An absent key arrives as
-    // `undefined`, an authored one as `null`; they say the same thing.
-    if (raw == null) return null;
-    const s = String(raw);
-    // Blank on purpose — the caller's default must not apply.
-    if (s === "") return "";
-    // Somebody else's to serve — emit it exactly as authored.
-    if (addressesAnotherPackage(s)) return s;
-    if (!config.assetRoot) {
+    const forms = resolvePathname(raw, config);
+    if (forms === null) return null;
+    if (forms.foundry !== null) return forms.foundry;
+    if (forms.own) {
         throw new Error(
-            `package-build: \`${s}\` names a file this package serves, and a ` +
-                `\`documentation\` package has no asset root to serve it from — ` +
-                `Foundry installs no such package. Address the owning package ` +
-                `(\`systems/…\`, \`modules/…\`) or a URL.`,
+            `package-build: \`${forms.authored}\` names a file this package serves, ` +
+                `and a \`documentation\` package has no asset root to serve it from — ` +
+                `Foundry installs no such package. Address a \`/\`-rooted path or a URL.`,
         );
     }
-    // Ours, so root it where Foundry serves this package's files from.
-    return `${config.assetRoot}/${s}`;
+    throw new Error(
+        `package-build: \`${forms.authored}\` names a file the \`${forms.package}\` ` +
+            `package ships, and this build declares no relationship with a package of ` +
+            `that name, so there is no Foundry address to derive. Declare it under ` +
+            `\`relationships\`, or address the file by a \`/\`-rooted path.`,
+    );
 }
 
 /**
@@ -804,6 +739,10 @@ export function buildContentLinkIndex(
             pack: router.resolveOrNull(fm, packForType(fm.type).docType),
             docPack: router.resolveOrNull(fm, "JournalEntry"),
             shortcode: fm.shortcode ?? null,
+            // What the note *is*, carried so a caller resolving a reference
+            // can group by the family its target declares rather than only by
+            // where the target lives.
+            subType: fm.subType ?? null,
             name: fm.name?.full ?? base,
             // Whether the note is tagged `draft`. Read from the tag
             // vocabulary that declares it, and used for one thing: a link

package/engine/index.mjs

@@ -96,6 +96,15 @@ export * as contentAddress from "./content-address.mjs";
 /** Which note-type → document-subtype maps this toolchain ships. */
 export * as subtypeRegistry from "./subtype-registry.mjs";
 
+/** The declared infobox: what a note's summary panel holds, in every medium. */
+export * as infobox from "./infobox.mjs";
+
+/** The infobox declarations this toolchain ships, one per system. */
+export * as infoboxRegistry from "./infobox-registry.mjs";
+
+/** Drawing a declared infobox as HTML for Foundry and as Typst for the book. */
+export * as infoboxRender from "./infobox-render.mjs";
+
 /** The id a note's document is filed under: its pin, or its address. */
 export * as noteIds from "./note-ids.mjs";
 
@@ -126,6 +135,12 @@ export * as contentIcons from "./content-icons.mjs";
 /** Raw HTML in a note's prose, which no book renderer can read. */
 export * as contentHtml from "./content-html.mjs";
 
+/** An image saying how wide it is and where it sits, in two closed vocabularies. */
+export * as contentImages from "./content-images.mjs";
+
+/** One authored pathname, and the four addresses the surfaces derive from it. */
+export * as pathnames from "./pathnames.mjs";
+
 /** Resolving every link in a tree, and the ones that land nowhere. */
 export * as contentLinks from "./content-links.mjs";