@heroiclands/package-build 10.0.1 → 11.1.0

package/engine/content-address.mjs

@@ -18,9 +18,17 @@
  * knowledgebase build renders the page, and the link manifest records the
  * address other packages link to. Stating it twice is how a manifest comes to
  * assert a URL that resolves at build time and 404s for the reader.
+ *
+ * **A page's URL is its address** — `<package>/<type>-<shortcode>/` (#181). It
+ * used to be derived from `name.full`, which made a display string load-bearing
+ * in three separate ways: a rename moved the URL and nothing redirected, two
+ * notes in one section could derive the same URL so a uniqueness check had to
+ * run, and a long name had to be abbreviated through a word table to keep the
+ * result short. `(type, shortcode)` is unique within a package by rule
+ * (`engine/content-lint.mjs`), so the address is **unique by construction** —
+ * there is no check to run, and no rename to survive.
  */
 
-import { contentSlug } from "./content-slug.mjs";
 // The scheme vocabulary is part of the configuration contract — a
 // repository names its scheme in `package-build.config.yaml` — so it is
 // declared beside the rest of that vocabulary rather than here, and this
@@ -49,22 +57,54 @@ export function sectionOf(fm) {
 }
 
 /**
- * A note's address below the knowledgebase mount, e.g. `affliction/aconite/`.
+ * The single path segment a note is addressed by: `type-shortcode`.
+ *
+ * Lowercased, so it is exactly the tail of the note's canonical key
+ * (`canonicalKey` in `engine/kb-manifest.mjs` lowercases too) — which is what
+ * makes a manifest entry's `path` derivable from the key it is filed under
+ * rather than transported beside it.
+ *
+ * The hyphen is a separator and never occurs inside a segment: a shortcode is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced by `content-lint.mjs`)
+ * and a type is a bare word. That is the same charset guarantee positional key
+ * parsing rests on, so the address and the key cannot disagree about where one
+ * ends and the other begins.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string} The address segment, e.g. `weapongear-dagger`.
+ * @throws {Error} When the note declares no type or no shortcode — either way
+ *   it has no address, which is reported rather than papered over: inventing
+ *   one would publish a page nothing can link to and record a manifest entry
+ *   pointing at it.
+ */
+export function addressSlug(fm) {
+    const type = typeof fm?.type === "string" ? fm.type.trim() : "";
+    if (!type) {
+        throw new Error("note declares no type, so it has no address");
+    }
+    const shortcode = typeof fm?.shortcode === "string" ? fm.shortcode.trim() : "";
+    if (!shortcode) {
+        throw new Error(
+            `note declares no shortcode, so it has no address — a page is ` +
+                `addressed as "${type}-<shortcode>"`,
+        );
+    }
+    return `${type}-${shortcode}`.toLowerCase();
+}
+
+/**
+ * A note's address below the knowledgebase mount, e.g. `affliction-aconite/`.
  *
  * A `README.md` **is** its section's landing page rather than a page within it,
- * so it addresses the section itself and has no slug of its own.
+ * so it addresses the section itself and has no address of its own.
  *
  * @param {object} fm - Parsed frontmatter.
- * @param {string} name - The note's display name; the slug derives from it
- *   (#1278), never from the shortcode, which is identity rather than
- *   presentation.
  * @param {boolean} isReadme - Whether the file is a `README.md`.
- * @returns {string} The section-relative address, with a trailing slash.
- * @throws {Error} When the name yields no usable slug.
+ * @returns {string} The mount-relative address, with a trailing slash.
+ * @throws {Error} When the note has no address.
  */
-export function contentAddress(fm, name, isReadme) {
-    const sec = sectionOf(fm);
-    return isReadme ? `${sec}/` : `${sec}/${contentSlug(name)}/`;
+export function contentAddress(fm, isReadme) {
+    return isReadme ? `${sectionOf(fm)}/` : `${addressSlug(fm)}/`;
 }
 
 /**
@@ -92,17 +132,30 @@ function landingOf(fm, isReadme, landing) {
 }
 
 /**
- * A note's address relative to its **package**, e.g. `kb/affliction/aconite/`.
+ * A note's address relative to its **package**, e.g. `affliction-aconite/`.
  *
  * This is the form the link manifest records and the site build emits pages at,
  * and it is one function because those two must agree — a manifest asserting an
  * address the site does not publish resolves at build time and 404s for the
  * reader, which is the failure this module exists to prevent.
  *
+ * **The prefix does not apply to a page's own address.** `prefix` says where the
+ * content tree *mounts inside the package* — where its section directories and
+ * their landing pages live — and a landing page is addressed by that mount
+ * (`kb/rules/`). An ordinary page is addressed by `(type, shortcode)`, which is
+ * a package-wide identity and takes no mount: `sohl` publishes
+ * `/sohl/affliction-aconite/` while its section landings stay at
+ * `/sohl/kb/affliction/`. The `type-` half is what keeps that flat namespace
+ * clear of the package's fixed mounts — `/<package>/` for the landing,
+ * `/<package>/api/` for generated API docs, neither of which contains a hyphen
+ * or names a type.
+ *
+ * **The section still decides where the *file* is written**, which is why a
+ * note without one still has no address: Hugo derives a section from a page's
+ * directory rather than from its URL, so a page with nowhere to be filed is a
+ * page with no section landing, no `.CurrentSection` and no per-section layout.
+ *
  * @param {object} fm - Parsed frontmatter.
- * @param {string} name - The note's display name; a page slug derives from it
- *   (#1278), never from the shortcode, which is identity rather than
- *   presentation.
  * @param {object} [options] - Options.
  * @param {boolean} [options.isReadme] - Whether the file is a `README.md`.
  * @param {{prefix?: string, landing?: string}} [options.scheme] - The
@@ -110,11 +163,11 @@ function landingOf(fm, isReadme, landing) {
  * @returns {string} The package-relative address, with a trailing slash and no
  *   leading one.
  * @throws {Error} When the note has no address — no section, a landing page
- *   naming no section, or a name yielding no usable slug. Each is a note that
+ *   naming no section, or no shortcode to be addressed by. Each is a note that
  *   is not published, and inventing an address for one would put a dead entry
  *   in the manifest.
  */
-export function packageAddress(fm, name, { isReadme = false, scheme } = {}) {
+export function packageAddress(fm, { isReadme = false, scheme } = {}) {
     const { prefix, landing } = { ...DEFAULT_ADDRESS_SCHEME, ...scheme };
     if (!LANDING_RULES.includes(landing)) {
         throw new Error(
@@ -133,5 +186,5 @@ export function packageAddress(fm, name, { isReadme = false, scheme } = {}) {
     if (typeof sec !== "string" || !sec) {
         throw new Error(`type "${fm.type}" has no section`);
     }
-    return `${prefix}${sec}/${contentSlug(name)}/`;
+    return `${addressSlug(fm)}/`;
 }

package/engine/content-format-check.mjs

@@ -269,7 +269,7 @@ function nearest(key, candidates) {
  * @type {ReadonlySet<string>}
  */
 export const NOTE_LEVEL_KEYS = Object.freeze(
-    new Set(["id", "type", "subType", "shortcode", "description", "tags", "name", "aliases"]),
+    new Set(["id", "type", "subType", "shortcode", "description", "tags", "name"]),
 );
 
 /** Whether a value is a plain object a block could be written as. */

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,