@heroiclands/package-build 20.3.1 → 20.5.0

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

@@ -1,6 +1,6 @@
 /**
  * The description an item carries: a pointer to its **item doc**, the
- * JournalEntry the journals pass compiles this same body into (#1348).
+ * JournalEntry the journals pass compiles this same body into.
  *
  * The prose is not rendered into the item at all. Carrying it would duplicate
  * it onto every actor holding the item — 7.59 MB of copies across the actors
@@ -40,6 +40,22 @@ export class SystemItemCompiler extends BasePackCompiler {
      * @type {import("./document-subtypes.mjs").DocumentSubtypeMap|undefined}
      */
     static documentSubtypes: import("./document-subtypes.mjs").DocumentSubtypeMap | undefined;
+    /**
+     * The `system` keys this pass writes for itself, and where each is read
+     * from.
+     *
+     * A note authoring one is refused, because the compiler writes the key
+     * unconditionally: the authored value is overwritten, or survives as the
+     * wrong type in a shipped document. Declared here rather than named in the
+     * refusal so that a second system states its own — see
+     * {@link module:engine/derived-fields}.
+     *
+     * @type {readonly {key: string, from: string}[]}
+     */
+    static derivedSystemKeys: readonly {
+        key: string;
+        from: string;
+    }[];
     /**
      * The frontmatter block this pass reads, and the registry it addresses.
      *
@@ -60,7 +76,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * **Looked up, not inferred.** For every type this system declares, the
      * emitted subtype is the map's, so the note vocabulary and the document
      * vocabulary are two separately-stated things rather than one string
-     * written twice (#79).
+     * written twice.
      *
      * **A type the map does not name belongs to the consumer**, and its
      * registry entry is the declaration: a repository shipping an item type of
@@ -69,7 +85,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * subtype of. That is an authored statement in the consumer's own
      * configuration, not a coincidence inside this package's source — and
      * refusing it here would silently drop every document of a type this system
-     * has no opinion about (#7/#1563).
+     * has no opinion about.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {string} The document's `type`.
@@ -84,7 +100,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * Nothing by default, which is the honest position for a system that has
      * not said otherwise: a key written here lands on every document of every
      * type, so inventing one that the receiving DataModel does not declare
-     * would be a finding on the whole pack (#155).
+     * would be a finding on the whole pack.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {object} at - What the pass already knows about this note.
@@ -111,7 +127,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * field for it and an undeclared `system` key is discarded at load without
      * a word.
      *
-     * **This is the one emitted key nothing else can check** (#283). A `system`
+     * **This is the one emitted key nothing else can check**. A `system`
      * key this pass invents is caught by the emitted-`system` check against the
      * receiving schema, but a flag is declared by no schema — so an omission
      * here is silent, and was: the Actor pass wrote the priority and this one

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

@@ -3,7 +3,7 @@
  * addressed by the virtual `doc<type>` qualifier.
  *
  * Every item type, plus `macro` — a macro note's body documents the script the
- * note also compiles into a Macro (#1514), which is the same shape as an item
+ * note also compiles into a Macro, which is the same shape as an item
  * and its description: one note, two documents, the prose living in the
  * journals pack.
  *
@@ -59,7 +59,7 @@ export function itemDocEntryId(itemId: string): string;
  * happens to contain a link, which the runtime would then show verbatim.
  *
  * @param {string} packageId - The Foundry package shipping the journals pack.
- *   Supplied rather than assumed (#1498).
+ *   Supplied rather than assumed.
  * @param {string} itemId - The item note's `id` frontmatter.
  * @param {string} name - The item's name, used as the link's label. It shows
  *   only if the target ever fails to resolve, where a broken link naming the

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

@@ -6,9 +6,9 @@
  * **Derived, never authored.** These are the keys of the consuming
  * repository's `itemBuilders` registry, so the whitelist and the builder table
  * are the same list and cannot drift apart. They already had: `trait` was
- * whitelisted long after the item type was retired (#651), with no builder
+ * whitelisted long after the item type was retired, with no builder
  * behind it, so every `type: trait` note passed the gate and then failed to
- * compile (#1504).
+ * compile.
  *
  * An accessor rather than a hoisted constant, so that importing this module
  * needs no configuration (#2).
@@ -21,7 +21,7 @@ export function itemTypes(): ReadonlySet<string>;
  *
  * Unreachable through the compiler — its whitelist *is* this registry's keys —
  * so a throw here means a caller invented a type. It names the type rather than
- * failing as an anonymous `is not a function` (#1504).
+ * failing as an anonymous `is not a function`.
  *
  * @param {string} type - The note's `type` frontmatter.
  * @param {string} [system] - The system compiling it, where a build declares
@@ -35,9 +35,9 @@ export function itemBuilder(type: string, system?: string): (fm: object) => obje
  * The frontmatter fields a type's registry entry declares, if any.
  *
  * Sparse by design: a type whose entry declares none compiles normally and is
- * simply undocumented (#22). What reads it is the `system`-block passthrough,
+ * simply undocumented. What reads it is the `system`-block passthrough,
  * which has to know which paths a declared field already writes before it
- * writes the rest (#58).
+ * writes the rest.
  *
  * @param {string} type - The item type.
  * @param {string} [system] - The system compiling it, where a build declares
@@ -51,7 +51,7 @@ export function itemFields(type: string, system?: string): readonly object[] | u
  *
  * Read from the consuming repository's `itemBuilders` registry, the same place
  * the type itself is declared, so a consumer's own type can bring art a
- * SoHL-owned table could never hold. Art used to be looked up in
+ * SoHL-owned table could never hold. Art is not looked up in
  * `sohl/default-item-art.mjs` instead: a type was configurable while its
  * default art was not, so a second consumer's items compiled only if every one
  * of its notes set `img:` (#7).

package/types/engine/journals.d.mts

@@ -29,7 +29,7 @@ export function splitPages(body: any, leadName?: string): {
  * on an identity alone:
  *
  * - **An anchor**, declared twice, has always collided.
- * - **A name**, repeated among the unanchored pages, collides since #268 took
+ * - **A name**, repeated among the unanchored pages, collides once
  *   the index out of the key. `MD024` with `siblings_only` already makes two
  *   sibling headings with the same text a lint error, so this is the same rule
  *   restated where the build can enforce it — a lint is a separate command, and
@@ -69,7 +69,7 @@ export function assertUniqueAnchors(rawPages: Array<{
  * doc's first page without having compiled it (see
  * {@link sohl.utils.packs.itemDocPointer}).
  *
- * **It takes no index** (#268). A page used to be keyed by position *and* name,
+ * **It takes no index**. Keying a page by position *and* name,
  * so inserting a heading renumbered every page after it and a re-import created
  * new pages beside the old ones — while nothing about those pages had changed.
  * The anchored case above never took one, and is the shape this now shares.
@@ -134,7 +134,7 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
  *   caller because it is a property of the *pack* being written, not of the
  *   entry: a module may ship the same content for two systems, and each pack's
- *   documents record the system version they were built against (#48). A
+ *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
@@ -147,6 +147,15 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, flags,
     flags?: object | undefined;
     stats?: object | undefined;
 }): object;
+/**
+ * Journals pack compiler.
+ *
+ * Walks the content tree and compiles every `type: doc` note, and every note of
+ * a doc-carrying type, into one JournalEntry document: the body split into
+ * pages on its top-level H1 headings, each rendered to HTML. A doc-carrying
+ * note's entry is that document's documentation, filed in the document's own
+ * folder.
+ */
 export class Journals extends BasePackCompiler {
     /**
      * How many of the compiled entries were documentation for a document

package/types/engine/map-notes.d.mts

@@ -8,7 +8,7 @@ export function isMapType(type?: string): boolean;
 /**
  * The canvas profile for a map subType.
  *
- * Keyed on the subType rather than the type since #174: every map note is
+ * Keyed on the subType rather than the type: every map note is
  * `type: map`, and which canvas it derives is the one thing the three
  * spellings ever decided.
  *
@@ -253,7 +253,7 @@ export const MAP_SUBTYPE_PROFILES: Readonly<Record<string, object>>;
  */
 export const DEFAULT_LEVEL_ID: "defaultLevel0000";
 /**
- * The behaviour types a map note may carry (issue #1525, v1).
+ * The behaviour types a map note may carry (v1).
  *
  * @type {ReadonlySet<string>}
  */

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

@@ -22,7 +22,7 @@ export function metadataFileName(pkg: string): string;
  * `itemCatalog: true` says a dependency supplies *items*; citing its
  * *addresses* is a separate edge, and a package may have either without the
  * other. `harn-ensemble` cites no foreign address and carries 324,016 embedded
- * item references (`HeroicLands/harn-ensemble#42`); a package citing addresses
+ * item references; a package citing addresses
  * and needing no items is the mirror of it. Gating the index on the catalogue
  * flag would serve neither.
  *
@@ -84,7 +84,7 @@ export function cachedMetadataFiles(config: object): string[];
  * The same fetched indexes, each paired with the package that published it.
  *
  * The id is what a SQL content table addresses a dependency's notes by
- * (`FROM sohl.notes`, #246), so the pairing has to survive the lookup —
+ * (`FROM sohl.notes`), so the pairing has to survive the lookup —
  * {@link cachedMetadataFiles} drops it, and a caller reconstructing the id from
  * the file name would be parsing a path to recover something the declaration
  * already stated.
@@ -113,7 +113,7 @@ export function cachedMetadataIndexes(config: object): Array<{
  * rather than being written once per cache. Two copies would be two chances to
  * get it wrong, and the wrong answer is invisible: every cached version is a
  * complete, stamped, perfectly valid artifact, so picking the older one reports
- * nothing and simply resolves against stale data (#272).
+ * nothing and simply resolves against stale data.
  *
  * @param {string[]} dirs - Complete cache directories, named `<id>@<version>`.
  * @returns {string} The newest one.
@@ -179,7 +179,7 @@ export function cachedIndexPath(config: object, pkg: string): string;
  * therefore reported against the index, once, instead of once per citing note.
  *
  * The realistic cause is a version skew: a dependency released before the
- * address grammar gained its `<system>` segment (#59) ships three-segment keys.
+ * address grammar gained its `<system>` segment ships three-segment keys.
  * Re-fetching after that dependency releases is the fix.
  *
  * @param {Map<string, object>} foreignIndex - The resolved foreign index.

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

@@ -7,22 +7,19 @@
  * pack from appearing to answer for any note.
  *
  * @param {string} docType - The Foundry document type a pack holds.
- * @param {ClaimSources} [sources] - What to answer from.
- * @param {object} [opts] - Options.
- * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above (#243). Defaults to the
+ * @param {ClaimSources} [sources] - What to answer from. Defaults to the
  *   configured registries and the systems this toolchain ships.
  * @returns {ReadonlySet<string>} The note types such a pass would claim.
  */
 export function noteTypesClaimedBy(docType: string, sources?: ClaimSources): ReadonlySet<string>;
 /**
- * Every document class a note of one type compiles into (#152).
+ * Every document class a note of one type compiles into.
  *
  * **A note produces more than one document, and that is the ordinary case.** An
  * item note compiles an Item *and* the JournalEntry its prose becomes; a map
- * note a Scene and a JournalEntry; since #337 an actor note an Actor and a
+ * note a Scene and a JournalEntry; an actor note an Actor and a
  * JournalEntry too. {@link claimedNoteTypes} unions over the configured packs
- * and so answers "is this note compiled *at all*", which is #146's question and
+ * and so answers "is this note compiled *at all*", and
  * cannot see a note that compiles one of its two documents and loses the other.
  *
  * Asked of the **claim table** rather than of a list of its own, so the set of
@@ -33,7 +30,7 @@ export function noteTypesClaimedBy(docType: string, sources?: ClaimSources): Rea
  * **Union across systems, never per system.** A type one system maps and
  * another does not appears once, because the `Item` and `Actor` rows already
  * fold the maps together — so this cannot report a document class a system
- * deliberately declines to produce, which is the silence #79 requires.
+ * deliberately declines to produce, which is the silence the rule requires.
  *
  * ## The JournalEntry row is the one that is per *note*
  *
@@ -73,13 +70,14 @@ export function documentClassesFor(type: string, sources?: ClaimSources, { hasPr
  *
  * The union across the configured pack list, so a type claimed by any one pack
  * is claimed — which is what keeps a type deliberately unmapped for one system,
- * and claimed for another, silent (#79).
+ * and claimed for another, silent.
  *
  * **A prebuilt pack claims nothing.** Its per-document JSON is checked in
  * rather than compiled, so it has no pass and no note is routed into one —
  * which `content-config.mjs` already states by refusing `default: true`
  * alongside `prebuilt`. Counting it would tell an author their note is claimed
- * by a pack that will never look at it. Before #259 the point could not arise:
+ * by a pack that will never look at it. With no unimplemented type declared,
+ * the point cannot arise:
  * the only prebuilt pack in the wild is `harn-adventures`'s Adventure pack, and
  * no compiler was registered for that document type, so the row answered for
  * nothing whatever it was asked. Now one is.
@@ -87,9 +85,6 @@ export function documentClassesFor(type: string, sources?: ClaimSources, { hasPr
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
  * @param {ClaimSources} [sources] - What to answer from.
- * @param {object} [opts] - Options.
- * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above (#243).
  * @returns {ReadonlySet<string>} The claimed note types.
  */
 export function claimedNoteTypes(config?: object, sources?: ClaimSources): ReadonlySet<string>;
@@ -103,9 +98,6 @@ export function claimedNoteTypes(config?: object, sources?: ClaimSources): Reado
  * declare on top.
  *
  * @param {ClaimSources} [sources] - What to answer from.
- * @param {object} [opts] - Options.
- * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above (#243).
  * @returns {ReadonlySet<string>} The vocabulary.
  */
 export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
@@ -124,7 +116,7 @@ export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
  * @param {ClaimSources} [sources] - What to answer from.
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above (#243).
+ *   compile and handed in — required, for the reason above.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per note.
  */
@@ -149,6 +141,22 @@ export function unclaimedNoteFindings(config?: object, sources?: ClaimSources, {
  * @type {ReadonlySet<string>}
  */
 export const NEVER_PACKED_TYPES: ReadonlySet<string>;
+/**
+ * The whole note vocabulary of a package that compiles no Foundry documents.
+ *
+ * Every other type in the vocabulary exists to *become* a document: a `skill` is
+ * an Item, a `being` an Actor, a `place` a JournalEntry, a `folder` the Folder
+ * they are filed under. In a `documentation` package none of them has a
+ * destination, so a note carrying one would be authored, validated, walked and
+ * then published as a page of something that was meant to be a compendium
+ * entry — the plausible-looking result that reads as success.
+ *
+ * `doc` is prose whose single document *is* the prose, and `homepage` is the
+ * authored front page every package publishes. Both are already pages first.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const DOCUMENTATION_NOTE_TYPES: ReadonlySet<string>;
 /**
  * Content types the specification states and this toolchain does not yet
  * compile.
@@ -162,11 +170,11 @@ export const NEVER_PACKED_TYPES: ReadonlySet<string>;
  * correctly and is worthless, because the configured vocabulary is *derived
  * from the routing*. Take a type's route away and it leaves the vocabulary too,
  * so the inference excuses precisely the mistake it was meant to catch. That is
- * not hypothetical: it is #241, where `place`, `lore` and `scenario` were
- * declared, validated and unrouted, and every gate reported success until a
- * downstream repository failed on 450 notes.
+ * not hypothetical: `place`, `lore` and `scenario` were declared, validated
+ * and unrouted, and every gate reported success until a downstream repository
+ * failed on the notes carrying them.
  *
- * A type leaves this set when it is implemented, the way `bundle` did in #259.
+ * A type leaves this set when it is implemented.
  * The membership is asserted, so it cannot be forgotten in either direction.
  *
  * @type {ReadonlySet<string>}
@@ -178,7 +186,7 @@ export const UNIMPLEMENTED_TYPES: ReadonlySet<string>;
  * A folder is the only one, and it is not unclaimed: it compiles to a real
  * `Folder` document. What it has no answer to is *which* pack claims it, because
  * that is not a property of the note — a folder materialises in every pack
- * holding a document that references it, and its ancestors with it (#257). So
+ * holding a document that references it, and its ancestors with it. So
  * it is exempt from the claim check for the opposite reason a homepage is:
  * a homepage is in no pack, and a folder may be in several.
  *

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

@@ -5,15 +5,15 @@
  * the rule but an application of it.** A `Folder` is a document of its own
  * class, and its id is hashed under the `folder` namespace so that a folder and
  * an item sharing a shortcode cannot derive one id — a collision Foundry would
- * not report, since it keys folders and documents in separate collections
- * (#258). So the answer for a folder comes from
+ * not report, since it keys folders and documents in separate collections.
+ * So the answer for a folder comes from
  * {@link module:engine/folder-notes.folderDocId}, the pass that emits those
  * documents, rather than from a second derivation here.
  *
  * That this function ever answered differently was invisible from inside a
  * build — no pass reads a folder's id from here — and surfaced only in the
  * content index, which is read from outside and had no way to be checked
- * against what shipped (#310).
+ * against what shipped.
  *
  * Returns `undefined` for a file with **no address** — no `type`, or no
  * `shortcode`. Such a file is not an addressable note, so it has no document
@@ -26,7 +26,7 @@
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {object} [opts]
  * @param {string} [opts.pkg] - The owning content package. Defaults to the
- *   configured one, which is the only package a tree's notes belong to (#56).
+ *   configured one, which is the only package a tree's notes belong to.
  * @param {readonly object[]} [opts.maps] - The document-subtype maps, which
  *   decide the address's `<system>` segment.
  * @returns {string|undefined} The document's `_id`, or `undefined` when the

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

@@ -6,7 +6,7 @@
  * field, so a collection note that scopes itself with `WHERE … and package =
  * "sohl"` would match nothing now that the field is gone, and would render an
  * **empty table** in silence. Supplying the derived value here is what kept the
- * sweep mechanical rather than a trap (#56) — and a query that never mentions
+ * sweep mechanical rather than a trap — and a query that never mentions
  * `package` is unaffected either way.
  *
  * The frontmatter is copied rather than written into: it is the note's own

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

@@ -1,10 +1,10 @@
 /**
- * The shortcodes a note declares it used to be published under (#278).
+ * The shortcodes a note declares it used to be published under.
  *
  * A package's `(type, shortcode)` addresses are a published interface, and
  * `addresses diff` reports what a build stopped publishing — telling a
  * **rename** from a **withdrawal** by matching document ids across two
- * releases. #270 removed the property that rested on. An id is now derived from
+ * releases. The property that rested on is gone: an id is derived from
  * the canonical address, which carries the shortcode, so renaming a shortcode
  * moves the id too: both sides of the join move together, the match finds
  * nothing, and a rename is reported as a withdrawal with no successor named.
@@ -39,7 +39,7 @@
  * **It is transient.** Once every baseline a build is compared against post-dates
  * the rename, the declaration has nothing left to say and may be deleted. That
  * is the difference from an `id:` pin, which is permanent, opaque, and a second
- * identity for a thing that already has one (#270).
+ * identity for a thing that already has one.
  *
  * **It is one key per note, at the top level, however many systems the note
  * compiles into.** A shortcode is the note's, not a system block's: a note