@heroiclands/package-build 22.5.0 → 22.6.0

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

@@ -82,13 +82,16 @@ export class BasePackCompiler {
     static readsPackOutputOf: readonly string[];
     /**
      * Whether this pass's document **is** a system's data, and therefore takes
-     * only notes that carry that system's block.
+     * only notes that carry the block this pass reads.
      *
-     * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
-     * and an `actors-sohl` from one tree — and the note-side half of that is
-     * the block named after the system. A note carrying no such block has
-     * nothing to say about it, so compiling it there would emit a **hollow
-     * document**: a subtype, and none of the fields the subtype exists for.
+     * The question is asked of {@link BasePackCompiler#system} — the pass's own
+     * system, which an Actor or Item pass always has — rather than of the
+     * pack's `system:`, which a pack need not declare. A note carrying no such
+     * block has nothing to say about that system, so compiling it would emit a
+     * **hollow document**: a subtype, and none of the fields the subtype exists
+     * for. `harn-ensemble` ships an `actors-hm3` and an `actors-sohl` from one
+     * tree, and `sohl-thalorna` ships one `actors` declaring nothing; the rule
+     * is the same in both, because it is the pass that reads a block.
      *
      * False by default, because most passes write documents that are not
      * system data at all. A JournalEntry of prose is the same document under
@@ -265,22 +268,49 @@ export class BasePackCompiler {
      *   routes to no pack at all — a build failure, never a silent drop.
      */
     routesHere(fm: object): boolean;
+    /**
+     * The system block this pass reads, where it reads one.
+     *
+     * `undefined` on the base class, because most passes read none: a
+     * JournalEntry, a Macro, a Scene and an Adventure are Foundry's documents
+     * rather than any system's. The Actor and Item passes answer with the
+     * block their {@link SystemActorCompiler.documentSubtypes} names, which is
+     * the same declaration that says which notes they claim and what each
+     * becomes.
+     *
+     * Stated here so {@link BasePackCompiler#eligibleFor} is total: a pass
+     * declaring `requiresSystemBlock` without a system reads no block, and a
+     * note can carry nothing for it.
+     *
+     * @returns {string|undefined} The block key, or `undefined`.
+     */
+    get system(): string | undefined;
     /**
      * Whether a claimed, routed note may become this pack's document at all.
      *
-     * The pack-eligibility gate, and it fails rather than skipping: a note that
-     * routed *here* and carries nothing for this pack's system is an authoring
-     * mistake with a hollow document at the end of it, not a note that belongs
-     * to another pass. Skipping it quietly is how a whole tree compiles to
-     * documents nobody can use.
+     * **A system block is what makes a game document.** A pass whose document
+     * *is* a system's data compiles a note only where the note carries the
+     * block that pass reads, so a note saying nothing about any system becomes
+     * no Actor and no Item anywhere — its prose still compiles into a page, a
+     * PDF leaf and a JournalEntry, which are documents no system defines.
+     *
+     * Asked of this pass's own {@link BasePackCompiler#system}, never of the
+     * pack's `system:`. A pack declaring none is a single-system convenience
+     * compiled by the fallback pass for its document type, and that pass still
+     * reads exactly one block — so the note-side question is the same one
+     * whether or not the pack answered it.
+     *
+     * A note this pass has nothing to compile is **skipped**, counted like any
+     * other note the pack does not own. A deliberately unstatted person is the
+     * ordinary case, and a block deleted by accident shows in the diff that
+     * deleted it; what would otherwise be discarded in silence is the block
+     * written for a system no pack of the class serves, and that is reported by
+     * {@link module:engine/note-claims.unclaimedNoteFindings} rather than here,
+     * where a pass can see only its own half of the configuration.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True when the note may be compiled here; `false` when
-     *   it belongs to another system's pass of the same document type, which is
-     *   skipped as quietly as any other note this pack does not own.
-     * @throws {Error} When this pack's system is absent from the note and no
-     *   other configured system claims it. The error carries a `position` where
-     *   the note's own file can be read.
+     *   it carries nothing for this pass's system.
      */
     eligibleFor(fm: object): boolean;
     /**

package/types/engine/content-index.d.mts

@@ -104,9 +104,10 @@ export function asciiAliases(aliases: unknown): Array<string>;
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
- *   holds no address and offers no anchor. It keeps everything else, its `id`
- *   and its `foundry` block included, because the document it compiles is
- *   derived from `data:` rather than from prose.
+ *   holds no address and offers no anchor. It keeps its `id`, and a `foundry`
+ *   block naming every document that was made — which is every document
+ *   derived from `data:`, and no journal, because a journal of an empty body
+ *   would be empty and is not created.
  * @throws {Error} When the note carries a key this module derives, which would
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.

package/types/engine/generate.d.mts

@@ -1,11 +1,40 @@
+/**
+ * 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
+ * pack's `system:` is what says whose data model its documents are shaped for.
+ * That is the same field the `_stats` stamp, the item-catalogue scope and the
+ * `itemBuilders` lookup already read, so nothing new is declared to make the
+ * compiler follow it.
+ *
+ * @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: readonly Function[]): Readonly<Record<string, Readonly<Record<string, Function>>>>;
 /**
  * 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: string, system?: string | null): Function | undefined;
 /**

package/types/engine/infobox-registry.d.mts

@@ -10,24 +10,23 @@ export function infoboxFor(system: string | undefined): object | undefined;
  * 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.

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

@@ -29,6 +29,17 @@ export function itemDescription(markdown: string, fm: object, name: string): str
  * a configuration one.
  */
 export class SystemItemCompiler 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.
      *

package/types/engine/note-claims.d.mts

@@ -102,7 +102,12 @@ export function claimedNoteTypes(config?: object, sources?: ClaimSources): Reado
  */
 export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
 /**
- * Every note in the content tree that no configured pack would compile.
+ * 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

package/types/engine/note-state.d.mts

@@ -59,6 +59,32 @@ export function isStubbableType(type: string | null | undefined, vocabulary?: Re
 export function isStubNote(frontmatter: Record<string, any> | null | undefined, body: string | null | undefined, vocabulary?: Readonly<Record<string, {
     stubbable?: boolean;
 }>>): boolean;
+/**
+ * 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: string | null | undefined): boolean;
 /**
  * The placeholder phrases a body reduces to, or an empty list.
  *

package/types/engine/subtype-registry.d.mts

@@ -50,12 +50,15 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.m
 /**
  * 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,
@@ -67,6 +70,30 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.m
  * @type {import("./document-subtypes.mjs").DocumentSubtypeMap}
  */
 export const DEFAULT_DOCUMENT_SUBTYPES: import("./document-subtypes.mjs").DocumentSubtypeMap;
+/**
+ * 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: readonly string[];
+/**
+ * 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: ReadonlySet<string>;
 /**
  * Every note type any shipped map compiles into an **Actor**.
  *