@heroiclands/package-build 10.0.1 → 11.0.0

package/engine/wikilinks.mjs

@@ -18,15 +18,14 @@
  *
  *   `[[type-shortcode|Text]]`   a document of that type
  *   `[[type-shortcode|]]`       the same, showing the target's current name
- *   `[[Text]]`                  an alias unique within the source's own type
  *   `[[type-shortcode#slug|T]]` a section (see below)
  *   `[[#slug|Text]]`            a section of the source note itself
  *   `[[doctype-shortcode|T]]`   an item's *documentation* (see below)
  *
- * **The pipe decides which of the two namespaces a target belongs to** (#131),
- * and neither falls back to the other — see {@link resolvesAsAddress}, which
- * states the rule for both builds. A piped target is parsed by the address
- * grammar; an unpiped one is looked up in the alias index.
+ * **Every link is an address, and every address carries a label** (#180). A
+ * link written without one addresses nothing and is reported — see
+ * {@link unlabelledLinkMessage}, which states the rule for both builds. The
+ * bare `[[Alias]]` form and the index it was looked up in are retired.
  *
  * The qualifier is the note's **type**, which with its shortcode is the system's
  * logical identity: `(type, shortcode)` is unique by rule (see the Shortcode
@@ -34,13 +33,11 @@
  * unique per type, not per directory, so a directory qualifier would add nothing
  * to the address while breaking every inbound link the moment a note is refiled.
  *
- * The bare form is a **name**, not an abbreviated address: it resolves against
- * the aliases of the source's **own type**, so a `doc` reaches any other `doc`
- * by name wherever it is filed. Nothing narrower is consulted — a note's
- * directory and its `category` play no part in resolution. Where two notes of a
- * type legitimately share a name (a rules page and a user-guide page both called
- * "Gear"), the bare form is ambiguous and resolves to neither; the author writes
- * the `[[type-shortcode|Text]]` address instead.
+ * Nothing narrower than `(type, shortcode)` is consulted — a note's directory
+ * and its `category` play no part in resolution — and nothing wider: a note's
+ * *name* is not an address, so two notes of a type may share a display name
+ * ("Gear" as a rules page and as a user-guide page) with nothing to disambiguate
+ * (#179, #180).
  *
  * At compile time each becomes a Foundry UUID enricher, routed to the pack that
  * the target's type compiles into (see {@link packForType}):
@@ -93,10 +90,12 @@ import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 // The syntax lives in `./wikilink-syntax.mjs`, so the web resolver and this
 // one cannot disagree about what counts as a link.
-import { authoredLabel, WIKILINK, parseWikilink, resolvesAsAddress } from "./wikilink-syntax.mjs";
-// The alias half of the two namespaces: what may be claimed, and how a claim
-// is keyed. Shared with the site build and the link checker (#131).
-import { aliasKey } from "./alias-index.mjs";
+import {
+    authoredLabel,
+    WIKILINK,
+    parseWikilink,
+    unlabelledLinkMessage,
+} from "./wikilink-syntax.mjs";
 
 export { ITEM_PACK, PACK_BY_TYPE, packForType };
 
@@ -145,7 +144,7 @@ export function resolveItemDocType(qualifier, types) {
 
 /**
  * Read a link target as a **qualified** `type-shortcode` reference, or report
- * that it is a bare alias instead.
+ * that it does not parse as one.
  *
  * Two separators are accepted, and they are **not** interchangeable in how
  * confidently they mark a target as qualified:
@@ -154,19 +153,20 @@ export function resolveItemDocType(qualifier, types) {
  *   a wikilink as a *path* and resolves it against the vault's folders, so a
  *   slash-qualified link is a broken link in the editor where the content is now
  *   authored. A hyphen qualifies **only when what precedes it is a known type**:
- *   note names contain hyphens too (`Grukar-ahk`), and those must keep resolving
- *   as aliases. The split is at the **first** hyphen, so a shortcode may itself
- *   contain one (`trauma-self-pro` → `trauma` + `self-pro`).
+ *   note names contain hyphens too (`Grukar-ahk`), and a target that is one is
+ *   reported as not an address rather than split at an arbitrary place. The
+ *   split is at the **first** hyphen, so a shortcode may itself contain one
+ *   (`trauma-self-pro` → `trauma` + `self-pro`).
  * - **`type/shortcode`** — the legacy form, still resolved so that a link
  *   written before the vault migrated does not silently die. A slash is
  *   *unconditionally* a qualifier: nothing else uses one, so an unknown type
- *   before it is an error rather than an invitation to try the alias index. The
- *   split is at the **last** slash, as it always was.
+ *   before it is reported rather than guessed at. The split is at the **last**
+ *   slash, as it always was.
  *
  * A leading **package** segment is optional and outermost: `sohl-skill-lang` is
  * `skill-lang` in the `sohl` package. It is read only when `packages` is given
  * and names the segment, and only when the remainder is itself a valid address,
- * so a note called "Grukar-ahk" stays an alias (#1499).
+ * so a note called "Grukar-ahk" is not mistaken for one (#1499).
  *
  * @param {string} target - The link target, anchor already removed.
  * @param {Set<string>} types - Every type the content tree contains.
@@ -175,7 +175,7 @@ export function resolveItemDocType(qualifier, types) {
  * @returns {{type: string, shortcode: string, itemDoc: boolean,
  *   package?: string, reason?: undefined} | {reason: "unknown-type"} | null}
  *   The resolved qualifier; a `reason` when the target is definitely qualified
- *   but names no known type; or `null` when it is a bare alias.
+ *   but names no known type; or `null` when it is not an address at all.
  */
 export function readQualifier(target, types, packages) {
     // A leading **package** segment is the optional outermost qualifier:
@@ -183,7 +183,7 @@ export function readQualifier(target, types, packages) {
     // here so everything below reads the same `type`/`shortcode` it always did,
     // and it is recognised only when what precedes the hyphen is a package this
     // build knows *and* the remainder is itself a valid address — so a note
-    // named "Sohl-something" is still an alias (#1499).
+    // named "Sohl-something" is not mistaken for one (#1499).
     if (packages?.size) {
         const hyphen = target.indexOf("-");
         if (hyphen > 0) {
@@ -204,7 +204,8 @@ export function readQualifier(target, types, packages) {
 
     const hyphen = target.indexOf("-");
     if (hyphen > 0) {
-        // A hyphen qualifies only on a known type; otherwise it is part of a name.
+        // A hyphen qualifies only on a known type; otherwise it is part of a
+        // name, and a name is not an address.
         return readTypeAndCode(target.slice(0, hyphen), target.slice(hyphen + 1), types);
     }
     return null;
@@ -257,21 +258,21 @@ export function anchorPageId(noteId, anchorSlug) {
  * Builds the link-resolution tables for a content tree.
  *
  * @param {Array<{type: string, id: string, shortcode?: string|null,
- *   aliases?: string[], name?: string, pack?: string, docPack?: string}>} docs -
+ *   name?: string, pack?: string, docPack?: string,
+ *   draft?: boolean}>} docs -
  *   One entry per content note. `pack` / `docPack` name the packs the note's
  *   document and its documentation entry landed in; omitted, the conventional
- *   one-pack-per-type names stand in.
+ *   one-pack-per-type names stand in. `draft` says the note carries the `draft`
+ *   tag, which marks links *into* it and changes nothing else (#183).
  * @param {string} packageId - The Foundry package shipping the packs; the first
  *   segment of every emitted UUID.
  * @param {Map<string, object>} [foreign] - Canonically keyed entries from
  *   vendored manifests of packages this build links into but does not publish.
  * @param {string} [contentPackage] - This build's *content* package, which an
  *   authored address may name explicitly. Defaults to `packageId`.
- * @returns {{byShortcode: Map<string, object>, byAlias: Map<string, object|null>,
- *   types: Set<string>}} `byAlias` holds `null` where a type-scoped alias is
- *   claimed by more than one document, which makes the bare `[[Text]]` form
- *   unusable for it. `types` is every type the tree actually contains, so a
- *   qualifier naming no real type can be told apart from a missing target.
+ * @returns {{byShortcode: Map<string, object>, types: Set<string>}} `types` is
+ *   every type the tree actually contains, so a qualifier naming no real type
+ *   can be told apart from a missing target.
  */
 export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
     if (!packageId) {
@@ -283,11 +284,6 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
     }
 
     const byShortcode = new Map();
-    const byAlias = new Map();
-    // key -> every note claiming it. `byAlias` records only the *verdict*
-    // (a note, or `null` for poisoned); this records the claimants, which is
-    // what an ambiguity report has to name.
-    const aliasClaims = new Map();
     const types = new Set();
 
     // Each note's address is computed once, here, and every reference to it is
@@ -312,19 +308,6 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
         });
 
         if (d.shortcode) byShortcode.set(`${norm(d.type)}/${norm(d.shortcode)}`, d);
-        for (const a of d.aliases ?? []) {
-            const key = aliasKey(d.type, a);
-            // Second claimant poisons the alias: it can no longer be resolved.
-            byAlias.set(key, byAlias.has(key) && byAlias.get(key) !== d ? null : d);
-            // Every claimant is kept alongside, because poisoning the alias
-            // discards exactly the information needed to report the problem.
-            // The note that *cites* an ambiguous alias is innocent — whoever
-            // added the second claimant broke it — so a message that can only
-            // name the citing note points at the wrong file (#13).
-            const claims = aliasClaims.get(key);
-            if (!claims) aliasClaims.set(key, [d]);
-            else if (!claims.includes(d)) claims.push(d);
-        }
     }
     // Entries published by *other* packages, keyed canonically. Merged as one
     // map rather than consulted separately: the keys are globally unique, so a
@@ -369,8 +352,6 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
 
     return {
         byShortcode,
-        byAlias,
-        aliasClaims,
         types,
         uuidByDoc,
         packageId,
@@ -382,22 +363,43 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
 /**
  * The foreign manifest entry an address names, or `null`.
  *
- * A package-qualified address is one lookup. A bare one names no package, so it
+ * A package-qualified address is one lookup. An unqualified one names no
+ * package, so it
  * resolves against whichever foreign package publishes it — and only when
  * exactly one does. Claimed by two, it is genuinely ambiguous and the author
  * writes the qualified form; guessing would make the build depend on which
  * manifest happened to load first.
  *
  * @param {object} index - From {@link buildWikilinkIndex}.
- * @param {object|null} read - The parsed qualifier, or `null` for a bare alias.
+ * @param {object|null} read - The parsed qualifier, or `null` when the target
+ *   did not parse as an address.
  * @returns {object|null} The manifest entry.
  */
 function findForeign(index, read) {
-    if (!read || read.reason || !index.foreign?.size) return null;
+    const hits = foreignHits(index, read);
+    return hits.length === 1 ? hits[0] : null;
+}
+
+/**
+ * Every foreign manifest entry an address names.
+ *
+ * The count is what separates *nothing publishes this* from *two packages do*,
+ * and those are different findings with different fixes (#184), so the caller
+ * gets the list rather than a single answer that has already collapsed the
+ * distinction.
+ *
+ * @param {object} index - From {@link buildWikilinkIndex}.
+ * @param {object|null} read - The parsed qualifier, or `null` when the target
+ *   did not parse as an address.
+ * @returns {object[]} The manifest entries.
+ */
+function foreignHits(index, read) {
+    if (!read || read.reason || !index.foreign?.size) return [];
     const wanted = norm(read.itemDoc ? `doc${read.type}` : read.type);
     const shortcode = norm(read.shortcode);
     if (read.package) {
-        return index.foreign.get(`${read.package}-${wanted}-${shortcode}`.toLowerCase()) ?? null;
+        const one = index.foreign.get(`${read.package}-${wanted}-${shortcode}`.toLowerCase());
+        return one ? [one] : [];
     }
     const hits = [];
     for (const [key, v] of index.foreign) {
@@ -405,7 +407,7 @@ function findForeign(index, read) {
         if (parts.length !== 3) continue;
         if (parts[1] === wanted && parts[2] === shortcode) hits.push(v);
     }
-    return hits.length === 1 ? hits[0] : null;
+    return hits;
 }
 
 /**
@@ -433,6 +435,36 @@ function unresolvedLink(text, target) {
     );
 }
 
+/**
+ * How a link to a **draft** note renders (#183).
+ *
+ * A note tagged `draft` exists so a link into it is not dead, and nothing more.
+ * Unmarked, a reader follows a promising link into an empty page and an author
+ * cannot see which of their links still owe content.
+ *
+ * **The wrapper carries the cue and nothing else.** The link itself is
+ * untouched — Foundry enriches inside HTML, so the `@UUID` still becomes a live
+ * content link, and the note is in the packs, the manifest and the index
+ * exactly as any other. Nothing here resembles the retired `draft:` field,
+ * which moved a note from published to unresolvable without saying so.
+ *
+ * The appearance lives in `scss/components/_draft-link.scss`, beside the
+ * unresolved-link partial, not here.
+ *
+ * **Byte-identical with the site build's copy** in `web-wikilinks.mjs`, down to
+ * the class name and the `title` wording — one authored link renders on two
+ * surfaces, and the two builds have drifted before over exactly this kind of
+ * detail (#1409). The argument is already-built markup and is deliberately not
+ * escaped; the *authored* text inside it was escaped, or made into a link, by
+ * whichever resolver called this.
+ *
+ * @param {string} inner - The resolved link, as that build emits it.
+ * @returns {string} An inline HTML span wrapping it.
+ */
+function draftLink(inner) {
+    return `<span class="sohl-draft-link" title="Draft — not yet written">${inner}</span>`;
+}
+
 /** Matches a whole wikilink, capturing its inner text. */
 
 /**
@@ -452,19 +484,23 @@ function unresolvedLink(text, target) {
  *
  * @param {string} markdown - The note body (frontmatter already stripped).
  * @param {object} ctx
- * @param {string} ctx.type - The source note's `type`, which scopes a bare `[[Text]]`.
+ * @param {string} ctx.type - The source note's `type`, which addresses a
+ *   `[[#slug]]` self-link.
  * @param {string} ctx.id - The source note's document id.
  * @param {string} [ctx.pack] - The pack the source note's own document landed
  *   in, which addresses a `[[#slug]]` self-link — the one target with no index
  *   entry.
  * @param {string} [ctx.docPack] - The pack the source note's documentation
  *   entry landed in.
- * @param {{byShortcode: Map, byAlias: Map, types: Set}} ctx.index - From
+ * @param {{byShortcode: Map, types: Set}} ctx.index - From
  *   {@link buildWikilinkIndex}.
  * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
- *   offset: number, reason: "unknown"|"ambiguous"|"unknown-type"}>}} `offset`
- *   is the link's 0-based position in `markdown`, which is what lets a caller
- *   report the line and column it sits on (#17).
+ *   offset: number, reason: string, packages?: string[], anchor?: string}>}}
+ *   Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all
+ *   three resolvers share (#184) — `ambiguous` carries the claiming `packages`
+ *   and `unknown-anchor` the section it named. `offset` is the link's 0-based
+ *   position in `markdown`, which is what lets a caller report the line and
+ *   column it sits on (#17).
  */
 export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
     const unresolved = [];
@@ -474,37 +510,47 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
     // one note tellable apart, and a position reportable at all (#17).
     const out = replaceOutsideCode(markdown, WIKILINK, (all, rawInner, offset) => {
         const parsed = parseWikilink(rawInner);
-        const { labelled } = parsed;
-        let target = parsed.target;
-        // An unlabelled link shows its interior verbatim, anchor included;
-        // a labelled one shows its label. An *empty* label is not a label
-        // — `[[x|]]` means "show the target's name" — and that reading
-        // comes from {@link authoredLabel} so the web resolver cannot draw
-        // the line somewhere else (#113).
-        let text = labelled ? (authoredLabel(parsed) ?? "") : parsed.inner;
+        const target = parsed.target;
         const slug = parsed.anchor || null;
 
-        // Resolve the document: same-page (empty target), an address, or an
-        // alias. **The pipe chooses which**, with no fallback either way
-        // (#131) — see {@link resolvesAsAddress}.
+        // **Every link carries a label** (#180). Without one there is nothing
+        // to resolve against: the alias namespace a bare `[[Text]]` was looked
+        // up in is retired, and a shortcode is an address rather than prose, so
+        // the link has neither a target this build can find nor text to show.
+        // Reported before anything else, including the same-page form, because
+        // it is a statement about how the link is *written* — `[[#slug]]` needs
+        // the pipe exactly as `[[skill-clmb]]` does.
+        if (!parsed.labelled) {
+            unresolved.push({
+                link: all,
+                target: target || (slug ? `#${slug}` : ""),
+                offset,
+                reason: "unlabelled",
+                addressed: false,
+            });
+            return unresolvedLink(parsed.inner, parsed.inner);
+        }
+
+        // An *empty* label is not a label — `[[x|]]` means "show the target's
+        // name" — and that reading comes from {@link authoredLabel} so the web
+        // resolver cannot draw the line somewhere else (#113).
+        let text = authoredLabel(parsed) ?? "";
+
+        // Resolve the document: the source note itself for an empty target, or
+        // the address the target parses as.
         let doc;
         // Set when the qualifier was the virtual `doc<type>` form, so the UUID
         // is built against the item doc entry rather than the item itself.
         let itemDoc = false;
-        // Set when the target was read as an address, which is what decides
-        // whether a foreign manifest is consulted for it below.
-        let addressed = false;
         // Kept for the foreign fallback below, which needs the parsed address.
         let qualifiedRead = null;
         if (target === "" && slug) {
             doc = { type, id, pack, docPack };
-        } else if (resolvesAsAddress(parsed)) {
+        } else {
             const qualified = readQualifier(target, index.types, index.packages);
             qualifiedRead = qualified;
-            // The author wrote a pipe, so they meant an address. A target that
-            // does not parse as one is therefore a defect and not, as it was
-            // under the old resolve-by-shape rule, an invitation to try the
-            // alias index — which is what let a note *name* resolve here.
+            // A target that does not parse as an address is a defect: there is
+            // no second namespace left to fall through to (#180).
             if (!qualified || qualified.reason) {
                 unresolved.push({
                     link: all,
@@ -515,36 +561,30 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
                 });
                 return unresolvedLink(text || target, target);
             }
-            addressed = true;
             itemDoc = qualified.itemDoc;
             doc = index.byShortcode.get(`${qualified.type}/${qualified.shortcode}`);
-        } else {
-            const key = aliasKey(type, target);
-            const hit = index.byAlias.get(key);
-            if (hit === null) {
+        }
+        if (!doc) {
+            // Nothing local answers. A foreign package may publish this
+            // address, in which case the manifest hands back a complete UUID —
+            // including, for a section link, the anchor's own — so nothing is
+            // derived here.
+            const hits = foreignHits(index, qualifiedRead);
+            if (hits.length > 1) {
+                // Two packages publish the short address, so it names neither.
+                // Its own class: the fix is the package-qualified form, not a
+                // corrected shortcode (#184).
                 unresolved.push({
                     link: all,
                     target,
                     offset,
                     reason: "ambiguous",
-                    // Who claimed it, so the report can name the collision
-                    // rather than the note that merely cites it (#13).
-                    candidates: (index.aliasClaims?.get(key) ?? []).map((d) => ({
-                        type: d.type,
-                        shortcode: d.shortcode,
-                        name: d.name,
-                    })),
+                    packages: hits.map((h) => h.package).filter(Boolean),
+                    addressed: true,
                 });
                 return unresolvedLink(text || target, target);
             }
-            doc = hit;
-        }
-        if (!doc) {
-            // Nothing local answers. A foreign package may publish this
-            // address, in which case the manifest hands back a complete UUID —
-            // including, for a section link, the anchor's own — so nothing is
-            // derived here.
-            const hit = findForeign(index, qualifiedRead);
+            const hit = hits[0] ?? null;
             if (hit) {
                 const uuid = slug ? hit.anchors?.[slug] : hit.uuid;
                 if (uuid) {
@@ -555,6 +595,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
                     target,
                     offset,
                     reason: "unknown-anchor",
+                    anchor: slug,
                     addressed: true,
                 });
                 return unresolvedLink(text || target, target);
@@ -563,24 +604,20 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
                 link: all,
                 target,
                 offset,
-                reason: "unknown",
-                // An *address* that resolves nowhere is a typo: every package
-                // it could name is either built here or vendored, so there is
-                // no third possibility left. A bare alias is not — it may
-                // simply be prose, or a worldbuilding placeholder.
-                addressed,
+                reason: "unresolved",
+                // An address that resolves nowhere is a typo: every package it
+                // could name is either built here or vendored, so there is no
+                // third possibility left.
+                addressed: true,
             });
             return unresolvedLink(text || target, target);
         }
 
-        // An address with no label — `[[skill-clmb|]]` — has no prose to show,
-        // a shortcode being an address rather than display text, so the
-        // document's **current** name stands in and a rename shows at every
-        // citation with no link edited (#1409, #131). A bare `[[Text]]` is
-        // already the prose the author wrote, and substituting the canonical
-        // name there would rewrite the sentence ("worsens the [[Shock State]]"
-        // must not render as "Shock"). The knowledgebase build reads the same
-        // authored link the same way.
+        // An address with an *empty* label — `[[skill-clmb|]]` — has no prose
+        // to show, a shortcode being an address rather than display text, so
+        // the document's **current** name stands in and a rename shows at every
+        // citation with no link edited (#1409). The knowledgebase build reads
+        // the same authored link the same way.
         if (!text) text = doc.name ?? target;
 
         // Both addresses were computed when the target was indexed. An item
@@ -605,7 +642,12 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
         // item's pages are addressed through its `doc<type>` counterpart.
         const uuid =
             slug && isJournal ? pageUuid(entryUuid, anchorPageId(entryId, slug)) : entryUuid;
-        return `@UUID[${uuid}]{${text}}`;
+        const link = `@UUID[${uuid}]{${text}}`;
+        // A link into a note that exists but is not written renders marked
+        // (#183). Presentation only — the UUID above is unchanged, and a
+        // `[[#slug]]` self-link is not marked because the reader is already in
+        // the note it would be telling them about.
+        return doc.draft ? draftLink(link) : link;
     });
 
     return { markdown: out, unresolved };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "10.0.1",
+    "version": "11.0.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/base-compiler.d.mts

@@ -269,7 +269,7 @@ export class BasePackCompiler {
     prepare(): Promise<void>;
     linkIndex: {
         byShortcode: Map<any, any>;
-        byAlias: Map<any, any>;
+        types: Set<any>;
     } | undefined;
     contentDocs: {
         fm: object;

package/types/engine/content-address.d.mts

@@ -10,32 +10,64 @@
  */
 export function sectionOf(fm: object): string | undefined;
 /**
- * A note's address below the knowledgebase mount, e.g. `affliction/aconite/`.
+ * The single path segment a note is addressed by: `type-shortcode`.
+ *
+ * Lowercased, so it is exactly the tail of the note's canonical key
+ * (`canonicalKey` in `engine/kb-manifest.mjs` lowercases too) — which is what
+ * makes a manifest entry's `path` derivable from the key it is filed under
+ * rather than transported beside it.
+ *
+ * The hyphen is a separator and never occurs inside a segment: a shortcode is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced by `content-lint.mjs`)
+ * and a type is a bare word. That is the same charset guarantee positional key
+ * parsing rests on, so the address and the key cannot disagree about where one
+ * ends and the other begins.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string} The address segment, e.g. `weapongear-dagger`.
+ * @throws {Error} When the note declares no type or no shortcode — either way
+ *   it has no address, which is reported rather than papered over: inventing
+ *   one would publish a page nothing can link to and record a manifest entry
+ *   pointing at it.
+ */
+export function addressSlug(fm: object): string;
+/**
+ * A note's address below the knowledgebase mount, e.g. `affliction-aconite/`.
  *
  * A `README.md` **is** its section's landing page rather than a page within it,
- * so it addresses the section itself and has no slug of its own.
+ * so it addresses the section itself and has no address of its own.
  *
  * @param {object} fm - Parsed frontmatter.
- * @param {string} name - The note's display name; the slug derives from it
- *   (#1278), never from the shortcode, which is identity rather than
- *   presentation.
  * @param {boolean} isReadme - Whether the file is a `README.md`.
- * @returns {string} The section-relative address, with a trailing slash.
- * @throws {Error} When the name yields no usable slug.
+ * @returns {string} The mount-relative address, with a trailing slash.
+ * @throws {Error} When the note has no address.
  */
-export function contentAddress(fm: object, name: string, isReadme: boolean): string;
+export function contentAddress(fm: object, isReadme: boolean): string;
 /**
- * A note's address relative to its **package**, e.g. `kb/affliction/aconite/`.
+ * A note's address relative to its **package**, e.g. `affliction-aconite/`.
  *
  * This is the form the link manifest records and the site build emits pages at,
  * and it is one function because those two must agree — a manifest asserting an
  * address the site does not publish resolves at build time and 404s for the
  * reader, which is the failure this module exists to prevent.
  *
+ * **The prefix does not apply to a page's own address.** `prefix` says where the
+ * content tree *mounts inside the package* — where its section directories and
+ * their landing pages live — and a landing page is addressed by that mount
+ * (`kb/rules/`). An ordinary page is addressed by `(type, shortcode)`, which is
+ * a package-wide identity and takes no mount: `sohl` publishes
+ * `/sohl/affliction-aconite/` while its section landings stay at
+ * `/sohl/kb/affliction/`. The `type-` half is what keeps that flat namespace
+ * clear of the package's fixed mounts — `/<package>/` for the landing,
+ * `/<package>/api/` for generated API docs, neither of which contains a hyphen
+ * or names a type.
+ *
+ * **The section still decides where the *file* is written**, which is why a
+ * note without one still has no address: Hugo derives a section from a page's
+ * directory rather than from its URL, so a page with nowhere to be filed is a
+ * page with no section landing, no `.CurrentSection` and no per-section layout.
+ *
  * @param {object} fm - Parsed frontmatter.
- * @param {string} name - The note's display name; a page slug derives from it
- *   (#1278), never from the shortcode, which is identity rather than
- *   presentation.
  * @param {object} [options] - Options.
  * @param {boolean} [options.isReadme] - Whether the file is a `README.md`.
  * @param {{prefix?: string, landing?: string}} [options.scheme] - The
@@ -43,11 +75,11 @@ export function contentAddress(fm: object, name: string, isReadme: boolean): str
  * @returns {string} The package-relative address, with a trailing slash and no
  *   leading one.
  * @throws {Error} When the note has no address — no section, a landing page
- *   naming no section, or a name yielding no usable slug. Each is a note that
+ *   naming no section, or no shortcode to be addressed by. Each is a note that
  *   is not published, and inventing an address for one would put a dead entry
  *   in the manifest.
  */
-export function packageAddress(fm: object, name: string, { isReadme, scheme }?: {
+export function packageAddress(fm: object, { isReadme, scheme }?: {
     isReadme?: boolean | undefined;
     scheme?: {
         prefix?: string;

package/types/engine/content-links.d.mts

@@ -86,30 +86,26 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
 /**
  * Every link in a tree that lands nowhere.
  *
- * **The two failure modes are separate findings, because they are separate
- * problems** (#131). A piped target the author declared to be an address, and
- * which resolves nowhere, is a typo: every package it could name is either
- * built here or vendored, so there is no third possibility. An unpiped target
- * naming no note of the source's type may be exactly that typo — or a
- * worldbuilding placeholder, which is a long-standing convention in the
- * setting trees. So the first is an error and the second a warning, and the
- * caller can tell them apart without parsing a message.
+ * **How the link is *written* is a separate finding from where it points**, and
+ * the two are kept apart because the corrections differ. An unlabelled link
+ * (#180) has to become `[[type-shortcode|Text]]`; a labelled one whose target
+ * resolves nowhere has a shortcode to fix. Reporting a bare `[[Name]]` as a
+ * dead address would send an author hunting for a note that was never named.
  *
  * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
  * @returns {{deadAnchors: object[], deadAddresses: object[],
- *   deadAliases: object[], aliasCollisions: object[],
- *   frontmatterLinks: object[], homepageLinks: object[],
- *   usedManifest: Set<string>}} The findings, and which addresses a foreign
- *   manifest answered. Each `deadAddresses` entry carries a `reason`:
- *   `"not-an-address"` when the target does not parse as one at all,
- *   `"unknown-type"` when it is qualified but names no known type, and
- *   `"unresolved"` when it parses and nothing answers it.
+ *   unlabelledLinks: object[], frontmatterLinks: object[],
+ *   homepageLinks: object[], usedManifest: Set<string>}} The findings, and
+ *   which addresses a foreign manifest answered. Each `deadAddresses` entry
+ *   carries a `reason` from {@link LINK_FINDING_REASONS} —
+ *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
+ *   `packages`), or `"unresolved"` — and every one of them is an **error**:
+ *   the three resolvers agree on severity for every class (#184).
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];
     deadAddresses: object[];
-    deadAliases: object[];
-    aliasCollisions: object[];
+    unlabelledLinks: object[];
     frontmatterLinks: object[];
     homepageLinks: object[];
     usedManifest: Set<string>;