@heroiclands/package-build 22.5.0 → 22.6.0

package/engine/foundry-entries.mjs

@@ -65,10 +65,13 @@ import {
     NEVER_PACKED_TYPES,
     DERIVED_PACKED_TYPES,
 } from "./note-claims.mjs";
+import { DEFAULT_DOCUMENT_SUBTYPES, SYSTEM_DOCUMENT_CLASSES } from "./subtype-registry.mjs";
+import { carriesSystemBlock } from "./system-block.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
 import { compendiumUuid, currentType, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
+import { journalHasContent } from "./note-state.mjs";
 import { isHomepage } from "./homepage.mjs";
 import { declaresNoPack } from "./pack-router.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
@@ -163,7 +166,19 @@ export function entriesForNote(fm, name, address, body, ctx) {
     // A published address must name the pack the document actually shipped in:
     // a consumer resolves the UUID verbatim, and a repository may ship several
     // packs of one type.
-    const uuidFor = (type, id, routeFm) =>
+    const uuidFor = (type, id, routeFm) => {
+        // **A document that would be empty is not created, so nothing names
+        // one.** A JournalEntry's content is the note's prose, and an empty
+        // body compiles no pages, so the pass emits no entry — and a manifest
+        // naming one would send every consumer to a document that is not
+        // there. Asked of the **document type**, which is what makes one
+        // statement cover both journals a note can produce: its own, and the
+        // documentation standing beside an item. Every other document is
+        // derived from `data:` and is emitted whatever the body holds.
+        if (packForType(type)?.docType === "JournalEntry" && !journalHasContent(body)) {
+            return undefined;
+        }
+
         // A type this cannot name a single compendium document for has no UUID
         // to publish, whatever id it derives. That used to follow from such a
         // note authoring no `id:`; every addressable note derives
@@ -185,21 +200,40 @@ export function entriesForNote(fm, name, address, body, ctx) {
         // statement: it publishes a page and compiles into nothing, so it has
         // an address and no UUID. The shared declaration is what is read,
         // because an entry names one document and this pass routes no system.
-        (
-            id &&
-            !NEVER_PACKED_TYPES.has(String(type)) &&
-            !DERIVED_PACKED_TYPES.has(String(type)) &&
-            !(routeFm && declaresNoPack(routeFm))
-        ) ?
-            compendiumUuid(
-                foundryPackageId,
-                type,
-                id,
-                routeFm ?
-                    packRouter.resolveOrNull(routeFm, packForType(type).docType)
-                :   packRouter.defaultOf("JournalEntry"),
-            )
-        :   undefined;
+        if (
+            !id ||
+            NEVER_PACKED_TYPES.has(String(type)) ||
+            DERIVED_PACKED_TYPES.has(String(type)) ||
+            (routeFm && declaresNoPack(routeFm))
+        ) {
+            return undefined;
+        }
+
+        const docType = routeFm ? packForType(type).docType : "JournalEntry";
+        const pack =
+            routeFm ?
+                packRouter.resolveOrNull(routeFm, docType)
+            :   packRouter.defaultOf("JournalEntry");
+
+        // **A system block is what makes a game document**, so a note carrying
+        // none compiles into no Actor and no Item — and an address naming one
+        // would send every consumer to a document that is not there. The same
+        // statement `pack: none` makes about a pack, made about a system: the
+        // note keeps its address, its page and its prose journal, and publishes
+        // no UUID for the document it does not produce.
+        //
+        // Which block is asked for is the pack's, because the pack decides the
+        // pass: one declaring a `system:` is compiled by that system's pass,
+        // and one declaring none by the fallback, which reads a single block of
+        // its own.
+        if (SYSTEM_DOCUMENT_CLASSES.has(docType)) {
+            const system =
+                (pack && packRouter.systemOf?.(pack)) || DEFAULT_DOCUMENT_SUBTYPES.system;
+            if (!carriesSystemBlock(routeFm, system)) return undefined;
+        }
+
+        return compendiumUuid(foundryPackageId, type, id, pack);
+    };
 
     const carriesDoc =
         ctx.docEntryTypes ?

package/engine/generate.mjs

@@ -102,7 +102,22 @@ const COMPILERS = {
 };
 
 /**
- * The system-specific compilers, by the system a pack declares.
+ * Every pass this toolchain ships that writes one system's data.
+ *
+ * The list a system joins, and the only place it is named. Each class already
+ * declares which system it is for (`documentSubtypes`) and which document it
+ * writes (`documentClass`), so the pairing is read off the passes rather than
+ * spelled a second time beside them — a table keyed by system id is a table
+ * free to disagree with the classes it names, and the way it disagrees is
+ * silent: a system absent from it took the fallback pass and compiled its packs
+ * out of a neighbour's blocks.
+ *
+ * @type {readonly Function[]}
+ */
+const SYSTEM_PASSES = Object.freeze([Items, Actors, Hm3Items, Hm3Actors]);
+
+/**
+ * The system-specific compilers, derived from the passes themselves.
  *
  * A repository feeding two systems declares one Item pack and one Actor pack
  * per system — `harn-ensemble` has `actors-hm3` and `actors-sohl` — and each
@@ -111,28 +126,84 @@ const COMPILERS = {
  * `itemBuilders` lookup already read, so nothing new is declared to make the
  * compiler follow it.
  *
- * A system with no entry — or a pack that declares none — falls back to
- * {@link COMPILERS}. That keeps every single-system configuration meaning
- * exactly what it did: SoHL's passes were the only ones, so they stay the
- * answer where nothing says otherwise.
+ * @param {readonly Function[]} passes - The system passes to table.
+ * @returns {Readonly<Record<string, Readonly<Record<string, Function>>>>}
+ *   System id → document class → pass.
+ * @throws {Error} When a pass declares no system or no document class, which is
+ *   a pass that cannot be addressed by either question this table answers.
+ */
+export function systemCompilers(passes) {
+    /** @type {Record<string, Record<string, Function>>} */
+    const table = {};
+    for (const pass of passes) {
+        const declared =
+            /** @type {{documentSubtypes?: {system?: string},
+             *   documentClass?: string, name: string}} */ (pass);
+        const system = declared.documentSubtypes?.system;
+        const docType = declared.documentClass;
+        if (!system || !docType) {
+            throw new Error(
+                `${declared.name} is registered as a system pass but declares ` +
+                    `${system ? "no `documentClass`" : "no `documentSubtypes`"} — a pass ` +
+                    `writing a system's data states both, so which system and which ` +
+                    `document it answers for is read from the class itself.`,
+            );
+        }
+        (table[system] ??= {})[docType] = pass;
+    }
+    return Object.freeze(
+        Object.fromEntries(
+            Object.entries(table).map(([system, byType]) => [system, Object.freeze(byType)]),
+        ),
+    );
+}
+
+/** @type {Readonly<Record<string, Readonly<Record<string, Function>>>>} */
+const SYSTEM_COMPILERS = systemCompilers(SYSTEM_PASSES);
+
+/**
+ * The document classes some system writes its own data into.
+ *
+ * Derived from {@link SYSTEM_COMPILERS}, so it is the set of classes for which
+ * "which system?" is a question with consequences. Every other class has one
+ * implementation whatever a pack declares.
  *
- * @type {Readonly<Record<string, Readonly<Record<string, Function>>>>}
+ * @type {ReadonlySet<string>}
  */
-const SYSTEM_COMPILERS = Object.freeze({
-    sohl: Object.freeze({ Item: Items, Actor: Actors }),
-    hm3: Object.freeze({ Item: Hm3Items, Actor: Hm3Actors }),
-});
+const SYSTEM_DOCUMENT_CLASSES = Object.freeze(
+    new Set(Object.values(SYSTEM_COMPILERS).flatMap((byType) => Object.keys(byType))),
+);
 
 /**
  * The compiler class a pack of one document type and one system gets.
  *
+ * A pack declaring **no** system takes the fallback pass for its document
+ * class, which reads
+ * {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} — the
+ * single-system convenience every tree shipping for one system is built on.
+ *
+ * A pack declaring a system this toolchain has no pass for is **refused by
+ * name**. Falling through to the fallback would compile that pack out of
+ * another system's blocks and ship it stamped with the system it asked for,
+ * which is the quiet failure the refusal exists to replace.
+ *
  * @param {string} docType - The Foundry document type the pack holds.
  * @param {string|null} [system] - The system the pack declares, if any.
  * @returns {Function|undefined} The compiler class, or `undefined` for a
  *   document type nothing here compiles — which {@link generatePack} reports
  *   rather than defaulting past.
+ * @throws {Error} When a system-bearing document class is asked for a system
+ *   this toolchain ships no pass for.
  */
 export function compilerFor(docType, system = null) {
+    if (system && SYSTEM_DOCUMENT_CLASSES.has(docType) && !SYSTEM_COMPILERS[system]?.[docType]) {
+        throw new Error(
+            `no ${docType} compiler for system "${system}" — this toolchain ships ` +
+                `passes for ${Object.keys(SYSTEM_COMPILERS).sort().join(", ")}. Declare a ` +
+                `system one of those names, or add the pass that reads a ` +
+                `\`${system}:\` block.`,
+        );
+    }
     return (system && SYSTEM_COMPILERS[system]?.[docType]) || COMPILERS[docType];
 }
 

package/engine/infobox-registry.mjs

@@ -58,24 +58,23 @@ export function infoboxFor(system) {
  * Whether one system compiles a document for one note.
  *
  * This is what a system box's _available_ asserts, and it is the compile's own
- * question rather than a reading of the frontmatter. A note carrying no block
- * is not a note a system has nothing for: where the pack compiling its document
- * declares no `system:`, the document is built from `data:` and the field
- * defaults and ships exactly like any other.
+ * question rather than a reading of the frontmatter.
  *
  * Three statements answer it, and they are the three the compile itself
  * follows:
  *
- * 1. **The map** says which document class this system makes of the note's
+ * 1. **The note's block.** A system block is what makes a game document, so a
+ *    note carrying nothing for this system compiles into no document of it
+ *    anywhere — the rule
+ *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
+ *    asked here from outside.
+ * 2. **The map** says which document class this system makes of the note's
  *    type. No row, no document — and no box either, which is why a caller
  *    reaching here already has one.
- * 2. **The router** says which pack that document goes to, read from the pack
- *    list this build is driven by.
- * 3. **That pack's `system:`** decides the rest. Declaring one, it writes that
- *    system's data and takes only notes that say something about it — the rule
- *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
- *    asked here from outside. Declaring none, it is compiled by the fallback
- *    pass, which needs no block and answers for
+ * 3. **The router** says which pack that document goes to, read from the pack
+ *    list this build is driven by, and **that pack's `system:`** decides whose
+ *    it is. Declaring one, it writes that system's data. Declaring none, it is
+ *    compiled by the fallback pass, which reads
  *    {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} alone —
  *    so a tree with no HM3 pack ships no HM3 document however a note is
  *    written.
@@ -86,6 +85,8 @@ export function infoboxFor(system) {
  * @returns {boolean} True when this system compiles a document for this note.
  */
 export function compilesSystemDocument(fm, map, router) {
+    if (!carriesSystemBlock(fm, map.block)) return false;
+
     const row = subtypeRow(map, fm?.type);
     if (!row?.document) return false;
 
@@ -94,7 +95,7 @@ export function compilesSystemDocument(fm, map, router) {
 
     const packSystem = router.systemOf(packName);
     if (!packSystem) return map.system === DEFAULT_DOCUMENT_SUBTYPES.system;
-    return packSystem === map.system && carriesSystemBlock(fm, map.block);
+    return packSystem === map.system;
 }
 
 /**

package/engine/item-compiler.mjs

@@ -116,6 +116,18 @@ export class SystemItemCompiler extends BasePackCompiler {
      */
     static requiresSystemBlock = true;
 
+    /**
+     * The Foundry document class this pass writes.
+     *
+     * Declared by the class that does the writing, so the table pairing a
+     * system with its passes is derived from the passes themselves rather than
+     * written out a second time — see
+     * {@link module:engine/generate.systemCompilers}.
+     *
+     * @type {string}
+     */
+    static documentClass = "Item";
+
     /**
      * An Item carries one piece of art — its icon — which this pass writes from
      * the address the note names, falling back to the type's default art.

package/engine/journals.mjs

@@ -55,6 +55,7 @@ import { infoboxesToHtml, linkToUuid } from "./infobox-render.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { JOURNAL_TYPES } from "./ids.mjs";
+import { journalHasContent } from "./note-state.mjs";
 
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
@@ -382,17 +383,24 @@ export class Journals extends BasePackCompiler {
     }
 
     /**
-     * An item with no prose gets no doc, and the items pass leaves its
-     * description empty rather than pointing at nothing; a map with no prose
-     * gets no entry and no pin target. The two passes apply the same rule to
-     * the same body, so they agree.
+     * **A journal that would be empty is not created**, and that is the whole
+     * rule — one test, asked of every note this pass claims, whether its
+     * journal is its own document or the documentation standing beside an item.
+     * A note with no prose gets no entry: the items pass leaves its description
+     * empty rather than pointing at nothing, a map gets no pin target, and
+     * {@link module:engine/foundry-entries} publishes no UUID, so nothing names
+     * a document that was not made.
+     *
+     * An entry holding only its infobox is empty by this test. The panel is a
+     * rendering of `data:` that the content index already carries, so a
+     * compendium entry of nothing else tells a reader what the index told them.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {string} body - The note body, frontmatter stripped.
      * @returns {boolean} True to skip the note.
      */
     skipNote(fm, body) {
-        return hasDocEntry(fm.type) && !String(body).trim();
+        return !journalHasContent(body);
     }
 
     /**

package/engine/note-claims.mjs

@@ -94,7 +94,13 @@ import { loadPackConfig } from "./pack-config.mjs";
 import { declaresNoPack } from "./pack-router.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 import { noteTypesFor, subtypeRow } from "./document-subtypes.mjs";
-import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+import {
+    DEFAULT_DOCUMENT_SUBTYPES,
+    KNOWN_DOCUMENT_SUBTYPE_MAPS,
+    SHIPPED_SYSTEMS,
+    subtypeMapFor,
+} from "./subtype-registry.mjs";
+import { carriesSystemBlock } from "./system-block.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { BUNDLE_TYPE } from "./bundle-notes.mjs";
@@ -615,7 +621,92 @@ function authoringMessage(type) {
 }
 
 /**
- * Every note in the content tree that no configured pack would compile.
+ * Which pass would read one system's block, given a configuration's packs.
+ *
+ * A pack declaring `system: hm3` is compiled by the HM3 pass and reads `hm3:`.
+ * A pack declaring **no** system is compiled by the fallback pass, which reads
+ * {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} and nothing
+ * else — so a systemless pack answers for one system, not for every system a
+ * note might carry. That asymmetry is the whole of this question: the router
+ * will happily route an `hm3:` document into a systemless pack, and the pass
+ * waiting there reads a different block.
+ *
+ * A **prebuilt** pack compiles nothing — its JSON is checked in — so it reads
+ * no block either.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {string} docType - The document class the block would compile into.
+ * @param {string} system - The system whose block is in question.
+ * @returns {{packs: number, serving: number}} How many non-prebuilt packs of
+ *   that class the configuration has, and how many of them compile that
+ *   system's documents.
+ */
+function packsServing(config, docType, system) {
+    const packs = (config?.packs ?? []).filter((pack) => !pack?.prebuilt && pack?.type === docType);
+    const serving = packs.filter((pack) =>
+        pack.system ? pack.system === system : system === DEFAULT_DOCUMENT_SUBTYPES.system,
+    );
+    return { packs: packs.length, serving: serving.length };
+}
+
+/**
+ * Every system block on one note that no pack in this package will read.
+ *
+ * **A discarded field is the quiet-failure class the diagnostics exist to
+ * close**, and a system block is the largest field a note can write: a whole
+ * document's worth of authored data, compiled by nobody and reported by
+ * nobody. The claim check beside this one asks whether a note's *type* is
+ * claimed; this asks whether its *systems* are.
+ *
+ * `error`, because the data is lost either way and the author cannot see it
+ * happen. It says nothing about a note carrying **no** block — that note is
+ * making a statement, and the statement is that nobody rolls dice against this
+ * person.
+ *
+ * Silent, too, where the class has no pack at all: the note's whole document is
+ * missing, which {@link partialMessage} already reports with the remedy.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} absPath - The note's path, for the finding's position.
+ * @param {string} type - The note's current type.
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string, type: string}>} One finding per
+ *   discarded block.
+ */
+function discardedSystemBlockFindings(fm, absPath, type, config) {
+    const findings = [];
+    for (const system of SHIPPED_SYSTEMS) {
+        if (!carriesSystemBlock(fm, system)) continue;
+        const docType = subtypeRow(subtypeMapFor(system), type)?.document;
+        // This system makes no document of this note type, so its block says
+        // nothing that could be discarded — it is read for the note's fields
+        // wherever another pass wants them.
+        if (!docType) continue;
+        const { packs, serving } = packsServing(config, docType, system);
+        if (!packs || serving) continue;
+        findings.push({
+            file: absPath,
+            ...locateFrontmatterKey(absPath, system, undefined, { topLevel: true }),
+            severity: /** @type {"error"} */ ("error"),
+            type,
+            message:
+                `carries a \`${system}:\` block, and no ${docType} pack in this ` +
+                `package compiles ${system} documents, so the block is discarded — ` +
+                `declare \`system: ${system}\` on one of the \`packs:\`, or remove ` +
+                `the block.`,
+        });
+    }
+    return findings;
+}
+
+/**
+ * Every note in the content tree that no configured pack would compile, and
+ * every system block no configured pack would read.
+ *
+ * Two questions of one walk, because they are the same question asked of a
+ * note's type and of a note's systems, and a note can fail either while passing
+ * the other — see {@link discardedSystemBlockFindings}.
  *
  * Read-only: it walks the tree and reports, and writes nothing. Three kinds of
  * note are passed over, each for a stated reason rather than by omission — a
@@ -672,6 +763,11 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // lint, which can say what to write instead.
         const current = currentType(type);
 
+        // Asked first, and asked whatever the type's claim turns out to be: a
+        // note whose documents all have packs may still carry a block none of
+        // them reads, and that is invisible to every question below.
+        findings.push(...discardedSystemBlockFindings(fm, absPath, current, config));
+
         // Every document this note produces, against the classes this
         // configuration has a pack for. Three outcomes, and the middle one is
         // the half-claimed one — invisible while the question is only "is anything

package/engine/note-state.mjs

@@ -114,6 +114,35 @@ export function isStubNote(frontmatter, body, vocabulary = NOTE_VOCABULARY) {
     return isEmptyBody(body) && isStubbableType(frontmatter?.type, vocabulary);
 }
 
+/**
+ * Whether a note's body compiles into a JournalEntry that holds anything.
+ *
+ * > **A document that would be empty is not created.** Nothing names one
+ * > either: the index records the note with every field that names an artefact
+ * > set to `null`.
+ *
+ * The question is about the **output**, not the input, and that is what makes
+ * one rule serve every caller: a note's own journal, and the documentation
+ * journal an item's prose compiles into beside it, are the same document asked
+ * the same question.
+ *
+ * A JournalEntry's content is its pages, and a page comes from
+ * {@link module:engine/journals.splitPages} — a lead page of the prose before
+ * the first heading, and one page per heading after it. A body of whitespace
+ * yields neither, so an empty body is exactly an empty journal.
+ *
+ * **An infobox does not count.** The panel is a rendering of `data:`, which the
+ * index already publishes; an entry holding nothing else gives a consumer
+ * nothing it cannot read from the record.
+ *
+ * @param {string|null|undefined} body - The note body, frontmatter stripped.
+ * @returns {boolean} Whether a JournalEntry compiled from this body holds
+ *   anything.
+ */
+export function journalHasContent(body) {
+    return !isEmptyBody(body);
+}
+
 /**
  * The phrases that stand in for prose nobody has written.
  *

package/engine/subtype-registry.mjs

@@ -68,12 +68,15 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
 /**
  * The map a pack declaring no `system:` compiles its documents against.
  *
- * A pack names the system its documents are shaped for, and one declaring none
- * is compiled by the fallback pass for its document type — a single-system
+ * **The single-system fallback, and not a default any system inherits.** A pack
+ * names the system its documents are shaped for, and one declaring none is
+ * compiled by the fallback pass for its document type — a single-system
  * package's ordinary arrangement, and the one `sohl-thalorna` ships. That pass
- * follows one map whatever a note carries, which makes this the answer to "a
- * document compiled here belongs to *which* system?" wherever a pack has not
- * said.
+ * reads this map's block and no other, so a note carrying nothing for this
+ * system compiles into no document there; a note carrying another system's
+ * block reaches that system's pass or nothing at all, never this one. This is
+ * the answer to "a document compiled here belongs to *which* system?" wherever
+ * a pack has not said, and it answers nothing about a system that has said.
  *
  * Stated here rather than read off the compiler classes because those are not
  * reachable from a leaf: `engine/item-compiler.mjs` imports the journals pass,
@@ -86,6 +89,40 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
  */
 export const DEFAULT_DOCUMENT_SUBTYPES = SOHL_DOCUMENT_SUBTYPES;
 
+/**
+ * Every system this toolchain ships a map for, by id.
+ *
+ * Derived from {@link KNOWN_DOCUMENT_SUBTYPE_MAPS}, so registering a map is the
+ * whole of adding a system to every reader that asks "which systems are there?"
+ * — the per-system findings among them.
+ *
+ * @type {readonly string[]}
+ */
+export const SHIPPED_SYSTEMS = Object.freeze(KNOWN_DOCUMENT_SUBTYPE_MAPS.map((map) => map.system));
+
+/**
+ * The Foundry document classes a system compiles its own data into.
+ *
+ * Derived from the shipped maps' rows, so it is the set of classes for which
+ * "which system?" is a question with consequences: a pack of one of these
+ * classes is compiled by one system's pass reading one system's block, and a
+ * note carrying no such block produces nothing there. Every other class — a
+ * JournalEntry, a Macro, a Scene, an Adventure — has one implementation
+ * whatever a pack declares, because it is Foundry's document rather than any
+ * system's.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_DOCUMENT_CLASSES = Object.freeze(
+    new Set(
+        KNOWN_DOCUMENT_SUBTYPE_MAPS.flatMap((map) =>
+            Object.values(map.types)
+                .map((row) => row?.document)
+                .filter(Boolean),
+        ),
+    ),
+);
+
 /**
  * Every note type any shipped map compiles into an **Actor**.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.5.0",
+    "version": "22.6.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/types/engine/actor-compiler.d.mts

@@ -199,6 +199,17 @@ export function loadItemsMap(itemsSourceDirs: readonly string[], foreignSourceDi
  * becomes embedded items. Nothing above that line is a system's business.
  */
 export class SystemActorCompiler extends BasePackCompiler {
+    /**
+     * The Foundry document class this pass writes.
+     *
+     * Declared by the class that does the writing, so the table pairing a
+     * system with its passes is derived from the passes themselves rather than
+     * written out a second time — see
+     * {@link module:engine/generate.systemCompilers}.
+     *
+     * @type {string}
+     */
+    static documentClass: string;
     /**
      * The note-type → document-subtype map this pass compiles against.
      *