@heroiclands/package-build 10.0.1 → 11.1.0

package/engine/homepage.mjs

@@ -47,18 +47,27 @@
  * type living in the SoHL registry would be unavailable to HM3 and to every HM3
  * module, which is most of the packages that need a homepage and nothing else.
  *
- * **Its address is the package's, not the note's.** A homepage publishes at
- * `/<contentPackage>/` because that is where the package is, so `name.full`,
- * `shortcode` and `id` decide nothing on it — nothing here reads them, and
- * {@link HOMEPAGE_REFUSED_FIELDS} refuses them outright rather than leaving an
- * author to believe they worked (#53). It compiles into no document, so it carries
- * no compendium UUID and appears in no pack and in no link-manifest entry.
+ * **Addressed like every other note.** A homepage declares a `shortcode` —
+ * conventionally {@link HOMEPAGE_SHORTCODE} — and publishes at its address,
+ * `/<package>/<type>-<shortcode>/`, written by the same rule as everything else
+ * (#182). It used to publish at `/<package>/` from a fixed destination, and
+ * that is why it refused `name` and `shortcode`: a URL derived from `name.full`
+ * while the destination did not, so `[[homepage-<shortcode>]]` resolved *green*
+ * to a page nothing wrote. A page's URL is its address now (#181), so the
+ * computed address is the published one and there is nothing left to refuse.
+ * The package's own `/<package>/` becomes a redirect its repository authors —
+ * see `CONTENT.md` — rather than a page this build writes.
+ *
+ * `id` is still refused, on ground the change does not touch: a homepage
+ * compiles into no document, so it carries no compendium UUID and appears in no
+ * pack and in no link-manifest entry.
  *
  * @module
  */
 
 import fs from "node:fs";
 
+import { addressSlug } from "./content-address.mjs";
 import { matchAllOutsideCode } from "./code-fences.mjs";
 import { formatLocator, positionInFrontmatter } from "./diagnostics.mjs";
 
@@ -74,23 +83,44 @@ export const HOMEPAGE_TYPE = "homepage";
  *
  * Empty on purpose, and declared rather than omitted: a type with no vocabulary
  * and a type that is unknown are different findings, and only the second is an
- * authoring error. The whole envelope is the two top-level keys `type` and an
- * optional `title`; there is no game-system data on a page that compiles to no
- * document.
+ * authoring error. The whole envelope is the top-level keys `type` and
+ * `shortcode`, plus an optional `title` or `name`; there is no game-system data
+ * on a page that compiles to no document.
  *
  * @type {readonly import("./field-spec.mjs").FieldSpec[]}
  */
 export const HOMEPAGE_FIELDS = Object.freeze([]);
 
 /**
- * Where a homepage is written, relative to the package's site root.
+ * The shortcode a package landing conventionally takes.
  *
- * Hugo's section landing, because the page *is* the package's landing: the
- * package root is a section and this is its index.
+ * A **convention, not a rule.** The address only has to be unique within the
+ * package, which `(type, shortcode)` already guarantees, and nothing here knows
+ * better than an author what their landing is called. What the constant buys is
+ * one spelling shared by the diagnostic, the documentation and the six trees —
+ * so `[[homepage-root|…]]` is the same link in every package.
  *
  * @type {string}
  */
-export const HOMEPAGE_DESTINATION = "_index.md";
+export const HOMEPAGE_SHORTCODE = "root";
+
+/**
+ * The file a homepage is written to, relative to the package's site root.
+ *
+ * Its **address**, flat at the package root, and stated in the page's own `url`
+ * — the same separation every other page has since #181, where the directory
+ * decides the Hugo section and the front matter decides the URL. Flat rather
+ * than inside a `homepage/` section directory, because a homepage is not one of
+ * a kind: a section holding exactly one page would publish a landing at
+ * `/<package>/kb/homepage/` that nothing links to and nobody wrote.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string} The destination filename, e.g. `homepage-root.md`.
+ * @throws {Error} When the note declares no shortcode, and so has no address.
+ */
+export function homepageDestination(fm) {
+    return `${addressSlug(fm)}.md`;
+}
 
 /**
  * Whether a note's frontmatter declares the homepage type.
@@ -103,58 +133,33 @@ export function isHomepage(fm) {
 }
 
 /**
- * The top-level fields a homepage refuses, and what each one would decide (#53).
- *
- * A note's URL derives from `name.full` and its identity from
- * `(type, shortcode)`. The homepage is the one page for which neither holds: it
- * publishes at `/<package>/`, fixed by the package id. An author fluent in the
- * conventions writes them here expecting exactly what they do everywhere else,
- * and gets none of it.
- *
- * **They were never inert, which is why ignoring them was the wrong answer.** A
- * `shortcode` puts the note in the address index and in the `dataview` link
- * universe, so `[[homepage-<shortcode>]]` resolves *green* — to
- * `homepage/<slug>/`, an address derived from `name.full` and published by
- * nothing, because a homepage is written to {@link HOMEPAGE_DESTINATION} at the
- * package root. A build that reports a live link to a 404 is worse than one
- * that says nothing. It also inflates `content-build lint`'s address tally, so
- * the lint and the link manifest disagree about what the package publishes.
- *
- * **A named class, not an allow-list, and that boundary is the decision.** The
- * documented envelope is `type` plus an optional `title`, and `landing`,
- * `description` and `banner` are legitimate beside them — but a homepage's
- * frontmatter is *emitted into the published page*
+ * The top-level field a homepage refuses, and what it would decide (#53).
+ *
+ * **One field, where there used to be three.** `name` and `shortcode` were
+ * refused because a page's URL derived from `name.full` while a homepage's
+ * destination was fixed, so the address a `shortcode` computed named a page the
+ * site build never wrote. A page's URL is its address now (#181) and a homepage
+ * publishes at its own, so both fields decide exactly what they decide
+ * everywhere else and are permitted (#182).
+ *
+ * `id` is untouched by that, and stays: it is the Foundry document id a
+ * compendium UUID is built from, and a homepage compiles into no document.
+ *
+ * **A named class, not an allow-list, and that boundary is the decision.** A
+ * homepage's frontmatter is *emitted into the published page*
  * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
  * parameter this build has never heard of and has no standing to refuse.
  * Rejecting unknown keys would make every new theme parameter wait on a
- * package-build release. What is refused is the specific class that makes a
- * false claim about *where this page is*.
+ * package-build release.
  *
- * `aliases` is deliberately not in the class: {@link homepageFrontmatter}
- * already drops it from every emitted page, with a reason of its own, so
- * authoring one is the same no-op it is on any other page rather than a wrong
- * belief about this one's address.
+ * `aliases` is deliberately not in the class: it is a **retired** field, refused
+ * on every note whatever its type (#180), so it is answered there rather than
+ * here.
  *
  * @type {ReadonlyMap<string, string>}
  */
 export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
     new Map([
-        [
-            "name",
-            "`name` decides nothing on a `type: homepage` note: a page's slug " +
-                "derives from `name.full`, and a homepage's destination is " +
-                `fixed — it is written to \`${HOMEPAGE_DESTINATION}\` at the ` +
-                "package's own address, `/<package>/`. Write `title:` for what " +
-                "the page is called, and delete `name`",
-        ],
-        [
-            "shortcode",
-            "`shortcode` decides nothing on a `type: homepage` note: this " +
-                "page's address is the package's own, `/<package>/`, fixed by " +
-                "the package id. It is not ignored either — it puts the note " +
-                "in the address index, so `[[homepage-<shortcode>]]` resolves " +
-                "to a page the site build never writes. Delete it",
-        ],
         [
             "id",
             "`id` decides nothing on a `type: homepage` note: it is the " +
@@ -166,30 +171,54 @@ export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
 );
 
 /**
- * The address-bearing fields one note authors, in the order it authored them.
+ * What the address rule says about one note's top-level fields.
  *
- * Authoring order rather than declaration order, so a caller emitting one
- * diagnostic per finding emits them top to bottom down the file — the order a
- * reader and a compiler-output parser both expect.
+ * Two statements about the same thing, so they are made together: the field a
+ * homepage **owes** and the field it may **not** write.
  *
- * Presence is the whole test: `shortcode:` authored empty still says "this page
- * has an address of its own", and a value cannot make the claim true.
+ * The missing `shortcode` comes first, and is located at `type:` rather than at
+ * a key that is not there — the `homepage` value is what makes the field
+ * required, it is a real position in the file, and inventing a `1:1` for an
+ * absent key would put the author on the opening fence. The refused fields
+ * follow in the order the note authored them, so a caller emitting one
+ * diagnostic per finding walks down the file.
  *
- * Returned without a locator, because the two things that would supply one —
- * the raw note text and the position helper — belong to the caller. This
- * mirrors {@link module:engine/retired-fields}, whose retired-field messages
- * are likewise positioned by whoever reports them.
+ * Presence is the whole test for a refused field, and absence-or-blank for the
+ * required one: `shortcode:` authored empty is no address, and a value cannot
+ * make `id` mean something on a page that compiles to no document.
+ *
+ * Each finding carries the `locator` key to position it at, because the two
+ * things that would resolve one — the raw note text and the position helper —
+ * belong to the caller. This mirrors {@link module:engine/retired-fields},
+ * whose retired-field messages are likewise positioned by whoever reports them.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {Array<{key: string, message: string}>} One entry per field the note
- *   authored, empty for any note that is not a homepage.
+ * @returns {Array<{field: string, locator: {key: string, literal?: string},
+ *   message: string}>} One entry per finding, empty for any note that is not a
+ *   homepage and declares nothing wrong.
  */
 export function checkHomepageAddressFields(fm) {
     if (!isHomepage(fm)) return [];
     const out = [];
+
+    const shortcode = typeof fm.shortcode === "string" ? fm.shortcode.trim() : "";
+    if (!shortcode) {
+        out.push({
+            field: "shortcode",
+            locator: { key: "type", literal: HOMEPAGE_TYPE },
+            message:
+                "a `type: homepage` note declares a `shortcode`, like every " +
+                "other note: it is addressed as `homepage-<shortcode>` and " +
+                "published at `/<package>/homepage-<shortcode>/`, which is " +
+                "where `[[homepage-<shortcode>|Text]]` lands. Write " +
+                `\`shortcode: ${HOMEPAGE_SHORTCODE}\` — the package landing is ` +
+                `\`homepage-${HOMEPAGE_SHORTCODE}\` in every package`,
+        });
+    }
+
     for (const key of Object.keys(fm)) {
         const message = HOMEPAGE_REFUSED_FIELDS.get(key);
-        if (message) out.push({ key, message });
+        if (message) out.push({ field: key, locator: { key }, message });
     }
     return out;
 }
@@ -203,12 +232,16 @@ export function checkHomepageAddressFields(fm) {
  * - _None_ and the package serves nothing at `/<package>/`. That is the failure
  *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
  *   homepage(s)` and exits 0.
- * - _Two_ and it serves a page nobody chose. Every homepage is written to the
- *   same {@link HOMEPAGE_DESTINATION}, so the second overwrites the first and
- *   the package's front page is decided by the order the walk happened to reach
- *   the files in — by *filename*, on a type whose whole point is that it is
- *   routed by frontmatter. There is no "first wins" convention to fall back on,
- *   so nothing here can pick the right one.
+ * - _Two_ and it serves a page nobody chose. **This is a cardinality rule, and
+ *   since #182 it is only that.** It used to rest on the fixed destination
+ *   every homepage shared — the second overwrote the first — so the address
+ *   rule enforced it as a side effect. A homepage is written at its own address
+ *   now, so two of them publish two pages and collide over nothing; the
+ *   duplicate-address check catches only the pair that happen to share a
+ *   shortcode, and says nothing at all about a `homepage-root` beside a
+ *   `homepage-front`. Which of the two the redirect at `/<package>/` should
+ *   name is a question nothing here can answer, and both being reachable is
+ *   not an answer to it.
  *
  * Neither has a safe default, so neither is a warning. A warning is the right
  * severity for something a build can proceed past correctly, and a build that
@@ -270,9 +303,10 @@ export function checkHomepageCount(found, { contentBase, contentPackage }) {
             message:
                 `duplicate \`type: homepage\` note, also declared by ` +
                 `${others.join(", ")}; a package has one front page` +
-                `${contentPackage ? `, at${address},` : ""} and every ` +
-                `homepage is written to the same \`${HOMEPAGE_DESTINATION}\` — ` +
-                `so the one the walk reaches last silently overwrites the rest`,
+                `${contentPackage ? `, at${address}` : ""}, and each of these ` +
+                `publishes at an address of its own — so nothing here can say ` +
+                `which one that address should redirect to. Keep one, and make ` +
+                `the rest ordinary notes`,
         };
     });
 }
@@ -325,24 +359,35 @@ export function homepageTitle(fm, config) {
 /**
  * The frontmatter a homepage publishes with.
  *
- * The note's own, plus the two derived values every emitted page carries: the
- * resolved `title`, and the package the build derived — no note declares one
+ * The note's own, plus the derived values every emitted page carries: the
+ * resolved `title`, the package the build derived — no note declares one
  * (`package:` is retired, #56) and the theme's breadcrumb partial reads
- * `.Params.package`.
+ * `.Params.package` — and its **address**.
+ *
+ * The address is stated as `url` for the same reason every other page states
+ * one (#181): Hugo publishes a page where its file sits unless told otherwise,
+ * and a homepage's file sits at the package's site root. `slug` is written
+ * beside it because it is the last segment of that address and Hugo's own key
+ * for one; it decides nothing while `url` is present, but a page carrying only
+ * `url` would report a slug Hugo had inferred from the filename.
  *
  * An authored `aliases` is dropped for the same reason it is on every other
- * page: Obsidian reads it as names a reader might call the note, Hugo reads it
- * as URL redirects, and passing it through would publish a redirect stub at
- * each one.
+ * page: Hugo reads it as URL redirects, so passing it through would publish a
+ * redirect stub at each one. The field is retired (#180) and refused before a
+ * build reaches here, which makes this a guard rather than a working path.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
+ * @param {string} options.base - Where the package is served, with both
+ *   slashes — `/<package>/`.
  * @returns {object} The frontmatter to write.
+ * @throws {Error} When the note declares no shortcode, and so has no address.
  */
-export function homepageFrontmatter(fm, { contentPackage, title }) {
-    const data = { ...fm, package: contentPackage, title };
+export function homepageFrontmatter(fm, { contentPackage, title, base }) {
+    const slug = addressSlug(fm);
+    const data = { ...fm, package: contentPackage, title, slug, url: `${base}${slug}/` };
     delete data.aliases;
     return data;
 }

package/engine/index.mjs

@@ -77,10 +77,10 @@ export * as noteVocabulary from "./note-vocabulary.mjs";
 
 /** The shipped Foundry manifest: locating it, reading it, guarding its id. */
 
-/** The URL a content note is published at — the one web-address rule. */
+/** The one normalisation this build makes: prose to a URL-safe token. */
 export * as contentSlug from "./content-slug.mjs";
 
-/** Section and address derivation on top of {@link contentSlug}. */
+/** Where a content note publishes: its section, and its `type-shortcode` URL. */
 export * as contentAddress from "./content-address.mjs";
 
 /** Whether a vendored manifest can still be addressed, not merely read. */
@@ -125,9 +125,6 @@ export * as wikilinks from "./wikilinks.mjs";
 /** What a `[[…]]` is, before either resolver decides where it points. */
 export * as wikilinkSyntax from "./wikilink-syntax.mjs";
 
-/** The alias namespace: what a note may be called, and who may claim a name. */
-export * as aliasIndex from "./alias-index.mjs";
-
 /** The address index a site build resolves its wikilinks against. */
 export * as siteIndex from "./site-index.mjs";
 

package/engine/manifest-emit.mjs

@@ -29,11 +29,20 @@
  * start, by {@link packageAddress}, and the emitting build's mount point is not
  * a fact it has to be told (#1465).
  *
+ * **An entry's `path` is derivable from the key it is filed under** (#181).
+ * `sohl-affliction-aconite` publishes at `affliction-aconite/`, because a page's
+ * URL *is* its address; nothing in it comes from a display name, so a rename
+ * moves no URL and no uniqueness check stands between the two. The field is
+ * still written rather than left for a consumer to compute, because a landing
+ * page is the one entry that is not derivable — it addresses its section under
+ * the configured mount — and because an absent `path` already means something
+ * else entirely (a package that publishes no pages).
+ *
  * **The address scheme is configuration, and it is shared with the site build.**
  * Where the content tree mounts inside the package and which note is a section's
  * landing page differ between repositories and are both load-bearing — `sohl`
- * records `kb/affliction/aconite/` and `thalorna` records
- * `affiliation/the-aerarium-imperii/`. Reading one setting here and in the page
+ * records `kb/rules/` for the landing of its rules section and `thalorna`
+ * records `affiliation/` for its own. Reading one setting here and in the page
  * emitter is what stops a manifest asserting an address the site does not
  * publish, which resolves at build time and 404s for the reader.
  *
@@ -54,8 +63,9 @@ import { canonicalKey, writeManifests } from "./kb-manifest.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { compendiumUuid, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
+import { isHomepage } from "./homepage.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
-import { assertNoDraftField } from "./retired-fields.mjs";
+import { assertNoAliasesField, assertNoDraftField } from "./retired-fields.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
@@ -222,14 +232,23 @@ export function collectManifestEntries(contentBase, ctx) {
             configured: ctx.contentPackage,
         });
         assertNoDraftField(fm, { file: rel, absPath });
+        assertNoAliasesField(fm, { file: rel, absPath });
         if (!fm.type || !fm.shortcode) continue;
+        // A homepage is addressed like every other note since #182, and a
+        // shortcode alone would now put it here. It stays out for the reason it
+        // always did, which that change does not touch: a manifest entry is how
+        // another package resolves a **document**, and a homepage compiles into
+        // none — the same ground `id` is refused on. A cross-package link to a
+        // package's front page is its bare `/<package>/` address, which needs
+        // no index.
+        if (isHomepage(fm)) continue;
 
         const base = path.basename(absPath);
         const name = fm.name?.full ?? path.basename(absPath, ".md");
 
         let address;
         try {
-            address = packageAddress(fm, name, {
+            address = packageAddress(fm, {
                 isReadme: base.toLowerCase() === "readme.md",
                 scheme: ctx.scheme,
             });

package/engine/note-vocabulary.mjs

@@ -206,6 +206,21 @@ const CHARGES = Object.freeze([
  * fishing village is a `village` that is `fishing`, and the single-valued field
  * this replaced had to spell it `Fishing Village` as a value of its own.
  */
+/**
+ * The declared tag that marks a note as **unfinished** (#183).
+ *
+ * Named once and referenced from the declaration below, because a second
+ * spelling is how the two come apart: rename the tag in `DECLARED_TAGS` and a
+ * private copy elsewhere keeps matching the old word, silently.
+ *
+ * It is a **presentation** fact and nothing more. A draft note compiles,
+ * validates, publishes and resolves like any other; only a link *into* it
+ * renders marked. What it emphatically is not is the retired `draft:` field,
+ * whose entire effect was to move a note from published to unresolvable — see
+ * {@link draftRetiredMessage}.
+ */
+export const DRAFT_TAG = "draft";
+
 export const DECLARED_TAGS = Object.freeze({
     /** What a place *is*. */
     placeKind: Object.freeze({
@@ -287,7 +302,7 @@ export const DECLARED_TAGS = Object.freeze({
         ]),
     }),
     /** A note's working state, which any note may carry. */
-    state: Object.freeze({ types: null, tags: Object.freeze(["draft"]) }),
+    state: Object.freeze({ types: null, tags: Object.freeze([DRAFT_TAG]) }),
 });
 
 /**
@@ -302,6 +317,48 @@ export function declaredTags(type, groups = DECLARED_TAGS) {
     return Object.freeze(applies.flatMap((g) => g.tags));
 }
 
+/**
+ * Whether a note carries a given tag, however the author wrote it.
+ *
+ * `tags:` is authored by hand and Obsidian is permissive about it: a single tag
+ * may be a scalar rather than a list, a value may carry the leading `#` it is
+ * written with in prose, and case and surrounding space are not significant.
+ * The spelling of the tag *itself* still is — a near miss is a near miss, and
+ * the frontmatter lint is what reports it; nothing here guesses.
+ *
+ * Reads `tags` and, as Dataview does, `tag` — the singular spelling Obsidian
+ * also accepts.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} tag - The tag to look for, in its declared spelling.
+ * @returns {boolean} Whether the note carries it.
+ */
+export function hasTag(fm, tag) {
+    const raw = fm?.tags ?? fm?.tag;
+    if (raw == null) return false;
+    const wanted = String(tag).toLowerCase();
+    for (const entry of Array.isArray(raw) ? raw : [raw]) {
+        if (typeof entry !== "string") continue;
+        if (entry.trim().replace(/^#/, "").toLowerCase() === wanted) return true;
+    }
+    return false;
+}
+
+/**
+ * Whether a note is tagged as an unfinished **draft** (#183).
+ *
+ * The one reader of {@link DRAFT_TAG}, so both builds ask the same question of
+ * the same field. Presentation only: a draft note is in the packs, in the
+ * manifest and on the site exactly as any other, and this decides nothing but
+ * whether a link into it renders marked.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether the note carries the `draft` tag.
+ */
+export function isDraftNote(fm) {
+    return hasTag(fm, DRAFT_TAG);
+}
+
 export const NOTE_VOCABULARY = Object.freeze({
     /* ----- actors --------------------------------------------------- */
 

package/engine/retired-fields.mjs

@@ -22,8 +22,9 @@
  * says what to write instead rather than which value to correct.
  *
  * `package:` is retired the same way and is refused from `note-package.mjs`,
- * where the concept it belonged to still lives. `draft:` has no such home —
- * there is no surviving concept it was part of — so it is refused here.
+ * where the concept it belonged to still lives. `draft:` and the top-level
+ * `aliases:` have no such home — there is no surviving concept either was part
+ * of — so they are refused here.
  *
  * **What `draft:` did (#69).** It excluded a note from the compiled packs, from
  * the link manifest and from a consuming site build. Nothing reported the
@@ -34,6 +35,20 @@
  * *unresolvable*, silently — and it also suppressed real build failures, since
  * a note the compilers never reached could not fail on the defects it carried.
  *
+ * **What `aliases:` did (#180).** It fed the alias index, which is what a bare
+ * `[[Alias]]` was looked up in. That form resolved to nothing anywhere in the
+ * corpus, while the collision rule guarding it folded in every note's
+ * `name.full` and so decided what a note could be named (#179). The form and
+ * the index are retired together, leaving the field with no reader at all.
+ *
+ * **`name.aliases` fed the same index and is nonetheless kept.** It is
+ * **reserved** — held for a use that does not exist yet — so it is the one
+ * field here that is neither retired nor read. Nothing consults it: no index,
+ * no resolver, no lint rule, no emitter. A note carrying one compiles,
+ * resolves and emits exactly as if it were absent, and `tests/name-aliases-
+ * reserved.test.ts` pins that equivalence so a future reader cannot be added
+ * by accident.
+ *
  * **A field retired in favour of another is a third case (#142).** `draft:` and
  * `package:` were retired outright: nothing replaced them, so no value made
  * writing one right and refusal was the only honest answer. A *renamed* field
@@ -73,8 +88,9 @@ export function draftRetiredMessage(file) {
         ". It excluded the note from the compiled packs, the link manifest " +
         "and the site, and no checker reported the exclusion, so every " +
         "wikilink into it read as a link to a note that does not exist. To " +
-        "mark a note as unfinished, tag it `#draft` instead: the build " +
-        "ignores tags, and a `FROM #draft` query still finds it"
+        "mark a note as unfinished, tag it `#draft` instead: the note still " +
+        "compiles and publishes, a link into it renders marked, and a " +
+        "`FROM #draft` query still finds it"
     );
 }
 
@@ -109,6 +125,97 @@ export function assertNoDraftField(fm, { file, absPath } = {}) {
     throw err;
 }
 
+/**
+ * What a note declaring a top-level `aliases:` is told, in one place.
+ *
+ * Shared by the compile-time refusal and the frontmatter lint, because an
+ * author meets whichever of the two runs first and they should read the same.
+ * It says what the field fed and what to write instead, rather than which value
+ * to correct: no value makes declaring it right.
+ *
+ * **What it did (#180).** It was the authored half of the alias index — the
+ * namespace a bare `[[Alias]]` was looked up in. Across the three content trees
+ * not one bare link resolved through it, while the collision rule that kept it
+ * unambiguous folded in every note's `name.full` and so dictated what a note
+ * could be named (#179). The form is retired, so the list has no reader.
+ *
+ * **`name.aliases` is a different field and is not retired.** It fed the same
+ * index, but unlike the top-level list it is being kept — reserved, unread,
+ * and deliberately unmentioned by this message, which would otherwise tell an
+ * author to delete a field they are allowed to write. See
+ * {@link assertNoAliasesField}.
+ *
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function aliasesRetiredMessage(file) {
+    return (
+        "`aliases:` is a retired frontmatter field — delete it" +
+        (file ? ` — ${file}` : "") +
+        ". It listed names the bare `[[Alias]]` form could cite, and that " +
+        "form is retired: every wikilink is now an address, written " +
+        "`[[type-shortcode|Text]]`. Nothing else ever read the list"
+    );
+}
+
+/**
+ * Refuse a note that declares a top-level `aliases:`.
+ *
+ * Presence is the whole test. `aliases: []` is as retired as a populated one —
+ * it reads as "this note claims no other names", a statement about a namespace
+ * that no longer exists.
+ *
+ * **The nested `name.aliases` is deliberately not refused.** Both spellings fed
+ * the retired alias index, and both lost their reader with it, but only the
+ * top-level one is retired: `name.aliases` is **reserved**, held for a use that
+ * does not exist yet. So it is neither refused nor read — no index consults it,
+ * no rule validates its contents, nothing derives from it, and nothing emits
+ * it. It rides in the note as inert data, and a note carrying one compiles,
+ * resolves and emits exactly as if it were absent.
+ *
+ * That distinction is the reason this checks `Object.hasOwn(fm, "aliases")`
+ * rather than resolving a dotted key: the top-level field is the whole subject,
+ * and reaching into `name` at all is the thing being avoided.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note declares a top-level `aliases`.
+ */
+export function assertNoAliasesField(fm, { file, absPath } = {}) {
+    if (!declaresRetiredAliasesField(fm)) return;
+
+    const err = new Error(`${aliasesRetiredMessage(file)}.`);
+    // Anchored at column 1: a permitted `name.aliases` writes the same key,
+    // indented, and a finding about the retired top-level field must never
+    // open on it.
+    const position = locateFrontmatterKey(absPath, "aliases", undefined, { topLevel: true });
+    if (position) err.position = position;
+    throw err;
+}
+
+/**
+ * Whether a note declares the retired top-level `aliases:`.
+ *
+ * A nested `name.aliases` is **not** this field and never answers true here —
+ * see {@link assertNoAliasesField} for why the two part company.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether the retired field is declared.
+ */
+export function declaresRetiredAliasesField(fm) {
+    return Boolean(fm) && typeof fm === "object" && Object.hasOwn(fm, "aliases");
+}
+
 /**
  * A frontmatter key's position in a note's file, or nothing.
  *
@@ -121,11 +228,15 @@ export function assertNoDraftField(fm, { file, absPath } = {}) {
  * @param {string} [value] - When given, prefer the occurrence whose line also
  *   carries this text — so a finding about one entry of a block opens on that
  *   entry rather than on the key that introduces it.
+ * @param {object} [options] - Options, forwarded to
+ *   {@link positionInFrontmatter}.
+ * @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}|undefined} Spreadable position
  *   fields, dropped rather than guessed when the file cannot be read or the key
  *   cannot be found — as `formatDiagnostic` requires.
  */
-export function locateFrontmatterKey(absPath, key, value = undefined) {
+export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel = false } = {}) {
     if (!absPath) return undefined;
     let raw;
     try {
@@ -133,7 +244,7 @@ export function locateFrontmatterKey(absPath, key, value = undefined) {
     } catch {
         return undefined;
     }
-    const at = positionInFrontmatter(raw, key, value);
+    const at = positionInFrontmatter(raw, key, value, { topLevel });
     return at.line === undefined ? undefined : at;
 }