@heroiclands/package-build 22.9.1 → 22.10.0

package/engine/site-build.mjs

@@ -51,6 +51,8 @@
  * @module
  */
 
+import { positionOfYamlPath } from "./diagnostics.mjs";
+import { decodeNoteAddresses, noteAddressContext, encodeAddresses } from "./note-addresses.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
@@ -136,13 +138,28 @@ function siteCorpusFiles(contentBase, ctx) {
  * @param {string} file - Absolute path.
  * @returns {{fm: object, body: string}|null}
  */
-function readNote(file) {
+function readNote(file, ctx) {
+    let parsed;
     try {
-        const { data, content } = matter(fs.readFileSync(file, "utf8"));
-        return { fm: data, body: content };
+        parsed = matter(fs.readFileSync(file, "utf8"));
     } catch {
         return null;
     }
+    const context = {
+        ...noteAddressContext(ctx.config ?? {}),
+        package: ctx.contentPackage ?? ctx.config?.contentPackage,
+    };
+    try {
+        return { fm: decodeNoteAddresses(parsed.data, context), body: parsed.content };
+    } catch (error) {
+        const position = positionOfYamlPath(parsed.matter, error.keyPath ?? [], {
+            key: error.addressKey,
+        });
+        if (position.line) position.line++;
+        error.file = file;
+        error.position = position;
+        throw error;
+    }
 }
 
 /**
@@ -182,7 +199,7 @@ export function collectContentPages(contentBase, ctx) {
     );
 
     for (const file of siteCorpusFiles(contentBase, ctx)) {
-        const note = readNote(file);
+        const note = readNote(file, ctx);
         if (!note) continue;
         applyComputedBeingAge(note.fm, present);
         const { fm, body } = note;
@@ -288,7 +305,7 @@ export function collectHomepages(contentBase, ctx) {
     const pages = [];
     const addressFindings = [];
     for (const file of siteCorpusFiles(contentBase, ctx)) {
-        const note = readNote(file);
+        const note = readNote(file, ctx);
         if (!note || !isHomepage(note.fm)) continue;
         try {
             addressSlug(note.fm);
@@ -347,7 +364,7 @@ export function writeHomepages(outRoot, pages, config, { related } = {}) {
         });
         const dest = path.join(outRoot, HOMEPAGE_DESTINATION);
         fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, matter.stringify(page.body, data));
+        fs.writeFileSync(dest, matter.stringify(page.body, encodeAddresses(data)));
     }
     return pages.length;
 }
@@ -377,7 +394,7 @@ export function writeHomepages(outRoot, pages, config, { related } = {}) {
  * @param {object} options.config - The resolved build configuration.
  * @returns {object} The gate results and, when they pass, the built index.
  */
-export function siteGates(pages, findings, { config }) {
+export function siteGates(pages, findings, { config, records }) {
     const out = {
         // Always empty here: the homepage count is decided in `buildSite`
         // before the content walk, and a failing count returns without ever
@@ -410,7 +427,10 @@ export function siteGates(pages, findings, { config }) {
     if (out.unaddressable.length) return out;
 
     out.index = buildSiteIndex(pages, {
+        package: config.contentPackage,
         foreignIndex: foreign.index,
+        foreignReferences: foreign.references,
+        records,
         noIndexPackages: noContentIndexPackages(config),
     });
     return out;
@@ -526,7 +546,7 @@ export function tableUniverse(pages) {
  * @param {object} options
  * @param {(data: object, page: object) => void} [options.decorate] - Called
  *   with each page's frontmatter, for whatever a consumer's own pass adds.
- * @param {(value: unknown, type: string) => string|null} [options.artSrc] -
+ * @param {(value: unknown, type: string, accepts?: Iterable<string>) => string|null} [options.artSrc] -
  *   Translates an art address into the pathname the website resolver takes, or
  *   `null` where nothing answers it.
  * @param {(src: string) => string} [options.webSrc] - Translates an authored
@@ -593,17 +613,17 @@ function pageTitle(page) {
  *
  * @param {object} data - The frontmatter being emitted, rewritten in place.
  * @param {(src: string) => string} webSrc - The website's pathname resolver.
- * @param {(value: unknown, type: string) => string|null} artSrc - The address
- *   resolver, yielding the pathname `webSrc` takes.
+ * @param {(value: unknown, type: string, accepts?: Iterable<string>) => string|null} artSrc -
+ *   The address resolver, yielding the pathname `webSrc` takes.
  * @returns {void}
  */
 function resolveArtFields(data, webSrc, artSrc) {
-    for (const { key, type } of ART_SLOTS) {
+    for (const { key, type, accepts } of ART_SLOTS) {
         const holder = isPlainObject(data.data) ? data.data : null;
         if (!holder) continue;
         const value = holder[key];
         if (typeof value !== "string" || value === "") continue;
-        const pathname = artSrc(value, type);
+        const pathname = artSrc(value, type, accepts);
         if (pathname === null) delete holder[key];
         else holder[key] = webSrc(pathname);
     }
@@ -798,7 +818,8 @@ export function renderPages(pages, options) {
         });
 
         const webSrc = webAddresses(page.file);
-        const artSrc = (value, type) => artPathname(artIndex, value, type).pathname;
+        const artSrc = (value, type, accepts) =>
+            artPathname(artIndex, value, type, accepts).pathname;
         const resolve = (text) => {
             let t = text;
             if (pass.beforeLinks) t = pass.beforeLinks(t, page);
@@ -856,7 +877,7 @@ export function renderPages(pages, options) {
             data.map = map.name;
             withMap += 1;
         }
-        fs.writeFileSync(dest, matter.stringify(body, data));
+        fs.writeFileSync(dest, matter.stringify(body, encodeAddresses(data)));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
@@ -1078,7 +1099,10 @@ export function buildSite({ config, sqlTables, locate } = {}) {
         url: base,
     }));
 
-    const gates = siteGates([...pages, ...homepageEntries], content, { config: resolved });
+    const gates = siteGates([...pages, ...homepageEntries], content, {
+        config: resolved,
+        records: ctx.records,
+    });
     if (gatesFailed(gates)) {
         return {
             gates,

package/engine/site-index.mjs

@@ -49,9 +49,20 @@
  * @module
  */
 
+import { buildReferenceTargets } from "./reference-targets.mjs";
+
+import { resolveShortcodeReference } from "./shortcode-references.mjs";
+
 import path from "node:path";
 
 import { canonicalKey, readCanonicalKey } from "./content-address.mjs";
+import {
+    readQualifier,
+    parseAddress,
+    renderAddress,
+    isAddressTuple,
+    completeAddress,
+} from "./address.mjs";
 import { NO_SYSTEM } from "./systems.mjs";
 import { systemOf } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./note-claims.mjs";
@@ -156,7 +167,13 @@ function mergeForeign(index, foreignIndex) {
  */
 export function buildSiteIndex(
     entries,
-    { foreignIndex = new Map(), noIndexPackages = new Set() } = {},
+    {
+        foreignIndex = new Map(),
+        noIndexPackages = new Set(),
+        package: builderPackage,
+        records = [],
+        foreignReferences = new Map(),
+    } = {},
 ) {
     const index = new Map();
     const contentTypes = new Set();
@@ -165,7 +182,7 @@ export function buildSiteIndex(
     // vendored manifest speaks for. Without it `readQualifier` cannot see the
     // leading package segment of a canonical address, and `kethira-place-x`
     // reads as the unknown type `kethira`.
-    const ownPackage = contentPackage();
+    const ownPackage = builderPackage ?? contentPackage();
     const packages = new Set(ownPackage ? [ownPackage] : []);
 
     // A page is addressed by `(type, shortcode)` and nothing else. Its name,
@@ -240,7 +257,13 @@ export function buildSiteIndex(
             // ordinary in-page anchor. One authored link, correct in both
             // builds — restricted to the types that actually have an item doc,
             // so a qualifier the packs would reject is reported broken here too.
-            if (hasDocEntry(type)) {
+            const proseAddress = completeAddress({
+                package: e.pkg ?? ownPackage,
+                system: NO_SYSTEM,
+                type,
+                shortcode,
+            });
+            if (proseAddress.type !== type || hasDocEntry(type)) {
                 contentTypes.add(`doc${type}`);
                 index.set(`doc${type}/${shortcode}`.toLowerCase(), value);
                 // The canonical documentation address too, so the page answers
@@ -259,6 +282,8 @@ export function buildSiteIndex(
     }
 
     return {
+        contentPackage: ownPackage,
+        referenceTargets: buildReferenceTargets(records, new Map([...foreignReferences, ...index])),
         index,
         ambiguous,
         contentTypes,
@@ -319,7 +344,7 @@ export function wikiContext(
         // none. Taken from the resolved configuration, the same source
         // the index's own addresses are built from, so a bare link cannot
         // resolve against a package the index never keyed.
-        contentPackage: contentPackage(),
+        contentPackage: built.contentPackage,
         type,
         errors,
         src,
@@ -329,79 +354,36 @@ export function wikiContext(
 }
 
 /**
- * Resolve one infobox reference against a site index.
- *
- * A note writes a reference three ways and all three reach here: a bare
- * **shortcode** (`slntlncmpny`), a short **address** (`affiliation-slntlncmpny`)
- * and a **canonical** one (`sohl-sohl-skill-melee`). The first is the ordinary
- * case and the ambiguous one — a shortcode is unique within a type and not
- * across a tree — so a caller that knows what it expects passes `hint.type`
- * and the lookup is narrowed to it.
- *
- * **Without a hint the types are tried in sorted order**, so two trees holding
- * the same note resolve it the same way. A shortcode two types both claim
- * answers with the first alphabetically, which is a stable wrong answer rather
- * than an unstable one; a caller that cares supplies the hint.
- *
- * The `address` on the answer is the slug form — `type-shortcode` — because
- * that is what the book's own link map is keyed by and what a wikilink is
- * written as.
- *
- * @param {SiteIndex} siteIndex - The index.
- * @param {unknown} ref - The reference, as authored.
- * @param {object} [hint] - `{type}`, where the caller knows it.
- * @returns {{name?: string, url?: string, address?: string, subType?: string}|undefined}
- *   The page, or `undefined` where nothing answers.
+ * Resolve one Address against the site's canonical identity index.
+ * A bare Shortcode requires a declared default type. The returned Address is
+ * the complete tuple; URL and display name are presentation values.
+ * @param {SiteIndex} siteIndex - The site index.
+ * @param {unknown} ref - Tuple or authored reference.
+ * @param {object} [hint] - A declared default type.
+ * @returns {object|undefined} The matching page and tuple.
  */
 export function resolveInfoboxRef(siteIndex, ref, hint) {
-    if (typeof ref !== "string" || !ref) return undefined;
-    const wanted = ref.toLowerCase();
-    const keys = [];
-    if (hint?.type) keys.push(`${String(hint.type).toLowerCase()}/${wanted}`);
-    // An authored address already names its own type, so it is tried whole
-    // before the type sweep — `affiliation-slntlncmpny` must not be read as a
-    // shortcode of some other type that happens to spell it.
-    if (wanted.includes("-")) {
-        keys.push(wanted);
-        const segments = wanted.split("-");
-        if (segments.length >= 2) {
-            keys.push(`${segments[segments.length - 2]}/${segments[segments.length - 1]}`);
-        }
-    }
-    if (!hint?.type) {
-        for (const type of [...(siteIndex?.contentTypes ?? [])].sort()) {
-            keys.push(`${type}/${wanted}`);
-        }
-    }
-    for (const key of keys) {
-        const found = siteIndex?.index?.get(key);
-        if (!found) continue;
-        const slug = key.includes("/") ? key.replace("/", "-") : addressSlugOfKey(key);
-        // No `uuid`, although a foreign entry carries one: this resolver
-        // answers for the **published** surfaces, which address a page by URL
-        // and an entry in the book by its slug. A compendium reference is what
-        // `resolveReference` answers with, from the compile's own index.
-        return {
-            ...(found.name ? { name: found.name } : {}),
-            ...(found.url ? { url: found.url } : {}),
-            ...(found.subType ? { subType: found.subType } : {}),
-            address: slug,
-        };
+    if (hint?.kind === "shortcode") {
+        const found = resolveShortcodeReference(
+            [siteIndex.referenceTargets ?? siteIndex.index],
+            ref,
+            hint,
+        );
+        return found ?
+                { name: found.name, url: found.url, subType: found.subType, address: found.address }
+            :   undefined;
     }
+    const context = {
+        package: siteIndex.contentPackage ?? contentPackage(),
+        system: "none",
+        types: siteIndex.contentTypes,
+        packages: siteIndex.packages,
+    };
+    const tuple = parseAddress(ref, { ...context, type: hint?.type });
+    if (tuple.reason) return undefined;
+    const found =
+        siteIndex.referenceTargets?.get(renderAddress(tuple)) ??
+        siteIndex.index?.get(renderAddress(tuple));
+    if (found) return { name: found.name, url: found.url, subType: found.subType, address: tuple };
     return undefined;
 }
-
-/**
- * The `type-shortcode` slug of a canonical key.
- *
- * A canonical key is `package-system-type-shortcode`, and its slug is the last
- * two segments — the same rule `contentAddress` states, applied to a key
- * rather than to frontmatter.
- *
- * @param {string} key - The canonical key.
- * @returns {string} The slug.
- */
-function addressSlugOfKey(key) {
-    const segments = String(key).split("-");
-    return segments.length >= 2 ? segments.slice(-2).join("-") : key;
-}

package/engine/sql-tables.mjs

@@ -33,6 +33,9 @@
  * @module
  */
 
+import { parseAddress, renderAddress, isAddressTuple } from "./address.mjs";
+import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { encodeAddresses } from "./address-values.mjs";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -41,7 +44,7 @@ import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
 import { MARKET_CLASSES } from "./market-class.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
 // The record accessors only — see `engine/index-records.mjs`.
-import { isNoteRecord, noteFile } from "./index-records.mjs";
+import { isNoteRecord, noteFile, sortKeysDeep } from "./index-records.mjs";
 
 /** Rendered in a cell whose value is absent. */
 const EMPTY_CELL = "—";
@@ -157,12 +160,15 @@ export function findSqlBlocks(markdown) {
  * @returns {Promise<{query: (sql: string) => Promise<object[]>,
  *   close: () => Promise<void>}>} The open database.
  */
-export async function openNotesDatabase(records, { dir, dependencies = [] } = {}) {
+export async function openNotesDatabase(records, { dir, dependencies = [], addressContext } = {}) {
     const { DuckDBInstance } = await import("@duckdb/node-api");
     const base = dir ?? fs.mkdtempSync(path.join(os.tmpdir(), "content-sql-"));
     fs.mkdirSync(base, { recursive: true });
     const jsonl = path.join(base, "notes.jsonl");
-    fs.writeFileSync(jsonl, records.map((record) => JSON.stringify(record)).join("\n"));
+    fs.writeFileSync(
+        jsonl,
+        records.map((record) => JSON.stringify(sortKeysDeep(encodeAddresses(record)))).join("\n"),
+    );
 
     const instance = await DuckDBInstance.create(":memory:");
     const connection = await instance.connect();
@@ -244,6 +250,11 @@ export async function openNotesDatabase(records, { dir, dependencies = [] } = {}
     }
 
     return {
+        addressContext: addressContext ?? {
+            package: records.find((record) => record.package)?.package,
+            types: new Set(Object.keys(NOTE_VOCABULARY)),
+            system: "none",
+        },
         stubsExcluded,
         async query(sql) {
             const reader = await connection.runAndReadAll(sql);
@@ -368,6 +379,15 @@ function readJsonAuto(file) {
  */
 export async function runSqlQuery(db, sql) {
     const { rows, columnNames } = await db.query(sql);
+    if (db.addressContext?.package) {
+        for (const row of rows) {
+            const value = row[RENDER_ALIASES.ref];
+            if (!value) continue;
+            const tuple = parseAddress(value, db.addressContext, { declared: true });
+            if (tuple.reason) throw new Error(`SQL _ref is not an Address: ${value}`);
+            row[RENDER_ALIASES.ref] = tuple;
+        }
+    }
     return { columns: columnNames.filter((key) => !key.startsWith("_")), rows };
 }
 
@@ -454,7 +474,10 @@ function cellText(value, column) {
  * @param {number} [opts.sectionLevel=2] - Heading level for `_section`.
  * @returns {string} The markdown.
  */
-export function renderSqlTable(result, { linkable = () => true, sectionLevel = 2 } = {}) {
+export function renderSqlTable(
+    result,
+    { linkable = () => true, sectionLevel = 2, addressContext } = {},
+) {
     const { columns, rows } = result;
     if (!columns.length) throw new Error("query selects no rendered column");
 
@@ -479,11 +502,18 @@ export function renderSqlTable(result, { linkable = () => true, sectionLevel = 2
         const cells = group.rows.map((row) =>
             columns.map((column, index) => {
                 const text = cellText(row[column], column);
-                const ref = row[RENDER_ALIASES.ref];
-                if (index !== 0 || !ref || !linkable(String(ref))) return text;
+                const written = row[RENDER_ALIASES.ref];
+                if (index !== 0 || !written) return text;
+                const ref =
+                    isAddressTuple(written) ? written : (
+                        parseAddress(written, addressContext ?? {}, { declared: true })
+                    );
+                if (ref.reason)
+                    throw new Error(`SQL _ref needs a complete Address context: ${written}`);
+                if (!linkable(ref)) return text;
                 // A wikilink's own separator is a literal `|`, written `\|`
                 // inside a table cell, so the label must not carry one.
-                return `[[${ref}\\|${text.replace(/\\?\|/g, "/")}]]`;
+                return `[[${renderAddress(ref)}\\|${text.replace(/\\?\|/g, "/")}]]`;
             }),
         );
         const align = columns.map((_column, index) => {
@@ -542,6 +572,7 @@ export async function prepareSqlTables(db, sources, { linkable } = {}) {
                 forNote.push({
                     markdown: renderSqlTable(result, {
                         linkable,
+                        addressContext: db.addressContext,
                         sectionLevel: block.sectionLevel,
                     }),
                     rows: result.rows.length,
@@ -621,7 +652,8 @@ export async function prepareTreeSqlTables(contentBase, { config, skipDirectorie
     const addresses = new Set(
         indexRecords
             .filter((record) => !record.documents)
-            .map((record) => record.address?.slug)
+            .map((record) => record.documentation ?? record.address?.canonical)
+            .map((target) => target && encodeAddresses(target))
             .filter(Boolean),
     );
     // Each declared dependency's published index, attached as its own schema so
@@ -639,7 +671,9 @@ export async function prepareTreeSqlTables(contentBase, { config, skipDirectorie
     }
     const db = await openNotesDatabase(indexRecords, { dependencies });
     try {
-        return await prepareSqlTables(db, sources, { linkable: (ref) => addresses.has(ref) });
+        return await prepareSqlTables(db, sources, {
+            linkable: (ref) => addresses.has(renderAddress(ref)),
+        });
     } finally {
         await db.close();
     }

package/engine/system-block.mjs

@@ -419,6 +419,27 @@ export function retiredTopLevelKey(field) {
     return rest === "" ? undefined : rest;
 }
 
+/**
+ * A shared source as the key an author writes, without the container holding it.
+ *
+ * `data.weight` is authored as `weight:` one level inside `data:`, so every
+ * question about the *note* rather than about the resolution order asks it under
+ * that spelling: which presentation overlay a row takes, which key a finding
+ * names, and whether two statements of one fact are the same fact. The
+ * specification's mapping tables write the whole path and a `data:` vocabulary
+ * writes the key, and this is what makes the two comparable.
+ *
+ * It takes a **name** rather than a declaration because both sides of that
+ * comparison reach it: one holds a field, the other a row of a table.
+ *
+ * @param {string|undefined} name - The shared source, as either side spells it.
+ * @returns {string} The key, without the container.
+ */
+export function authoredKey(name) {
+    const path = String(name ?? "");
+    return path.startsWith(DATA_PREFIX) ? path.slice(DATA_PREFIX.length) : path;
+}
+
 /**
  * Where a declared field's value came from.
  *

package/engine/system-vocabulary.mjs

@@ -0,0 +1,46 @@
+/*
+ * 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>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Systems named by package declarations and pack targets.
+ * @param {object} [config] - Resolved build configuration.
+ * @returns {string[]} Declared system identifiers.
+ */
+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] : [];
+}
+
+/**
+ * System field vocabularies supplied by the configuration and caller.
+ * @param {object} [config] - Resolved build configuration.
+ * @param {object} [options] - Caller schema context.
+ * @param {string} [options.schemaSystem] - Owner of the caller's schemas.
+ * @returns {object} System block declarations.
+ */
+export function systemBlocksFor(config, { schemaSystem } = {}) {
+    const byName = config?.itemFieldsBySystem ?? {};
+    /** @type {Record<string, object>} */
+    const blocks = {};
+    for (const system of declaredSystems(config)) {
+        /** @type {object} */
+        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);
+}

package/engine/web-wikilinks.mjs

@@ -41,6 +41,7 @@
 // cannot drift apart on it: they disagreed once over the unlabelled hyphen
 // form, which the packs showed as a raw shortcode and the knowledgebase as a
 // name.
+import { readWikilink } from "./wikilink-syntax.mjs";
 import { readQualifier } from "./wikilinks.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 // The canonical `package-system-type-shortcode` key, so a package-qualified
@@ -390,8 +391,14 @@ export function resolveWebWikilinks(body, ctx) {
     // Code is verbatim: a `[[…]]` inside a code fence, an indented block or an
     // inline span is source text, not a link.
     return replaceOutsideCode(embedded.markdown, WIKILINK, (all, rawInner) => {
-        const parsed = parseWikilink(rawInner);
-        const { target, anchor, display } = parsed;
+        const parsed = readWikilink(rawInner, {
+            package: ctx.contentPackage,
+            system: "none",
+            types: ctx.contentTypes ?? new Set(),
+            packages: ctx.packages,
+            noIndexPackages: ctx.noIndexPackages,
+        });
+        const { rawTarget: target, anchor, display } = parsed;
         // An empty label is not a label: `[[x|]]` addresses the target and
         // shows its name, so `""` falls through to the same place `null` does.
         // One reading, from {@link authoredLabel}.
@@ -415,12 +422,7 @@ export function resolveWebWikilinks(body, ctx) {
         // The canonical separator has to be resolved, not merely
         // recognised. `null` here means the target is not an address at all,
         // which is a defect: there is no other namespace to try.
-        const read = readQualifier(
-            target,
-            ctx.contentTypes ?? new Set(),
-            ctx.packages,
-            ctx.noIndexPackages,
-        );
+        const read = parsed.problem ?? parsed.target;
         const rawKey = target.toLowerCase();
         const hit =
             lookupRead(ctx.index, read, ctx.contentPackage) ??
@@ -475,7 +477,7 @@ export function resolveWebWikilinks(body, ctx) {
         // names its package. A qualified target that matched more than one
         // document is reported by the matcher instead, not by this set.
         const collideKey =
-            read && !read.reason && !read.package ?
+            read && !read.reason && read.package === ctx.contentPackage ?
                 `${read.type}/${read.shortcode}`.toLowerCase()
             :   rawKey;
         const reason =

package/engine/wikilink-syntax.mjs

@@ -11,6 +11,8 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
+import { parseAddress, isAddressTuple } from "./address.mjs";
+
 /**
  * What a `[[…]]` **is**, before anything decides where it points.
  *
@@ -368,3 +370,22 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
 export function isSamePage({ target, anchor }) {
     return !target && Boolean(anchor);
 }
+
+/**
+ * Read an operational link target in its enclosing Address context.
+ * @param {string} inner - Lexical link contents.
+ * @param {object} context - Builder defaults and type vocabulary.
+ * @returns {object} Typed target and diagnostic source spelling.
+ */
+export function readWikilink(inner, context) {
+    const parsed = parseWikilink(inner);
+    const rawTarget = parsed.target;
+    if (!rawTarget) return { ...parsed, rawTarget, target: { kind: "same-page" } };
+    const target = parseAddress(rawTarget, context);
+    if (target.reason === "no-type") target.reason = "not-an-address";
+    if (!target.reason && !isAddressTuple(target))
+        throw new Error("Wikilink read requires complete builder Address context");
+    return target.reason ?
+            { ...parsed, rawTarget, target: { kind: "literal", text: rawTarget }, problem: target }
+        :   { ...parsed, rawTarget, target };
+}