@heroiclands/package-build 5.0.0 → 6.1.0

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,
@@ -158,6 +167,7 @@ const argv = yargs(hideBin(process.argv))
     .command(manifestCommand())
     .command(siteCommand())
     .command(reachabilityCommand())
+    .command(addressesCommand())
     .version(ownVersion())
     .help()
     .alias("help", "h")
@@ -340,7 +350,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.
@@ -366,7 +380,8 @@ function lintCommand() {
                 } else {
                     log.info(
                         `Addresses and frontmatter are well-formed ` +
-                            `(${addresses.keys} across ${addresses.notes} note(s)).`,
+                            `(${addresses.keys} address(es) across ` +
+                            `${addresses.notes} note(s)).`,
                     );
                 }
             } catch (err) {
@@ -582,6 +597,7 @@ function linksCommand() {
                     deadAnchors,
                     deadAddresses,
                     frontmatterLinks,
+                    homepageLinks,
                     usedManifest,
                 } = auditLinks(index);
 
@@ -614,10 +630,24 @@ function linksCommand() {
                     });
                 }
 
+                // The package homepage. Its addresses are markdown links and
+                // `landing:` url/href fields rather than wikilinks — it is
+                // published verbatim, so nothing resolves a wikilink on it —
+                // and until #54 nothing looked at them at all.
+                for (const h of homepageLinks) {
+                    emitDiagnostic({
+                        file: h.note.file,
+                        ...positionOfLiteral(h.note.raw, h.text, h.occurrence),
+                        severity: "error",
+                        message: `${h.field}: ${h.message}`,
+                    });
+                }
+
                 const failures =
                     deadAnchors.length +
                     deadAddresses.length +
-                    frontmatterLinks.length;
+                    frontmatterLinks.length +
+                    homepageLinks.length;
                 if (failures) {
                     log.error(
                         `${failures} link problem(s) across ${index.notes.length} note(s).`,
@@ -628,7 +658,8 @@ function linksCommand() {
                         `${index.notes.length} notes: every anchor link lands ` +
                             `and every qualified address resolves ` +
                             `(${usedManifest.size} cross-package reference(s) ` +
-                            `via manifest), no wikilink in frontmatter.`,
+                            `via manifest), no wikilink in frontmatter, ` +
+                            `every homepage address resolvable.`,
                     );
                 }
             } catch (err) {
@@ -750,6 +781,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,
@@ -1023,6 +1059,154 @@ function depsCommand() {
     };
 }
 
+/**
+ * `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;
+            }
+        },
+    };
+}
+
 function packageCommand() {
     return {
         command: "package <action> [pack] [entry]",

package/bin/package-build.mjs

@@ -78,7 +78,7 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
-import { loadPackConfig } from "../engine/pack-config.mjs";
+import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { validateLangSource } from "../lang.mjs";
 import {
@@ -354,6 +354,8 @@ function manifestCommand() {
                 artifact: config.artifact,
                 outDir: path.join(config.rootDir, config.stageDir),
                 flags,
+                // So a `packFolders` finding names the line it is about.
+                configFile: packConfigPath(),
             });
             console.log(
                 `✅ Wrote ${path.relative(config.rootDir, written)} ` +

package/content-config.mjs

@@ -602,7 +602,7 @@ const SITE_KEYS = [
     "backfillSections",
 ];
 const SITE_TREE_KEYS = ["from", "section"];
-const SECTION_META_KEYS = ["title", "banner"];
+const SECTION_META_KEYS = ["title", "banner", "description"];
 const DOC_PAGE_KEYS = ["title", "out", "preamble"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
 const RELATIONSHIP_KEYS = [
@@ -973,16 +973,32 @@ function normalizeDocs(value) {
 }
 
 /**
- * One section's landing metadata — the title and hero a generated `_index.md`
- * carries.
- *
- * `banner` is optional because the hero images are external assets and not
- * every section has one. It is left off entirely rather than written as
+ * One section's landing metadata — what a section says about itself on the
+ * `_index.md` this build generates for it.
+ *
+ * A generated landing is the *only* place a section can speak: a content
+ * package has no authored `_index.md` for `weapongear` or `affliction`, so the
+ * file the theme reads is the one the site build writes. This is therefore the
+ * whole vocabulary, and it is deliberately a **closed** one.
+ *
+ * The alternative — passing whatever a section declared straight through, as
+ * `site.landing` does — was weighed and refused. `landing` is written once, for
+ * the mount, and its keys are one landing template's own; a section entry is
+ * written fourteen to twenty times per build against a contract every package
+ * and every section shares. Unbounded there, a mistyped `descrption:` publishes
+ * into front matter, is read by nobody, and says nothing to anyone — which is
+ * the failure #91 was filed about, moved one step downstream where no build can
+ * see it. So the keys are named here, and the writers emit what this produced
+ * rather than transcribing a second list of their own (#91).
+ *
+ * `banner` and `description` are optional — the hero images are external assets
+ * and not every section has one, and a section may reasonably have nothing to
+ * add to its title. Each is left off entirely rather than written as
  * `undefined`, which is not a value YAML can carry.
  *
  * @param {unknown} value - The declared entry.
  * @param {string} where - Dotted path, for the error.
- * @returns {Readonly<{title: string, banner?: string}>}
+ * @returns {Readonly<{title: string, banner?: string, description?: string}>}
  */
 function normalizeSectionMeta(value, where) {
     if (!isPlainObject(value)) fail(where, "must be a mapping");
@@ -992,6 +1008,12 @@ function normalizeSectionMeta(value, where) {
     if (input.banner !== undefined) {
         out.banner = requireNonEmptyString(input.banner, `${where}.banner`);
     }
+    if (input.description !== undefined) {
+        out.description = requireNonEmptyString(
+            input.description,
+            `${where}.description`,
+        );
+    }
     return Object.freeze(out);
 }
 

package/engine/address-diff.mjs

@@ -0,0 +1,290 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Diffing a package's published item addresses against a released one (#66).
+ *
+ * A package's `(type, shortcode)` addresses are a **published interface**.
+ * Every satellite that declares `itemCatalog: true` assembles its beings out of
+ * them — `attribute:str`, `skill:awar`, `weapongear:Tabri` — resolving each one
+ * against the Item packs of the release its `compatibility.verified` pins. So
+ * renaming a shortcode is a breaking change to something other repositories
+ * consume, and until this module there was nothing that noticed: 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, so the rename is self-contained". 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, with an error reading like a missing item.
+ *
+ * **The comparison is release-to-release, in the repository doing the
+ * renaming.** The alternative — checking a consumer's addresses against its
+ * pinned release — already exists and already fails the build (`no predefined
+ * item for "weapongear:Taburi"`); what it lacks is an explanation, and it
+ * cannot honestly produce one, because at the point of the miss all it holds is
+ * the address string. It has no document id and no name to match a candidate
+ * against, so any successor it named would be a guess at a similar-looking
+ * string. Here both sides are whole documents, so the question is decidable.
+ *
+ * **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, and the `Tabri` → `Taburi` commit changed
+ * the shortcode alone. So an address that disappeared while its document is
+ * still published elsewhere *is* a rename — not "probably" one. When the id is
+ * published under no address at all, that is all this can say: **withdrawn**,
+ * with no successor named. A split, a deletion and a merge are indistinguish-
+ * able from one another at that point, and inventing a "did you mean" from
+ * string similarity would be worse than saying nothing, because a wrong one
+ * sends the reader to the wrong fix.
+ *
+ * **Severity is decided per case.** A withdrawal is legitimate — content is
+ * allowed to be retired — so it is reported and does not fail a build. A rename
+ * is equally legitimate as a decision (#1397's charset rule forces some), which
+ * is why it does not fail one either; what it must not do is happen in silence.
+ * A caller that wants a gate passes `error` and treats any finding as one.
+ *
+ * Item packs only, because that is the address space consumers resolve
+ * against: {@link foreignItemCatalogDirs} extracts nothing else, and a being's
+ * embedded items are the only cross-package resolution by `(type, shortcode)`.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { formatDiagnostic, positionInFrontmatter } from "./diagnostics.mjs";
+import { positionOfLiteral } from "./diagnostics.mjs";
+import { walkMarkdownTree } from "./helpers.mjs";
+
+/**
+ * The address space a set of compiled Item pack directories publishes.
+ *
+ * The directories are read as one space for the same reason the actors pass
+ * reads them as one: a being names an item by `(type, shortcode)` and never by
+ * the pack it happens to ship in. Both sides of a diff are built by this one
+ * function, so a released catalogue extracted by `deps fetch` and a freshly
+ * compiled pack are indexed identically and a difference between them is a real
+ * one rather than an artefact of two readers.
+ *
+ * A missing directory throws rather than reading as an empty space: an empty
+ * baseline would report every address in the package as withdrawn, and an empty
+ * current side would report every address as gone — the loudest possible
+ * output from the quietest possible mistake.
+ *
+ * @param {readonly string[]} dirs - Directories of item JSON.
+ * @returns {Map<string, {id: string, name: string, type: string, shortcode: string, file: string}>}
+ *   Every item, keyed `type:shortcode`.
+ */
+export function readItemAddresses(dirs) {
+    const space = new Map();
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir)) {
+            throw new Error(
+                `Item source directory ${dir} does not exist — an address ` +
+                    `diff reads compiled Item pack output, so those packs ` +
+                    `must be compiled (or the catalogue fetched) first`,
+            );
+        }
+        for (const name of fs.readdirSync(dir)) {
+            if (!name.endsWith(".json")) continue;
+            if (name.startsWith("folder_")) continue;
+            const file = path.join(dir, name);
+            let doc;
+            try {
+                doc = JSON.parse(fs.readFileSync(file, "utf8"));
+            } catch {
+                // Unparseable output is the compile's problem to report, not
+                // this pass's; skipping it here loses one address rather than
+                // failing a diff that has nothing to do with it.
+                continue;
+            }
+            const shortcode = doc?.system?.shortcode;
+            if (!doc?.type || !shortcode || !doc?._id) continue;
+            space.set(`${doc.type}:${shortcode}`, {
+                id: doc._id,
+                name: doc.name ?? "",
+                type: doc.type,
+                shortcode,
+                file,
+            });
+        }
+    }
+    return space;
+}
+
+/**
+ * Every address the baseline published that this build does not.
+ *
+ * An address that merely *arrived* is not a finding: adding one breaks nobody.
+ * The arrivals are read only to answer the one question that matters about a
+ * departure — is the document still here under another name?
+ *
+ * @param {Map<string, object>} baseline - The released address space.
+ * @param {Map<string, object>} current - This build's address space.
+ * @param {object} opts
+ * @param {string} opts.baseline - What the baseline is, for the message —
+ *   conventionally `<package>@<version>`.
+ * @returns {Array<object>} One finding per departed address, in address order
+ *   so two runs read the same. `kind` is `"renamed"` (with `to`) or
+ *   `"withdrawn"`.
+ */
+export function diffItemAddresses(baseline, current, { baseline: label }) {
+    // A baseline that yields no address at all cannot produce a finding, so it
+    // reports a clean result for every possible input — the one failure a check
+    // like this can never catch, and the same one `foreign-manifests.mjs` exists
+    // to stop. It is a real state, not a hypothetical: `sohl-kethira-basic@0.5.3`
+    // shipped 307 items carrying no `system.shortcode` between them.
+    if (!baseline.size) {
+        throw new Error(
+            `${label} publishes no addressable item — no document in its Item ` +
+                `packs carries a \`system.shortcode\`. A diff against it can ` +
+                `only report that nothing changed, whatever this build does, ` +
+                `so it is refused rather than passed`,
+        );
+    }
+    // Where each still-published document lives now. Built once: a rename is
+    // decided by identity, so this is the whole evidence base.
+    const currentById = new Map();
+    for (const [address, entry] of current) {
+        if (!currentById.has(entry.id)) currentById.set(entry.id, address);
+    }
+
+    const findings = [];
+    for (const [address, entry] of baseline) {
+        if (current.has(address)) continue;
+        const to = currentById.get(entry.id);
+        findings.push({
+            kind: to ? "renamed" : "withdrawn",
+            address,
+            ...(to ? { to } : {}),
+            id: entry.id,
+            name: entry.name,
+            shortcode: entry.shortcode,
+            baselineFile: entry.file,
+            baseline: label,
+        });
+    }
+    findings.sort((a, b) => (a.address < b.address ? -1 : 1));
+    return findings;
+}
+
+/**
+ * Every content note in a tree, indexed by the document id it authors.
+ *
+ * The address space is read from compiled output because that is what actually
+ * ships; the tree is read only to place a finding somewhere a reader can open
+ * and fix it. Each source answers the question it is good at, and the id is the
+ * exact key that joins them.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Passed to the walk.
+ * @returns {Map<string, string>} Document id → the note's absolute path.
+ */
+export function noteFilesById(contentBase, { skipDirectories } = {}) {
+    const byId = new Map();
+    const walkOpts = skipDirectories ? { skipDirectories } : undefined;
+    for (const { frontmatter: fm, absPath } of walkMarkdownTree(
+        contentBase,
+        walkOpts,
+    )) {
+        if (fm?.id && !byId.has(fm.id)) byId.set(fm.id, absPath);
+    }
+    return byId;
+}
+
+/**
+ * Where to send the reader for one finding.
+ *
+ * A rename is fixed in the note that made it, so a finding whose id is still in
+ * this tree is reported at that note's `shortcode:` line — the line the author
+ * just edited. A withdrawal has no such note by definition, so it degrades to
+ * the baseline document, which is the only artefact left that records the
+ * address existing. When neither is readable the position is **dropped**, never
+ * defaulted to `1:1`.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @param {Map<string, string>} noteFiles - From {@link noteFilesById}.
+ * @returns {{file?: string, line?: number, column?: number}} Spreadable
+ *   position fields for {@link formatDiagnostic}.
+ */
+export function locateAddressFinding(finding, noteFiles) {
+    const note = noteFiles?.get(finding.id);
+    if (note) {
+        try {
+            const raw = fs.readFileSync(note, "utf8");
+            return { file: note, ...positionInFrontmatter(raw, "shortcode") };
+        } catch {
+            return { file: note };
+        }
+    }
+    if (!finding.baselineFile) return {};
+    try {
+        const raw = fs.readFileSync(finding.baselineFile, "utf8");
+        return {
+            file: finding.baselineFile,
+            ...positionOfLiteral(raw, `"${finding.shortcode}"`),
+        };
+    } catch {
+        return { file: finding.baselineFile };
+    }
+}
+
+/**
+ * What one finding says, without a locator or a severity.
+ *
+ * The rename message names the identity it matched on, because that is what
+ * separates this from a spelling suggestion: the reader can check the id in
+ * both artefacts. The withdrawal message names no successor, because none is
+ * known — and says so, rather than leaving the reader to wonder whether one was
+ * looked for.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @returns {string} The message.
+ */
+export function addressFindingMessage(finding) {
+    if (finding.kind === "renamed") {
+        return (
+            `since ${finding.baseline}, ${finding.address} is no longer ` +
+            `published; the same document (${finding.id}) is now published ` +
+            `as ${finding.to}. Every package that resolves ${finding.address} ` +
+            `breaks when it moves past ${finding.baseline}`
+        );
+    }
+    return (
+        `since ${finding.baseline}, ${finding.address} is no longer ` +
+        `published, and its document (${finding.id}) is published under no ` +
+        `other address`
+    );
+}
+
+/**
+ * One finding, in the standard `file:line:column: severity: message` form.
+ *
+ * @param {object} finding - One finding from {@link diffItemAddresses}.
+ * @param {{file?: string, line?: number, column?: number}} at - From
+ *   {@link locateAddressFinding}.
+ * @param {"warning"|"error"} [severity] - `error` when the caller is gating.
+ * @returns {string} The formatted diagnostic, path first on the line.
+ */
+export function formatAddressFinding(finding, at, severity = "warning") {
+    return formatDiagnostic({
+        ...at,
+        severity,
+        message: addressFindingMessage(finding),
+    });
+}

package/engine/base-compiler.mjs

@@ -34,9 +34,11 @@
  * | {@link BasePackCompiler#finish} | Work that needs every note first. |
  * | {@link BasePackCompiler#reportCompiled} / {@link BasePackCompiler#reportDetail} | The pass's own log lines. |
  *
- * plus two static switches — `requiresId` (a note with no id is fatal, or
- * merely skipped) and `convertsWikilinks` (whether the body reaching
- * `buildEntry` is converted or exactly as authored).
+ * plus three static switches — `requiresId` (a note with no id is fatal, or
+ * merely skipped), `convertsWikilinks` (whether the body reaching
+ * `buildEntry` is converted or exactly as authored) and `readsPackOutputOf`
+ * (the document types whose compiled output this pass reads, which is what the
+ * generator derives the compile order from).
  *
  * `selects` answers *which document type* a pass claims, and it is the same
  * answer for every pack of that type. Which **pack of that type** a claimed
@@ -141,6 +143,29 @@ export class BasePackCompiler {
      */
     static convertsWikilinks = true;
 
+    /**
+     * The document types whose **compiled output** this pass reads.
+     *
+     * Empty for every pass that reads only the content tree. The actors pass
+     * is the exception: a being names its embedded items by
+     * `(type, shortcode)`, and it resolves them against the JSON the item
+     * passes wrote — so an Actor pass must run after every Item pass, and it
+     * says so here.
+     *
+     * The generator derives the compile order from this (#73), so the order
+     * `packs:` declares is presentation only — it is the manifest's `packs`
+     * array as well, and a consumer orders that for a reader. A pass that
+     * reads another's output states the dependency once, in the class that
+     * does the reading, instead of every consuming repository having to know
+     * it when writing its pack list.
+     *
+     * A consumer registering a compiler of its own declares its dependencies
+     * the same way; a type no pack declares is simply not waited for.
+     *
+     * @type {readonly string[]}
+     */
+    static readsPackOutputOf = Object.freeze([]);
+
     /** @type {string} */
     contentBase;
     /** @type {string} */