@heroiclands/package-build 10.0.1 → 11.0.0

package/engine/content-links.mjs

@@ -22,20 +22,17 @@
  *    anchor slug; nothing checks that a heading declaring that slug exists. A
  *    link to an anchor nobody declares compiles cleanly, emits an enricher, and
  *    dead-ends for the reader.
- * 2. **A dead address.** A *piped* target — `[[x|…]]` — is an address, and one
- *    resolving to no note is a typo. So is one that does not parse as an
- *    address at all: the pipe says the author meant one.
- * 3. **A dead alias.** An *unpiped* target — `[[x]]` — names a note of the
- *    source's own type. One that finds nothing may be a worldbuilding
- *    placeholder, so it is reported as a warning rather than a failure; it is a
- *    different problem from a dead address and reads differently.
+ * 2. **A dead address.** Every link is an address, and one resolving to no note
+ *    is a typo. So is a target that does not parse as an address at all.
+ * 3. **An unlabelled link.** `[[x]]` addresses nothing: the alias namespace it
+ *    used to name is retired (#180), and a shortcode is an address rather than
+ *    prose, so the link has neither a resolvable target nor text to show. The
+ *    correction is always `[[type-shortcode|Text]]`.
  * 4. **A wikilink authored in frontmatter.** Both builds walk a note's *body*
  *    and copy frontmatter through verbatim, so a link written in a
  *    `description` is never resolved and publishes as literal `[[…]]` text.
  *    Frontmatter is data: a `WikiLink` field is parsed by the address grammar
  *    and a bracketed link there is a finding naming the note and the field.
- * 5. **An alias two notes of one type both claim.** It used to be deleted
- *    silently, so the pair resolved to nothing and nobody was told (#131).
  *
  * **This resolves links the way the builds do**, calling the same
  * {@link readQualifier} and the same {@link parseWikilink} rather than a second
@@ -72,9 +69,8 @@ import {
 import { frontmatterWikilinks, slugify } from "./web-wikilinks.mjs";
 import { homepageAddresses, isHomepage } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
-import { parseWikilink, resolvesAsAddress, WIKILINK } from "./wikilink-syntax.mjs";
+import { parseWikilink, WIKILINK } from "./wikilink-syntax.mjs";
 import { readQualifier } from "./wikilinks.mjs";
-import { aliasesOf, aliasKey, indexAliases } from "./alias-index.mjs";
 
 /**
  * Every `{#anchor}` a note declares on a heading.
@@ -154,21 +150,6 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
         }
     }
 
-    // The alias half of the two namespaces, built by the shared rule so the
-    // checker, the pack build and the site build cannot disagree about what a
-    // bare `[[…]]` can name (#131).
-    const {
-        byKey: byAlias,
-        claims: aliasClaims,
-        collisions: aliasCollisions,
-    } = indexAliases(
-        notes.map((note) => ({
-            type: note.type,
-            aliases: aliasesOf(note.fm),
-            value: note,
-        })),
-    );
-
     const types = new Set(notes.map((n) => n.type));
 
     // A foreign package may use a type this tree has never seen, so its types
@@ -201,8 +182,8 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
      * @param {object} note - A note from this index.
      * @returns {Array<{target: string, anchor: string, text: string,
      *   occurrence: number, labelled: boolean}>} `target` is `""` for a
-     *   same-page `[[#anchor]]`; `labelled` says which namespace the target
-     *   belongs to (#131).
+     *   same-page `[[#anchor]]`; `labelled` says whether the link carries the
+     *   `|` every link must have (#180).
      */
     function linksOf(note) {
         let body = note.body;
@@ -234,28 +215,12 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
                 anchor,
                 text: all,
                 occurrence,
-                labelled: resolvesAsAddress(parsed),
+                labelled: parsed.labelled,
             });
         }
         return out;
     }
 
-    /**
-     * The note an **alias** names, or `undefined`.
-     *
-     * Scoped to the *source* note's own type, so one word may be an alias in
-     * several types without colliding. An alias two same-type notes claim is
-     * absent from the index entirely — see {@link indexAliases} — so this can
-     * never resolve to whichever was walked first.
-     *
-     * @param {object} note - The note the link is written in.
-     * @param {string} target - The link target, anchor already removed.
-     * @returns {object|undefined} The note it names.
-     */
-    function resolveAlias(note, target) {
-        return byAlias.get(aliasKey(note.type, target));
-    }
-
     /**
      * The note an **address** names, or `undefined`.
      *
@@ -278,45 +243,47 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
     }
 
     /**
-     * Resolve a link target the way both builds do, or `undefined`.
+     * Every foreign manifest entry an address names, in package order.
      *
-     * **The pipe chooses the namespace, and there is no fallback either way**
-     * (#131) — see {@link resolvesAsAddress} for why. The caller therefore has
-     * to say which form was authored; it is a required argument rather than a
-     * defaulted one, because either default would silently resolve half the
-     * corpus through the wrong namespace.
+     * A **package-qualified** address names at most one, by construction. An
+     * unqualified one names no package, so it resolves against any foreign one
+     * that publishes it — and only when exactly one does. Two claimants make it
+     * ambiguous, which is a different finding from resolving nowhere and has a
+     * different fix, so the count is returned rather than collapsed here
+     * (#184).
      *
-     * @param {object} note - The note the link is written in.
      * @param {string} target - The link target.
-     * @param {boolean} labelled - Whether the link carried a `|`.
-     * @returns {object|undefined} The note it names.
+     * @returns {object[]} The foreign entries, each carrying its `package`.
      */
-    function resolve(note, target, labelled) {
-        return labelled ? resolveAddress(target) : resolveAlias(note, target);
+    function foreignHits(target) {
+        const q = readQualifier(target, types, packages);
+        if (!q || q.reason) return [];
+        if (q.package) {
+            const one = foreign.index.get(canonicalKey(q.package, q.type, q.shortcode));
+            return one ? [one] : [];
+        }
+        const type = String(q.type).toLowerCase();
+        const shortcode = String(q.shortcode).toLowerCase();
+        return [...foreign.index]
+            .filter(([k]) => {
+                const parts = readCanonicalKey(k);
+                return parts?.type === type && parts.shortcode === shortcode;
+            })
+            .map(([, v]) => v);
     }
 
     /**
      * The manifest entry a qualified address names in another package, or null.
      *
+     * The single-hit reading of {@link foreignHits}: an address two packages
+     * publish names neither.
+     *
      * @param {string} target - The link target.
      * @returns {object|null} The foreign entry.
      */
     function manifestHit(target) {
-        const q = readQualifier(target, types, packages);
-        if (!q || q.reason) return null;
-        if (q.package) {
-            return foreign.index.get(canonicalKey(q.package, q.type, q.shortcode)) ?? null;
-        }
-        // A bare address names no package, so it resolves against any foreign
-        // one that publishes it. Claimed by two, it is ambiguous and the author
-        // must write the qualified form.
-        const type = String(q.type).toLowerCase();
-        const shortcode = String(q.shortcode).toLowerCase();
-        const hits = [...foreign.index].filter(([k]) => {
-            const parts = readCanonicalKey(k);
-            return parts?.type === type && parts.shortcode === shortcode;
-        });
-        return hits.length === 1 ? hits[0][1] : null;
+        const hits = foreignHits(target);
+        return hits.length === 1 ? hits[0] : null;
     }
 
     return {
@@ -333,15 +300,16 @@ export function buildLinkIndex(contentBase, { manifestDir, skipDirectories } = {
         contentPackage: pkg,
         foreign,
         manifests: manifestsComplete(localPackages, foreign.packages),
-        /** Every note claiming each type-scoped alias, colliding ones included. */
-        aliasClaims,
-        /** One entry per alias two or more same-type notes claim (#131). */
-        aliasCollisions,
         linksOf,
-        resolve,
-        resolveAlias,
+        /**
+         * Resolve a link target the way both builds do, or `undefined`. Every
+         * link is an address, so this is {@link resolveAddress} under the name
+         * the walkers use (#180).
+         */
+        resolve: resolveAddress,
         resolveAddress,
         manifestHit,
+        foreignHits,
         /** Whether a target reads as a qualified address at all. */
         isAddress: (target) => Boolean(readQualifier(target, types, packages)),
     };
@@ -655,24 +623,21 @@ export function auditHomepageLinks(index) {
 /**
  * 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) {
     const { notes, anchors, linksOf, resolve, manifestHit, isAddress } = index;
@@ -680,10 +645,10 @@ export function auditLinks(index) {
     const deadAnchors = [];
     for (const note of notes) {
         for (const { target, anchor, text, occurrence, labelled } of linksOf(note)) {
-            if (!anchor) continue;
-            const dest = target ? resolve(note, target, labelled) : note;
-            // An unresolvable target is reported by the address or alias pass
-            // below; its anchor has nothing to be checked against.
+            if (!anchor || !labelled) continue;
+            const dest = target ? resolve(target) : note;
+            // An unresolvable target is reported by the pass below; its anchor
+            // has nothing to be checked against.
             if (!dest) continue;
             if (!anchors.get(dest).has(slugify(anchor))) {
                 deadAnchors.push({
@@ -698,22 +663,26 @@ export function auditLinks(index) {
     }
 
     const deadAddresses = [];
-    const deadAliases = [];
+    const unlabelledLinks = [];
     const usedManifest = new Set();
     for (const note of notes) {
-        for (const { target, text, occurrence, labelled } of linksOf(note)) {
-            if (!target) continue; // a same-page `[[#anchor]]`
-            const at = { note, target, text, occurrence };
-
+        for (const { target, anchor, text, occurrence, labelled } of linksOf(note)) {
+            // The label is required whatever the link part is, an anchor
+            // included — so this is tested before the same-page form (#180).
             if (!labelled) {
-                if (index.resolveAlias(note, target)) continue;
-                // Kept alongside, so a report can say *why* nothing answered:
-                // an alias claimed twice is absent from the index, and blaming
-                // this note for it would blame the wrong file.
-                const claimants = index.aliasClaims.get(aliasKey(note.type, target)) ?? [];
-                deadAliases.push({ ...at, ambiguous: claimants.length > 1, claimants });
+                unlabelledLinks.push({
+                    note,
+                    target: target || (anchor ? `#${anchor}` : ""),
+                    text,
+                    occurrence,
+                    // Carried like every other finding's, so a reporter reads
+                    // one field rather than knowing which list it drew from.
+                    reason: "unlabelled",
+                });
                 continue;
             }
+            if (!target) continue; // a same-page `[[#anchor|Text]]`
+            const at = { note, target, text, occurrence };
 
             if (!isAddress(target)) {
                 deadAddresses.push({ ...at, reason: "not-an-address" });
@@ -722,10 +691,23 @@ export function auditLinks(index) {
             if (index.resolveAddress(target)) continue;
             // A manifest answers with the target package's own build output
             // rather than a reviewed guess.
-            if (manifestHit(target)) {
+            const hits = index.foreignHits(target);
+            if (hits.length === 1) {
                 usedManifest.add(target.toLowerCase());
                 continue;
             }
+            if (hits.length > 1) {
+                // Two packages publish the short address, so it names neither.
+                // Reported as its own class: "no document has that identity" is
+                // false here — two do — and the fix is the qualified form
+                // rather than a corrected shortcode (#184).
+                deadAddresses.push({
+                    ...at,
+                    reason: "ambiguous",
+                    packages: hits.map((h) => h.package).filter(Boolean),
+                });
+                continue;
+            }
             const read = readQualifier(target, index.types, index.packages);
             deadAddresses.push({
                 ...at,
@@ -737,8 +719,7 @@ export function auditLinks(index) {
     return {
         deadAnchors,
         deadAddresses,
-        deadAliases,
-        aliasCollisions: index.aliasCollisions,
+        unlabelledLinks,
         frontmatterLinks: index.frontmatterLinks,
         homepageLinks: auditHomepageLinks(index),
         usedManifest,
@@ -793,8 +774,8 @@ export function walkReachability(index, { root, scope, stopAt = () => false }) {
         const note = queue.shift();
         if (stopAt(note)) continue;
         for (const { target, labelled } of index.linksOf(note)) {
-            if (!target) continue;
-            const dest = index.resolve(note, target, labelled);
+            if (!target || !labelled) continue;
+            const dest = index.resolve(target);
             if (!dest || !scope(dest) || reached.has(dest)) continue;
             reached.add(dest);
             queue.push(dest);

package/engine/content-lint.mjs

@@ -41,9 +41,9 @@
  * its own `type-shortcode` address in the top-level `aliases:` list. That
  * served exactly one reader — **Obsidian**, so `[[type-shortcode]]` resolved in
  * the editor — and nothing else ever read it: both resolvers parse the hyphen
- * qualifier themselves, and the alias list feeds only the bare-alias fallback
- * index. The project no longer authors in Obsidian, so the rule required a line
- * of frontmatter per note for a reader that does not exist. Removing it was
+ * qualifier themselves. The project no longer authors in Obsidian, so the rule
+ * required a line of frontmatter per note for a reader that does not exist. The
+ * field itself is retired now (#180), refused from `retired-fields.mjs`. Removing it was
  * verified output-neutral beforehand: across 1,735 stripped notes,
  * `package compile` produced byte-identical `build/packs-json` and the site
  * build byte-identical `site/content`.
@@ -178,13 +178,17 @@ export function lintContentTree(contentBase, { skipDirectories, contentPackage }
     // green on the one state it most needs to catch.
     //
     // The state that catches is an **empty walk**, not an empty key set (#77).
-    // A note may be keyless by design: a homepage carries no `shortcode`
-    // because it is addressed by the package rather than by a slug, so a
-    // package in `publish.site: homepage` mode has a content tree that is
-    // populated, correct, and permanently unkeyed. Reporting that as a missing
-    // checkout trains its author to stop reading the output — the one thing
-    // this guard needs them to do. A tree holding notes is therefore a tree;
-    // only a tree holding none is the absent one.
+    // Notes may be keyless: a folder document carries no `shortcode`, and a
+    // tree of them is populated, correct, and unkeyed. Reporting that as a
+    // missing checkout trains its author to stop reading the output — the one
+    // thing this guard needs them to do. A tree holding notes is therefore a
+    // tree; only a tree holding none is the absent one.
+    //
+    // The homepage used to be the headline example, because it was addressed
+    // by the package rather than by a slug — so a `publish.site: homepage`
+    // package had a tree with exactly one note and no key at all. It carries an
+    // address like every other note now (#182); the guard is unchanged, because
+    // what it reads was never the key count.
     if (notes.length === 0) {
         findings.push({
             file: path.relative(process.cwd(), contentBase) || contentBase,

package/engine/content-slug.mjs

@@ -12,50 +12,39 @@
  */
 
 /**
- * The URL segment of a content note — derived from its name.
- *
- * Content notes carry no authored `slug`: it was a hand-maintained second
- * spelling of something already determined, free to drift from the page it
- * named. The URL is derived instead.
- *
- * It is derived from the **name**, deliberately not from the `shortcode`, even
- * though `(type, shortcode)` is unique by rule and would be a tempting key. A
- * shortcode is *identity*: it is referenced from saved world data — actions,
- * cohorts, expressions, archetypes, pack lookups — so binding the public URL to
- * it would make a cosmetic URL change into a data migration. A URL is
- * presentation, and it should read like one (`/creature/nusvorroth/`, not
- * `/creature/nsvrroth/`). Renames are what a URL must survive, and they do:
- * every change appends to the legacy-URL map, which emits a redirect.
- *
- * **One normalisation, for every slug this build makes.** {@link slugify} is it.
- * Two things are layered on top of it for **document identity** only, in
- * {@link contentSlug}:
- *
- * - it must produce something, and throws when a name yields no slug;
- * - it **abbreviates** — see {@link ABBREVIATIONS}.
- *
- * Abbreviation stops at the document's own address on purpose. A heading anchor
- * is not a name the build invents: an author writes the matching key by hand —
- * a map note pins `locations.stair-foot` at a heading called *Stair Foot* — so a
- * slug that silently became `stair-ft` would break a reference nobody could
- * have predicted. The same goes for a pack filename, which is only ever read
- * back by the unpacker. Shortening either buys nothing and costs the author's
- * ability to guess the key.
- *
- * This header used to claim the opposite — that anchor slugs, filename slugs and
- * this one were deliberately separate operations. Three of them had drifted into
- * dropping non-ASCII letters instead of transliterating them, so `Kûrbúl Helm`
- * addressed a page at `kurbul-helm` while its pack file was `k-rb-l-helm` and a
- * link to a heading of the same name pointed at `#k-rb-l-helm`. Twenty-two of
- * this repository's notes were affected. That was not a design; it was three
- * copies of a regex, and the differences between them were all mistakes.
+ * One normalisation, for every slug this build makes.
+ *
+ * {@link slugify} reduces a piece of prose — a heading, a document name — to a
+ * URL-safe token. It is **not** how a page is addressed: a note's URL is its
+ * address, `type-shortcode`, derived in `engine/content-address.mjs` and
+ * touching no display string at all (#181).
+ *
+ * That used to be the other way round. This module carried a `contentSlug` that
+ * derived a page's URL from `name.full`, abbreviating it through a table of 200
+ * words so the result stayed short, and a `findSlugCollisions` to catch the two
+ * notes that would then claim one URL. Its own header justified the readability
+ * cost with a rename-survival story — *"every change appends to the legacy-URL
+ * map, which emits a redirect"* — and no such map was ever written, in this
+ * package or in any consumer. So a rename silently 404'd every existing link,
+ * a display string was load-bearing, and a uniqueness check was needed to keep
+ * it correct. An address has none of those properties, so all three went.
+ *
+ * What is left is the normalisation the rest of the build still needs, in the
+ * two places it was always right for:
+ *
+ * - **heading anchors**, where an author writes the matching key by hand — a map
+ *   note pins `locations.stair-foot` at a heading called *Stair Foot*;
+ * - **pack filenames**, read back only by the unpacker.
+ *
+ * Neither is abbreviated, and neither ever was: abbreviation existed solely to
+ * shorten a name-derived URL, so it left with it.
  *
  * What the rule does, and why:
  *
  * - **Transliterate, don't discard.** `unidecode` carries every non-ASCII letter
  *   to its ASCII sense — `æ` → `ae`, `þ` → `th`, `œ` → `oe`, `ß` → `ss`,
  *   `ö` → `o`, `¾` → `3/4`. A rule that merely strips them turns a name into
- *   punctuation.
+ *   punctuation, which is how `Kûrbúl Helm` once became `k-rb-l-helm`.
  * - **An apostrophe elides.** `’` and `'` mark a pronunciation break — a glottal
  *   stop — inside one word, so `Kenbet’Pat` is `kenbetpat`, not `kenbet-pat`.
  * - **Everything else non-alphanumeric becomes a hyphen**, collapsed and
@@ -70,31 +59,26 @@
 
 import unidecode from "unidecode";
 
-import { abbreviateTokens } from "./abbreviations.mjs";
-
 /**
- * The URL segment for one content note.
+ * The URL-safe token a piece of prose reduces to.
  *
- * The name is **transliterated** before it is reduced, so an accented character
- * is carried across rather than dropped — dropping is what turned `Nüsvōrroth`
- * into `n-sv-rroth` and forced a hand-written slug. Ligatures expand the way a
- * reader would spell them out: `þ`→`th`, `æ`→`ae`, `œ`→`oe`, `ß`→`ss`, `ij`→`ij`,
- * `fi`→`fi`, and eth (`ð`) follows the Icelandic convention of a bare `d`.
+ * The text is **transliterated** before it is reduced, so an accented character
+ * is carried across rather than dropped. Ligatures expand the way a reader would
+ * spell them out: `þ`→`th`, `æ`→`ae`, `œ`→`oe`, `ß`→`ss`, `ij`→`ij`, `fi`→`fi`,
+ * and eth (`ð`) follows the Icelandic convention of a bare `d`.
  *
  * Two reductions are ours rather than the transliterator's:
  *
  * - **apostrophes are removed**, not treated as separators (`Armorer's Kit` →
- *   `armorers-kit`), matching the URLs these pages already publish at;
+ *   `armorers-kit`);
  * - **a fraction keeps its digits together** — a vulgar fraction expands to
  *   `3/4`, and the solidus would otherwise split it into `3-4`, so a slash
  *   *between digits* is closed up (`Kûrbúl ¾-Helm` → `kurbul-34-helm`).
  *
- * @param {string | undefined} name - The note's display name (`name.full`),
- *   which a malformed note may not have at all.
- * @returns {string} The URL segment (never empty).
- * @throws {Error} When there is no name, or the name carries no URL-safe
- *   characters — either way the note cannot be addressed, which is a content
- *   error rather than something to paper over with a fallback.
+ * @param {string | undefined} text - The prose to reduce.
+ * @returns {string} The token, or `""` when the text carries nothing URL-safe.
+ *   Empty is an ordinary answer here: nothing is addressed by a slug any more,
+ *   so an anchor that reduces to nothing is the caller's to judge.
  */
 export function slugify(text) {
     const raw = typeof text === "string" ? text.trim() : "";
@@ -102,10 +86,10 @@ export function slugify(text) {
     const tokens = unidecode(raw)
         .toLowerCase()
         // An apostrophe marks a pronunciation break, not a word boundary:
-        // `Kenbet\u2019Pat` is one name said with a catch in it, so it elides
+        // `Kenbet’Pat` is one name said with a catch in it, so it elides
         // rather than becoming a hyphen.
         .replace(/['\u2019]/g, "")
-        // A vulgar fraction transliterates to its digits (`\u00be` \u2192 `3/4`); the
+        // A vulgar fraction transliterates to its digits (`¾` → `3/4`); the
         // solidus between them is not a word boundary either.
         .replace(/(\d)\/(\d)/g, "$1$2")
         .split(/[^a-z0-9]+/)
@@ -113,53 +97,3 @@ export function slugify(text) {
 
     return tokens.join("-");
 }
-
-/**
- * The URL segment a content note publishes at.
- *
- * {@link slugify} with the rule that a document *must* be addressable: a note
- * that yields no slug is a content error, not something to paper over with a
- * fallback, because the alternative is a page nobody can reach.
- *
- * @param {string | undefined} name - The note's display name (`name.full`),
- *   which a malformed note may not have at all.
- * @returns {string} The URL segment (never empty).
- * @throws {Error} When there is no name, or the name carries no URL-safe
- *   characters.
- */
-export function contentSlug(name) {
-    const raw = typeof name === "string" ? name.trim() : "";
-    if (!raw) {
-        throw new Error("content note has no name, so it has no URL");
-    }
-    const normalised = slugify(raw);
-    const slug = abbreviateTokens(normalised.split("-").filter(Boolean)).join("-");
-    if (!slug) {
-        throw new Error(`name "${raw}" has no URL-safe characters, so it cannot address a page`);
-    }
-    return slug;
-}
-
-/**
- * Find pages that would publish to the same URL.
- *
- * Nothing constrains two notes in one section from sharing a name, and a
- * collision silently overwrites one page with the other. This turns it into a
- * build failure that names every claimant, so the fix is a more specific title.
- * (The content tree has no collisions today.)
- *
- * @param {Array<{sec: string, slug: string, src: string}>} pages
- * @returns {Array<{url: string, sources: string[]}>} One entry per collision, in
- *   first-claim order; empty when every URL is unique.
- */
-export function findSlugCollisions(pages) {
-    const byUrl = new Map();
-    for (const { sec, slug, src } of pages) {
-        const url = `/${sec}/${slug}/`;
-        if (!byUrl.has(url)) byUrl.set(url, []);
-        byUrl.get(url).push(src);
-    }
-    return [...byUrl.entries()]
-        .filter(([, sources]) => sources.length > 1)
-        .map(([url, sources]) => ({ url, sources }));
-}

package/engine/diagnostics.mjs

@@ -181,16 +181,27 @@ export function positionInBody(body, offset, { bodyLine = 1, bodyColumn = 1, lin
  * a line of prose — sending the reader to a position that is not the problem,
  * which is the one thing the located form exists to prevent.
  *
+ * The key match tolerates leading whitespace by default, so a nested key of the
+ * same name answers when no top-level one is present — which is usually what a
+ * reader wants, the key being unique in nearly every note. Pass `topLevel` where
+ * it is not: `aliases` is both a retired top-level field and a **permitted**
+ * `name.aliases` (#180), and a finding about the first must never open on the
+ * second, which would tell an author to delete a field they are allowed to
+ * write.
+ *
  * @param {string} raw - The file's full contents, frontmatter included.
  * @param {string} key - The top-level frontmatter key.
  * @param {string} [value] - When given, prefer the occurrence whose line also
  *   carries this text. A list-valued key (`aliases`) is reported at the entry
  *   that is wrong, not at the key that introduces it.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
+ *   an identically named nested key cannot answer for it.
  * @returns {{line?: number, column?: number}} Spreadable position fields, empty
  *   when the key cannot be located — dropped rather than guessed, as
  *   {@link formatDiagnostic} requires.
  */
-export function positionInFrontmatter(raw, key, value = undefined) {
+export function positionInFrontmatter(raw, key, value = undefined, { topLevel = false } = {}) {
     if (typeof raw !== "string" || !key) return {};
     const fence = raw.match(/^---\n([\s\S]*?)\n---/);
     if (!fence) return {};
@@ -205,7 +216,10 @@ export function positionInFrontmatter(raw, key, value = undefined) {
             keyLine = i;
             break;
         }
-        if (keyLine === -1 && new RegExp(`^\\s*${escape(key)}\\s*:`).test(lines[i])) {
+        if (
+            keyLine === -1 &&
+            new RegExp(`^${topLevel ? "" : "\\s*"}${escape(key)}\\s*:`).test(lines[i])
+        ) {
             keyLine = i;
             if (wanted == null) break;
         }