@heroiclands/package-build 22.9.2 → 22.11.0

package/engine/frontmatter-lint.mjs

@@ -54,6 +54,8 @@
  * @module
  */
 
+import { isAddressTuple } from "./address.mjs";
+import { AddressEntries } from "./address-values.mjs";
 import { authoredFields, readsLegacyKey } from "./field-spec.mjs";
 import {
     legacyKeyOf,
@@ -66,6 +68,8 @@ import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.
 import { pathnameProblem } from "./pathnames.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES, RENAMED_TYPES, currentType, renamedTypeMessage } from "./ids.mjs";
+import { parseAddress, acceptsType } from "./address.mjs";
+import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
 // The one place the "every pack not named" key is spelled. Imported rather
 // than repeated, because a linter holding its own copy of what the compiler
@@ -196,19 +200,7 @@ export const DEFAULT_SYSTEM_BLOCKS = Object.freeze({
  * @param {object} [config] - A resolved configuration from `defineConfig`.
  * @returns {string[]} The system ids, deduplicated, in declared order.
  */
-export function declaredSystems(config) {
-    const out = [];
-    for (const system of Object.keys(config?.systems ?? {})) {
-        if (!out.includes(system)) out.push(system);
-    }
-    for (const pack of config?.packs ?? []) {
-        const system = pack?.system;
-        if (typeof system === "string" && system && !out.includes(system)) out.push(system);
-    }
-    if (out.length) return out;
-    const packageWide = config?.stats?.systemId;
-    return typeof packageWide === "string" && packageWide ? [packageWide] : [];
-}
+export { declaredSystems } from "./system-vocabulary.mjs";
 
 /**
  * The system blocks a configuration says its tree carries, and what each
@@ -261,19 +253,7 @@ export function declaredSystems(config) {
  * @returns {Readonly<Record<string, SystemBlockSpec>>} The blocks to check, in
  *   declared order. A system nothing states the vocabulary of is absent.
  */
-export function systemBlocksFor(config, { schemaSystem } = {}) {
-    const byName = config?.itemFieldsBySystem ?? {};
-    /** @type {Record<string, SystemBlockSpec>} */
-    const blocks = {};
-    for (const system of declaredSystems(config)) {
-        /** @type {SystemBlockSpec} */
-        const spec = {};
-        if (system === schemaSystem) spec.fieldVocabulary = true;
-        if (byName[system]) spec.fields = byName[system];
-        if (Object.keys(spec).length) blocks[system] = Object.freeze(spec);
-    }
-    return Object.freeze(blocks);
-}
+export { systemBlocksFor } from "./system-vocabulary.mjs";
 
 /**
  * Edit distance, capped — enough to answer "did you mean".
@@ -337,10 +317,15 @@ function nearest(key, candidates) {
  *
  * @param {unknown} value - The authored value.
  * @param {string} kind - The declared kind.
+ * @param {object} [context] - Complete Address defaults and known type vocabulary.
  * @returns {boolean} Whether it is acceptable.
  */
-export function matchesKind(value, kind) {
+export function matchesKind(value, kind, context = {}) {
     switch (kind) {
+        case "address":
+            return !parseAddress(value, context, { declared: true }).reason;
+        case "shortcode":
+            return isAddressSegment(value);
         case "number":
             return typeof value === "number" ?
                     Number.isFinite(value)
@@ -382,6 +367,7 @@ export function matchesKind(value, kind) {
  * @returns {Record<string, unknown>|null} Its entries, or `null` for a scalar.
  */
 function mapEntries(value) {
+    if (isAddressTuple(value)) return null;
     if (Array.isArray(value)) return value.length === 0 ? {} : null;
     if (typeof value !== "object" || value === null) return null;
     return /** @type {Record<string, unknown>} */ (value);
@@ -427,6 +413,7 @@ function dataBlock(fm) {
  * @param {object} opts
  * @param {string} opts.type - The note's type, for the message.
  * @param {readonly object[]} opts.fields - The type's `data:` declaration.
+ * @param {object} [opts.addressContext] - Builder package and Address type vocabulary.
  * @param {readonly string[]} [opts.packs] - The pack names this package
  *   declares, against which a `keys: "pack"` map's keys are checked. Absent,
  *   no claim is made about them: a caller that cannot see the configuration
@@ -434,7 +421,7 @@ function dataBlock(fm) {
  *   was loaded to recognise it would be worse than not checking.
  * @returns {object[]} Findings.
  */
-function checkDataContainer(note, { type, fields, packs }) {
+function checkDataContainer(note, { type, fields, packs, addressContext }) {
     const findings = [];
     const { present, entries, malformed } = dataBlock(note.fm ?? {});
     if (!present) return findings;
@@ -489,10 +476,12 @@ function checkDataContainer(note, { type, fields, packs }) {
             ...positionOfFrontmatterPath(raw, ["data", key], { key: true }),
             severity: "error",
             message:
-                `"${key}" is not a \`data:\` property declared by ${type}; ` +
-                `the container is closed, so unlike a top-level key it is ` +
-                `not passed through to the page` +
-                (guess ? `. Did you mean "${guess}"?` : ""),
+                type === "affiliation" && key === "commonSkills" ?
+                    "`data.commonSkills` is not an affiliation field; write skill Addresses at `sohl.system.commonSkills`"
+                :   `"${key}" is not a \`data:\` property declared by ${type}; ` +
+                    `the container is closed, so unlike a top-level key it is ` +
+                    `not passed through to the page` +
+                    (guess ? `. Did you mean "${guess}"?` : ""),
         });
     }
 
@@ -504,7 +493,7 @@ function checkDataContainer(note, { type, fields, packs }) {
             value = value && typeof value === "object" ? value[segment] : undefined;
         }
         if (value === undefined || value === null) continue;
-        if (!matchesKind(value, field.kind)) {
+        if (!matchesKind(value, field.kind, { ...addressContext, type: field.ref })) {
             findings.push({
                 file: note.file,
                 ...positionOfFrontmatterPath(raw, ["data", ...segments]),
@@ -515,6 +504,7 @@ function checkDataContainer(note, { type, fields, packs }) {
             });
             continue;
         }
+        findings.push(...checkDataReferences(note, field, value, segments, addressContext));
         // A `scalar-or-map` written in its map form is checked entry by entry,
         // because that is the correction an author has to make: one key's
         // value, not the whole map. Quoting the map back would name every
@@ -530,6 +520,76 @@ function checkDataContainer(note, { type, fields, packs }) {
     return findings;
 }
 
+/**
+ * Validate typed entries without resolving their targets.
+ * @param {object} note - The authored note.
+ * @param {object} field - Its data field declaration.
+ * @param {unknown} value - The field value.
+ * @param {string[]} segments - The field's path under `data`.
+ * @param {object} context - The builder's Address context.
+ * @returns {object[]} Located findings.
+ */
+function checkDataReferences(note, field, value, segments, context) {
+    const checks = [];
+    if (field.kind === "address") checks.push({ value, path: [], kind: "address" });
+    if (field.entryKind) {
+        if (Array.isArray(value)) {
+            value.forEach((entry, i) =>
+                checks.push({ value: entry, path: [i], kind: field.entryKind }),
+            );
+        } else if (value && typeof value === "object" && !isAddressTuple(value)) {
+            Object.entries(value).forEach(([key, entry]) => {
+                if (entry != null)
+                    checks.push({ value: entry, path: [key], kind: field.entryKind, atKey: true });
+            });
+        } else checks.push({ value, path: [], kind: field.entryKind });
+    }
+    if (field.keyKind) {
+        if (value instanceof AddressEntries) {
+            for (const entry of value.entries)
+                checks.push({
+                    value: entry.target,
+                    path: [entry.sourceKey],
+                    kind: field.keyKind,
+                    key: true,
+                });
+        } else
+            Object.keys(value).forEach((key) =>
+                checks.push({ value: key, path: [key], kind: field.keyKind, key: true }),
+            );
+    }
+    const findings = [];
+    const defaults = { ...context, type: field.ref };
+    const accepted = field.accepts;
+    for (const check of checks) {
+        if (
+            check.key &&
+            field.keySelector === "subType" &&
+            typeof check.value === "string" &&
+            check.value.startsWith("subType:") &&
+            isAddressSegment(check.value.slice("subType:".length))
+        )
+            continue;
+        let reason;
+        if (!matchesKind(check.value, check.kind, defaults))
+            reason = `should be ${check.kind === "address" ? "an Address" : "a Shortcode"}`;
+        else if (check.kind === "address" && accepted) {
+            const tuple = parseAddress(check.value, defaults, { declared: true });
+            if (!acceptsType(tuple, accepted))
+                reason = `accepts ${accepted.join(" or ")}, not ${tuple.type}`;
+        }
+        if (!reason) continue;
+        const path = ["data", ...segments, ...check.path];
+        findings.push({
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", path, { key: check.key || check.atKey }),
+            severity: "error",
+            message: `\`${path.join(".")}\` ${reason}, but reads ${JSON.stringify(check.value)}`,
+        });
+    }
+    return findings;
+}
+
 /**
  * Check one `scalar-or-map` field written in its map form, entry by entry.
  *
@@ -578,7 +638,7 @@ function checkKeyedMap(note, { field, segments, entries, raw, packs }) {
         // An explicit `~` under a key is a statement, not an omission: it says
         // "at the root there", which is different from saying nothing.
         if (value === undefined || value === null) continue;
-        if (matchesKind(value, "string")) continue;
+        if (field.entryKind || matchesKind(value, "string")) continue;
         findings.push({
             file: note.file,
             // On the key, not the value: an entry whose value is itself a map
@@ -1000,7 +1060,7 @@ function checkEmbeddedShortcodes(note, blockName) {
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
  * @param {object} [opts.index] - The link index, for the reference check, which
- *   runs through its `referenceHit`. Its absence skips that check rather than
+ *   runs through its `shortcodeHit`. Its absence skips that check rather than
  *   reporting every reference as dead.
  * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
  *   it declares, as `engine/note-vocabulary.mjs` states them. Supplied
@@ -1019,6 +1079,7 @@ function checkEmbeddedShortcodes(note, blockName) {
  *   for the same reason `schemas` is — a build derives them from its
  *   configuration through {@link systemBlocksFor}, and this module states no
  *   system name of its own. See {@link DEFAULT_SYSTEM_BLOCKS} for the fallback.
+ * @param {object} [opts.addressContext] - Builder package and Address type vocabulary.
  * @param {readonly string[]} [opts.packs] - The pack names this package
  *   declares, for a `data:` field whose map is keyed by pack. Supplied by the
  *   caller like `schemas` and `vocabulary`, and absent it no claim is made
@@ -1027,10 +1088,29 @@ function checkEmbeddedShortcodes(note, blockName) {
  */
 export function lintNote(
     note,
-    { schemas, index, vocabulary, packs, emittedArt, systems = DEFAULT_SYSTEM_BLOCKS },
+    {
+        schemas,
+        index,
+        vocabulary,
+        packs,
+        emittedArt,
+        addressContext,
+        systems = DEFAULT_SYSTEM_BLOCKS,
+    },
 ) {
     const findings = [];
     const fm = note.fm ?? {};
+    const referenceContext = {
+        package: index?.contentPackage,
+        system: "none",
+        ...addressContext,
+        types: new Set([
+            ...Object.keys(vocabulary ?? {}),
+            ...ASSET_TYPE_NAMES,
+            ...(index?.types ?? []),
+            ...(addressContext?.types ?? []),
+        ]),
+    };
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
@@ -1197,7 +1277,7 @@ export function lintNote(
             inData,
             blockCollides: blockCollisions.has(key),
         });
-        if (typeof authored !== "string") continue;
+        if (typeof authored !== "string" && !isAddressTuple(authored)) continue;
         findings.push({
             file: note.file,
             ...at(key),
@@ -1225,7 +1305,7 @@ export function lintNote(
             inData,
             blockCollides: blockCollisions.has(key),
         });
-        if (typeof authored !== "string") continue;
+        if (typeof authored !== "string" && !isAddressTuple(authored)) continue;
         const problem = pathnameProblem(authored);
         if (!problem) continue;
         findings.push({
@@ -1438,6 +1518,7 @@ export function lintNote(
                 // the container check would have to be told about.
                 fields,
                 packs,
+                addressContext: referenceContext,
             }),
         );
         findings.push(...checkSubType(note, { type, entry }));
@@ -1605,20 +1686,37 @@ export function lintNote(
             continue;
         }
 
-        // A reference names another note by shortcode, and the field supplies
-        // the type, so the resolver is handed the whole `type-shortcode` pair.
-        // It resolves in any reachable package: the value is persisted as
-        // written and looked up at runtime among one actor's embedded items,
-        // which come from every package the actor draws on.
-        if (field.ref && index && typeof value === "string" && value) {
-            const target = `${field.ref}-${value}`;
-            if (!index.referenceHit(target)) {
+        // A `code:` field's value is a Shortcode, not an Address: one segment,
+        // persisted verbatim and resolved at runtime among the items embedded
+        // on one actor, where packages do not exist. The charset is checked
+        // first, because a value carrying the separator cannot mean what this
+        // position asks for, whatever the field supplies as the type — and the
+        // message says so, rather than reporting a lookup failure for a value
+        // that was never going to resolve. Once it passes, the field's type and
+        // the value form the `(type, shortcode)` pair the resolver takes; it
+        // resolves in any reachable package, because the value comes from
+        // every package the actor draws on.
+        const codeType = field.code;
+        if (codeType && typeof value === "string" && value) {
+            if (!isAddressSegment(value)) {
+                findings.push({
+                    file: note.file,
+                    ...at(head, value),
+                    severity: "error",
+                    message:
+                        `${label} must be a shortcode — the ${codeType}'s ` +
+                        `\`shortcode\`, not an address — because this position ` +
+                        `resolves it at runtime among one actor's embedded ` +
+                        `items, where packages do not exist, but reads ` +
+                        `${JSON.stringify(value)}`,
+                });
+            } else if (index && !index.shortcodeHit(codeType, value)) {
                 findings.push({
                     file: note.file,
                     ...at(head, value),
                     severity: "error",
                     message:
-                        `${label} names ${field.ref} ` +
+                        `${label} names ${codeType} ` +
                         `"${value}", and no note or fetched index declares it`,
                 });
             }
@@ -1665,6 +1763,11 @@ export function lintFrontmatter(
                 packs,
                 emittedArt,
                 index: references ? index : undefined,
+                addressContext: {
+                    package: index.contentPackage,
+                    system: "none",
+                    types: index.types,
+                },
                 ...(systems ? { systems } : {}),
             }),
         );

package/engine/frontmatter.mjs

@@ -30,6 +30,7 @@
 // build package rather than restated here, so the pipeline and the runtime
 // enum cannot drift apart — a value absent from the list is a build
 // error, never a silent ship.
+import { AddressEntries } from "./address-values.mjs";
 import { AFFILIATION_STANDINGS } from "../sohl/affiliation-standings.mjs";
 
 /**
@@ -87,20 +88,48 @@ export function sohlField(fm, key, defaultValue = undefined) {
  * has to be told both. It is the same split `FieldSpec.name`/`legacyKey` makes,
  * for the same reason — one name cannot key two positions.
  *
+ * `shared` is the field's declared shared source, and it completes the order the
+ * three other positions are two thirds of. A field whose source is a path into
+ * `data:` is authored there by the specification's own mapping tables, and a
+ * reader that knew the destination, the block and the top level alone skipped
+ * straight past the container: every authored value read as unset, and the
+ * document shipped the field's default with nothing said. It sits **between**
+ * the block and the top level, exactly where
+ * {@link module:engine/system-block.resolveFieldValue} puts it — the block is the
+ * position a tree still writes and wins while it does, and the bare top-level
+ * key is the spelling `data:` gathered the fact off.
+ *
  * @param {object} fm - The note's frontmatter.
  * @param {string} to - The key at the destination, dotted for a nested one.
  * @param {any} [defaultValue] - What an unauthored field reads as.
  * @param {object} [options] - Options.
  * @param {string} [options.legacyKey] - The key the block still carries, when
  *   it is not spelled `to`. Defaults to `to`.
+ * @param {string} [options.shared] - The field's declared shared source, when it
+ *   is a path into a container (`data.relations`). Omitted by a field whose
+ *   shared position is the note's top level, which `sohlField` already reads.
  * @returns {any} The value.
  */
-export function sohlSystemField(fm, to, defaultValue = undefined, { legacyKey = to } = {}) {
+export function sohlSystemField(fm, to, defaultValue = undefined, { legacyKey = to, shared } = {}) {
     const system = fm?.sohl?.system;
     if (system && typeof system === "object" && !Array.isArray(system)) {
         const found = getFrontmatter(system, to, undefined);
         if (found !== undefined) return found;
     }
+    if (shared !== undefined) {
+        const block = fm?.sohl;
+        const inBlock =
+            block && typeof block === "object" ?
+                getFrontmatter(block, legacyKey, undefined)
+            :   undefined;
+        // Consulted only where the block does not carry the key, so step 2 keeps
+        // winning; `sohlField` below then reads the block and the retiring
+        // top-level spelling exactly as it always has.
+        if (inBlock === undefined) {
+            const container = getFrontmatter(fm, shared, undefined);
+            if (container !== undefined) return container;
+        }
+    }
     return sohlField(fm, legacyKey, defaultValue);
 }
 
@@ -122,12 +151,16 @@ export function sohlSystemField(fm, to, defaultValue = undefined, { legacyKey =
  *
  * @param {object} fm - The item frontmatter.
  * @param {string} key - The property name, read via {@link sohlSystemField}.
+ * @param {object} [options] - Forwarded to {@link sohlSystemField}.
+ * @param {string} [options.shared] - The field's declared shared source, when it
+ *   is a path into a container.
  * @returns {[string, unknown][] | null} The property's entries — empty when the
  *   note authors none — or `null` when the value is not a map.
  */
-function readMapEntries(fm, key) {
-    const raw = sohlSystemField(fm, key, undefined);
+function readMapEntries(fm, key, { shared } = {}) {
+    const raw = sohlSystemField(fm, key, undefined, { shared });
     if (raw == null) return [];
+    if (raw instanceof AddressEntries) return raw.entries.map((e) => [e.target, e.value]);
     if (Array.isArray(raw)) return raw.length === 0 ? [] : null;
     if (typeof raw !== "object") return null;
     return Object.entries(raw);
@@ -155,11 +188,16 @@ export function resolveCharges(fm) {
         const num = Number(raw);
         return Number.isFinite(num) ? Math.trunc(num) : null;
     };
-    const max = toCount(sohlSystemField(fm, "charges.max", null));
+    const max = toCount(sohlSystemField(fm, "charges.max", null, { shared: "data.charges.max" }));
     // A blank maximum means "does not use charges" — a stray current count
     // cannot outlive it, since the logic layer disables both modifiers.
     return {
-        value: max === null ? null : toCount(sohlSystemField(fm, "charges.value", null)),
+        value:
+            max === null ? null : (
+                toCount(
+                    sohlSystemField(fm, "charges.value", null, { shared: "data.charges.value" }),
+                )
+            ),
         max,
     };
 }
@@ -186,7 +224,7 @@ export function resolveCharges(fm) {
  * @throws {Error} When the value is not a map, or a value is not an integer.
  */
 export function resolveSkillAptitudes(fm, ctx = "item") {
-    const entries = readMapEntries(fm, "skillAptitudes");
+    const entries = readMapEntries(fm, "skillAptitudes", { shared: "data.skillAptitudes" });
     if (entries === null) {
         throw new Error(`${ctx}: skillAptitudes must be a map of selector → number`);
     }
@@ -229,12 +267,18 @@ export function resolveRelation(fm, ctx = "item") {
     // Probed at the destination too: a note that has moved to
     // `sohl.system.relations` carries the current spelling, and a probe that
     // could not see it would fall through to the retired one and read `{}`.
-    const key = sohlSystemField(fm, "relations", undefined) == null ? "relation" : "relations";
-    const entries = readMapEntries(fm, key);
+    // Each spelling is probed at all four of its positions, the `data:` source
+    // the specification names included, so a retirement and a container move are
+    // independent of each other.
+    const current = sohlSystemField(fm, "relations", undefined, { shared: "data.relations" });
+    const key = current == null ? "relation" : "relations";
+    const entries = readMapEntries(fm, key, { shared: `data.${key}` });
     if (entries === null) {
         throw new Error(`${ctx}: ${key} must be a map of shortcode → standing`);
     }
+    const typed = entries.some(([code]) => typeof code === "object");
     const out = {};
+    const typedEntries = [];
     for (const [code, value] of entries) {
         const standing = String(value);
         if (!AFFILIATION_STANDINGS.includes(standing)) {
@@ -242,9 +286,10 @@ export function resolveRelation(fm, ctx = "item") {
                 `${ctx}: ${key}["${code}"] must be one of ${AFFILIATION_STANDINGS.join(", ")}, got "${value}"`,
             );
         }
-        out[code] = standing;
+        if (typed) typedEntries.push({ target: code, value: standing, sourceKey: "" });
+        else out[code] = standing;
     }
-    return out;
+    return typed ? new AddressEntries(typedEntries) : out;
 }
 
 /**

package/engine/generate.mjs

@@ -39,6 +39,7 @@
  * HeroicLands vault is no longer a build input for SoHL content.
  */
 
+import { noteAddressContext } from "./note-addresses.mjs";
 import fs from "fs";
 import path from "path";
 import log from "loglevel";
@@ -805,7 +806,12 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
                     )
                     .map((record) => {
                         const absPath = noteFile(contentBase, record);
-                        return { frontmatter: parseMarkdownFile(absPath).frontmatter, absPath };
+                        return {
+                            frontmatter: parseMarkdownFile(absPath, {
+                                addressContext: noteAddressContext(config),
+                            }).frontmatter,
+                            absPath,
+                        };
                     }),
                 // The package this build resolved, not the ambient accessor:
                 // they are the same value in a real repository and different

package/engine/helpers.mjs

@@ -25,6 +25,12 @@
  * journals.mjs, actors.mjs).
  */
 
+import { buildReferenceTargets } from "./reference-targets.mjs";
+
+import { decodeNoteAddresses } from "./note-addresses.mjs";
+import { positionOfYamlPath } from "./diagnostics.mjs";
+import { completeAddress, renderAddress } from "./address.mjs";
+import { encodeAddresses } from "./address-values.mjs";
 import fs from "fs";
 import crypto from "crypto";
 import path from "path";
@@ -131,7 +137,7 @@ export const md = markdownit({ html: true })
  * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
  * position: there is no body to have one.
  */
-export function parseMarkdownFile(filePath) {
+export function parseMarkdownFile(filePath, { addressContext } = {}) {
     const content = fs.readFileSync(filePath, "utf8");
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
     if (!fmMatch) {
@@ -144,6 +150,19 @@ export function parseMarkdownFile(filePath) {
         log.warn(`YAML parse error in ${filePath}: ${err.message}`);
         return { frontmatter: null, body: "", description: "" };
     }
+    if (addressContext) {
+        try {
+            decodeNoteAddresses(frontmatter, addressContext);
+        } catch (error) {
+            const position = positionOfYamlPath(fmMatch[1], error.keyPath ?? [], {
+                key: error.addressKey,
+            });
+            if (position.line) position.line++;
+            error.file = filePath;
+            error.position = position;
+            throw error;
+        }
+    }
     const raw = fmMatch[2];
     const body = raw.trim();
     const description = body ? md.render(body) : "";
@@ -238,7 +257,7 @@ export function assertSuppliedCorpus(records, who) {
  * @throws {Error} When `skipDirectories` is not stated — see
  *   {@link assertStatedScope}.
  */
-export function* walkMarkdownTree(rootDir, { skipDirectories } = {}) {
+export function* walkMarkdownTree(rootDir, { skipDirectories, addressContext } = {}) {
     // Stated by the caller, never resolved here. A default here
     // — `loadPackConfig().skipDirectories` — read whichever configuration
     // resolved from the working directory rather than the one the caller was
@@ -269,7 +288,7 @@ export function* walkMarkdownTree(rootDir, { skipDirectories } = {}) {
                 stack.push(absPath);
             } else if (entry.isFile() && entry.name.endsWith(".md")) {
                 yield {
-                    ...parseMarkdownFile(absPath),
+                    ...parseMarkdownFile(absPath, { addressContext }),
                     file: entry.name,
                     absPath,
                 };
@@ -702,12 +721,16 @@ export function buildContentLinkIndex(
     const assets = new Map();
     const resolved = config ?? loadPackConfig();
     assertSuppliedCorpus(records, "buildContentLinkIndex");
+    const recordsByAddress = new Map(
+        records.map((record) => [encodeAddresses(record.address?.canonical), record]),
+    );
     for (const record of records) {
         // An asset's record addresses a file rather than a note, so it becomes
         // no `doc` and takes no part in link resolution — it is keyed for the
         // art fields, which name a file and never a document.
         if (isAssetRecord(record)) {
-            if (record.address?.canonical) assets.set(record.address.canonical, record);
+            if (record.address?.canonical)
+                assets.set(encodeAddresses(record.address.canonical), record);
             continue;
         }
         // A documentation journal is a document this tree emits, not a note in
@@ -734,7 +757,9 @@ export function buildContentLinkIndex(
         // several frames deeper with nothing to go on.
         assertTypeNotRetired(fm.type, absPath);
         const base = String(record.file.name).replace(/_/g, " ");
+        const documentation = recordsByAddress.get(encodeAddresses(record.documentation));
         docs.push({
+            documentationUuid: documentation?.foundry?.none?.uuid ?? null,
             type: fm.type,
             id: fm.id,
             // Where this note's own document lands, and where the JournalEntry
@@ -770,11 +795,11 @@ export function buildContentLinkIndex(
     // a contributor without every repository checked out resolves the same
     // links CI does — from an artifact the producer shipped rather than a copy
     // this repository committed.
-    const { index: foreign, stale } = loadForeignIndexes(
-        resolved,
-        [resolved.contentPackage],
-        PACKAGE_BASE,
-    );
+    const {
+        index: foreign,
+        references: foreignReferences,
+        stale,
+    } = loadForeignIndexes(resolved, [resolved.contentPackage], PACKAGE_BASE);
     if (stale.length) {
         for (const st of stale) {
             log.error(`Unusable content index for "${st.package}": ${st.reason}`);
@@ -788,7 +813,10 @@ export function buildContentLinkIndex(
         `Wikilink index: ${docs.length} local document(s), ` +
             `${foreign.size} foreign address(es)`,
     );
+    const referenceTargets = buildReferenceTargets(records);
     return buildWikilinkIndex(docs, resolved.foundryPackage, foreign, resolved.contentPackage, {
+        referenceTargets,
+        foreignReferences,
         assets,
         noIndexPackages: noContentIndexPackages(resolved),
     });