@heroiclands/package-build 15.0.0 → 17.0.0

package/engine/note-vocabulary.mjs

@@ -395,7 +395,13 @@ export const NOTE_VOCABULARY = Object.freeze({
             { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },
             { name: "occupation", ...TEXT, describe: "What the being does for a living." },
             { name: "stations", ...LINKS, describe: "Stations the being holds." },
-            { name: "peoples", ...LINKS, describe: "Peoples the being belongs to." },
+            {
+                name: "lore",
+                ...LINKS,
+                describe:
+                    "Lore concerning this being — the people it is of, the standing it " +
+                    "holds, the law it lives under.",
+            },
             { name: "homes", ...LINKS, describe: "Places the being calls home." },
             {
                 name: "affiliations",
@@ -425,6 +431,14 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
     }),
 
+    vehicle: Object.freeze({
+        subTypes: null,
+        data: Object.freeze([
+            { name: "portrait", ...TEXT, describe: "Path to the portrait image." },
+            TEMPLATE_PRIORITY,
+        ]),
+    }),
+
     /* ----- items ---------------------------------------------------- */
 
     affiliation: Object.freeze({
@@ -448,6 +462,18 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...TEXT,
                 describe: "What one member is called — a Vylarian.",
             },
+            {
+                name: "epithet",
+                ...TEXT,
+                describe: "The by-name it is known by — a god's, an order's, a company's.",
+            },
+            {
+                name: "symbol",
+                ...TEXT,
+                describe:
+                    "Its emblem in words: a feather atop a golden scale, a chisel carving " +
+                    "a star.",
+            },
             {
                 name: "governance.model",
                 ...TEXT,
@@ -481,7 +507,13 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...LINKS,
                 describe: "What its economic life runs on — currencies, banking bodies, goods.",
             },
-            { name: "peoples", ...LINKS, describe: "Peoples associated with it." },
+            {
+                name: "lore",
+                ...LINKS,
+                describe:
+                    "Lore concerning it — the peoples it draws on, the god a faith " +
+                    "venerates, its law, its calendar.",
+            },
             { name: "parents", ...LINKS, describe: "Affiliations it is subordinate to." },
             {
                 name: "relations",
@@ -532,6 +564,11 @@ export const NOTE_VOCABULARY = Object.freeze({
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR]),
     }),
 
+    armorlocation: Object.freeze({
+        subTypes: null,
+        data: Object.freeze([TEMPLATE_PRIORITY]),
+    }),
+
     attribute: Object.freeze({
         data: Object.freeze([TEMPLATE_PRIORITY]),
     }),
@@ -674,6 +711,86 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     macro: Object.freeze({ data: Object.freeze([]) }),
 
+    lore: Object.freeze({
+        subTypes: Object.freeze([
+            "cosmology",
+            "deity",
+            "theology",
+            "arcana",
+            "spirit",
+            "economy",
+            "law",
+            "calendar",
+            "history",
+            "material",
+            "folk",
+            "culture",
+            "bestiary",
+        ]),
+        // Nothing of its own: a lore note is prose, and what it *is* about is
+        // its subType. The specification declares an empty table for it, and
+        // the authored corpus writes no `data:` key on any of the 180.
+        data: Object.freeze([]),
+    }),
+
+    place: Object.freeze({
+        subTypes: Object.freeze(["world", "region", "settlement", "site", "structure", "feature"]),
+        data: Object.freeze([
+            {
+                name: "demonym",
+                ...TEXT,
+                describe: "What a person from this place is called — a Vylarian.",
+            },
+            {
+                name: "lore",
+                ...LINKS,
+                describe:
+                    "Lore concerning this place — its peoples, its law, its calendar, " +
+                    "its history.",
+            },
+            {
+                name: "parents",
+                ...LINKS,
+                describe: "Enclosing places this one sits within.",
+            },
+            {
+                name: "population",
+                ...NUM,
+                describe: "Approximate population, to two significant digits.",
+            },
+        ]),
+    }),
+
+    scenario: Object.freeze({
+        subTypes: Object.freeze(["campaign", "adventure", "encounter"]),
+        data: Object.freeze([
+            { name: "parents", ...LINKS, describe: "Scenarios this one sits within." },
+            { name: "locations", ...LINKS, describe: "Places the scenario takes place in." },
+            { name: "cast", ...LINKS, describe: "Beings who appear in it." },
+            { name: "factions", ...LINKS, describe: "Affiliations with a stake in it." },
+            {
+                name: "follows",
+                ...LINKS,
+                describe: "Scenarios that should be played before this one.",
+            },
+            {
+                name: "status",
+                ...TEXT,
+                describe: "`draft`, `playtested` or `published`.",
+            },
+            {
+                name: "party.size",
+                ...TEXT,
+                describe: "`solo`, `small`, `standard`, `large` or `host`.",
+            },
+            {
+                name: "party.archetypes",
+                ...LIST,
+                describe: "Archetypes the scenario is written for.",
+            },
+        ]),
+    }),
+
     homepage: Object.freeze({ data: Object.freeze([]) }),
 
     map: Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "15.0.0",
+    "version": "17.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/note-schemas.mjs

@@ -87,6 +87,22 @@ const MACRO_FIELDS = Object.freeze([
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
+/**
+ * A `vehicle` note — a conveyance that carries goods and people.
+ *
+ * Empty, and the emptiness is the declaration: the specification gives a
+ * vehicle two `data` properties and no `sohl:` field of its own, and the
+ * closed `data:` container is where `engine/note-vocabulary.mjs` holds them.
+ * Declaring the type with no fields distinguishes a type with no vocabulary
+ * from a type that is unknown, which are different findings (#231).
+ *
+ * It is here rather than in the engine because a vehicle is a SoHL actor —
+ * the specification maps it to `sohl` and marks it NA for hm3.
+ *
+ * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
+ */
+const VEHICLE_FIELDS = Object.freeze([]);
+
 const BEING_FIELDS = Object.freeze([
     {
         name: "body",
@@ -330,5 +346,6 @@ export const NOTE_SCHEMAS = Object.freeze({
     doc: DOC_FIELDS,
     macro: MACRO_FIELDS,
     being: Object.freeze([...BEING_FIELDS, ...PRESENTATION_FIELDS.being]),
+    vehicle: VEHICLE_FIELDS,
     map: MAP_FIELDS,
 });

package/types/content-config.d.mts

@@ -41,6 +41,7 @@ export namespace DEFAULT_PATHS {
     let content: "assets/content";
     let manifests: "assets/manifests";
     let manifestOut: "build/manifests";
+    let contentIndex: "build/content-index";
     let packJson: "build/packs-json";
     let stage: "build/stage/packs";
     let unpack: "build/tmp/packs";
@@ -296,6 +297,13 @@ export type PathsInput = {
      *       `manifests` directory.
      */
     manifestOut?: string | undefined;
+    /**
+     * Where `content-index` writes this
+     *      package's note index. Outbound, and a
+     *      derived artifact — never a source, and
+     *      never inside `stage`.
+     */
+    contentIndex?: string | undefined;
     /**
      * Build-only per-entry JSON intermediate.
      */
@@ -316,6 +324,7 @@ export type ResolvedPaths = {
     content: string;
     manifests: string;
     manifestOut: string;
+    contentIndex: string;
     packJson: string;
     stage: string;
     unpack: string;

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

@@ -21,44 +21,32 @@
  */
 export function addressSlug(fm: object): string;
 /**
- * A note's address below the knowledgebase mount, e.g. `affliction-aconite/`.
+ * A note's address: `<type>-<shortcode>/`, e.g. `affliction-aconite/`.
  *
- * Every note, without exception. A `README.md` used to be its section's landing
- * page and to address the section instead of itself; a section is a Hugo
- * directory concept the note format no longer carries (#204), so a file's name
- * decides nothing about where it publishes.
- *
- * @param {object} fm - Parsed frontmatter.
- * @returns {string} The mount-relative address, with a trailing slash.
- * @throws {Error} When the note has no address.
- */
-export function contentAddress(fm: object): string;
-/**
- * A note's address relative to its **package**, e.g. `affliction-aconite/`.
- *
- * This is the form the link manifest records and the site build emits pages at,
- * and it is one function because those two must agree — a manifest asserting an
+ * This is the one form a note is addressed by. It is what the link manifest
+ * records as an entry's `path` and what the site build emits the page at, and
+ * it is one function because those two must agree — a manifest asserting an
  * address the site does not publish resolves at build time and 404s for the
  * reader, which is the failure this module exists to prevent.
  *
- * **It is a pure function of the frontmatter.** Nothing about the file the note
- * was read from reaches it: the `README.md` convention that made one note
- * address a whole section is retired with the section itself (#204), so there
- * is one rule and no branch.
- *
- * **The prefix does not apply to a page's own address.** `prefix` says where the
- * content tree *mounts inside the package* — the Hugo directory its pages are
- * written under — and an address is `(type, shortcode)`, a package-wide identity
- * that takes no mount: `sohl` publishes `/sohl/affliction-aconite/` from a file
- * written under `kb/`. The `type-` half is what keeps that flat namespace clear
- * of the package's fixed mounts — `/<package>/` for the landing,
- * `/<package>/api/` for generated API docs, neither of which contains a hyphen
- * or names a type.
- *
- * **It takes no address scheme.** It took one until #215, to validate the
- * `landing` rule it then discarded; with that key retired, `prefix` was the
- * only thing left in the scheme and the paragraph above is the reason it never
- * applied. A parameter read by nothing is the defect this deletion is about.
+ * **The address is relative to the package**, and to nothing finer. A consumer
+ * composing a URL prepends where the package is served (`/<package>/`); a
+ * consumer composing a manifest entry measures against that same base. Nothing
+ * else is prepended: `prefix` says where the content tree *mounts inside the
+ * package* — the Hugo directory its pages are written under — and an address is
+ * `(type, shortcode)`, a package-wide identity that takes no mount, so `sohl`
+ * publishes `/sohl/affliction-aconite/` from a file written under `kb/`. The
+ * `type-` half is what keeps that flat namespace clear of the package's fixed
+ * mounts — `/<package>/` for the landing, `/<package>/api/` for generated API
+ * docs, neither of which contains a hyphen or names a type.
+ *
+ * **It is a pure function of the frontmatter**, and takes no options. Nothing
+ * about the file the note was read from reaches it: the `README.md` convention
+ * that made one note address a whole section is retired with the section itself
+ * (#204), so every note is addressed alike and there is one rule and no branch.
+ * It took an address scheme until #215, to validate a `landing` rule it then
+ * discarded; with that key retired, `prefix` was the only thing left in the
+ * scheme and the paragraph above is the reason it never applied.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string} The package-relative address, with a trailing slash and no

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

@@ -0,0 +1,194 @@
+/**
+ * The `{#slug}` anchors a note's body declares, with where each one sits.
+ *
+ * Only headings carrying an explicit anchor are collected. A bare `#` heading
+ * also starts a journal page, but it declares no slug, so nothing can address
+ * it with `#…` — listing it would offer a link that cannot be written.
+ *
+ * @param {string} body - The note's markdown body, frontmatter already removed.
+ * @param {number} [bodyLine] - The 1-based file line the body starts on, from
+ *   `parseMarkdownFile`. Anchors are reported at their position in the **file**,
+ *   so an editor can jump straight to one; passing nothing numbers from the body.
+ * @returns {Array<{slug: string, name: string, level: number, line: number}>}
+ *   In document order.
+ */
+export function collectAnchors(body: string, bodyLine?: number): Array<{
+    slug: string;
+    name: string;
+    level: number;
+    line: number;
+}>;
+/**
+ * The address a wikilink writes to reach a note, or `null` when it has none.
+ *
+ * A wikilink target is an address: `being-aurochs` locally, or
+ * `sohl-being-aurochs` from another package (`readQualifier` also accepts
+ * `being/aurochs`, the same two fields with a different separator). Both forms
+ * are already derivable from `type` and `shortcode`, which every record
+ * carries — so this field adds no information. What it adds is the *rule*:
+ * the lowercasing and the hyphen join live in one place, and a consumer that
+ * reimplements them slightly differently gets a lookup that matches nothing and
+ * says nothing about why. That is a real failure, not a hypothetical one — it
+ * is precisely how a resolver keyed on a bare `type/shortcode` silently misses
+ * every canonical `pkg-type-shortcode` entry.
+ *
+ * Derived by the same functions the link manifest and the site build use, so an
+ * index cannot disagree with either about where a note lives.
+ *
+ * @param {Record<string, any>} frontmatter - The note's parsed frontmatter.
+ * @param {string} contentPackage - The package the tree compiles as.
+ * @returns {{slug: string, canonical: string}|null} `slug` is what goes inside
+ *   `[[…]]` within this package; `canonical` is the package-qualified key the
+ *   manifest files the note under. `null` for a note with no type or no
+ *   shortcode, which has no address at all and is stated as such rather than
+ *   left for every reader to rediscover.
+ */
+export function noteAddress(frontmatter: Record<string, any>, contentPackage: string): {
+    slug: string;
+    canonical: string;
+} | null;
+/**
+ * Recursively sort an object's keys, so serialization is order-independent.
+ *
+ * Arrays keep their order — it is authored — but every object inside one is
+ * sorted too. Anything that is not a plain object is returned as it is.
+ *
+ * @param {unknown} value - The value to normalize.
+ * @returns {unknown} The value with every plain object's keys in sorted order.
+ */
+export function sortKeysDeep(value: unknown): unknown;
+/**
+ * A note's display name reduced to printable 7-bit ASCII.
+ *
+ * Content names carry the setting's orthography — `Kûrbúl Helm`, `Hârn`,
+ * `Kèthîra` — and nobody types them. A reader searching the index, or an editor
+ * completing a wikilink, needs a form that matches what a keyboard produces, so
+ * the record states one rather than leaving every consumer to invent it (and to
+ * invent a *different* one, which is how two searches over the same data come
+ * to disagree).
+ *
+ * **Transliterated, not stripped.** `unidecode` — the same table
+ * {@link slugify} already runs, so an ASCII name and a slug can never disagree
+ * about a character — carries a letter across rather than deleting it:
+ * diacritics fold (`â`→`a`, `è`→`e`), ligatures expand (`æ`→`ae`, `Œ`→`OE`,
+ * `ß`→`ss`), the runic letters spell out (`þ`→`th`, `Þ`→`Th`, `ð`→`d`), and
+ * even a vulgar fraction becomes readable (`¾`→`3/4`). Deleting them instead
+ * would collapse `Kûrbúl` to `Krbl`, which is worse than the original.
+ *
+ * Anything still outside printable ASCII after that becomes a space, and runs
+ * of whitespace collapse — a space rather than nothing, so a character that
+ * transliterates away cannot silently weld two words together.
+ *
+ * The value is emitted even when it equals the name, so a consumer matching on
+ * it never has to branch on whether the name happened to be ASCII already.
+ *
+ * @param {unknown} name - The note's `name.full`.
+ * @returns {string|null} The ASCII form, or `null` when there is no name, or
+ *   nothing printable survives.
+ */
+export function asciiName(name: unknown): string | null;
+/**
+ * A note's `name.aliases` reduced to printable 7-bit ASCII, in order.
+ *
+ * An alias is the name a reader is at least as likely to reach for as the
+ * canonical one — `Killer Whale` for an orca, `Ice Bear` for a polar bear,
+ * `Ix'balam` for a jaguar — so anything searching or completing over the index
+ * has to match them too, and needs the same keyboard-typeable form
+ * {@link asciiName} gives the primary name.
+ *
+ * Order is the authored order, so a caller can pair an entry with the alias it
+ * came from. An alias that is not a non-empty string, or that leaves nothing
+ * printable behind, is dropped rather than left as a hole — the array is a set
+ * of names to match, and a null in it is not one.
+ *
+ * @param {unknown} aliases - The note's `name.aliases`; may be absent or null.
+ * @returns {Array<string>} Possibly empty, never null: a note with no aliases
+ *   has an empty set of them, which is a fact rather than a missing value, and
+ *   a consumer iterating it should not have to check first.
+ */
+export function asciiAliases(aliases: unknown): Array<string>;
+/**
+ * Build one index record from a note's frontmatter and its place in the tree.
+ *
+ * @param {object} options - Options.
+ * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
+ * @param {string} options.relPath - Its path below the content root, POSIX-separated.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {string} [options.body] - The note's markdown body, for its anchors.
+ * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
+ * @returns {Record<string, any>} The record, keys sorted at every depth.
+ * @throws {Error} When the note carries a key this module derives, which would
+ *   otherwise be overwritten without a word.
+ */
+export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, bodyLine }: {
+    frontmatter: Record<string, any>;
+    relPath: string;
+    contentPackage: string;
+    body?: string | undefined;
+    bodyLine?: number | undefined;
+}): Record<string, any>;
+/**
+ * Read a content tree into index records, in the order they will be written.
+ *
+ * @param {string} contentBase - The content tree to walk.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {Array<string>} [options.skipDirectories] - Directory names to skip.
+ * @returns {Array<Record<string, any>>} The records, in a total order that does
+ *   not depend on directory-read order.
+ */
+export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories }: {
+    contentPackage: string;
+    skipDirectories?: string[] | undefined;
+}): Array<Record<string, any>>;
+/**
+ * Serialize records as JSON Lines.
+ *
+ * @param {Array<Record<string, any>>} records - From {@link collectContentIndex}.
+ * @returns {string} One compact JSON object per line, newline-terminated. An
+ *   empty set serializes to the empty string rather than to a lone newline, so
+ *   the file is exactly the lines it holds.
+ */
+export function serializeContentIndex(records: Array<Record<string, any>>): string;
+/**
+ * Emit this package's content index.
+ *
+ * @param {object} [options] - Options.
+ * @param {string} [options.contentBase] - The content tree; defaults to the
+ *   configured `paths.content`.
+ * @param {string} [options.outDir] - Where to write; defaults to the configured
+ *   `paths.contentIndex`.
+ * @param {object} [options.config] - A resolved configuration; loaded when omitted.
+ * @returns {{file: string, notes: number, bytes: number}} Where it was written,
+ *   how many notes it holds, and its size.
+ * @throws {Error} When the content tree is absent, or when it yields no note at
+ *   all — an empty index is indistinguishable from a mis-pointed tree, and a
+ *   reader would take it as the authoritative statement that this package has
+ *   no content.
+ */
+export function emitContentIndex({ contentBase, outDir, config }?: {
+    contentBase?: string | undefined;
+    outDir?: string | undefined;
+    config?: object | undefined;
+}): {
+    file: string;
+    notes: number;
+    bytes: number;
+};
+/**
+ * The keys this module adds to a record, which a note therefore may not carry
+ * itself.
+ *
+ * `package` is the note's distribution unit — the configured `contentPackage`,
+ * since a note declaring its own is a hard error (package-build#56) — and it
+ * matches what the content-table expander puts on the same field, so a query
+ * reads the same value from either. `file` namespaces the note's place in the
+ * tree, again matching the expander's `file.*`.
+ *
+ * Both are checked rather than assumed: `folder` is real frontmatter on most
+ * notes, so the neighbouring names are close enough to a real key that a silent
+ * overwrite is a plausible future rather than a hypothetical one.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const DERIVED_KEYS: ReadonlyArray<string>;

package/types/engine/index.d.mts

@@ -17,6 +17,7 @@ export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";
 export * as kbManifest from "./kb-manifest.mjs";
 export * as manifestEmit from "./manifest-emit.mjs";
+export * as contentIndex from "./content-index.mjs";
 export * as siteBuild from "./site-build.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentLinks from "./content-links.mjs";

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

@@ -187,6 +187,10 @@ export const NOTE_VOCABULARY: Readonly<{
         subTypes: null;
         data: readonly DataFieldSpec[];
     }>;
+    vehicle: Readonly<{
+        subTypes: null;
+        data: readonly DataFieldSpec[];
+    }>;
     affiliation: Readonly<{
         subTypes: readonly string[];
         data: readonly DataFieldSpec[];
@@ -198,6 +202,10 @@ export const NOTE_VOCABULARY: Readonly<{
     armorgear: Readonly<{
         data: readonly DataFieldSpec[];
     }>;
+    armorlocation: Readonly<{
+        subTypes: null;
+        data: readonly DataFieldSpec[];
+    }>;
     attribute: Readonly<{
         data: readonly DataFieldSpec[];
     }>;
@@ -256,6 +264,48 @@ export const NOTE_VOCABULARY: Readonly<{
     macro: Readonly<{
         data: readonly never[];
     }>;
+    lore: Readonly<{
+        subTypes: readonly string[];
+        data: readonly never[];
+    }>;
+    place: Readonly<{
+        subTypes: readonly string[];
+        data: readonly ({
+            describe: string;
+            shape: "string";
+            kind: "string";
+            name: string;
+        } | {
+            describe: string;
+            shape: "list of wikilinks";
+            kind: "list";
+            name: string;
+        } | {
+            describe: string;
+            shape: "number";
+            kind: "number";
+            name: string;
+        })[];
+    }>;
+    scenario: Readonly<{
+        subTypes: readonly string[];
+        data: readonly ({
+            describe: string;
+            shape: "list of wikilinks";
+            kind: "list";
+            name: string;
+        } | {
+            describe: string;
+            shape: "string";
+            kind: "string";
+            name: string;
+        } | {
+            describe: string;
+            shape: "list";
+            kind: "list";
+            name: string;
+        })[];
+    }>;
     homepage: Readonly<{
         data: readonly never[];
     }>;