@heroiclands/package-build 25.1.3 → 25.2.0

package/engine/glossary-entries.mjs

@@ -51,6 +51,7 @@ import {
     noteTerms,
 } from "./culture-reach.mjs";
 import { pronunciationProblem } from "./word-terms.mjs";
+import { noteLang } from "./glossary-language.mjs";
 
 /** Whether a value is a plain map. */
 const isMap = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -126,11 +127,10 @@ export function checkGlossary(note, { index } = {}) {
                     [i],
                     "error",
                     `\`${entry.name}\` resolves to no language: the entry states no ` +
-                        "`language`, and " +
-                        (type === "affiliation" ?
-                            "neither the affiliation, its parents nor its culture states one"
-                        :   "the culture states no `data.language`") +
-                        "; state `language` on the entry or `data.language` on the note",
+                        "`language`, and the note's language" +
+                        (noteLang(note) ? ` ${noteLang(note)}` : "") +
+                        " has no `note` in `languages:`; state `language` on the entry, or " +
+                        "`data.lang` on the note naming a language with a note",
                 ),
             );
         const senses = noteTerms(index, note, entry).get(name);

package/engine/glossary-language.mjs

@@ -16,16 +16,11 @@
  *
  * 1. the entry's own `language`;
  * 2. the note it is written on, when that note is a language;
- * 3. on an affiliation, its own `data.language`, then the nearest parent
- *    affiliation's (breadth first, parents in the order listed), then its
- *    culture's `data.language`;
- * 4. on a culture, its own `data.language`.
+ * 3. the language note of the code the content index derived for the note it
+ *    is written on, its `lang` — see {@link module:engine/note-language}.
  *
- * An affiliation's culture is the one the index resolves for it, its own or
- * one inherited through its parents, and a culture's language includes one it
- * inherits from its parent cultures. The lint and the `glossary` relation both
- * resolve through here, each handing over how it reads an Address and looks a
- * note up.
+ * The lint and the `glossary` relation both resolve through here, each handing
+ * over how it reads an Address, looks a note up and finds a code's note.
  *
  * A leaf module, importing nothing.
  *
@@ -35,12 +30,6 @@
 /** A note's parsed frontmatter, whichever shape the caller hands over. */
 const payload = (note) => note?.fm ?? note ?? {};
 
-/** A note's `data`, or an empty map. */
-const dataOf = (note) => {
-    const data = payload(note).data;
-    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
-};
-
 /** A note's type or subType, lowercased. */
 const lower = (value) => String(value ?? "").toLowerCase();
 
@@ -51,11 +40,22 @@ const lower = (value) => String(value ?? "").toLowerCase();
  * @property {(value: unknown, type: string) => string|undefined} keyOf - A
  *   value's canonical Address in the `note` system, read with `type` as the
  *   default type, or `undefined` where it is no Address.
- * @property {(key: string) => object|undefined} lookup - The note an Address
- *   names, or `undefined` where none is known.
+ * @property {(code: string) => string|undefined} noteOf - The Address of a
+ *   language code's note, or `undefined` where no note is configured for it.
  * @property {string} [self] - The owning note's own Address, for a language.
  */
 
+/**
+ * The language a note is in, as the content index derived it.
+ *
+ * @param {object} note - An index record, or a link-index note carrying it.
+ * @returns {string|undefined} The code.
+ */
+export function noteLang(note) {
+    const lang = note?.lang;
+    return typeof lang === "string" && lang ? lang : undefined;
+}
+
 /**
  * The language a glossary entry resolves to.
  *
@@ -66,34 +66,11 @@ const lower = (value) => String(value ?? "").toLowerCase();
  * @returns {string|undefined} The language's Address, or `undefined` where the
  *   chain finds none.
  */
-export function glossaryLanguage(entry, owner, { keyOf, lookup, self }) {
+export function glossaryLanguage(entry, owner, { keyOf, noteOf, self }) {
     const own = keyOf(entry?.language, "skill");
     if (own) return own;
     const fm = payload(owner);
-    const type = lower(fm.type);
-    if (type === "skill" && lower(fm.subType) === "language") return self;
-    if (type === "lore" && lower(fm.subType) === "culture")
-        return keyOf(dataOf(owner).language, "skill");
-    if (type !== "affiliation") return undefined;
-
-    const seen = new Set();
-    let level = [owner];
-    while (level.length) {
-        const next = [];
-        for (const body of level) {
-            if (seen.has(body)) continue;
-            seen.add(body);
-            const language = keyOf(dataOf(body).language, "skill");
-            if (language) return language;
-            for (const parent of Array.isArray(dataOf(body).parents) ? dataOf(body).parents : []) {
-                const key = keyOf(parent, "affiliation");
-                const target = key ? lookup(key) : undefined;
-                if (target && lower(payload(target).type) === "affiliation") next.push(target);
-            }
-        }
-        level = next;
-    }
-    const culture = keyOf(dataOf(owner).culture, "lore");
-    const target = culture ? lookup(culture) : undefined;
-    return target ? keyOf(dataOf(target).language, "skill") : undefined;
+    if (lower(fm.type) === "skill" && lower(fm.subType) === "language") return self;
+    const code = noteLang(owner);
+    return code ? noteOf(code) : undefined;
 }

package/engine/homepage.mjs

@@ -355,9 +355,6 @@ export function homepageTitle(fm, config) {
  * **No `url` and no `slug`.** The homepage publishes at the package root, so
  * the page has no address to state.
  *
- * An authored `aliases` is dropped, as it is on every other page: this build
- * emits no redirects.
- *
  * `related` is derived like every other page's — what links to the homepage
  * is a fact about the rest of the tree — so an authored value is dropped and
  * the caller's block, where it has one, is set in its place.
@@ -372,7 +369,6 @@ export function homepageTitle(fm, config) {
  */
 export function homepageFrontmatter(fm, { contentPackage, title, related }) {
     const data = { ...fm, package: contentPackage, title };
-    delete data.aliases;
     delete data.related;
     if (related) data.related = related;
     return data;

package/engine/index-records.mjs

@@ -56,7 +56,9 @@ export const DERIVED_KEYS = Object.freeze([
     "address",
     "anchors",
     "nameAscii",
-    "aliasesAscii",
+    "formsAscii",
+    "lang",
+    "languageCode",
     "foundry",
     "documentation",
     "documents",

package/engine/infobox.mjs

@@ -129,6 +129,7 @@ import {
 } from "./standings.mjs";
 import { AddressEntries } from "./address-values.mjs";
 import { noteCalendar } from "./note-calendars.mjs";
+import { nameFormsOf } from "./name-forms.mjs";
 
 /**
  * How a section arranges what it holds.
@@ -288,6 +289,9 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
         withheld: "template machinery, not a fact about the subject",
     }),
     id: Object.freeze({ withheld: "document identity machinery, not a fact about the subject" }),
+    lang: Object.freeze({
+        withheld: "language machinery, a code rather than a fact a reader follows",
+    }),
     pack: Object.freeze({ withheld: "compendium routing machinery, not a fact about the subject" }),
     packFolder: Object.freeze({
         withheld: "compendium routing machinery, not a fact about the subject",
@@ -1040,9 +1044,8 @@ function noteBox(
     const shown = new Set();
     const name = fm?.name?.full;
     if (hasValue(name)) rows.push({ label: "Name", kind: "text", value: String(name) });
-    if (Array.isArray(fm?.name?.aliases) && fm.name.aliases.length) {
-        rows.push({ label: "Aliases", kind: "list", value: fm.name.aliases });
-    }
+    const forms = nameFormsOf(fm?.name);
+    if (forms.length) rows.push({ label: "Other names", kind: "list", value: forms });
     if (fm?.type === "being" && Object.hasOwn(BEING_SUBTYPE_LABELS, fm.subType)) {
         rows.push({ label: "Type", kind: "text", value: BEING_SUBTYPE_LABELS[fm.subType] });
     }

package/engine/language-names.mjs

@@ -17,8 +17,9 @@
  *
  * A `skill` note of `subType: language` states them as `data.names`, and
  * `package-build npc new` draws a person's name from them, or checks a name it
- * is given against them. A culture reaches them through `data.language`, so
- * cultures sharing a tongue share its lists.
+ * is given against them. A culture reaches them through its language, the
+ * note `languages:` names for its `data.lang`, so cultures sharing a tongue
+ * share its lists.
  *
  * - `pattern` — the name's shape: placeholders such as `{given}` and `{clan}`,
  *   each naming a list, with literal text around them or directly against

package/engine/language-rows.mjs

@@ -68,6 +68,7 @@ import {
     SOUND_CHANGE_STEP_KEYS,
     TONGUE_KEYS,
 } from "./language-terms.mjs";
+import { nameFormsOf } from "./name-forms.mjs";
 
 /** The columns every list relation opens with. */
 const IDENTITY = Object.freeze(["language", "position"]);
@@ -354,7 +355,7 @@ const soundsOf = (data) => (isMap(data.sounds) ? data.sounds : {});
 
 /**
  * Every name a note of the package carries, with the Addresses carrying it:
- * each string of a note's `name`, its aliases, an affiliation's rank and
+ * each string of a note's `name`, its listed forms, an affiliation's rank and
  * office titles, and the name of each anchor, cited with the anchor.
  *
  * @param {Iterable<Record<string, any>>} records - Index records.
@@ -371,12 +372,10 @@ function carriedNames(records) {
     for (const record of records) {
         const address = noteAddressOf(record);
         if (!address || record.documents || record.type === "folder") continue;
-        if (isMap(record.name))
-            for (const [key, value] of Object.entries(record.name)) {
-                if (key === "aliases" && Array.isArray(value))
-                    for (const alias of value) carry(alias, address);
-                else carry(value, address);
-            }
+        if (isMap(record.name)) {
+            for (const value of Object.values(record.name)) carry(value, address);
+            for (const form of nameFormsOf(record.name)) carry(form, address);
+        }
         const governance = isMap(record.data?.governance) ? record.data.governance : {};
         for (const rank of Array.isArray(governance.ranks) ? governance.ranks : [])
             if (isMap(rank)) carry(rank.title, address);

package/engine/lexical-sections.mjs

@@ -26,6 +26,7 @@ import { scanBlocks } from "./content-blocks.mjs";
 import { renderDictionary, renderGlossary } from "./dictionary-layout.mjs";
 import { DICTIONARY_COLUMNS, TERM_COLUMNS, dictionaryAndTermRows } from "./dictionary-rows.mjs";
 import { glossaryLanguage } from "./glossary-language.mjs";
+import { languageNotesByCode } from "./note-language.mjs";
 import { scanHeadingAttributes } from "./heading-attributes.mjs";
 import { isNoteRecord } from "./index-records.mjs";
 
@@ -117,6 +118,7 @@ export function lexicalSectionsFor(records, all = records) {
     const visible = encodeAddresses(records).filter(isNoteRecord);
     const complete = encodeAddresses(all).filter(isNoteRecord);
     const byKey = new Map(visible.map((record) => [keyOf(record), record]));
+    const languageNotes = languageNotesByCode(complete, keyOf);
     const addressContext = {
         types: new Set(complete.map((record) => record.type)),
         packages: new Set(complete.map((record) => record.package)),
@@ -136,7 +138,7 @@ export function lexicalSectionsFor(records, all = records) {
         const pageLanguage = glossaryLanguage(undefined, record, {
             self: key,
             keyOf: (value) => (typeof value === "string" ? value : undefined),
-            lookup: (address) => byKey.get(address),
+            noteOf: (code) => languageNotes.get(code),
         });
         sections.set(key, [
             {

package/engine/literature-notes.mjs

@@ -17,10 +17,8 @@
  * `data.culture`, is a field every lore note but a culture note may state,
  * declared in `culture-choice.mjs`.
  *
- * `data.language` is shared beyond literature: a work names the tongue it is
- * composed in, a culture the tongue its people speak, whose name lists
- * `package-build npc new` draws from, and an affiliation the trade, temple or
- * order tongue it keeps.
+ * The tongue a work is composed in is its `data.lang`, which every note may
+ * state.
  *
  * `DataFieldSpec` declares the keys a type accepts, not the subType that may
  * write them, so {@link checkLiteratureNote} scopes these keys to the subTypes
@@ -29,74 +27,13 @@
  * @module
  */
 
-import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 
 /** The `lore` subType whose notes are works of literature. */
 export const LITERATURE_SUBTYPE = "literature";
 
-/** The `lore` subTypes that may name a language. */
-export const LANGUAGE_SUBTYPES = Object.freeze([LITERATURE_SUBTYPE, "culture"]);
-
-/**
- * Require `data.language` to address a `skill` note whose subType is
- * `language`.
- *
- * An Address that does not resolve is the reference check's to report, so
- * this speaks only about a target that exists and is the wrong kind.
- *
- * @param {object} note
- * @param {{index?: object}} [options]
- * @returns {object[]} The findings.
- */
-export function checkLanguageChoice(note, { index } = {}) {
-    const value = note.fm?.data?.language;
-    if (value === undefined || value === null || !index?.addressHit) return [];
-    const tuple = parseAddress(value, {
-        package: index.contentPackage,
-        system: "note",
-        type: "skill",
-        types: index.types,
-        packages: index.packages,
-    });
-    if (tuple.reason) return [];
-    const target = index.addressHit(renderAddress(tuple));
-    if (!target) return [];
-    const fm = target.fm ?? target;
-    if (tuple.type === "skill" && fm.subType === "language") return [];
-    return [
-        {
-            file: note.file,
-            ...positionOfFrontmatterPath(note.raw ?? "", ["data", "language"]),
-            severity: "error",
-            message: `data.language ${isAddressTuple(value) ? renderAddress(value) : value} names a note that is not a skill whose subType is language`,
-        },
-    ];
-}
-
-/**
- * `data.language`: the tongue a work is composed in, the tongue a culture's
- * people speak, or the tongue an affiliation keeps. Optional on all three.
- *
- * @type {object}
- */
-export const LANGUAGE_FIELD = Object.freeze({
-    name: "language",
-    shape: "an Address",
-    kind: "address",
-    ref: "skill",
-    accepts: Object.freeze(["skill"]),
-    check: checkLanguageChoice,
-    describe:
-        "The tongue the note is in, as a language skill note: the tongue a work is composed " +
-        "in, a culture's people speak, or an affiliation keeps as its trade, temple or order " +
-        "tongue. `package-build npc new` draws a culture's names from its language's " +
-        "`data.names`. A `literature` or `culture` lore note, or an affiliation, only.",
-});
-
 /**
- * The fields only a `literature` note may state, beside the shared
- * {@link LANGUAGE_FIELD}. Every one is optional.
+ * The fields only a `literature` note may state. Every one is optional.
  *
  * @type {ReadonlyArray<object>}
  */
@@ -124,8 +61,7 @@ export const LITERATURE_FIELDS = Object.freeze([
 const LITERATURE_KEYS = Object.freeze(LITERATURE_FIELDS.map((field) => field.name));
 
 /**
- * Refuse a literature field on a lore note of any other subType, and
- * `data.language` on a lore note that is neither a work nor a culture.
+ * Refuse a literature field on a lore note of any other subType.
  *
  * @param {object} note
  * @returns {object[]} One error per key written off the subTypes that take it.
@@ -153,13 +89,5 @@ export function checkLiteratureNote(note) {
                         `\`subType\` is not \`literature\``,
                 ),
             );
-    if (!LANGUAGE_SUBTYPES.includes(subType) && stated(LANGUAGE_FIELD.name))
-        findings.push(
-            finding(
-                LANGUAGE_FIELD.name,
-                "`data.language` names the tongue of a work of literature or of a culture, " +
-                    "and this note's `subType` is neither `literature` nor `culture`",
-            ),
-        );
     return findings;
 }

package/engine/metadata-index.mjs

@@ -62,6 +62,7 @@ import {
 } from "./content-address.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { isGmNote } from "./note-vocabulary.mjs";
+import { nameFormLists } from "./name-forms.mjs";
 
 /**
  * Written once a fetch completes, so a half-finished cache is never used.
@@ -448,7 +449,13 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 ...(typeof record.name?.sort === "string" && record.name.sort ?
                     { nameSort: record.name.sort }
                 :   {}),
-                aliases: record.name?.aliases,
+                // Every form the note's name lists, by language, and the
+                // language the publishing package derived for the note.
+                forms:
+                    nameFormLists(record.name).length ?
+                        Object.fromEntries(nameFormLists(record.name))
+                    :   undefined,
+                lang: typeof record.lang === "string" ? record.lang : undefined,
                 // Absent where the package publishes no page for it. A consumer
                 // must tolerate that rather than invent an href, exactly as it
                 // already tolerates an entry with no `uuid`.
@@ -489,15 +496,15 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 // walking that parent's own chain.
                 culture: record.data?.culture ?? undefined,
                 ...(parts.type === "lore" && record.subType === "culture" ?
-                    {
-                        data: {
-                            language: record.data?.language,
-                            appearanceProfile: record.data?.appearanceProfile,
-                        },
-                    }
+                    { data: { appearanceProfile: record.data?.appearanceProfile } }
                 :   {}),
                 ...(parts.type === "skill" && record.subType === "language" ?
-                    { data: { names: record.data?.names } }
+                    {
+                        data: { names: record.data?.names },
+                        ...(typeof record.languageCode === "string" ?
+                            { languageCode: record.languageCode }
+                        :   {}),
+                    }
                 :   {}),
                 population: record.data?.population ?? undefined,
                 ...(Object.hasOwn(record.data ?? {}, "government") ?

package/engine/name-forms.mjs

@@ -0,0 +1,99 @@
+/*
+ * 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
+ */
+
+/**
+ * A note's names, by language.
+ *
+ * `name` is `{full, <code>: [forms]}`. `full` is the English name a page,
+ * a compendium entry and an index print. Every other name the subject goes by
+ * is listed under the code of its language: a code `languages:` declares, or
+ * `en`, which needs no declaration. The first form of a list is that
+ * language's standard form, and `full` counts as an English form.
+ *
+ * `sort`, and a character's `given` and `clan`, are single strings and no
+ * language's forms, so a configured language may not take one of those names.
+ *
+ * A leaf module, importing nothing.
+ *
+ * @module
+ */
+
+/**
+ * A whole visible label as names are matched: NFC, straight apostrophes,
+ * single spaces, trimmed, and case folded. Matching ignores case; a name is
+ * displayed as it was written, never in this form.
+ *
+ * @param {string} text - A visible name, `full` or a form.
+ * @returns {string} Its matching key.
+ */
+export function normalizeName(text) {
+    return displayName(text).toLowerCase();
+}
+
+/**
+ * A whole visible label as it is displayed: NFC, straight apostrophes, single
+ * spaces and trimmed, its case as written.
+ *
+ * @param {string} text - A visible name, `full` or a form.
+ * @returns {string} The label for display.
+ */
+export function displayName(text) {
+    return text.normalize("NFC").replaceAll("’", "'").replace(/\s+/g, " ").trim();
+}
+
+/** The language every note falls back to, and a code no configuration need declare. */
+export const FALLBACK_LANGUAGE = "en";
+
+/** The single-string name keys every note accepts, in display order. */
+export const NOTE_NAME_KEYS = Object.freeze(["full", "sort"]);
+
+/** Additional name components accepted by an individual character. */
+export const CHARACTER_NAME_KEYS = Object.freeze(["given", "clan"]);
+
+/** Every `name` key that is not a language's list of forms. */
+export const NAME_STRING_KEYS = Object.freeze([...NOTE_NAME_KEYS, ...CHARACTER_NAME_KEYS]);
+
+const STRING_KEYS = new Set(NAME_STRING_KEYS);
+
+/**
+ * A note's form lists, in authored order: each key of `name` that is not one
+ * of {@link NAME_STRING_KEYS} and holds a list, with its string forms.
+ *
+ * Read without the configuration, so a reader of an index gets every list a
+ * note states; which codes a note may state is the frontmatter lint's
+ * question, not a reader's.
+ *
+ * @param {unknown} name - A note's `name`.
+ * @returns {Array<[string, string[]]>} `[code, forms]` pairs; a form that is
+ *   not a nonempty string is left out, and so is a list left empty by that.
+ */
+export function nameFormLists(name) {
+    if (!name || typeof name !== "object" || Array.isArray(name)) return [];
+    const out = [];
+    for (const [code, value] of Object.entries(name)) {
+        if (STRING_KEYS.has(code) || !Array.isArray(value)) continue;
+        const forms = value.filter((form) => typeof form === "string" && form.trim() !== "");
+        if (forms.length) out.push([code, forms]);
+    }
+    return out;
+}
+
+/**
+ * Every form a note's name lists, in authored order, without `full`.
+ *
+ * @param {unknown} name - A note's `name`.
+ * @returns {string[]} The forms; empty where it lists none.
+ */
+export function nameFormsOf(name) {
+    return nameFormLists(name).flatMap(([, forms]) => forms);
+}

package/engine/name-refs.mjs

@@ -0,0 +1,143 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The `ref=` attribute of a `.name` span: the note a spelling belongs to, or a
+ * page-local key for a subject with no note. Shape findings need no catalog;
+ * resolution findings take the prepared name catalog.
+ * @module
+ */
+
+import { rebaseNameSpans } from "./name-markup.mjs";
+import { scanSpans } from "./content-spans.mjs";
+
+/** A page-local key: `#` then a word of letters, digits, `_` and `-`. */
+const LOCAL_KEY = /^#[\p{L}\p{N}][\p{L}\p{N}_-]*$/u;
+
+const isName = (span) =>
+    span.attrs.some(([key, value]) => key === "class" && value.split(/\s+/).includes("name"));
+
+/**
+ * Whether a `ref` value is a page-local key rather than a note address.
+ * @param {string} ref - The attribute value as written.
+ * @returns {boolean} True for a value beginning with `#`.
+ */
+export const isLocalRef = (ref) => ref.startsWith("#");
+
+/**
+ * The `ref` a span states.
+ * @param {{attrs: ReadonlyArray<readonly [string, string]>}} span - A parsed span.
+ * @returns {string|null} The value as written, or null when the span has none.
+ */
+export function readNameRef(span) {
+    return span.attrs.find(([key]) => key === "ref")?.[1] ?? null;
+}
+
+/** A finding at a named attribute part, with the position left out when unknown. */
+function at(span, key, part, file, message) {
+    const site = span.attributePositions?.[key]?.[part];
+    return {
+        ...(file === undefined ? {} : { file }),
+        ...(Number.isFinite(site?.line) ? { line: site.line } : {}),
+        ...(Number.isFinite(site?.column) ? { column: site.column } : {}),
+        severity: "error",
+        message,
+    };
+}
+
+/**
+ * The `ref=` findings that depend on the span alone.
+ * @param {ReadonlyArray<import("./names.mjs").ParsedNameSpan>} spans - Every parsed span, at file coordinates.
+ * @param {{file?: string}} [options] - Authored source file.
+ * @returns {Array<{file?: string, line?: number, column?: number, severity: "error", message: string}>} One error per defect.
+ */
+export function nameRefFindings(spans, { file } = {}) {
+    const findings = [];
+    for (const span of spans) {
+        const ref = readNameRef(span);
+        if (ref === null) continue;
+        if (!isName(span)) {
+            findings.push(
+                at(
+                    span,
+                    "ref",
+                    "key",
+                    file,
+                    "ref= belongs on a .name span; a wikilink never takes ref",
+                ),
+            );
+            continue;
+        }
+        if (span.attrs.some(([key]) => key === "data-type"))
+            findings.push(
+                at(
+                    span,
+                    "data-type",
+                    "key",
+                    file,
+                    "data-type is for a name with no note; the ref states the type",
+                ),
+            );
+        if (isLocalRef(ref) && !LOCAL_KEY.test(ref))
+            findings.push(
+                at(
+                    span,
+                    "ref",
+                    "value",
+                    file,
+                    `ref ${JSON.stringify(ref)} must be a note address or a page-local key such as #jane`,
+                ),
+            );
+    }
+    return findings;
+}
+
+/**
+ * Create the check that every note `ref=` of a note names a note.
+ * @param {object} options - The lint's prepared inputs.
+ * @param {import("./names.mjs").NameCatalog} options.catalog - Resolves an address to its note.
+ * @param {Map<string, {raw: string, body: string, bodyLine?: number, bodyColumn?: number}>} [options.parsed] - Captured authored bodies.
+ * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Exact-text scanner projections.
+ * @returns {(note: {file: string, raw: string}) => Array<{file: string, line?: number, column?: number, severity: "error", message: string}>} One error per unresolved address.
+ */
+export function createNameRefChecker({ catalog, parsed, syntax }) {
+    return ({ file, raw }) => {
+        const authored = parsed?.get(file);
+        const spans =
+            authored?.raw === raw && Number.isInteger(authored.bodyLine) ?
+                rebaseNameSpans(
+                    (syntax ? syntax(authored.body).spans : scanSpans(authored.body)).names,
+                    {
+                        raw,
+                        bodyLine: authored.bodyLine,
+                        bodyColumn: authored.bodyColumn,
+                    },
+                )
+            :   scanSpans(raw).names;
+        const findings = [];
+        for (const span of spans) {
+            const ref = readNameRef(span);
+            if (ref === null || isLocalRef(ref) || catalog.resolve(ref)) continue;
+            findings.push(
+                at(
+                    span,
+                    "ref",
+                    "value",
+                    file,
+                    `ref ${JSON.stringify(ref)} names no note in this package or its declared dependencies`,
+                ),
+            );
+        }
+        return findings;
+    };
+}