@heroiclands/package-build 8.1.0 → 10.0.0

package/types/engine/generate.d.mts

@@ -10,14 +10,27 @@
  * order among packs of one type — and every one of them is written before the
  * actors pass that reads them.
  *
+ * **Scoped to one system when the caller has one (#58).** A being addresses an
+ * item by `(type, shortcode)`, and that address is unique within one system and
+ * not across two: `skill:sword` is an HM3 skill *and* a SoHL skill, with
+ * different data models behind them. The reference itself is unambiguous — it
+ * sits inside a system block, so position says which it means — but the
+ * resolver has to know which catalogue it is searching, or it resolves the pair
+ * by whichever pack was read first. So an Actor pass reads the Item packs of
+ * **its own** system plus the system-neutral ones, which belong to every
+ * system. Asking for no system reads them all, which is every single-system
+ * build and the behaviour this always had.
+ *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
+ * @param {string|null} [system] - The system whose catalogue is wanted. Omitted
+ *   or `null`, every Item pack is read.
  * @returns {string[]} Each Item pack's JSON directory. Empty when the
  *   repository ships no items at all, which is a legitimate package: the actors
  *   pass accepts an empty list and reports an item it cannot resolve per
  *   `(type, shortcode)` instead, naming the being (#49).
  */
-export function itemPackJsonDirs(config?: object): string[];
+export function itemPackJsonDirs(config?: object, system?: string | null): string[];
 /**
  * The passes to run, ordered so that each one follows the output it reads.
  *
@@ -98,7 +111,7 @@ export function emptyPassErrors(passes: Array<{
  * @throws {Error} If the configured Foundry package id has drifted from the
  *   shipped manifest's `id` (see `package-manifest.mjs`).
  */
-export function generatePacksJson({ only, config, }?: {
+export function generatePacksJson({ only, config }?: {
     only?: string | undefined;
     config?: object | undefined;
 }): Promise<number>;

package/types/engine/helpers.d.mts

@@ -62,8 +62,8 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
 }, void, unknown>;
 /**
  * Resolve the required `sohl.archetype` frontmatter for an Item/Actor entry
- * (see the archetype contract, #604 — `flags.sohl.docArchetype`). The property
- * is a nullable number that authors must state explicitly:
+ * (the archetype contract, #604). The property is a nullable number that
+ * authors must state explicitly:
  *   - a number → the document is an archetype of that priority.
  *   - `null`   → the document is not an archetype.
  *   - absent   → an authoring error (throws), so "not an archetype" is never
@@ -79,19 +79,27 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
  */
 export function resolveArchetype(fm: object, label: string): number | undefined;
 /**
- * Merge the required `sohl.archetype` frontmatter into a document's `flags`,
- * returning a new object (the input is never mutated). A numeric archetype
- * seeds `flags.sohl.docArchetype`; `null` omits the flag (and clears any stale
- * `docArchetype` while preserving sibling `sohl` flags); an absent value
- * throws. See {@link resolveArchetype}.
- *
- * @param {object} fm              Parsed frontmatter.
- * @param {object} [flags]         The entry's existing flags (e.g. `fm.flags`).
- * @param {string} label           Human-readable context for error messages.
- * @returns {object}               The flags object with the archetype applied.
+ * The value a document's `system.archetype` carries, from the required
+ * `sohl.archetype` frontmatter (#126, sohl#1780).
+ *
+ * A **schema field**, so the tri-state is written out in full rather than
+ * expressed by a key's presence: a number is an archetype at that priority,
+ * and `null` is not an archetype. This is where {@link resolveArchetype}'s
+ * `undefined` becomes the field's `null` — an emitted `undefined` would be
+ * dropped by `JSON.stringify`, leaving the compiled document with no
+ * `archetype` at all and the tri-state readable as two.
+ *
+ * **`0` is an archetype.** It is the priority SoHL's own archetypes ship at,
+ * and it is falsy, so this returns it unchanged and every caller must ask
+ * `typeof v === "number"` rather than testing truthiness.
+ *
+ * @param {object} fm      Parsed frontmatter.
+ * @param {string} label   Human-readable context for error messages.
+ * @returns {number|null}  The archetype priority, or `null` for a document
+ *   that is not an archetype.
  * @throws {Error} When `sohl.archetype` is absent or invalid.
  */
-export function withArchetypeFlag(fm: object, flags?: object, label: string): object;
+export function systemArchetype(fm: object, label: string): number | null;
 /**
  * Generates a compendium-source filename: `Name_id.json` with non-
  * alphanumeric runs replaced by underscores.
@@ -276,7 +284,7 @@ export function buildContentLinkIndex(contentBase: string, router?: object): {
  *   carries `file` and `position`, so a caller reports it in the same form
  *   rather than re-deriving one.
  */
-export function convertNoteWikilinks(body: string, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap, }: object): {
+export function convertNoteWikilinks(body: string, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap }: object): {
     markdown: string;
     unresolved: Array<object>;
 };

package/types/engine/ids.d.mts

@@ -84,6 +84,16 @@ export function pageUuid(entryUuid: string, pageId: string): string;
  * @type {ReadonlySet<string>}
  */
 export const MAP_TYPES: ReadonlySet<string>;
+/**
+ * The map subTypes, which differ only in the canvas defaults derived for them.
+ *
+ * They were three *types* until #174, which cost three entries in the pack
+ * router, three in the claims set and three in every consumer's section config
+ * — for one idea that the specification had always described as one type.
+ *
+ * @type {readonly string[]}
+ */
+export const MAP_SUBTYPES: readonly string[];
 /**
  * Content type → the pack its documents compile into, and the document type
  * that pack holds.

package/types/engine/index.d.mts

@@ -1,14 +1,17 @@
 export * as ids from "./ids.mjs";
+export * as systemBlock from "./system-block.mjs";
 export * as codeFences from "./code-fences.mjs";
 export * as frontmatter from "./frontmatter.mjs";
 export * as contentTree from "./content-tree.mjs";
 export * as packConfig from "./pack-config.mjs";
 export * as packRouter from "./pack-router.mjs";
+export * as noteClaims from "./note-claims.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
+export * as noteVocabulary from "./note-vocabulary.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";
@@ -21,9 +24,11 @@ export * as webWikilinks from "./web-wikilinks.mjs";
 export * as contentTables from "./content-tables.mjs";
 export * as helpers from "./helpers.mjs";
 export * as itemRegistry from "./item-registry.mjs";
+export * as documentSubtypes from "./document-subtypes.mjs";
 export * as itemDocs from "./item-docs.mjs";
 export * as wikilinks from "./wikilinks.mjs";
 export * as wikilinkSyntax from "./wikilink-syntax.mjs";
+export * as aliasIndex from "./alias-index.mjs";
 export * as siteIndex from "./site-index.mjs";
 export * as baseCompiler from "./base-compiler.mjs";
 export * as journals from "./journals.mjs";

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

@@ -24,10 +24,27 @@ export function itemTypes(): ReadonlySet<string>;
  * failing as an anonymous `is not a function` (#1504).
  *
  * @param {string} type - The note's `type` frontmatter.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry. Omitted, a type only one registry declares still
+ *   resolves; a contested one throws rather than picking a side.
  * @returns {(fm: object) => object} The builder for that type.
  * @throws {Error} When the configuration registers no builder for `type`.
  */
-export function itemBuilder(type: string): (fm: object) => object;
+export function itemBuilder(type: string, system?: string): (fm: object) => object;
+/**
+ * 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,
+ * which has to know which paths a declared field already writes before it
+ * writes the rest (#58).
+ *
+ * @param {string} type - The item type.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry.
+ * @returns {readonly object[]|undefined} The declaration, or `undefined`.
+ */
+export function itemFields(type: string, system?: string): readonly object[] | undefined;
 /**
  * The default art for an item type — the image a note of that type is given
  * when it carries no `img:` of its own.
@@ -51,7 +68,9 @@ export function itemBuilder(type: string): (fm: object) => object;
  * One spelling, one meaning, wherever it is written.
  *
  * @param {string} type - the item type.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry.
  * @returns {string} The default image path for that type.
  * @throws {Error} When the type's registry entry pairs no `img`.
  */
-export function itemArt(type: string): string;
+export function itemArt(type: string, system?: string): string;

package/types/engine/kb-manifest.d.mts

@@ -24,18 +24,34 @@ export function canonicalKey(pkg: string, type: string, shortcode: string): stri
 /**
  * Reads a canonical key back into its parts.
  *
- * Unambiguous because no package, type or shortcode contains a hyphen — types
- * are bare words and shortcodes are `^[A-Za-z0-9]+$` (#1397).
- *
- * @param {string} key - A canonical key.
- * @returns {{package: string, type: string, shortcode: string}|null} The parts,
- *   or `null` when the key is not in canonical form.
+ * Parsing is plain positional counting: split on the separator, require
+ * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
+ * **The charset rule is what makes that sound** — every segment is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
+ * so the hyphen is purely a separator and the count alone determines every
+ * field. That is enforced at each of the three sources rather than assumed of
+ * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
+ * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * carry a hyphen, no amount of counting would recover the fields and the reader
+ * would need a vocabulary to match against instead.
+ *
+ * **Nothing to read and nothing readable are different answers.** A key that
+ * cannot be canonical — `harn-adventures-skill-melee`, four segments — yields
+ * `null`, while an absent or blank input yields `undefined`. Both are falsy, so
+ * every call site (all of which test the result for truthiness) is unaffected;
+ * the distinction is there so a caller reporting "this key is unreadable" can
+ * tell that it has a key to report about.
+ *
+ * @param {unknown} key - A canonical key, or nothing.
+ * @returns {{package: string, type: string, shortcode: string}|null|undefined}
+ *   The parts; `null` when there is a string that is not in canonical form;
+ *   `undefined` when there is no key at all.
  */
-export function readCanonicalKey(key: string): {
+export function readCanonicalKey(key: unknown): {
     package: string;
     type: string;
     shortcode: string;
-} | null;
+} | null | undefined;
 /**
  * The package-relative address a site-absolute URL records as.
  *
@@ -151,6 +167,17 @@ export function manifestsComplete(localPackages: Iterable<string>, manifestPacka
  * relaxes the build rather than breaking it.
  */
 export const LINK_PACKAGES: readonly string[];
+/**
+ * How many segments a canonical key has, and therefore how many the reader
+ * below counts.
+ *
+ * Named rather than written as a literal because it is the *grammar*, not an
+ * implementation detail of one function: it is the number a change to the
+ * address form would move, and the thing a reader of that change has to find.
+ *
+ * @type {number}
+ */
+export const CANONICAL_KEY_SEGMENTS: number;
 /**
  * Manifest format version.
  *

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

@@ -6,14 +6,19 @@
  */
 export function isMapType(type?: string): boolean;
 /**
- * The canvas profile for a map type.
+ * The canvas profile for a map subType.
  *
- * @param {string} type - The note's `type`.
- * @returns {object} The profile from {@link MAP_TYPE_PROFILES}.
- * @throws {Error} When the type is not a map type — the build's fail-fast
- *   contract, so a typo never ships a scene with Foundry's own defaults.
+ * Keyed on the subType rather than the type since #174: every map note is
+ * `type: map`, and which canvas it derives is the one thing the three
+ * spellings ever decided.
+ *
+ * @param {string} subType - The note's `subType`.
+ * @returns {object} The profile from {@link MAP_SUBTYPE_PROFILES}.
+ * @throws {Error} When the subType is not a map subType — the build's
+ *   fail-fast contract, so a typo never ships a scene with Foundry's own
+ *   defaults.
  */
-export function mapProfile(type: string): object;
+export function mapProfile(subType: string): object;
 /**
  * The id of one region within its scene.
  *
@@ -141,7 +146,7 @@ export function buildShape(spec: object, geom: MapGeometry): object;
  */
 export function buildScene(fm: object, ctx: object): object;
 /**
- * Synthesise the scene's single embedded Level from `image:` / `overlay:`.
+ * Synthesise the scene's single embedded Level from `img:` / `overlay:`.
  *
  * Authors never write `levels:`. A scene must ship at least one Level — the
  * client-side `_preCreate` net that would create one does not run for offline
@@ -151,9 +156,13 @@ export function buildScene(fm: object, ctx: object): object;
  *
  * @param {object} sohl - The note's `sohl:` block.
  * @param {string} sceneId - The owning scene's `_id`.
+ * @param {string} [img] - The background art, already resolved from the note.
+ *   Passed by {@link buildScene}, which reads it from the note rather than from
+ *   the block; defaults to whichever spelling the block itself carries, so a
+ *   direct two-argument call still works (#142).
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl: object, sceneId: string): object;
+export function buildLevel(sohl: object, sceneId: string, img?: string): object;
 /**
  * Compile the `walls:` and `doors:` blocks into Wall documents.
  *
@@ -225,9 +234,8 @@ export function buildLocations(sohl: object, geom: MapGeometry, ctx: object): ob
  * @returns {object[]} The Region documents.
  */
 export function buildRegions(sohl: object, geom: MapGeometry, ctx: object): object[];
-export { MAP_TYPES };
 /**
- * Per-type canvas defaults, emitted **explicitly** on every scene.
+ * Per-subtype canvas defaults, emitted **explicitly** on every scene.
  *
  * This is not a convenience. `grid.type`, `grid.distance` and `grid.units` all
  * declare `initial: () => game.system.grid.*`, and there is no `game` at build
@@ -237,7 +245,7 @@ export { MAP_TYPES };
  *
  * @type {Readonly<Record<string, object>>}
  */
-export const MAP_TYPE_PROFILES: Readonly<Record<string, object>>;
+export const MAP_SUBTYPE_PROFILES: Readonly<Record<string, object>>;
 /**
  * Foundry's own id for the level a scene is created with
  * (`Scene.metadata.defaultLevelId`). Adopting it makes every reference to the
@@ -280,4 +288,6 @@ export type MapGeometry = {
      */
     dimensions: number[];
 };
+import { MAP_SUBTYPES } from "./ids.mjs";
 import { MAP_TYPES } from "./ids.mjs";
+export { MAP_SUBTYPES, MAP_TYPES };

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

@@ -0,0 +1,113 @@
+/**
+ * The note types a pass of one document type claims — the claim table.
+ *
+ * Each row restates one pass's `selects`, in the only form that can be asked of
+ * a pack the configuration does not declare. A document type no compiler is
+ * registered for claims nothing, which is what keeps a prebuilt `Adventure`
+ * 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. 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 note type some pack in a configuration would compile.
+ *
+ * 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).
+ *
+ * @param {object} [config] - The resolved build configuration. Defaults to this
+ *   repository's.
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @returns {ReadonlySet<string>} The claimed note types.
+ */
+export function claimedNoteTypes(config?: object, sources?: ClaimSources): ReadonlySet<string>;
+/**
+ * Every note type this build knows, whatever any one repository configures.
+ *
+ * Wider than {@link claimedNoteTypes} on purpose: it is what distinguishes a
+ * repository that has not configured a pack for a real content type from an
+ * author who wrote a word nothing anywhere compiles. The engine's own types,
+ * the types every shipped system maps, and whatever the configured registries
+ * declare on top.
+ *
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @returns {ReadonlySet<string>} The vocabulary.
+ */
+export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
+/**
+ * Every note in the content tree that no configured pack would compile.
+ *
+ * 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
+ * file with no frontmatter is not a note; a note with no `type:` is the
+ * frontmatter linter's finding, which can say what a type is *for*; and a
+ * retired type is answered by `assertTypeNotRetired` in `ids.mjs`, which names the
+ * replacement.
+ *
+ * @param {object} [config] - The resolved build configuration. Defaults to this
+ *   repository's.
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string, type: string}>} One finding per note.
+ */
+export function unclaimedNoteFindings(config?: object, sources?: ClaimSources): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "error";
+    message: string;
+    type: string;
+}>;
+/**
+ * Note types that compile into **no compendium document, by design**.
+ *
+ * A homepage compiles into a *page*: it carries no compendium UUID, appears in
+ * no pack and in no link-manifest entry, and every package that publishes one
+ * would otherwise be told its front page is unclaimed. It is the one type whose
+ * absence from every pack is the intended state rather than a gap.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const NEVER_PACKED_TYPES: ReadonlySet<string>;
+/**
+ * The note-type → document-subtype maps this toolchain ships.
+ *
+ * One today. `hm3/` is #139, and when it lands its map joins this list rather
+ * than the claim table below growing a second copy of the same fact.
+ *
+ * `engine/` importing from `sohl/` is the arrangement `generate.mjs` already
+ * has — its `COMPILERS` table names the SoHL compilers by class — and for the
+ * same reason: the engine owns the *mechanism* that asks each system what it
+ * compiles, and the systems own the answers.
+ *
+ * @type {readonly import("./document-subtypes.mjs").DocumentSubtypeMap[]}
+ */
+export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[];
+/**
+ * What a claim question is asked against.
+ *
+ * Each field defaults to what the compilers themselves read, so the answer here
+ * and the answer a pass gives are drawn from one source. They are parameters so
+ * that a test can pose a configuration this toolchain does not ship — two
+ * systems cutting the vocabulary differently, a registry declaring nothing —
+ * without a content tree or a config file on disk.
+ */
+export type ClaimSources = {
+    /**
+     * -
+     * The systems' note-type → document-subtype maps.
+     */
+    maps?: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[] | undefined;
+    /**
+     * - The declared item vocabulary.
+     */
+    itemTypes?: ReadonlySet<string> | undefined;
+    /**
+     * - The doc-carrying types.
+     */
+    docEntryTypes?: ReadonlySet<string> | undefined;
+};