@heroiclands/package-build 8.1.0 → 10.0.0

package/bin/content-build.mjs

@@ -39,6 +39,9 @@
  *   npx content-build package clean [pack] [entry]
  *   npx content-build docs item-fields [--out <path>] [--title <title>]
  *   npx content-build lint [root] [--no-references]
+ *   npx content-build content-format schema --schema <system>=<path>
+ *   npx content-build content-format fields [--fields <system>]
+ *   npx content-build content-format notes [root] [--strict]
  *   npx content-build links [root] [--manifests <dir>]
  *   npx content-build format [paths..] [--write]
  *   npx content-build markdown [paths..] [--fix]
@@ -59,11 +62,7 @@ import log from "loglevel";
 import prefix from "loglevel-plugin-prefix";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
-import {
-    compilePacks,
-    cleanPacks,
-    unpackPacks,
-} from "../engine/compendiums.mjs";
+import { compilePacks, cleanPacks, unpackPacks } from "../engine/compendiums.mjs";
 import { loadPackConfig } from "../engine/pack-config.mjs";
 import {
     fetchAllCatalogs,
@@ -73,6 +72,12 @@ import {
 import { renderItemFieldReference } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
+import { loadContentFormat } from "../engine/content-format.mjs";
+import {
+    checkDeclaredFields,
+    checkSchemaTargets,
+    measureCorpus,
+} from "../engine/content-format-check.mjs";
 import {
     compareFields,
     resolveSchemaArtifact,
@@ -83,9 +88,13 @@ import {
 // set — an adventure module ships skills, beings and magic swords — so no
 // consumer gets a subset (#19, #20).
 import { NOTE_SCHEMAS } from "../sohl/note-schemas.mjs";
+// The shipped declarations, so this repository can check its own specification
+// against them without standing up a consumer's configuration (#136).
+import { ITEM_FIELDS } from "../sohl/item-fields.mjs";
 // The engine's own types, merged under the registry's so the vocabulary stands
 // in a package that configures no `itemBuilders` at all (#51).
 import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
+import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { checkFormatting, lintMarkdown } from "../engine/prose-lint.mjs";
 import { emitLinkManifest } from "../engine/manifest-emit.mjs";
 import {
@@ -93,12 +102,13 @@ import {
     gatesFailed,
     formatUnaddressableFinding as formatUnaddressable,
 } from "../engine/site-build.mjs";
+import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
 import {
-    auditLinks,
-    buildLinkIndex,
-    walkReachability,
-} from "../engine/content-links.mjs";
-import { emitDiagnostic, positionOfLiteral } from "../engine/diagnostics.mjs";
+    emitDiagnostic,
+    positionInFrontmatter,
+    positionOfLiteral,
+} from "../engine/diagnostics.mjs";
+import { reportFindings } from "./report.mjs";
 import {
     readItemAddresses,
     diffItemAddresses,
@@ -107,6 +117,7 @@ import {
     addressFindingMessage,
 } from "../engine/address-diff.mjs";
 import { itemPackJsonDirs } from "../engine/generate.mjs";
+import { walkMarkdownTree } from "../engine/helpers.mjs";
 import {
     formatUnaddressableFinding,
     unaddressableForeignPackages,
@@ -143,9 +154,7 @@ function configuredPacks() {
  * @returns {string} The `version` field of this package's manifest.
  */
 function ownVersion() {
-    return JSON.parse(
-        fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-    ).version;
+    return JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 }
 
 // Configure loglevel
@@ -176,16 +185,23 @@ prefix.apply(log, {
  */
 function reportFailure(err) {
     const message = err instanceof Error ? err.message : String(err);
-    if (/** @type {{located?: boolean}} */ (err)?.located)
-        console.error(message);
+    if (/** @type {{located?: boolean}} */ (err)?.located) console.error(message);
     else log.error(message);
 }
 
+/**
+ * The declaration sets this package ships, addressable by system id.
+ *
+ * @type {Record<string, Record<string, readonly object[]>>}
+ */
+const SHIPPED_ITEM_FIELDS = { sohl: ITEM_FIELDS };
+
 const argv = yargs(hideBin(process.argv))
     .command(packageCommand())
     .command(depsCommand())
     .command(docsCommand())
     .command(lintCommand())
+    .command(contentFormatCommand())
     .command(linksCommand())
     .command(formatCommand())
     .command(markdownCommand())
@@ -245,13 +261,11 @@ function docsCommand() {
                 choices: ["item-fields"],
             });
             yargs.option("out", {
-                describe:
-                    "Write to this file instead of the configured location.",
+                describe: "Write to this file instead of the configured location.",
                 type: "string",
             });
             yargs.option("check", {
-                describe:
-                    "Compare against the file already there; write nothing.",
+                describe: "Compare against the file already there; write nothing.",
                 type: "boolean",
                 default: false,
             });
@@ -274,13 +288,10 @@ function docsCommand() {
                 const config = loadPackConfig();
                 const spec = config.docs?.itemFields ?? {};
                 const destination =
-                    argv.out ??
-                    (spec.out ? path.resolve(config.rootDir, spec.out) : null);
+                    argv.out ?? (spec.out ? path.resolve(config.rootDir, spec.out) : null);
 
                 const page = `${renderItemFieldReference({
-                    ...((title ?? spec.title) ?
-                        { title: title ?? spec.title }
-                    :   {}),
+                    ...((title ?? spec.title) ? { title: title ?? spec.title } : {}),
                     ...(spec.preamble ? { preamble: spec.preamble } : {}),
                     generatedBy: "`content-build docs item-fields`",
                     config,
@@ -296,9 +307,7 @@ function docsCommand() {
                     }
                     const relative = path.relative(config.rootDir, destination);
                     const current =
-                        fs.existsSync(destination) ?
-                            fs.readFileSync(destination, "utf8")
-                        :   "";
+                        fs.existsSync(destination) ? fs.readFileSync(destination, "utf8") : "";
                     if (current !== page) {
                         // Staleness belongs to the whole file, so no line is
                         // named — the diagnostics contract drops a field it
@@ -321,11 +330,130 @@ function docsCommand() {
                         recursive: true,
                     });
                     fs.writeFileSync(destination, page);
+                    log.info(`Wrote ${path.relative(config.rootDir, destination)}`);
+                } else {
+                    process.stdout.write(page);
+                }
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
+/**
+ * `content-build content-format` — check the format specification itself (#130).
+ *
+ * Two checks, because the specification makes claims about two different
+ * worlds, and they fail for different reasons and at different times:
+ *
+ * - `schema` compares every `system.*` target the document names against the
+ *   naming system's published `schema.json`. A failure means the specification
+ *   and the system disagree, which is a defect in one of the two.
+ * - `fields` compares the per-type tables against the field declarations that
+ *   compile them, so the hand-written half cannot drift from the generated one
+ *   (#136).
+ * - `notes` measures a content tree against the vocabulary the document
+ *   declares per type. During #127 it is the migration's progress bar rather
+ *   than a gate, so it **reports** by default and `--strict` makes it fatal —
+ *   turned on one class at a time as each slice lands.
+ *
+ * Both read the committed document rather than a transcription of it, so
+ * editing `docs/content-format.md` changes what they assert.
+ *
+ * @returns {object} The yargs command module.
+ */
+// eslint-disable-next-line
+function contentFormatCommand() {
+    return {
+        command: "content-format <action>",
+        describe: "Check the content format specification against schemas and notes",
+        builder: (yargs) =>
+            yargs
+                .command(contentFormatSchemaCommand())
+                .command(contentFormatFieldsCommand())
+                .command(contentFormatNotesCommand())
+                .demandCommand(1, "Name an action.")
+                .strict(),
+        handler: () => {},
+    };
+}
+
+/**
+ * The parsed specification a `content-format` action should read.
+ *
+ * @param {object} argv - The parsed command line.
+ * @returns {import("../engine/content-format.mjs").ContentFormat} The document.
+ */
+function specFrom(argv) {
+    return argv.spec ? loadContentFormat(path.resolve(argv.spec)) : loadContentFormat();
+}
+
+/**
+ * `content-format schema` — every `system.*` target, against a published schema.
+ *
+ * The schemas are named on the command line as `<system>=<path>`, because a
+ * consumer holds one and this repository holds a committed fixture, and neither
+ * arrangement should be the one the other has to pretend to. A system the
+ * document maps onto but no schema was supplied for is reported as unchecked —
+ * HM3 publishes no artifact today, so that is the ordinary case for a fifth of
+ * the claims, and a check that quietly skipped them would read as one that
+ * passed.
+ *
+ * @returns {object} The yargs command module.
+ */
+function contentFormatSchemaCommand() {
+    return {
+        command: "schema",
+        describe: "Check every `system.*` target the format names against a published schema.json",
+        builder: (yargs) => {
+            yargs.option("spec", {
+                describe:
+                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                type: "string",
+            });
+            yargs.option("schema", {
+                describe:
+                    "A published schema, as `<system>=<path>`. Repeatable; a system with none is reported unchecked.",
+                type: "string",
+                array: true,
+                demandOption: true,
+            });
+        },
+        handler: (argv) => {
+            try {
+                const format = specFrom(argv);
+                /** @type {Record<string, object>} */
+                const schemas = {};
+                for (const entry of argv.schema) {
+                    const at = String(entry).indexOf("=");
+                    if (at <= 0) {
+                        log.error(`--schema takes \`<system>=<path>\`, not "${entry}".`);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    const system = entry.slice(0, at);
+                    const file = path.resolve(entry.slice(at + 1));
+                    schemas[system] = JSON.parse(fs.readFileSync(file, "utf8"));
+                }
+
+                const { findings, checked, unchecked } = checkSchemaTargets({ format, schemas });
+                for (const finding of findings) emitDiagnostic(finding);
+                for (const [system, count] of Object.entries(unchecked)) {
                     log.info(
-                        `Wrote ${path.relative(config.rootDir, destination)}`,
+                        `${count} claim(s) about ${system} are unchecked — no ` +
+                            `schema was supplied for it, so nothing here confirms them.`,
+                    );
+                }
+                if (findings.length) {
+                    log.error(
+                        `${findings.length} of ${checked} checked claim(s) name a ` +
+                            `field no schema declares.`,
                     );
+                    process.exitCode = 1;
                 } else {
-                    process.stdout.write(page);
+                    log.info(`${checked} mapping claim(s) confirmed against the supplied schemas.`);
                 }
             } catch (err) {
                 reportFailure(err);
@@ -335,6 +463,198 @@ function docsCommand() {
     };
 }
 
+/**
+ * The field declarations a `content-format fields` run should compare against.
+ *
+ * Either this package's own shipped registry, named on the command line, or the
+ * consuming repository's resolved configuration. Both are real arrangements and
+ * neither should have to pretend to be the other: this repository ships the
+ * specification *and* the SoHL declarations and configures no content tree,
+ * while a consumer configures `itemBuilders` and resolves the specification
+ * from its toolchain.
+ *
+ * @param {object} argv - The parsed command line.
+ * @returns {{itemFields: Record<string, readonly object[]>, system: string}}
+ *   The declarations, and the system column of the mapping tables they compile.
+ */
+function declarationsFrom(argv) {
+    if (argv.fields) return { itemFields: SHIPPED_ITEM_FIELDS[argv.fields], system: argv.fields };
+    const config = loadPackConfig();
+    const system = config.stats?.systemId;
+    if (!system) {
+        throw new Error(
+            "package-build: this repository's configuration names no system, so " +
+                "nothing says which column of the format's mapping tables its " +
+                "`itemBuilders` declarations compile. Name a shipped set with " +
+                "`--fields <system>` instead.",
+        );
+    }
+    return { itemFields: config.itemFields ?? {}, system };
+}
+
+/**
+ * `content-format fields` — the per-type tables, against the declarations.
+ *
+ * The specification hand-writes a `data` table under most of its type sections,
+ * covering ground {@link module:engine/field-reference} already generates from
+ * the `fields` on each `itemBuilders` entry — the duplication that module exists
+ * to prevent, one document over (#136).
+ *
+ * **Checked, not merged.** The document's vocabulary spans note types that
+ * produce Scenes, Macros and JournalEntries, which no item registry covers, so
+ * there is no wholesale generation to fall back on. What the two *can* be held
+ * to is agreement where they both speak: a mapping row saying `data.weight`
+ * reaches `system.weightBase` and a declaration writing `weight` to `weightBase`
+ * are one statement made twice, and a rename that moves only one of them is a
+ * defect. A type only one side describes is named as out of reach rather than
+ * skipped in silence.
+ *
+ * @returns {object} The yargs command module.
+ */
+function contentFormatFieldsCommand() {
+    return {
+        command: "fields",
+        describe: "Check the format's per-type tables against the field declarations",
+        builder: (yargs) => {
+            yargs.option("spec", {
+                describe:
+                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                type: "string",
+            });
+            yargs.option("fields", {
+                describe:
+                    "A declaration set this package ships, by system id. Defaults to the consuming repository's own `itemBuilders`.",
+                type: "string",
+                choices: Object.keys(SHIPPED_ITEM_FIELDS),
+            });
+            yargs.option("coverage", {
+                describe:
+                    "List, per type, the fields only one side names. They are not findings — the two vocabularies differ by design until #127 lands.",
+                type: "boolean",
+                default: false,
+            });
+        },
+        handler: (argv) => {
+            try {
+                const format = specFrom(argv);
+                const { itemFields, system } = declarationsFrom(argv);
+                const result = checkDeclaredFields({ format, itemFields, system });
+                for (const finding of result.findings) emitDiagnostic(finding);
+
+                // Named rather than left implicit: a check that silently
+                // compared nine of twenty-two types would read as one that
+                // covered them all.
+                log.info(
+                    `${result.checked.length} type(s) compared against ${system}'s ` +
+                        `declarations (${result.fields} field pair(s)).`,
+                );
+                log.info(
+                    `${result.skipped.spec.length} type(s) the format declares are ` +
+                        `out of reach — no \`itemBuilders\` entry covers them: ` +
+                        `${result.skipped.spec.join(", ")}.`,
+                );
+                if (result.skipped.registry.length) {
+                    log.info(
+                        `${result.skipped.registry.length} declared type(s) the ` +
+                            `format names no section for: ` +
+                            `${result.skipped.registry.join(", ")}.`,
+                    );
+                }
+                if (argv.coverage) {
+                    for (const entry of result.coverage) {
+                        log.info(
+                            `${entry.type}: format only [${entry.specOnly.join(", ")}], ` +
+                                `declaration only [${entry.registryOnly.join(", ")}]`,
+                        );
+                    }
+                }
+
+                if (result.findings.length) {
+                    log.error(
+                        `${result.findings.length} of ${result.fields} compared field ` +
+                            `pair(s) disagree between the specification and the ` +
+                            `declaration that compiles them.`,
+                    );
+                    process.exitCode = 1;
+                }
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
+/**
+ * `content-format notes` — a content tree, against the declared vocabulary.
+ *
+ * **A report, not a gate.** Every authored note predates the format, so a
+ * failing check would be red in every repository from the day it lands and
+ * would stay red for the length of #127 — which is a check nobody can act on.
+ * `--strict` raises the findings to errors, and #127 turns it on slice by
+ * slice as each class of finding reaches zero.
+ *
+ * @returns {object} The yargs command module.
+ */
+function contentFormatNotesCommand() {
+    return {
+        command: "notes [root]",
+        describe: "Measure a content tree against the vocabulary the format declares (a report)",
+        builder: (yargs) => {
+            yargs.positional("root", {
+                describe: "Content tree to measure. Defaults to the configured contentBase.",
+                type: "string",
+            });
+            yargs.option("spec", {
+                describe:
+                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                type: "string",
+            });
+            yargs.option("strict", {
+                describe:
+                    "Fail on the findings instead of reporting them. Turned on per slice of #127, as each class reaches zero.",
+                type: "boolean",
+                default: false,
+            });
+        },
+        handler: (argv) => {
+            try {
+                const config = loadPackConfig();
+                const root = argv.root ?? config.paths.content;
+                const format = specFrom(argv);
+
+                const notes = [];
+                for (const { frontmatter, absPath } of walkMarkdownTree(root, {
+                    skipDirectories: config.skipDirectories,
+                })) {
+                    if (!frontmatter || typeof frontmatter.type !== "string") continue;
+                    notes.push({
+                        file: absPath,
+                        fm: frontmatter,
+                        raw: fs.readFileSync(absPath, "utf8"),
+                    });
+                }
+
+                const { findings, byClass } = measureCorpus(notes, format, {
+                    strict: argv.strict,
+                });
+                for (const finding of findings) emitDiagnostic(finding);
+
+                const counts = Object.entries(byClass).sort(([a], [b]) => (a < b ? -1 : 1));
+                for (const [cls, count] of counts) log.info(`${cls}: ${count}`);
+                log.info(
+                    `${findings.length} finding(s) across ${notes.length} note(s) ` +
+                        `measured against ${format.file}.`,
+                );
+                if (argv.strict && findings.length) process.exitCode = 1;
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
 /**
  * `content-build lint` — check a content tree's addresses.
  *
@@ -353,8 +673,7 @@ function lintCommand() {
         describe: "Check a content tree's addresses and frontmatter",
         builder: (yargs) => {
             yargs.positional("root", {
-                describe:
-                    "Content tree to lint. Defaults to the configured contentBase.",
+                describe: "Content tree to lint. Defaults to the configured contentBase.",
                 type: "string",
             });
             yargs.option("references", {
@@ -389,6 +708,11 @@ function lintCommand() {
                 });
                 const frontmatter = lintFrontmatter(index, {
                     schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
+                    // The closed frontmatter regions (#128). Passed in rather
+                    // than reached for, so the linter stays a checker of
+                    // whatever it is handed and this stays the one place that
+                    // decides which vocabulary a tree is held to.
+                    vocabulary: NOTE_VOCABULARY,
                     references: argv.references,
                 });
 
@@ -466,12 +790,23 @@ function lintCommand() {
                     ...frontmatter.findings,
                     ...schemaFindings,
                 ];
-                for (const finding of findings) emitDiagnostic(finding);
-                if (findings.length) {
-                    log.error(
-                        `${findings.length} finding(s) across ${addresses.notes} note(s).`,
-                    );
+                // Only an **error** fails the run. Every finding was an error
+                // until #142, so this changed nothing on the day it landed —
+                // but a field retired in favour of another is reported while
+                // both spellings still compile, and failing a build over a note
+                // that produces the correct document would red a tree that has
+                // done nothing wrong. `reportFindings` already draws exactly
+                // that line, so the rule is the shared one rather than a second
+                // copy here. Each finding names its own file.
+                const errors = reportFindings(findings, {});
+                if (errors) {
+                    log.error(`${findings.length} finding(s) across ${addresses.notes} note(s).`);
                     process.exitCode = 1;
+                } else if (findings.length) {
+                    log.warn(
+                        `${findings.length} advisory finding(s) across ` +
+                            `${addresses.notes} note(s); none fails the build.`,
+                    );
                 } else {
                     log.info(
                         `Addresses and frontmatter are well-formed ` +
@@ -510,19 +845,16 @@ function formatCommand() {
         describe: "Check formatting with the shared Prettier configuration",
         builder: (yargs) => {
             yargs.positional("paths", {
-                describe:
-                    "Files or directories to check. Defaults to the whole repository.",
+                describe: "Files or directories to check. Defaults to the whole repository.",
                 type: "string",
             });
             yargs.option("write", {
-                describe:
-                    "Rewrite unformatted files in place instead of reporting them.",
+                describe: "Rewrite unformatted files in place instead of reporting them.",
                 type: "boolean",
                 default: false,
             });
             yargs.option("check", {
-                describe:
-                    "Report unformatted files without rewriting them (the default).",
+                describe: "Report unformatted files without rewriting them (the default).",
                 type: "boolean",
             });
         },
@@ -532,30 +864,37 @@ function formatCommand() {
                 // it contradicts `--write`; naming both is a mistake worth
                 // saying out loud rather than silently resolving.
                 if (argv.check === true && argv.write) {
-                    log.error(
-                        "--check and --write ask for opposite things; name one.",
-                    );
+                    log.error("--check and --write ask for opposite things; name one.");
                     process.exitCode = 1;
                     return;
                 }
                 const root = process.cwd();
-                const { findings, checked, written } = await checkFormatting(
-                    root,
-                    { paths: argv.paths, write: argv.write },
-                );
+                const { findings, checked, written } = await checkFormatting(root, {
+                    paths: argv.paths,
+                    write: argv.write,
+                });
                 if (argv.write) {
                     log.info(
                         written.length ?
                             `Formatted ${written.length} of ${checked} file(s).`
                         :   `Already formatted (${checked} file(s)).`,
                     );
+                    // `--write` collects findings too — a file Prettier cannot
+                    // parse, or one that will not format to a fixpoint — and
+                    // used to discard them, so a run that had left files
+                    // unformatted still reported success and exited 0 (#125).
+                    for (const finding of findings) emitDiagnostic(finding);
+                    if (findings.length) {
+                        log.error(
+                            `${findings.length} of ${checked} file(s) could not be formatted.`,
+                        );
+                        process.exitCode = 1;
+                    }
                     return;
                 }
                 for (const finding of findings) emitDiagnostic(finding);
                 if (findings.length) {
-                    log.error(
-                        `${findings.length} of ${checked} file(s) are not formatted.`,
-                    );
+                    log.error(`${findings.length} of ${checked} file(s) are not formatted.`);
                     process.exitCode = 1;
                 } else {
                     log.info(`Formatting is clean (${checked} file(s)).`);
@@ -586,8 +925,7 @@ function markdownCommand() {
         describe: "Lint markdown with the shared markdownlint rule set",
         builder: (yargs) => {
             yargs.positional("paths", {
-                describe:
-                    "Globs to lint. Defaults to every markdown file in the repository.",
+                describe: "Globs to lint. Defaults to every markdown file in the repository.",
                 type: "string",
             });
             yargs.option("fix", {
@@ -635,8 +973,7 @@ function linksCommand() {
         describe: "Check that every link in a content tree lands somewhere",
         builder: (yargs) => {
             yargs.positional("root", {
-                describe:
-                    "Content tree to check. Defaults to the configured contentBase.",
+                describe: "Content tree to check. Defaults to the configured contentBase.",
                 type: "string",
             });
             yargs.option("manifests", {
@@ -665,9 +1002,7 @@ function linksCommand() {
                             message: `unusable link manifest: ${s.reason}`,
                         });
                     }
-                    log.error(
-                        "Refresh the vendored copy from that package's own build.",
-                    );
+                    log.error("Refresh the vendored copy from that package's own build.");
                     process.exitCode = 1;
                     return;
                 }
@@ -675,14 +1010,10 @@ function linksCommand() {
                 // Readable is not the same as addressable: a key shape the
                 // lookup cannot parse makes every cross-package link miss, and
                 // the audit then blames the *notes*.
-                const drifted = unaddressableForeignPackages(
-                    index.foreign.index,
-                );
+                const drifted = unaddressableForeignPackages(index.foreign.index);
                 if (drifted.length) {
                     for (const f of drifted) {
-                        console.error(
-                            formatUnaddressableFinding(f, manifestDir),
-                        );
+                        console.error(formatUnaddressableFinding(f, manifestDir));
                     }
                     process.exitCode = 1;
                     return;
@@ -691,6 +1022,8 @@ function linksCommand() {
                 const {
                     deadAnchors,
                     deadAddresses,
+                    deadAliases,
+                    aliasCollisions,
                     frontmatterLinks,
                     homepageLinks,
                     usedManifest,
@@ -706,14 +1039,62 @@ function linksCommand() {
                             `heading in ${d.dest.rel} declares`,
                     });
                 }
+                // The pipe says the author meant an address (#131), so all
+                // three of these are errors — but they read differently
+                // because the corrections differ.
                 for (const d of deadAddresses) {
                     emitDiagnostic({
                         file: d.note.file,
                         ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
                         severity: "error",
-                        message: `dead address [[${d.target}]] — no document has that identity`,
+                        message:
+                            d.reason === "not-an-address" ?
+                                `"${d.target}" is written as an address — the ` +
+                                `"|" says so — but it is not one; write ` +
+                                `[[type-shortcode|Text]], or drop the "|" to ` +
+                                `name it as an alias within this note's type`
+                            : d.reason === "unknown-type" ?
+                                `address [[${d.target}]] names no known ` + `content type`
+                            :   `dead address [[${d.target}]] — no document ` + `has that identity`,
                     });
                 }
+                // An alias that names nothing may be a worldbuilding
+                // placeholder — a long-standing convention in the setting
+                // trees — so it is reported and does not fail the build. The
+                // ambiguous case is the collision below, reported at its
+                // claimants rather than here.
+                for (const d of deadAliases) {
+                    emitDiagnostic({
+                        file: d.note.file,
+                        ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
+                        severity: "warning",
+                        message:
+                            d.ambiguous ?
+                                `alias [[${d.target}]] is claimed by ` +
+                                `${d.claimants.length} ${d.note.type} notes, ` +
+                                `so it names none of them; address the ` +
+                                `intended one as [[type-shortcode|Text]]`
+                            :   `unresolved alias [[${d.target}]] — no ` +
+                                `${d.note.type} note claims that name`,
+                    });
+                }
+                // Reported once per claimant, at the claimant, because the
+                // note that merely cites an ambiguous alias is innocent (#13).
+                for (const c of aliasCollisions) {
+                    const others = c.claimants.map((n) => n.rel).join(", ");
+                    for (const claimant of c.claimants) {
+                        emitDiagnostic({
+                            file: claimant.file,
+                            ...positionInFrontmatter(claimant.raw, "aliases", c.alias),
+                            severity: "error",
+                            message:
+                                `alias "${c.alias}" is claimed by ` +
+                                `${c.claimants.length} ${c.type} notes ` +
+                                `(${others}), so [[${c.alias}]] names none of ` +
+                                `them; rename all but one`,
+                        });
+                    }
+                }
                 for (const f of frontmatterLinks) {
                     emitDiagnostic({
                         file: f.note.file,
@@ -738,23 +1119,32 @@ function linksCommand() {
                     });
                 }
 
+                // Warnings are reported and do not fail: a dead alias may be a
+                // note not yet written, which is the placeholder convention.
                 const failures =
                     deadAnchors.length +
                     deadAddresses.length +
+                    aliasCollisions.reduce((n, c) => n + c.claimants.length, 0) +
                     frontmatterLinks.length +
                     homepageLinks.length;
                 if (failures) {
-                    log.error(
-                        `${failures} link problem(s) across ${index.notes.length} note(s).`,
-                    );
+                    log.error(`${failures} link problem(s) across ${index.notes.length} note(s).`);
                     process.exitCode = 1;
                 } else {
                     log.info(
                         `${index.notes.length} notes: every anchor link lands ` +
-                            `and every qualified address resolves ` +
+                            `and every address resolves ` +
                             `(${usedManifest.size} cross-package reference(s) ` +
-                            `via manifest), no wikilink in frontmatter, ` +
-                            `every homepage address resolvable.`,
+                            `via manifest), no alias claimed twice, no ` +
+                            `wikilink in frontmatter, every homepage address ` +
+                            `resolvable.`,
+                    );
+                }
+                if (deadAliases.length) {
+                    log.warn(
+                        `${deadAliases.length} unresolved alias(es) — a bare ` +
+                            `[[Name]] naming no note may be a placeholder, so ` +
+                            `these are reported rather than failed.`,
                     );
                 }
             } catch (err) {
@@ -789,14 +1179,12 @@ function manifestCommand() {
         describe: "Emit this package's cross-package link manifest",
         builder: (yargs) => {
             yargs.positional("root", {
-                describe:
-                    "Content tree to read. Defaults to the configured contentBase.",
+                describe: "Content tree to read. Defaults to the configured contentBase.",
                 type: "string",
             });
             yargs.option("out", {
                 describe:
-                    "Directory to write into. Defaults to the configured " +
-                    "`paths.manifestOut`.",
+                    "Directory to write into. Defaults to the configured " + "`paths.manifestOut`.",
                 type: "string",
             });
         },
@@ -825,10 +1213,7 @@ function manifestCommand() {
                 // lost its address becomes a dead link in every consumer.
                 for (const s of skipped) {
                     emitDiagnostic({
-                        file: path.join(
-                            argv.root ?? config.paths.content,
-                            s.file,
-                        ),
+                        file: path.join(argv.root ?? config.paths.content, s.file),
                         severity: "warning",
                         message: `no address, so it is absent from the manifest: ${s.reason}`,
                     });
@@ -864,8 +1249,7 @@ function siteCommand() {
         describe: "Build a Hugo content tree from the content tree",
         builder: (yargs) => {
             yargs.option("out", {
-                describe:
-                    "Write the mount here instead of the configured `site.out`.",
+                describe: "Write the mount here instead of the configured `site.out`.",
                 type: "string",
             });
         },
@@ -903,26 +1287,16 @@ function siteCommand() {
                 }
                 for (const s of gates.staleManifests) {
                     emitDiagnostic({
-                        file: path.join(
-                            loadPackConfig().paths.manifests,
-                            `${s.package}.json`,
-                        ),
+                        file: path.join(loadPackConfig().paths.manifests, `${s.package}.json`),
                         severity: "error",
                         message: `unusable link manifest: ${s.reason}`,
                     });
                 }
                 for (const f of gates.unaddressable) {
-                    console.error(
-                        formatUnaddressable(
-                            f,
-                            loadPackConfig().paths.manifests,
-                        ),
-                    );
+                    console.error(formatUnaddressable(f, loadPackConfig().paths.manifests));
                 }
                 for (const c of gates.conflicts) {
-                    log.error(
-                        `address ${c.key} is also published by ${c.package}`,
-                    );
+                    log.error(`address ${c.key} is also published by ${c.package}`);
                 }
                 if (gatesFailed(gates)) {
                     process.exitCode = 1;
@@ -937,9 +1311,7 @@ function siteCommand() {
                     log.error(`bad content table: ${e.reason}  (${e.source})`);
                 }
                 for (const e of result.wikiErrors) {
-                    log.error(
-                        `bad wikilink [[${e.target}]]: ${e.reason}  (${e.file})`,
-                    );
+                    log.error(`bad wikilink [[${e.target}]]: ${e.reason}  (${e.file})`);
                 }
                 if (result.tableErrors.length || result.wikiErrors.length) {
                     process.exitCode = 1;
@@ -989,8 +1361,7 @@ function reachabilityCommand() {
         describe: "Check that every document in a corpus is reachable",
         builder: (yargs) => {
             yargs.positional("dir", {
-                describe:
-                    "The corpus directory, relative to the content tree root.",
+                describe: "The corpus directory, relative to the content tree root.",
                 type: "string",
             });
             yargs.positional("file", {
@@ -1008,8 +1379,7 @@ function reachabilityCommand() {
                 default: [],
             });
             yargs.option("root", {
-                describe:
-                    "Content tree to read. Defaults to the configured contentBase.",
+                describe: "Content tree to read. Defaults to the configured contentBase.",
                 type: "string",
             });
         },
@@ -1026,9 +1396,7 @@ function reachabilityCommand() {
                     stopAt: (n) => indexes.has(String(n.fm.shortcode)),
                 });
 
-                const total = index.notes.filter((n) =>
-                    n.rel.startsWith(`${dir}/`),
-                ).length;
+                const total = index.notes.filter((n) => n.rel.startsWith(`${dir}/`)).length;
 
                 for (const o of orphans) {
                     // Unreachability is a property of the whole document, so
@@ -1052,8 +1420,7 @@ function reachabilityCommand() {
                     process.exitCode = 1;
                 } else {
                     log.info(
-                        `All ${total} document(s) in ${dir} are reachable ` +
-                            `from ${argv.file}.`,
+                        `All ${total} document(s) in ${dir} are reachable ` + `from ${argv.file}.`,
                     );
                 }
             } catch (err) {
@@ -1144,8 +1511,7 @@ function depsCommand() {
                     return;
                 }
                 const count = await fetchAllCatalogs(config);
-                if (count)
-                    log.info(`Fetched ${count} dependency catalogue(s).`);
+                if (count) log.info(`Fetched ${count} dependency catalogue(s).`);
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -1192,24 +1558,15 @@ async function diffAddresses(config, argv) {
         ...config,
         paths: {
             ...config.paths,
-            foreignCache: path.join(
-                path.dirname(config.paths.foreignCache),
-                "baseline",
-            ),
+            foreignCache: path.join(path.dirname(config.paths.foreignCache), "baseline"),
         },
     };
-    const dir = await fetchCatalogFromPath(
-        cacheConfig,
-        { id: config.foundryPackage },
-        argv.from,
-    );
+    const dir = await fetchCatalogFromPath(cacheConfig, { id: config.foundryPackage }, argv.from);
     // `<id>@<version>`, which is what the diagnostics name the baseline by.
     const label = path.basename(dir);
 
     const itemsRoot = path.join(dir, "items");
-    const baselineDirs = fs
-        .readdirSync(itemsRoot)
-        .map((name) => path.join(itemsRoot, name));
+    const baselineDirs = fs.readdirSync(itemsRoot).map((name) => path.join(itemsRoot, name));
     const currentDirs = itemPackJsonDirs(config);
     if (!currentDirs.length) {
         throw new Error(
@@ -1254,8 +1611,7 @@ async function diffAddresses(config, argv) {
 function addressesCommand() {
     return {
         command: "addresses <action>",
-        describe:
-            "Compare the addresses this build publishes against a release's",
+        describe: "Compare the addresses this build publishes against a release's",
         builder: (yargs) => {
             // Required, for the reason every other action is (#57): an
             // optional one exits 0 having compared nothing.