@heroiclands/package-build 6.0.0 → 7.0.0

package/CONTENT.md

@@ -155,7 +155,9 @@ the file sits in, fills the optional halves with their defaults
 manifest switches off and `publish.site` at its `homepage` floor),
 derives `assetRoot`, `packDirectories`, `itemTypes` and `docEntryTypes`, and
 freezes the result. A malformed configuration throws a `TypeError` naming the
-offending field, so it fails at load rather than as an empty pack much later.
+offending field — and the line and column it was written on, in the
+[located form](#diagnostics) — so it fails at load rather than as an empty pack
+much later.
 
 **Four values are derived rather than authored**, because each is something a
 file can be asked for rather than told:
@@ -474,6 +476,7 @@ npx content-build markdown [paths..] [--fix]
 npx content-build manifest [root] [--out <dir>]
 npx content-build site [--out <dir>]
 npx content-build reachability <dir> [file] [--index <shortcode>]
+npx content-build addresses diff --from <zip|dir> [--strict]
 ```
 
 | Command        | What it does                                                                                                                                                            |
@@ -487,6 +490,7 @@ npx content-build reachability <dir> [file] [--index <shortcode>]
 | `manifest`     | Emit this package's cross-package link manifest. See [Publishing a link manifest](#publishing-a-link-manifest).                                                         |
 | `site`         | Publish the content tree as a website. See [Publishing a website](#publishing-a-website).                                                                               |
 | `reachability` | Walk outward from an index note and report what no path reaches, for a tree meant to be navigable from one entry point.                                                 |
+| `addresses`    | Report every published item address this build has stopped publishing. See [Diffing published addresses](#diffing-published-addresses).                                 |
 
 Every path, pack name and root it needs comes from the consuming repository's
 `package-build.config.yaml`, so the usual invocation takes no arguments beyond
@@ -505,7 +509,7 @@ npx content-build lint            # the configured `paths.content`
 npx content-build lint some/tree  # or a tree named outright
 ```
 
-Checks the two rules every note's **identity** is authored against, and reports
+Checks the three rules every note's **identity** is authored against, and reports
 each finding in the located form below:
 
 - **Shape** — a `shortcode` is strictly ASCII-alphanumeric. It is the identity
@@ -514,6 +518,8 @@ each finding in the located form below:
 - **Uniqueness** — `(type, shortcode)` names one note. A document is addressed
   across _every_ pack of its document type, so routing two same-address notes to
   different packs with `pack:` does not separate them.
+- **The package's own address** — exactly one note claims `/<package>/`. See
+  [Exactly one homepage](#exactly-one-homepage) below.
 
 It compiles nothing, opens no LevelDB and needs no Foundry manifest, so it runs
 in about a second and can gate a commit. An empty or untyped tree **fails**
@@ -527,6 +533,48 @@ addressed by the package rather than by a slug — so a package in
 permanently unkeyed. That tree passes; a tree holding no notes at all still
 fails.
 
+### Exactly one homepage
+
+A content tree declares **exactly one** `type: homepage` note (#52). Zero is an
+error and two is an error, at the same severity, because they are one defect: a
+package whose front page is not the page a person chose.
+
+- _Zero_ and the package serves nothing at `/<package>/` — the failure the
+  authored homepage exists to prevent, and a silent one: 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
+  `_index.md`, so the second overwrites the first and the front page is decided
+  by the order the walk reached 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 can pick the right one.
+
+Neither has a safe default, so neither is a warning: a build that proceeded past
+either would publish the wrong front page while reporting success, which is
+exactly what a warning tolerates.
+
+**Where it fires: `lint` _and_ `site`.** No single command reaches every
+package — `HarnMaster-3-FoundryVTT` runs `content-build site` and no
+`content-build lint`; `sohl-thalorna` runs `content-build lint` and its own site
+builder — so a rule in one of them is a rule two of the six packages do not
+have. Both call the same function, so there is one rule and two call sites
+rather than two rules. In the site build it runs **before the output tree is
+cleared**, so a failing gate cannot destroy a good site to report a bad tree.
+
+**It does not vary by `publish.site`.** That setting chooses whether the
+_content_ surfaces are published; the homepage is the floor beneath both modes.
+The lint call site reads no `site:` block at all, and so could not vary by mode
+even if the rule wanted to.
+
+Zero has no file to name, so the locator is the **content root** — a real path,
+and the directory the note has to be added to. No line or column is invented for
+it. Two is reported once per offending note, located at its own `type:` value and
+naming the other, because each note is a place an author has to open and edit:
+
+```text
+assets/content: error: holds no `type: homepage` note, so package "sohl" publishes nothing at its own address /sohl/ — a package's front page is one authored note in this tree, routed by `type:` rather than by filename
+assets/content/homepage.md:3:7: error: duplicate `type: homepage` note, also declared by assets/content/Landing.md; a package has one front page, at /sohl/, and every homepage is written to the same `_index.md` — so the one the walk reaches last silently overwrites the rest
+```
+
 ### Frontmatter, against the schema its type declares
 
 The same command also checks that each note's `sohl:` block is what its **type**
@@ -570,6 +618,55 @@ does not exist. Removing it was verified output-neutral first: across 1,735
 stripped notes, `package compile` produced byte-identical `build/packs-json` and
 the site build byte-identical `site/content`.
 
+### The homepage carries no address of its own
+
+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. So `content-build lint`
+**refuses** `name`, `shortcode` and `id` on a `type: homepage` note (#53) rather
+than ignoring them — 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` that the site build never writes, because a
+homepage goes to `_index.md` at the package root. A build reporting a live link
+to a 404 is worse than one saying nothing. It also inflates this command's own
+address tally, so the lint and the link manifest disagree about what the package
+publishes: SoHL's tree reports `1607 address(es) across 1607 note(s)` with a
+`shortcode` on its landing and `1606 address(es) across 1607 note(s)` without
+one. That is one defect, not two — the tally is only ever printed on a clean run,
+so refusing the field is what makes the count honest.
+
+Each finding is located at the offending key and says what the field would have
+decided, not merely that it does not belong:
+
+```text
+assets/content/homepage.md:26:1: error: `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
+assets/content/homepage.md:28:1: error: `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 `_index.md` at the package's own address, `/<package>/`. Write `title:` for what the page is called, and delete `name`
+```
+
+**A named class, not an allow-list.** The documented envelope is `type` plus an
+optional `title`, with `landing`, `description` and `banner` legitimate beside
+them — but an unknown top-level key is **not** refused, and that boundary is the
+decision rather than an omission. A homepage's frontmatter is emitted into the
+published page, so an unrecognised key is a Hugo or theme parameter this build
+has never heard of and has no standing to reject; a closed list 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_. `aliases` is
+not in that class either: it is already dropped from every emitted page, so
+authoring one here is the same no-op it is anywhere else.
+
+**Where it fires: `content-build lint` only.** Unlike a rule about the shape of
+the _tree_, which the site build has its own reason to gate on, this is a
+_frontmatter-schema_ rule and `content-build site` runs none of them — wiring in one type's field
+rule would have the site build refuse `shortcode` on a homepage while accepting
+`weight: heavy` on a weapon. The gap that leaves is `HarnMaster-3-FoundryVTT`,
+which runs no `content-build lint` at all and so receives no frontmatter finding
+of any kind; that is a missing script in that repository, not a rule to duplicate
+one at a time.
+
 ### The homepage's own links
 
 The homepage is the page a reader arrives at, and until #54 it was the one page
@@ -789,6 +886,10 @@ title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.t
 What the module is, which system it needs, how to install it.
 ```
 
+A package declares **exactly one** of these, and both `content-build lint` and
+`content-build site` require it — see
+[Exactly one homepage](#exactly-one-homepage).
+
 That is the whole envelope. A homepage **compiles into no compendium
 document**, appears in no pack and in no link manifest, and is addressed by the
 _package_ rather than by its own name — so `name.full`, `shortcode` and `id`
@@ -853,7 +954,10 @@ site:
   trees:
     - { from: kb/dev-docs, section: dev-docs }
   sections:
-    being: { title: Beings, banner: banners/creature.webp }
+    being:
+      title: Beings
+      banner: banners/creature.webp
+      description: Folk, animals and the things that walk the world.
   readmeSections:
     dev-docs: { title: Developer Documentation, banner: banners/dev-docs.webp }
 ```
@@ -863,7 +967,7 @@ site:
 | `out`              | The Hugo content root. **Required** in both modes, and wiped on every run — see below.           |
 | `base`             | Where the package is served. Defaults to `/<contentPackage>/`.                                   |
 | `packages`         | Which content packages this site renders. Defaults to its own.                                   |
-| `sections`         | Landing title and hero per section, so a landing matches the card that links to it.              |
+| `sections`         | What each section says about itself on its landing — see below.                                  |
 | `readmeSections`   | The same, for a section whose landing comes from a `README`.                                     |
 | `landing`          | Frontmatter for the mount's own `_index.md`. Passed through — the vocabulary is the theme's.     |
 | `backfillSections` | Write a bare `_index.md` for any other section directly under the mount.                         |
@@ -871,6 +975,42 @@ site:
 | `pass`             | A named bundle of this repository's own body rewrites.                                           |
 | `passOptions`      | That bundle's options.                                                                           |
 
+### What a section may declare
+
+A generated section landing is the **only** place a section can describe itself.
+A content package authors no `_index.md` for `weapongear` or `affliction`, so
+the file the theme reads is the one this build writes from `sections` — and
+whatever that entry may carry is the whole of what the section can say.
+
+| Key           | Required | What it does                                                              |
+| ------------- | -------- | ------------------------------------------------------------------------- |
+| `title`       | yes      | The landing's heading, so it matches the card that links to it.           |
+| `banner`      | no       | The hero image, resolved as a CDN asset like any other `banner:`.         |
+| `description` | no       | The hero standfirst under the heading, and the blurb a landing card uses. |
+
+`readmeSections` takes the same three, for a section whose landing comes from a
+`README` rather than from nothing. What the section declares wins over what the
+`README` happens to carry — the landing has to match the card that links to it.
+
+**The vocabulary is closed, and a key outside it is refused by name:**
+
+```text
+package-build config: `site.sections.affliction.descrption` is not a
+recognized option (expected one of: title, banner, description).
+```
+
+That refusal is the point. `landing` is passed through unvalidated because it is
+written once, for the mount, in one landing template's own vocabulary. A section
+entry is written fourteen to twenty times per build against a contract every
+package and every section shares, so an unbounded one would let a mistyped
+`descrption:` publish into front matter, be read by nobody, and say nothing to
+anyone. Refusing it costs one line here when the vocabulary genuinely grows, and
+buys a build that cannot quietly emit a key no theme reads.
+
+The **writers** name no keys: a section's `_index.md` is whatever the entry
+resolved to, `title` first. So extending the vocabulary is a change to the
+schema alone, and the two can no longer drift apart.
+
 ### Why `out` is required
 
 The output tree is a build artifact and is **deleted on every run**, so that a
@@ -931,6 +1071,72 @@ None of them exits the process from inside the library; the command decides. Tha
 is what makes them testable, which the consumer scripts' inline `process.exit`
 calls were not.
 
+## Diffing published addresses
+
+```bash
+gh release download v0.8.2 -p system.zip -D build/baseline
+npx content-build addresses diff --from build/baseline/system.zip
+npx content-build addresses diff --from build/baseline/system.zip --strict
+```
+
+A package's `(type, shortcode)` addresses are a **published interface**. Every
+satellite declaring `itemCatalog: true` assembles its beings out of them —
+`attribute:str`, `skill:awar`, `weapongear:Tabri` — resolving each against the
+Item packs of the release its `compatibility.verified` pins. Renaming a
+shortcode is therefore a breaking change to something other repositories
+consume, and it used to cost nothing and produce no signal: the check that got
+made was a repository-local grep, which cannot see the other repositories and
+reports the reassuring answer.
+
+`sohl` renamed one weapon's shortcode from `Tabri` to `Taburi` two days after
+the `v0.8.2` tag, on the stated ground that "nothing referenced the old value".
+True of that repository. Both satellites pin `v0.8.2` and address
+`weapongear:Tabri` on their copy of the same character — five lookups that
+resolve today and fail the moment either pin moves, reporting a missing item.
+
+**A rename is told from a removal by the document id, and that is an identity
+match rather than an inference.** A note authors its `_id` in frontmatter; it is
+not derived from the shortcode, so it survives a rename. An address that
+disappeared while its document is still published elsewhere _is_ a rename:
+
+```text
+assets/content/Weapons/Melee/Taburi.md:12:1: warning: since sohl@0.8.2, weapongear:Tabri is no longer published; the same document (s5D6QJbw7ZbETxdN) is now published as weapongear:Taburi. Every package that resolves weapongear:Tabri breaks when it moves past sohl@0.8.2
+```
+
+Where the id is published under no address at all, that is all it says —
+**withdrawn**, with no successor named. A split, a deletion and a merge are
+indistinguishable at that point, and a "did you mean" guessed from string
+similarity would be worse than silence, because a wrong one sends the reader to
+the wrong fix.
+
+| Finding     | What it means                                            | Severity                                |
+| ----------- | -------------------------------------------------------- | --------------------------------------- |
+| `renamed`   | Address gone; the same document publishes under another. | `warning` — legitimate, but not silent  |
+| `withdrawn` | Address gone; its document publishes under none.         | `warning` — retiring content is allowed |
+
+Neither fails a build. Retiring content is legitimate, and so is renaming — the
+shortcode charset rule forces some. What a rename must not do is happen without
+anyone noticing. `--strict` reports both as errors and exits non-zero, for a
+release workflow that wants a gate.
+
+**A finding is placed against the note, not the pack it was read from.** The
+address space is read from compiled output because that is what actually ships;
+the content tree is read only to find the note carrying the id, so the reader
+lands on the `shortcode:` line they just edited. A withdrawal has no such note,
+so it degrades to the baseline document — and where neither is readable the
+position is dropped rather than guessed.
+
+**The baseline is named, never derived, and never downloaded.** `--from` takes
+the artifact for the same reason `deps fetch --from` does: a command that
+reaches the network on its own is not reproducible and fails strangely offline.
+A baseline that yields **no** addressable item is refused rather than read as
+"nothing changed" — it would report a clean result for every possible input,
+which is the one failure a check like this can never catch.
+
+Item packs only, because that is the address space consumers resolve against: a
+being's embedded items are the only cross-package resolution by
+`(type, shortcode)`.
+
 ## Diagnostics
 
 Every warning or error a build reports **about a content note** is emitted in the
@@ -956,6 +1162,24 @@ Two rules keep it that way, both in `engine/diagnostics.mjs`:
   meaningless, `file: …` when only the note is known. Nothing defaults to
   `1:1`, which would send a reader to the frontmatter every time.
 
+**A configuration error is located the same way.** Every check in
+`content-config.mjs` and `config.mjs` reports through one `fail()`, naming the
+offending key's dotted path — a good description and a bad locator, in a file
+that runs to hundreds of lines with sibling entries flow-mapped onto one. The
+path now rides on the error, and the loader that read the file resolves it
+against the YAML, so all of them come out located:
+
+```text
+package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner).
+```
+
+The same two rules apply. A key the file never declares — a required one that is
+simply missing — has no node of its own, so the position names the **mapping it
+belongs in** and no further out; a missing _top-level_ key has nothing above it
+but the document, and an `.mjs` configuration has no YAML to resolve a path
+against at all. Both report `package-build.config.yaml: error: …`, the file
+without a line, rather than a line that would be wrong.
+
 Establishing a position at all takes three corrections, applied only where they
 hold — see `positionInBody`. A body offset is not a file line until the
 frontmatter's lines are added (`bodyLine`); the trim that strips the body can

package/bin/content-build.mjs

@@ -45,6 +45,7 @@
  *   npx content-build manifest [root] [--out <dir>]
  *   npx content-build site [--out <dir>]
  *   npx content-build reachability <dir> [file] [--index <shortcode>]
+ *   npx content-build addresses diff --from <zip|dir> [--strict]
  *
  * In a consuming repository, wrapped as npm scripts — SoHL spells them:
  *   npm run build:compiledb                // → … package compile (all packs)
@@ -92,6 +93,14 @@ import {
     walkReachability,
 } from "../engine/content-links.mjs";
 import { emitDiagnostic, positionOfLiteral } from "../engine/diagnostics.mjs";
+import {
+    readItemAddresses,
+    diffItemAddresses,
+    noteFilesById,
+    locateAddressFinding,
+    addressFindingMessage,
+} from "../engine/address-diff.mjs";
+import { itemPackJsonDirs } from "../engine/generate.mjs";
 import {
     formatUnaddressableFinding,
     unaddressableForeignPackages,
@@ -147,6 +156,25 @@ prefix.apply(log, {
     },
 });
 
+/**
+ * Report a command's failure.
+ *
+ * A configuration error carries its own `file:line:column: error: ` locator
+ * (#95), and `loglevel`'s `[timestamp] [ERROR]:` prefix occupies exactly the
+ * position a parser reads the path from — so a located failure is printed
+ * unprefixed, as `emitDiagnostic` prints every other finding. Everything else
+ * is ordinary prose and keeps the log line it always had.
+ *
+ * @param {unknown} err - What was thrown.
+ * @returns {void}
+ */
+function reportFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/** @type {{located?: boolean}} */ (err)?.located)
+        console.error(message);
+    else log.error(message);
+}
+
 const argv = yargs(hideBin(process.argv))
     .command(packageCommand())
     .command(depsCommand())
@@ -158,6 +186,7 @@ const argv = yargs(hideBin(process.argv))
     .command(manifestCommand())
     .command(siteCommand())
     .command(reachabilityCommand())
+    .command(addressesCommand())
     .version(ownVersion())
     .help()
     .alias("help", "h")
@@ -293,7 +322,7 @@ function docsCommand() {
                     process.stdout.write(page);
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -340,7 +369,11 @@ function lintCommand() {
                 const root = argv.root ?? config.paths.content;
                 const manifestDir = argv.manifests ?? config.paths.manifests;
 
-                const addresses = lintContentTree(root);
+                // The package is passed for the homepage rule (#52), which
+                // names the address a tree with no front page fails to serve.
+                const addresses = lintContentTree(root, {
+                    contentPackage: config.contentPackage,
+                });
                 // One index, built once, for the reference check. It is the
                 // same resolver the wikilink audit uses, so a frontmatter
                 // reference and a body link answer the same way.
@@ -371,7 +404,7 @@ function lintCommand() {
                     );
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -452,7 +485,7 @@ function formatCommand() {
                     log.info(`Formatting is clean (${checked} file(s)).`);
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -501,7 +534,7 @@ function markdownCommand() {
                     log.info("Markdown is clean.");
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -649,7 +682,7 @@ function linksCommand() {
                     );
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -725,7 +758,7 @@ function manifestCommand() {
                     });
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -767,6 +800,11 @@ function siteCommand() {
                 });
                 const { gates } = result;
 
+                // First, because it is decided before the tree is walked and
+                // before the output is cleared: a package with no front page,
+                // or two competing for it, has nothing to say about its pages
+                // yet (#52).
+                for (const f of gates.homepages) emitDiagnostic(f);
                 for (const f of gates.frontmatterLinks) {
                     emitDiagnostic({
                         file: f.file,
@@ -849,7 +887,7 @@ function siteCommand() {
                         `landing(s) to ${path.relative(process.cwd(), s.out)}`,
                 );
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -943,7 +981,7 @@ function reachabilityCommand() {
                     );
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },
@@ -1032,6 +1070,154 @@ function depsCommand() {
                 const count = await fetchAllCatalogs(config);
                 if (count)
                     log.info(`Fetched ${count} dependency catalogue(s).`);
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
+/**
+ * `addresses diff` — report every published `(type, shortcode)` this build no
+ * longer publishes, against a released artifact.
+ *
+ * The address space is a published interface (see `engine/address-diff.mjs`),
+ * and renaming a shortcode used to cost nothing and produce no signal. This is
+ * the signal, emitted in the repository doing the renaming while the change is
+ * still in front of the author.
+ *
+ * **Its own command rather than a step of `package compile`.** It reads a
+ * *second* artifact that the compile knows nothing about and that has to be
+ * obtained separately, and it is a question about a release rather than about a
+ * build — a repository between releases has nothing to compare against.
+ *
+ * **The baseline is named, never derived, and never downloaded.** `--from`
+ * takes the artifact — the `.zip` a release publishes, or a directory built
+ * from one — for the same reason `deps fetch --from` does: a command that
+ * reaches the network on its own is not reproducible and fails strangely
+ * offline. In a release workflow the artifact is one line ahead of it:
+ *
+ * ```sh
+ * gh release download v0.8.2 -p system.zip -D build/baseline
+ * npx content-build addresses diff --from build/baseline/system.zip
+ * ```
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{from: string, strict?: boolean}} argv - The parsed arguments.
+ * @returns {Promise<void>}
+ */
+async function diffAddresses(config, argv) {
+    // The baseline is this package's own earlier self, so it is cached beside
+    // the dependency catalogues rather than among them — a release of `sohl`
+    // is not a dependency of `sohl`, and filing it as one would collide with a
+    // genuine relationship of the same id.
+    const cacheConfig = {
+        ...config,
+        paths: {
+            ...config.paths,
+            foreignCache: path.join(
+                path.dirname(config.paths.foreignCache),
+                "baseline",
+            ),
+        },
+    };
+    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 currentDirs = itemPackJsonDirs(config);
+    if (!currentDirs.length) {
+        throw new Error(
+            'this repository declares no pack of type "Item", so it ' +
+                "publishes no item addresses to diff",
+        );
+    }
+
+    const findings = diffItemAddresses(
+        readItemAddresses(baselineDirs),
+        readItemAddresses(currentDirs),
+        { baseline: label },
+    );
+    if (!findings.length) {
+        log.info(`Every address ${label} published is still published.`);
+        return;
+    }
+
+    // A rename is fixed in the note that made it, so findings are placed
+    // against the tree rather than against the compiled output they were read
+    // from.
+    const noteFiles = noteFilesById(config.paths.content);
+    const severity = argv.strict ? "error" : "warning";
+    for (const finding of findings) {
+        emitDiagnostic({
+            ...locateAddressFinding(finding, noteFiles),
+            severity,
+            message: addressFindingMessage(finding),
+        });
+    }
+    const renamed = findings.filter((f) => f.kind === "renamed").length;
+    log.info(
+        `${findings.length} address(es) ${label} published are no longer ` +
+            `published (${renamed} renamed, ${findings.length - renamed} ` +
+            `withdrawn).`,
+    );
+    // Retiring content is legitimate and so is renaming; neither fails a build
+    // unless the caller asked for a gate.
+    if (argv.strict) process.exitCode = 1;
+}
+
+function addressesCommand() {
+    return {
+        command: "addresses <action>",
+        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.
+            yargs.positional("action", {
+                describe: "The action to perform.",
+                type: "string",
+                choices: ["diff"],
+            });
+            yargs.option("from", {
+                describe:
+                    "The released artifact to compare against — a package " +
+                    "zip, or the directory it was built from.",
+                type: "string",
+            });
+            yargs.option("strict", {
+                describe:
+                    "Report findings as errors and exit non-zero, for a " +
+                    "release workflow that gates on them.",
+                type: "boolean",
+                default: false,
+            });
+            // Checked while parsing, so it fails in a repository whose
+            // configuration a handler would never get far enough to resolve.
+            yargs.check((parsed) => {
+                if (parsed.action === "diff" && !parsed.from) {
+                    throw new Error(
+                        "`addresses diff` needs `--from <zip|dir>`: the " +
+                            "release to compare against. There is nothing to " +
+                            "derive it from — a repository between releases " +
+                            "has no previous artifact on disk.",
+                    );
+                }
+                return true;
+            });
+        },
+        handler: async (argv) => {
+            try {
+                await diffAddresses(loadPackConfig(), argv);
             } catch (err) {
                 log.error(err.message);
                 process.exitCode = 1;
@@ -1095,7 +1281,7 @@ function packageCommand() {
                         });
                 }
             } catch (err) {
-                log.error(err.message);
+                reportFailure(err);
                 process.exitCode = 1;
             }
         },

package/bin/package-build.mjs

@@ -135,7 +135,14 @@ function ownVersion() {
  */
 function die(err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`package-build: ${message}`);
+    // A located diagnostic already starts with `file:line:column:`, which is
+    // exactly the position a parser reads the path from — prefixing it would
+    // yield a filename no editor can open (#95).
+    console.error(
+        /** @type {{located?: boolean}} */ (err)?.located ? message : (
+            `package-build: ${message}`
+        ),
+    );
     process.exit(1);
 }