@heroiclands/package-build 10.0.0 → 11.0.0

package/engine/frontmatter-lint.mjs

@@ -64,6 +64,8 @@ import { declaredTags } from "./note-vocabulary.mjs";
 import {
     RETIRED_FIELD_ALIASES,
     declaresRetiredAlias,
+    aliasesRetiredMessage,
+    declaresRetiredAliasesField,
     draftRetiredMessage,
     readAliasedField,
     retiredAliasMessage,
@@ -466,21 +468,32 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
             message: draftRetiredMessage(),
         });
     }
+    // Only the top-level `aliases` is retired. `name.aliases` writes the same
+    // key indented under `name:` and is **permitted** — reserved and unread —
+    // so both the test and the locator are anchored at column 1 (#180).
+    if (declaresRetiredAliasesField(fm)) {
+        findings.push({
+            file: note.file,
+            ...positionInFrontmatter(raw(), "aliases", undefined, { topLevel: true }),
+            severity: "error",
+            message: aliasesRetiredMessage(),
+        });
+    }
 
-    // A homepage's address is its package's, so the top-level fields that
-    // decide an address decide nothing on it (#53). Reported beside the retired
-    // fields above because it is the same kind of statement — a top-level key
-    // this note may not write — and, like them, it must survive the two early
+    // What the address rule says about a homepage's top-level fields: the
+    // `shortcode` it owes, and the `id` it may not write (#53, #182). Reported
+    // beside the retired fields above because it is the same kind of statement
+    // about the same note, and, like them, it must survive the two early
     // returns below: the finding stands whatever else the type is.
     // Tags are checked here for the same reason: a classifying tag is not a
     // type's property — `draft` belongs to any note and `village` to a place —
     // so the finding must survive the early returns below.
     findings.push(...checkTags(note, { type }));
 
-    for (const { key, message } of checkHomepageAddressFields(fm)) {
+    for (const { locator, message } of checkHomepageAddressFields(fm)) {
         findings.push({
             file: note.file,
-            ...at(key),
+            ...at(locator.key, locator.literal),
             severity: "error",
             message,
         });
@@ -642,9 +655,16 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
         // link index's own resolver, so a cross-package reference answered by a
         // vendored manifest lands exactly as the same address in a wikilink
         // would — rather than through a second, subtly different rule.
+        //
+        // **As an address, always** — which is now the only namespace there
+        // is (#180). A frontmatter reference is a bare address by construction:
+        // there is no pipe to read intent from, and the field supplies the
+        // type. The resolver once took a namespace argument, and omitting it
+        // read every `ref:` value as an alias, which `type-shortcode` never was
+        // (#176).
         if (field.ref && index && typeof value === "string" && value) {
             const target = `${field.ref}-${value}`;
-            if (!index.resolve(note, target) && !index.manifestHit(target)) {
+            if (!index.resolve(target) && !index.manifestHit(target)) {
                 findings.push({
                     file: note.file,
                     ...at(head, value),

package/engine/helpers.mjs

@@ -39,10 +39,14 @@ import { contentPackage, foundryPackageId } from "./content-package.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 import { loadForeignManifests, PACKAGE_BASE } from "./kb-manifest.mjs";
 import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
-// The alias sources every index shares (#131).
-import { aliasesOf } from "./alias-index.mjs";
+// One vocabulary of link findings, and one message per class, so the three
+// resolvers cannot word the same defect differently (#184).
+import { linkFindingMessage } from "./wikilink-syntax.mjs";
+// The declared tag vocabulary (#172), which is where `draft` is stated. Read
+// from there rather than respelt, so the tag and its one reader cannot drift.
+import { isDraftNote } from "./note-vocabulary.mjs";
 import { expandContentTables } from "./content-tables.mjs";
-import { emitDiagnostic, positionInBody } from "./diagnostics.mjs";
+import { positionInBody } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
 // registry can import them without reaching back through this one (#1504).
 // Re-exported here so every existing importer keeps its single import path.
@@ -429,7 +433,7 @@ import { assertTypeNotRetired, packForType } from "./ids.mjs";
  * @param {object} [router] - The pack router. Supplied by the calling pass so
  *   the index and the compile agree about where each note landed; defaults to
  *   this repository's own.
- * @returns {{byShortcode: Map, byAlias: Map}} From `buildWikilinkIndex`.
+ * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
 export function buildContentLinkIndex(contentBase, router = packRouter()) {
     const docs = [];
@@ -450,10 +454,11 @@ export function buildContentLinkIndex(contentBase, router = packRouter()) {
             docPack: router.resolveOrNull(fm, "JournalEntry"),
             shortcode: fm.shortcode ?? null,
             name: fm.name?.full ?? base,
-            // The shared alias sources (#131): `aliases`, `name.aliases` and
-            // `name.full`, and deliberately not the filename — see
-            // {@link aliasesOf} for what that admitted and why it went.
-            aliases: aliasesOf(fm),
+            // Whether the note is tagged `draft` (#183). Read from the tag
+            // vocabulary that declares it, and used for one thing: a link
+            // *into* this note renders marked. It takes no part in resolution,
+            // so the note is indexed, compiled and published as any other.
+            draft: isDraftNote(fm),
         });
     }
     // Packages this build links *into* but does not publish. Their manifests
@@ -500,7 +505,8 @@ export function buildContentLinkIndex(contentBase, router = packRouter()) {
  *   entry. Position is carried by `{ file, bodyLine, bodyColumn, lineMap }`,
  *   the last from {@link expandNoteTables}.
  * @returns {{markdown: string, unresolved: Array<object>}}
- * @throws {Error} On an ambiguous alias or a dead qualified address. The error
+ * @throws {Error} On any link that does not resolve — an unlabelled one, a
+ *   target that is not an address, or an address nothing publishes. The error
  *   carries `file` and `position`, so a caller reports it in the same form
  *   rather than re-deriving one.
  */
@@ -539,70 +545,27 @@ export function convertNoteWikilinks(
      * @returns {never}
      */
     const fail = (u, message) => {
-        const err = new Error(message);
+        const at = locate(u);
+        // A link this build wrote is not at any authored position, so say
+        // where it came from rather than implying an edit site.
+        const err = new Error(
+            at.generated ? `${message} Emitted by the content table on this line.` : message,
+        );
         err.file = file;
-        err.position = locate(u);
+        err.position = at;
         throw err;
     };
 
     for (const u of result.unresolved) {
-        // An ambiguous alias matched real content — twice. There is no
-        // defensible way to pick one, and the correction is mechanical: write
-        // the qualified form. So it fails rather than warning, which also puts
-        // the failure in front of whoever created the collision instead of
-        // leaving it in a log line attributed to an innocent citing note.
-        // The knowledgebase build has always treated this as fatal; agreeing
-        // means one authored note cannot get two verdicts (#13).
-        if (u.reason === "ambiguous") {
-            const claims = u.candidates ?? [];
-            const named =
-                claims.length ?
-                    claims.map((c) => `"${c.name}" (${c.type}-${c.shortcode})`).join(" and ")
-                :   "two or more notes";
-            fail(
-                u,
-                `ambiguous wikilink ${u.link} in "${name}" — claimed by ` +
-                    `${named}. Rename one alias, or address the intended one ` +
-                    `as [[type-shortcode|Text]].`,
-            );
-        }
-        // The author wrote a pipe, so they meant an address — and this target
-        // is not one. Its own message, because the correction is its own: a
-        // note *name* has to become an address, which is not the same job as
-        // fixing a shortcode that resolves nowhere (#131).
-        if (u.reason === "not-an-address") {
-            fail(
-                u,
-                `wikilink ${u.link} in "${name}" is written as an address — ` +
-                    `the "|" says so — but "${u.target}" is not one. Write ` +
-                    `[[type-shortcode|Text]], or drop the "|" to name it as ` +
-                    `an alias within this note's own type.`,
-            );
-        }
-        // A qualified address resolving nowhere is a typo, now that every
-        // linkable package is either built here or vendored (#1499) — so it
-        // fails the note rather than degrading to text. A bare alias stays a
-        // warning: it may be ordinary prose that merely looks like a link.
-        if (u.addressed) {
-            fail(
-                u,
-                `unresolved address ${u.link} in "${name}" — no package ` +
-                    `publishes it. Fix the shortcode, or re-vendor that ` +
-                    `package's manifest into assets/manifests/.`,
-            );
-        }
-        const at = locate(u);
-        emitDiagnostic({
-            file,
-            line: at.line,
-            column: at.column,
-            severity: "warning",
-            message:
-                `unresolved wikilink ${u.link} (${u.reason}) in "${name}"` +
-                // A link this build wrote is not at any authored position, so
-                // say where it came from instead of implying an edit site.
-                (at.generated ? " — emitted by the content table on this line" : ""),
-        });
+        // Every class fails, and every class is worded by the shared table
+        // (#184). The three resolvers read one authored link, so an author who
+        // ran the pack build first and the link checker second must not be told
+        // two different things about the same mistake — and a class the pack
+        // build alone knew how to describe is how they came apart before.
+        //
+        // The note's name is appended rather than woven in: the message is the
+        // defect, the name is the context this build can add.
+        fail(u, `${linkFindingMessage(u)} — in "${name}".`);
     }
     return result;
 }

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,
             });