@heroiclands/package-build 22.14.1 → 22.14.3

package/engine/frontmatter.mjs

@@ -137,11 +137,10 @@ export function sohlSystemField(fm, to, defaultValue = undefined, { legacyKey =
  * Read a frontmatter property that is authored as a **map**, returning its
  * entries — or `null` when the note authors none.
  *
- * Obsidian's property editor serializes an **emptied map as an empty list**, so
- * a note whose map property was ever touched and cleared in the editor arrives
- * as `[]`, not `{}`. The two spellings mean the same thing — this note authors
+ * An empty map may be written as `{}` or `[]`. Both spellings mean the same
+ * thing — this note authors
  * no entries — and a build that accepted only one of them failed on notes the
- * editor itself had produced (#8; 44 affiliation notes in `sohl-thalorna`).
+ * editor itself had produced ( 44 affiliation notes in `sohl-thalorna`).
  * Normalizing the notes would fix only today's tree: the next editor touch puts
  * the empty list back.
  *
@@ -213,8 +212,7 @@ export function resolveCharges(fm) {
  * kept — an element a sign leaves untouched still beats one another sign
  * hinders, so it carries real weight when maps merge.
  *
- * An absent property, an empty map, and the empty **list** Obsidian's property
- * editor writes for a cleared map all mean the same thing — see
+ * An absent property, an empty map, and an empty list all mean the same thing — see
  * {@link readMapEntries}.
  *
  * @param {object} fm - The item frontmatter.
@@ -249,8 +247,7 @@ export function resolveSkillAptitudes(fm, ctx = "item") {
  * and be dropped silently, shipping an affiliation whose authored hostility had
  * quietly become neutrality — so it is a build error instead.
  *
- * An absent property, an empty map, and the empty **list** Obsidian's property
- * editor writes for a cleared map all mean the same thing — neutral toward
+ * An absent property, an empty map, and an empty list all mean the same thing — neutral toward
  * everyone. See {@link readMapEntries}.
  *
  * @param {object} fm - The item frontmatter.

package/engine/helpers.mjs

@@ -249,9 +249,8 @@ export function assertSuppliedCorpus(records, who) {
  * is warned about and skipped.
  *
  * Directory names in `skipDirectories` are ignored wherever they appear. The
- * walk itself knows nothing about what they mean: `Templates/` is an Obsidian
- * templater convention this repository's vault happens to use, not a property
- * of a content tree, so it is stated by the caller rather than hard-coded.
+ * walk itself knows nothing about what they mean: `Templates/` is authoring
+ * scaffolding rather than content, so the caller names it explicitly.
  *
  * @param {string} rootDir - Root of the tree to walk.
  * @param {object} opts
@@ -652,7 +651,7 @@ let cachedDefaultStats;
  * Each compiler used to hoist `const STATS = buildStats()` at module scope,
  * which read the shipped package manifest the moment the module was imported —
  * so importing a compiler required a manifest to exist even when nothing was
- * going to be compiled (#2). Deferred to first use and memoised here, the
+ * going to be compiled. Deferred to first use and memoised here, the
  * cost and the identity are what they always were; only the moment moved.
  *
  * @returns {object} The default `_stats` block, shared by every compiler.

package/engine/index.mjs

@@ -184,6 +184,9 @@ export * as packagebuildIndex from "./packagebuild-index.mjs";
 /** Publishing a content tree as a website: the pass, and its integrity gates. */
 export * as siteBuild from "./site-build.mjs";
 
+/** In-memory page rendering for an editor preview. */
+export * as sitePreview from "./site-preview.mjs";
+
 /** Address rules every content tree is linted against: shape, uniqueness, alias. */
 export * as contentLint from "./content-lint.mjs";
 

package/engine/infobox.mjs

@@ -112,7 +112,7 @@
  * @module
  */
 
-import { isAddressTuple, renderAddress } from "./address.mjs";
+import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
 import { getFrontmatter } from "./frontmatter.mjs";
 import { currentType } from "./ids.mjs";
 import { NOTE_VOCABULARY, dataFields } from "./note-vocabulary.mjs";
@@ -274,6 +274,7 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
     bgImage: Object.freeze({ withheld: "an image, which the box never carries" }),
     banner: Object.freeze({ withheld: "an image, which the box never carries" }),
     overlay: Object.freeze({ withheld: "an image, which the box never carries" }),
+    "lore.event": Object.freeze({ withheld: "chronology machinery, not a summary row" }),
 
     assocSkill: Object.freeze({ label: "Skill" }),
     assocAffiliation: Object.freeze({ label: "Affiliation" }),
@@ -555,6 +556,58 @@ function rowValue(kind, raw, resolve, hint) {
     return presentValue(raw);
 }
 
+/** Expand structured references using the existing linked-row shape. */
+function structuredRows(field, raw, resolve, label, fm) {
+    if (Array.isArray(raw) && raw.some(isMapping)) {
+        const links = raw
+            .filter((entry) => isMapping(entry) && hasValue(entry.to))
+            .map((entry) => {
+                const link = linkValue(entry.to, resolve, { type: field.ref ?? "place" });
+                const details = Object.entries(entry)
+                    .filter(([key, value]) => key !== "to" && hasValue(value))
+                    .map(([key, value]) => `${humanizeFieldName(key)}: ${presentValue(value)}`);
+                return {
+                    ...link,
+                    text: details.length ? `${link.text} (${details.join(", ")})` : link.text,
+                };
+            });
+        return links.length ? [{ label, kind: "links", value: links }] : [];
+    }
+    if (isMapping(raw) && !isAddressTuple(raw)) {
+        const groups = new Map();
+        for (const [target, relation] of Object.entries(raw)) {
+            if (!hasValue(target) || !hasValue(relation) || isMapping(relation)) continue;
+            const term = String(relation);
+            if (field.terms && !field.terms.some((entry) => entry.term === term)) continue;
+            if (field.terms && field.keyKind === "address") {
+                const address = parseAddress(
+                    target,
+                    {
+                        package: fm.package ?? "local",
+                        system: "note",
+                        types: new Set(field.accepts),
+                    },
+                    { declared: true },
+                );
+                if (address.reason || (field.accepts && !field.accepts.includes(address.type)))
+                    continue;
+            }
+            const links = groups.get(term) ?? [];
+            links.push(linkValue(target, resolve, { type: field.ref }));
+            groups.set(term, links);
+        }
+        const terms = field.terms ? field.terms.map(({ term }) => term) : [...groups.keys()];
+        return terms
+            .filter((term) => groups.has(term))
+            .map((term) => ({
+                label: presentValue(term),
+                kind: "links",
+                value: groups.get(term),
+            }));
+    }
+    return null;
+}
+
 /**
  * One row, with its unit on it.
  *
@@ -664,7 +717,19 @@ function noteBox(
         // The current name wins, which is the whole of the retirement window's
         // behaviour and is `readAliasedField`'s answer, not a second one.
         const own = getFrontmatter(data, field.name, undefined);
-        const raw = hasValue(own) ? own : readAliasedField(fm, field.name, { inData: true });
+        const raw = own !== undefined ? own : readAliasedField(fm, field.name, { inData: true });
+        const structured = structuredRows(
+            field,
+            raw,
+            resolve,
+            overlay.label ?? humanizeFieldName(field.name),
+            fm,
+        );
+        if (structured) {
+            rows.push(...structured);
+            if (structured.length) shown.add(field.name);
+            continue;
+        }
         if (!hasValue(raw)) continue;
 
         if (overlay.group) {

package/engine/item-registry.mjs

@@ -57,7 +57,7 @@ import { resolveImg } from "./helpers.mjs";
  * compile.
  *
  * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration (#2).
+ * needs no configuration.
  *
  * @returns {ReadonlySet<string>} The configured item types.
  */
@@ -163,7 +163,7 @@ export function itemFields(type, system) {
  * 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).
+ * of its notes set `img:`.
  *
  * **Still fail-fast.** A type with neither a note-level `img:` nor paired art
  * aborts the pack build rather than shipping a mismatched icon — the contract

package/engine/note-vocabulary.mjs

@@ -96,12 +96,16 @@ import {
 // package's declared present compute — the closed `data:` container's own
 // question, asked the way `checkPlace` and `checkCalendarNote` are.
 import { checkBeingAge } from "./being-age.mjs";
+import { checkSocialTies } from "./social-ties.mjs";
+import { SOCIAL_TIES } from "./social-tie-terms.mjs";
+import { parseNoteDate } from "./note-dates.mjs";
 import { checkHeld } from "./holdings.mjs";
 import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 // What trade a settlement supports — the scale and the check that holds a
 // value to it, read rather than restated, so the reference below and the
 // finding an author meets state one list.
 import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 
 /**
  * One `data:` key a note type may carry.
@@ -365,6 +369,51 @@ function checkPlace(note, opts) {
     return [...checkHeld(note, opts), ...checkWorldFacts(note, opts)];
 }
 
+/** Validate a being's authored date using the shared note-date grammar. */
+function checkBeingDate(key) {
+    return (note) =>
+        parseNoteDate(note.fm?.data?.[key], {
+            field: `data.${key}`,
+            file: note.file,
+            raw: note.raw,
+            keyPath: ["data", key],
+        }).findings;
+}
+
+/** A place's purpose selects one of its own character tags. */
+function checkPlacePurpose(note) {
+    const value = note.fm?.data?.purpose;
+    if (value === undefined || value === null) return [];
+    const at = () => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(note.raw ?? "", ["data", "purpose"]),
+        severity: "error",
+    });
+    const subType = note.fm?.subType;
+    if (!["settlement", "site", "structure"].includes(subType))
+        return [
+            {
+                ...at(),
+                message: `data.purpose applies to a settlement, site, or structure; this place is ${subType ?? "untyped"}`,
+            },
+        ];
+    if (!DECLARED_TAGS.placeCharacter.tags.includes(value))
+        return [
+            {
+                ...at(),
+                message: `data.purpose ${JSON.stringify(value)} is not a placeCharacter tag; choose one of ${DECLARED_TAGS.placeCharacter.tags.join(", ")}`,
+            },
+        ];
+    if (hasTag(note.fm, value)) return [];
+    const tags = note.fm?.tags ?? note.fm?.tag;
+    return [
+        {
+            ...at(),
+            message: `data.purpose ${JSON.stringify(value)} must select one of this place's tags; it carries ${JSON.stringify(tags ?? [])}`,
+        },
+    ];
+}
+
 /* --------------------------------------------------------------------- */
 /*  The vocabulary                                                        */
 /* --------------------------------------------------------------------- */
@@ -485,6 +534,10 @@ export const DECLARED_TAGS = Object.freeze({
             "holy",
             "sacred",
             "free",
+            "ford",
+            "portage",
+            "pass",
+            "well",
         ]),
     }),
     /** A place's scale, where the subtype does not distinguish it. */
@@ -564,14 +617,13 @@ export function exclusiveTagGroups(type, groups = DECLARED_TAGS) {
 /**
  * Whether a note carries a given tag, however the author wrote it.
  *
- * `tags:` is authored by hand and Obsidian is permissive about it: a single tag
+ * `tags:` accepts common YAML forms: a single tag
  * may be a scalar rather than a list, a value may carry the leading `#` it is
  * written with in prose, and case and surrounding space are not significant.
  * The spelling of the tag *itself* still is — a near miss is a near miss, and
  * the frontmatter lint is what reports it; nothing here guesses.
  *
- * Reads `tags` and, as Dataview does, `tag` — the singular spelling Obsidian
- * also accepts.
+ * Reads `tags` and the singular `tag` spelling.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} tag - The tag to look for, in its declared spelling.
@@ -663,6 +715,16 @@ export const NOTE_VOCABULARY = Object.freeze({
                 accepts: ["affiliation"],
                 describe: "Affiliations the being belongs to — traditions, polities, and the rest.",
             },
+            {
+                name: "socialTies",
+                kind: "map",
+                keyKind: "address",
+                accepts: ["being", "affiliation"],
+                terms: SOCIAL_TIES,
+                shape: "a map keyed by Address",
+                check: checkSocialTies,
+                describe: `Defining ties directed from this being to others: ${SOCIAL_TIES.map(({ term, meaning }) => `\`${term}\` (${meaning})`).join("; ")}`,
+            },
             { name: "gender", ...TEXT, describe: "`male`, `female` or `other`." },
             {
                 name: "species",
@@ -674,6 +736,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "born",
                 ...TEXT,
+                check: checkBeingDate("born"),
                 describe:
                     "When the being was born — a date, or `unknown` where the birth is " +
                     "unrecorded. Absent, the being was never born.",
@@ -681,6 +744,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "died",
                 ...TEXT,
+                check: checkBeingDate("died"),
                 describe:
                     "When the being died — a date, or `unknown` where the death is " +
                     "unrecorded. Absent, the being is alive.",
@@ -1097,13 +1161,20 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     doc: Object.freeze({
         stubbable: true,
-        // Five genres, and a genre is all this field carries: what kind of page
+        // A genre is all this field carries: what kind of page
         // it is, never who reads it. An audience term alongside them would give
         // a developer how-to two valid values and no rule for choosing.
         //
         // `userguide` and `howto`, not `user-guide` and `how-to`: a subType is
         // held to the address charset, and a segment carries no hyphen.
-        subTypes: Object.freeze(["rules", "userguide", "reference", "howto", "concept"]),
+        subTypes: Object.freeze([
+            "rules",
+            "userguide",
+            "reference",
+            "howto",
+            "concept",
+            "settingguide",
+        ]),
         check: checkCitedPopulations,
         data: Object.freeze([]),
     }),
@@ -1189,7 +1260,15 @@ export const NOTE_VOCABULARY = Object.freeze({
         // because `DataFieldSpec` declares the keys a type accepts and not the
         // subType that may write them.
         check: checkCalendarNote,
-        data: CALENDAR_FIELDS,
+        data: Object.freeze([
+            ...CALENDAR_FIELDS,
+            {
+                name: "event",
+                kind: "map",
+                shape: "event metadata map",
+                describe: "A dated occurrence and its relationships to other events and places.",
+            },
+        ]),
     }),
 
     place: Object.freeze({
@@ -1210,6 +1289,13 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...TEXT,
                 describe: "What a person from this place is called — a Vylarian.",
             },
+            {
+                name: "purpose",
+                ...TEXT,
+                check: checkPlacePurpose,
+                describe:
+                    "The reason this settlement, site, or structure exists, selected from its placeCharacter tags.",
+            },
             {
                 name: "lore",
                 ...LINKS,

package/engine/pack-config.mjs

@@ -37,7 +37,7 @@
  * only the derivations differ, and they differ because a code file can do its
  * own I/O while `defineConfig` deliberately does none.
  *
- * **Resolved on first read, never at import (#2).** {@link loadPackConfig}
+ * **Resolved on first read, never at import.** {@link loadPackConfig}
  * is a function rather than a module-level constant, so importing this module —
  * or the `engine` barrel, or a leaf module that happens to sit downstream of it
  * — costs nothing and requires nothing. A repository with no configuration can
@@ -705,7 +705,7 @@ let loadedFrom;
  *
  * Every engine module that needs a configured value calls this, rather than
  * hoisting one at import: that is what keeps the library importable without a
- * configuration (#2). The result is memoised, so calling it in a default
+ * configuration. The result is memoised, so calling it in a default
  * parameter — the usual spelling here — costs one property read per call.
  *
  * @returns {import("../content-config.mjs").ContentBuildConfig} The frozen configuration.

package/engine/pack-router.mjs

@@ -43,7 +43,7 @@
  * - A declared name that no pack answers to — or that names a pack holding
  *   another document type, or a companion pack, which no note may address —
  *   fails the build, naming the note and what it asked for. A silent fall-back
- *   to the default would be #1502 in a new costume.
+ *   to the default would publish an address into the wrong compendium.
  * - A note's **derived** documents are routed by the default of *their* type,
  *   not by the note's declaration: an item note's prose compiles into a
  *   JournalEntry, and `pack:` names where the *item* goes.
@@ -501,7 +501,7 @@ export function routerFor(config) {
  * asks where a note's document lives.
  *
  * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration (#2). {@link routerFor} keeps one router per
+ * needs no configuration. {@link routerFor} keeps one router per
  * configuration object, so repeated calls return the same instance.
  *
  * @returns {ReturnType<typeof createPackRouter>} This repository's router.

package/engine/pdf-render.mjs

@@ -956,7 +956,7 @@ export function bookTypstPreamble() {
 /**
  * The whole book, as one Typst document.
  *
- * **Pure, and that is the point.** Everything a reviewer of #316 has to check
+ * **Pure, and that is the point.** The book's structural properties
  * about structure — the outline's shape, the anchors, which links went inward,
  * the order entries print in — is decided here from a plan and a map of bodies,
  * with no filesystem and no compiler. {@link module:engine/pdf-build} supplies

package/engine/pdf-toc.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The document tree a PDF is built from, and the plan it resolves to (#316).
+ * The document tree a PDF is built from, and the plan it resolves to.
  *
  * The packs and the website both render the *whole* content tree: every note
  * becomes a document and a page, and the three surfaces agreeing about what the
@@ -39,7 +39,7 @@
  * handed back as `selections`, the way `expandContentTables` is handed its
  * `sqlTables` because DuckDB is async and the pass is not. That is what lets the
  * whole structure of a 2,500-entry book be asserted in a unit test with no
- * renderer present, which is most of what #316 asks for.
+ * renderer present, covering the structure before presentation is applied.
  *
  * **Every gate reports; none exits.** A filter that will not parse, a `file:`
  * that resolves nowhere and a filter reaching another package's schema are
@@ -415,7 +415,7 @@ export async function runTreeFilters(nodes, db, { keep = () => true, text } = {}
  * The plan is an ordered list of entries — `section`, `prose`, `note` — and it
  * is the artifact worth having. Order, depth, the outline, the table of
  * contents, anchor uniqueness and every link destination are all readable from
- * it, so nearly the whole of what #316 asks for can be asserted here, on data,
+ * it, so the book's structure can be asserted here, on data,
  * without a renderer or a PDF. Only how the result *looks* needs eyes.
  *
  * **Notes are sorted, prose is not.** A section's entries come out in

package/engine/retired-fields.mjs

@@ -84,7 +84,7 @@
  * {@link RETIRED_FIELD_ALIASES}.
  *
  * **The third step is deletion, and it needs no code.** `image`, a map's
- * background art, is the first rename to have run all three: reported (#142),
+ * background art, illustrates all three states: reported,
  * swept, then dropped from the
  * table. Removing the entry is the whole of it — with no alias, the spelling is
  * an ordinary unknown key in the `sohl:` block, which the frontmatter lint

package/engine/scene-levels.mjs

@@ -43,7 +43,7 @@
  * Plain ESM with no Foundry, so the rule itself is a pure function over records
  * and is unit-tested directly.
  *
- * **What a report has to say (#9).** The likeliest way to meet any of this is a
+ * **What a report has to say.** The likeliest way to meet any of this is a
  * compendium CLI older than {@link LEVEL_SPLITTING_CLI}, which does not split
  * Scene Levels into the sublevel at all — so the guard fires on every scene at
  * once, and each `levels` entry is an inline Level *object* rather than an id.
@@ -71,7 +71,7 @@ const ADVENTURE_PREFIX = "!adventures!";
 /**
  * The compendium CLI release that began splitting Scene Levels into the
  * `!scenes.levels!` sublevel. Anything older writes them inline on the Scene
- * document, which is the shape the reports below name (#9).
+ * document, which is the shape the reports below name.
  */
 const LEVEL_SPLITTING_CLI = "3.0.3";
 
@@ -184,7 +184,7 @@ function predatesLevelSplitting(version) {
 
 /**
  * What to do about it, decided from the version actually resolved — so the
- * report ends in an instruction rather than a lead to follow (#9).
+ * report ends in an instruction rather than a lead to follow.
  *
  * @param {string | undefined} cliVersion - The resolved compendium CLI
  *   version, when it is known.
@@ -222,7 +222,7 @@ function describeRemedy(cliVersion) {
  * it on that record's write path; a pack that has none never split them, which
  * is what a compendium CLI older than {@link LEVEL_SPLITTING_CLI} does — two
  * different diagnoses, so the message names whichever shape it found rather
- * than guessing (#9).
+ * than guessing.
  *
  * @param {Array<[string, object]>} declaring - `[sceneId, scene]` for every
  *   scene declaring at least one level.

package/engine/schema-check.mjs

@@ -26,7 +26,7 @@
  *   of `sohl-kethira-basic`'s deities, is not defined at the version that module
  *   targets, so the divine/arcane split evaporates on load.
  * - **Declared, not emitted.** The mirror image, fixed by hand in
- *   content-build#3.
+ *   the shared build.
  *
  * Neither was found by tooling. Both were found by set-subtracting compiled
  * documents' `system` keys against `defineSchema()` **by hand**, which is how