@heroiclands/package-build 5.0.0 → 6.0.0

package/engine/homepage.mjs

@@ -56,6 +56,8 @@
  * @module
  */
 
+import { matchAllOutsideCode } from "./code-fences.mjs";
+
 /**
  * The note type that compiles to the package homepage.
  *
@@ -148,3 +150,110 @@ export function homepageFrontmatter(fm, { contentPackage, title }) {
     delete data.aliases;
     return data;
 }
+
+/**
+ * An inline markdown link — `[text](target)`, but not an image.
+ *
+ * Reference-style links are deliberately not matched: a landing's prose fields
+ * are single YAML scalars with nowhere to put a link definition, so a `[x][y]`
+ * in one could never resolve and is not an address anybody wrote.
+ *
+ * @type {RegExp}
+ */
+const MARKDOWN_LINK = /(?<!!)\[[^\]]*\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g;
+
+/**
+ * The two frontmatter keys that hold an address, and what each one means.
+ *
+ * They are **not** interchangeable, and a check that treated them as one would
+ * be wrong about both. The theme resolves a `url` against the site with
+ * `relURL`, so a package writes `kb/rules/` and is served `/sohl/kb/rules/`
+ * without ever naming its own prefix. An `href` is an address that is *already*
+ * resolved and is used verbatim — which is what `cards.source: sections` fills
+ * in, since a section's permalink already carries the prefix.
+ *
+ * So a leading `/` is a defect in a `url` (it is prefixed a second time) and
+ * correct in an `href`.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const HOMEPAGE_ADDRESS_KEYS = Object.freeze(new Set(["url", "href"]));
+
+/**
+ * Collect the markdown links in one prose value.
+ *
+ * @param {string} text - The value.
+ * @param {string} field - Where it came from.
+ * @param {string} kind - The address kind to record.
+ * @param {object[]} out - Accumulator.
+ * @param {boolean} [skipCode] - Whether to ignore links inside code.
+ */
+function collectProse(text, field, kind, out, skipCode = false) {
+    const pattern = new RegExp(MARKDOWN_LINK.source, "g");
+    const matches =
+        skipCode ?
+            matchAllOutsideCode(text, pattern)
+        :   [...text.matchAll(pattern)];
+    for (const m of matches) out.push({ field, url: m[1], kind });
+}
+
+/**
+ * Every address a homepage carries, wherever it is written.
+ *
+ * **Both halves of the page are in scope, and that is the finding rather than
+ * the assumption.** Of the six homepages authored today, four carry every link
+ * in the body as ordinary markdown and two carry them in `landing:` — and the
+ * one whose dead links prompted the check has an *empty body*, so a body-only
+ * reading would have found nothing at all on it. A dead link in a card is
+ * exactly as broken as one in a paragraph.
+ *
+ * Three shapes are gathered, and the caller needs to tell them apart because
+ * the rules differ:
+ *
+ * - **`url`** — package-relative, resolved against the site by the theme.
+ * - **`href`** — already resolved, used verbatim.
+ * - **prose and body markdown links** — emitted as written and resolved by the
+ *   browser against the landing's own address, which *is* the package root, so
+ *   a relative one means the same thing a `url` does.
+ *
+ * `banner:` is not an address: it is an image path resolved through the CDN
+ * base, and `banner: none` is a sentinel rather than a target. Top-level
+ * `title` and `description` are not walked either — they are set as text, never
+ * rendered as markdown.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {string} [body] - The note's markdown body.
+ * @returns {Array<{field: string, url: string, kind: string}>} Every address,
+ *   frontmatter first and then the body, each with the dotted path it was
+ *   written at.
+ */
+export function homepageAddresses(fm, body = "") {
+    const out = [];
+
+    const walk = (value, field) => {
+        if (typeof value === "string") {
+            collectProse(value, field, "prose", out);
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((v, i) => walk(v, `${field}[${i}]`));
+            return;
+        }
+        if (!value || typeof value !== "object") return;
+        for (const [key, v] of Object.entries(value)) {
+            const child = `${field}.${key}`;
+            // An address field holds an address, not prose: reading it for
+            // markdown links as well would report the same target twice
+            // whenever one happened to look like a link.
+            if (HOMEPAGE_ADDRESS_KEYS.has(key) && typeof v === "string") {
+                out.push({ field: child, url: v, kind: key });
+                continue;
+            }
+            walk(v, child);
+        }
+    };
+
+    walk(fm?.landing, "landing");
+    collectProse(String(body ?? ""), "body", "body", out, true);
+    return out;
+}

package/engine/pack-config.mjs

@@ -453,6 +453,9 @@ function loadCodeConfig(configPath) {
 /** The loaded configuration, memoised — the file is read at most once. */
 let loaded;
 
+/** The file {@link loadPackConfig} read, alongside the memoised result. */
+let loadedFrom;
+
 /**
  * The consuming repository's resolved, frozen configuration.
  *
@@ -492,5 +495,23 @@ export function loadPackConfig() {
                 YAML.parse(fs.readFileSync(configPath, "utf8")),
                 configPath,
             );
+    loadedFrom = configPath;
     return loaded;
 }
+
+/**
+ * The file {@link loadPackConfig} resolved the configuration from.
+ *
+ * A diagnostic about a *configured* value has to name the file it was declared
+ * in, and re-deriving that path at the point of the finding would be a second
+ * resolution free to disagree with the first — the `PACKAGE_BUILD_CONFIG`
+ * override, the upward walk and the one-file-per-directory rule all have to
+ * come out the same way. This reports the path actually read.
+ *
+ * @returns {string} Its absolute path.
+ * @throws {Error} As {@link loadPackConfig}, when there is no configuration.
+ */
+export function packConfigPath() {
+    loadPackConfig();
+    return /** @type {string} */ (loadedFrom);
+}

package/engine/site-build.mjs

@@ -291,10 +291,16 @@ export function collectHomepages(contentBase, ctx) {
  * Writes each homepage at the package's own root.
  *
  * Its own writer, deliberately small. A homepage is authored markdown published
- * verbatim — no table expansion, no section landing, and (until #54) no link
- * resolution — so routing it through {@link renderPages} would buy it a pipeline
- * it has no input for, and would make homepage-only mode depend on the index,
- * the foreign manifests and the table universe that mode exists to not build.
+ * verbatim — no table expansion, no section landing and no link resolution — so
+ * routing it through {@link renderPages} would buy it a pipeline it has no input
+ * for, and would make homepage-only mode depend on the index, the foreign
+ * manifests and the table universe that mode exists to not build.
+ *
+ * **Verbatim is the answer to #54, not a gap left by it.** A landing's links
+ * could not be *resolved* here without giving `homepage` mode the index its
+ * licensing fence exists to not build, so they are **checked** instead:
+ * {@link auditHomepageLinks} reads the `landing:` addresses and the body's
+ * markdown links, and reports a wikilink on the page rather than resolving one.
  *
  * @param {string} outRoot - The package's site root — the configured `site.out`,
  *   one level above the content mount.

package/manifest.mjs

@@ -49,8 +49,11 @@
  */
 
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import path from "node:path";
 
+import { emitDiagnostic, positionOfYamlPath } from "./engine/diagnostics.mjs";
+
 /**
  * The two package kinds Foundry defines, as the artifact name each one's
  * manifest and release archive are called.
@@ -197,6 +200,130 @@ export function manifestPacks(config) {
     });
 }
 
+/**
+ * Where a `packFolders` declaration lives in the configuration file.
+ *
+ * @type {readonly string[]}
+ */
+const PACK_FOLDERS_PATH = Object.freeze([
+    "packageBuild",
+    "manifest",
+    "packFolders",
+]);
+
+/**
+ * Every pack name a folder tree names, with the folder that named it.
+ *
+ * Foundry nests pack folders three deep — `PackageCompendiumFolder` re-declares
+ * itself while `depth < 4` — so a rule reading only the top level would miss
+ * every nested name in both directions: a broken one it never checked, and a
+ * working one it would then report as ungrouped.
+ *
+ * @param {unknown} folders - A `packFolders` list, or a nested `folders` list.
+ * @param {Array<string|number>} at - Config key path of `folders`.
+ * @returns {Array<{pack: string, folder: string, keyPath: Array<string|number>}>}
+ *   One entry per named pack, in declaration order, depth first.
+ */
+function namedPacks(folders, at) {
+    if (!Array.isArray(folders)) return [];
+    const found = [];
+    folders.forEach((folder, index) => {
+        if (folder === null || typeof folder !== "object") return;
+        const name = String(folder.name ?? "");
+        const packs = Array.isArray(folder.packs) ? folder.packs : [];
+        packs.forEach((pack, position) => {
+            found.push({
+                pack: String(pack),
+                folder: name,
+                keyPath: [...at, index, "packs", position],
+            });
+        });
+        found.push(...namedPacks(folder.folders, [...at, index, "folders"]));
+    });
+    return found;
+}
+
+/**
+ * What `packFolders` and the derived `packs[]` disagree about.
+ *
+ * `packFolders` is the one **declared** manifest key that names something the
+ * build **derives**: every other declared key states a fact about the package
+ * (`title`, `socket`, `grid`) or addresses a staged file (`esmodules`,
+ * `styles`, `languages`), and a staged file is a different relation, checked
+ * against the stage rather than against configuration. So this is the one place
+ * a declaration can go stale against a value the build already computed — and
+ * until now nothing compared them (#81).
+ *
+ * `HarnMaster-3-FoundryVTT` shipped the consequence: its folder named four
+ * packs, three of which had not existed since the compendium was consolidated,
+ * and omitted `items` — 1,577 of 1,597 documents, loose in Foundry's compendium
+ * browser, with the build reporting nothing (HM3#420).
+ *
+ * **The two findings are not the same finding**, and giving them one severity
+ * gets one of them wrong:
+ *
+ * - _A folder names a pack that does not exist_ is an **error**. Foundry
+ *   resolves the name against the package's own packs and silently skips what
+ *   it cannot find, so the declaration does nothing at all; there is no
+ *   arrangement in which it is intended, and the fix is unambiguous.
+ * - _A pack no folder names_ is a **warning**. It is legal and can be
+ *   deliberate — a package may want one pack at the root — so failing on it
+ *   would break working packages for a matter of taste. But a package that
+ *   bothered to declare a folder rarely meant to leave one out, which is
+ *   exactly how HM3's `items` went unnoticed.
+ * - _A package declaring no folders_ says **nothing**. Everything at the root
+ *   is the majority arrangement, not an omission.
+ *
+ * Errors come first, in declaration order, then warnings in pack order: the
+ * unresolvable names are what a reader fixes, and a folder gaining a name often
+ * settles a warning too.
+ *
+ * @param {object} options
+ * @param {unknown} [options.packFolders] - The declared `packFolders`.
+ * @param {ReadonlyArray<{name: string}>} [options.packs] - The derived packs,
+ *   as {@link manifestPacks} returns them.
+ * @returns {Array<{severity: "error"|"warning", message: string, pack: string,
+ *   folder?: string, keyPath: Array<string|number>}>} The findings, ordered.
+ */
+export function packFolderFindings({ packFolders, packs = [] }) {
+    if (!Array.isArray(packFolders) || packFolders.length === 0) return [];
+
+    const shipped = packs.map((pack) => pack?.name).filter(Boolean);
+    const known = new Set(shipped);
+    const named = namedPacks(packFolders, PACK_FOLDERS_PATH);
+    const grouped = new Set(named.map((entry) => entry.pack));
+
+    const findings = named
+        .filter((entry) => !known.has(entry.pack))
+        .map((entry) => ({
+            severity: /** @type {const} */ ("error"),
+            pack: entry.pack,
+            folder: entry.folder,
+            keyPath: entry.keyPath,
+            message:
+                `packFolders: folder "${entry.folder}" names pack ` +
+                `"${entry.pack}", which this package does not ship ` +
+                `(packs: ${shipped.join(", ")})`,
+        }));
+
+    for (const name of shipped) {
+        if (grouped.has(name)) continue;
+        findings.push({
+            severity: /** @type {const} */ ("warning"),
+            pack: name,
+            // No folder omitted it in particular — every one of them did — so
+            // the position is the declaration a reader edits, not one entry
+            // inside it. Each warning names its own pack, so they stay
+            // distinguishable despite sharing a line.
+            keyPath: [...PACK_FOLDERS_PATH],
+            message:
+                `packFolders: pack "${name}" is named by no folder, so it ` +
+                `ships outside every folder this package declares`,
+        });
+    }
+    return findings;
+}
+
 /**
  * Relationship keys that direct the **build**, rather than describe the
  * package.
@@ -330,16 +457,66 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     return ordered;
 }
 
+/**
+ * Report what {@link packFolderFindings} found, and say whether it was fatal.
+ *
+ * The position comes from the configuration file, when one was named and can be
+ * read: a `packFolders` finding is about a line of YAML, and the file is the
+ * only place a line exists. Anything that cannot be established — an `.mjs`
+ * configuration, an unreadable file, a path that resolves to nothing — is
+ * dropped rather than guessed, so the diagnostic degrades from
+ * `file:line:column:` to `file:` to no locator at all.
+ *
+ * @param {ReturnType<typeof packFolderFindings>} findings - What was found.
+ * @param {string} [configFile] - Absolute path of the configuration file.
+ * @returns {number} How many of them were errors.
+ */
+function reportPackFolders(findings, configFile) {
+    if (!findings.length) return 0;
+
+    let text;
+    if (configFile) {
+        try {
+            text = fsSync.readFileSync(configFile, "utf8");
+        } catch {
+            text = undefined;
+        }
+    }
+
+    let errors = 0;
+    for (const finding of findings) {
+        if (finding.severity === "error") errors += 1;
+        emitDiagnostic({
+            ...(configFile ? { file: configFile } : {}),
+            ...(text ? positionOfYamlPath(text, finding.keyPath) : {}),
+            severity: finding.severity,
+            message: finding.message,
+        });
+    }
+    return errors;
+}
+
 /**
  * Write the generated manifest into the staged package.
  *
+ * The declared `packFolders` is checked against the derived `packs[]` first,
+ * and an unresolvable name **stops the write**: a manifest already known to
+ * describe packs the package does not ship should not reach the stage, where
+ * the next command would deploy it (#81). See {@link packFolderFindings} for
+ * the rule and why its two findings carry different severities.
+ *
  * @param {object} options - As {@link buildManifest}, plus where to write.
  * @param {object} options.config - The resolved content configuration.
  * @param {object} options.packageJson - The repository's `package.json`.
  * @param {string} options.artifact - `system` or `module`.
  * @param {string} options.outDir - Directory to write into.
  * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
+ * @param {string} [options.configFile] - Absolute path of the configuration
+ *   file the manifest was resolved from, so a finding about it can be located.
+ *   Omitting it costs the position, not the finding.
  * @returns {Promise<{path: string, manifest: object}>} Where it went, and what.
+ * @throws {Error} When a `packFolders` entry names a pack the package does not
+ *   ship. Nothing is written in that case.
  */
 export async function writeManifest({
     config,
@@ -347,8 +524,26 @@ export async function writeManifest({
     artifact,
     outDir,
     flags,
+    configFile,
 }) {
     const manifest = buildManifest({ config, packageJson, artifact, flags });
+
+    const errors = reportPackFolders(
+        packFolderFindings({
+            packFolders: manifest.packFolders,
+            packs: manifest.packs,
+        }),
+        configFile,
+    );
+    if (errors) {
+        throw new Error(
+            `packFolders names ${errors} pack${errors === 1 ? "" : "s"} this ` +
+                `package does not ship (reported above). Foundry skips a name ` +
+                `it cannot resolve, so the folder would ship missing those ` +
+                `packs — correct \`packageBuild.manifest.packFolders\`.`,
+        );
+    }
+
     await fs.mkdir(outDir, { recursive: true });
     const outPath = path.join(outDir, `${artifact}.json`);
     // Trailing newline: the file is committed to a release archive and read by

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "5.0.0",
+    "version": "6.0.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/sohl/actors.mjs

@@ -186,8 +186,16 @@ function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
     const shadowed = [];
     for (const itemsSourceDir of itemsSourceDirs) {
         if (!fs.existsSync(itemsSourceDir)) {
+            // The generator orders the actors pass after every Item pass (#73),
+            // so a whole-package build cannot reach this. What can is a run
+            // restricted to this one pack, or a caller constructing the
+            // compiler itself — neither of which reordering a pack list fixes,
+            // so the message no longer suggests it.
             throw new Error(
-                `Items source directory ${itemsSourceDir} does not exist — actors must be generated after items`,
+                `Items source directory ${itemsSourceDir} does not exist — ` +
+                    `a being resolves its embedded items against the Item ` +
+                    `packs' compiled output, so those packs must be compiled ` +
+                    `before this one`,
             );
         }
         for (const name of fs.readdirSync(itemsSourceDir)) {
@@ -310,6 +318,11 @@ export class Actors extends BasePackCompiler {
     static id = "actors";
     static label = "actor";
 
+    // A being's embedded items are resolved against the *output* of the item
+    // passes, so every Item pack compiles before this one. Declared rather than
+    // left to the order `packs:` happens to list (#73).
+    static readsPackOutputOf = Object.freeze(["Item"]);
+
     /** @type {readonly string[]} */
     itemsSourceDirs;
     foreignSourceDirs;

package/sohl/item-fields.mjs

@@ -231,11 +231,6 @@ const GEAR_COMMON = Object.freeze([
         value: true,
         describe: "Whether it is being carried. Possession state.",
     },
-    {
-        to: "isEquipped",
-        value: false,
-        describe: "Whether it is equipped. Possession state.",
-    },
 ]);
 
 /* --------------------------------------------------------------------- */

package/sohl/kb-passes.mjs

@@ -27,35 +27,98 @@
  * map sits, what the API is served at, which GitHub tree to link into — is
  * options, supplied beside the name.
  *
- * Neither pass ever fails a build. A `{@link}` the map does not know degrades to
- * a code span, and a relative link that resolves outside the documentation tree
- * becomes a GitHub blob URL. Both are legible to a reader; a broken link or a
- * failed build for a syntax example in prose would not be.
+ * Neither *rewrite* ever fails a build. A `{@link}` the map does not know
+ * degrades to a code span, and a relative link that resolves outside the
+ * documentation tree becomes a GitHub blob URL. Both are legible to a reader; a
+ * broken link or a failed build for a syntax example in prose would not be.
+ *
+ * Building the bundle is a different matter: a `symbolMap` that is configured
+ * and cannot be used fails, loudly, before a page is rendered (#75). Degrading
+ * a tag the map does not know is a judgement about *prose*; degrading every tag
+ * on the site because the map was never read is a build that lied.
  *
  * @module
  */
 
 import fs from "node:fs";
 import path from "node:path";
+import log from "loglevel";
 
 /**
  * Reads the TypeDoc symbol map, or an empty one.
  *
- * Absent is not an error: the map is generated by `npm run docs`, and a
- * knowledgebase build that runs before it — or in a checkout that has never run
- * it — should publish prose with `{@link}` tags degraded to code spans rather
- * than refuse to build.
+ * **Not configuring a map is the empty case, and it is silent.** The map is
+ * generated by `npm run docs`, and a knowledgebase build in a repository that
+ * has no API documentation should publish prose with `{@link}` tags degraded to
+ * code spans rather than refuse to build.
+ *
+ * **Configuring one that cannot be used is a defect, and it fails the build.**
+ * A missing file, a malformed one, a permissions error and a path typo used to
+ * be indistinguishable from each other *and* from a correctly configured build
+ * with no symbols: a bare `catch` returned `{}` for all five. Nothing then
+ * compares an emitted page against what its source asked for, so the first
+ * observer of a broken map was a reader who clicked nothing, because every
+ * `{@link}` on the published site had quietly become a code span (#75).
+ *
+ * The path is resolved against the **repository root**, never the process cwd.
+ * `site.passOptions.symbolMap` is authored repo-relative, so a cwd-relative
+ * read misses the moment `content-build site` is driven from anywhere but the
+ * repository root — which is exactly how #51's end-to-end verification, running
+ * through `PACKAGE_BUILD_CONFIG` from outside the tree, found this.
  *
  * @param {string|undefined} file - Path to the map, if configured.
+ * @param {string|undefined} repoRoot - The repository root to resolve against.
  * @returns {Record<string, string>} Qualified name → API page path.
+ * @throws {Error} When a configured map cannot be resolved, read, parsed, or is
+ *   not a name → page object.
  */
-function readSymbolMap(file) {
+function readSymbolMap(file, repoRoot) {
     if (!file) return {};
+
+    // Refused rather than quietly resolved against the cwd, which is the
+    // defect this function was fixed for: a fallback would let it return.
+    if (!path.isAbsolute(file) && !repoRoot) {
+        throw new Error(
+            `site.passOptions.symbolMap ${JSON.stringify(file)} is relative ` +
+                `and no repoRoot was supplied to resolve it against`,
+        );
+    }
+    const resolved = path.resolve(repoRoot ?? "", file);
+
+    let raw;
     try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    } catch {
-        return {};
+        raw = fs.readFileSync(resolved, "utf8");
+    } catch (err) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} cannot be read: ` +
+                `${err.message}`,
+        );
     }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} is not valid JSON: ` +
+                `${err.message}`,
+        );
+    }
+
+    // `[]`, `"x"` and `null` all parse, and then every lookup misses — the same
+    // silent degradation reached a different way.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(
+            `site.passOptions.symbolMap ${resolved} is not an object mapping ` +
+                `qualified names to API page paths`,
+        );
+    }
+
+    // Reported because a map that loaded and a map that loaded empty are
+    // otherwise indistinguishable without reading the emitted HTML — and an
+    // empty one degrades every tag exactly as a missing one used to.
+    log.info(`resolved ${Object.keys(parsed).length} API symbols from ${file}`);
+    return parsed;
 }
 
 /**
@@ -182,14 +245,18 @@ export function rewriteRepoLinks(body, docRel, options) {
  * Both run inside code-fence protection, so neither can rewrite a fenced example.
  *
  * @param {object} options - Resolved from `site.passOptions`.
- * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map.
+ * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map,
+ *   relative to `repoRoot`. Absent means no API links; present and unusable is
+ *   a build failure.
  * @param {string} [options.apiBase] - Where the API documentation is served.
  * @param {string} [options.blob] - GitHub blob base for repository files.
  * @param {string} options.repoRoot - The repository root, for relative paths.
  * @returns {{beforeLinks: Function, afterLinks: Function}} The bundle.
+ * @throws {Error} When a configured `symbolMap` cannot be resolved, read,
+ *   parsed, or is not a name → page object.
  */
 export function sohlKbPass(options) {
-    const symbols = readSymbolMap(options.symbolMap);
+    const symbols = readSymbolMap(options.symbolMap, options.repoRoot);
     const apiBase = options.apiBase ?? "";
     return {
         beforeLinks: (text) => resolveApiLinks(text, symbols, apiBase),

package/types/engine/base-compiler.d.mts

@@ -57,6 +57,28 @@ export class BasePackCompiler {
      * @type {boolean}
      */
     static convertsWikilinks: boolean;
+    /**
+     * 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: readonly string[];
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.