@heroiclands/package-build 22.14.1 → 22.14.3

package/engine/social-ties.mjs

@@ -0,0 +1,84 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { parseAddress, renderAddress } from "./address.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { SOCIAL_TIES } from "./social-tie-terms.mjs";
+
+export { SOCIAL_TIES };
+
+const TERMS = new Set(SOCIAL_TIES.map(({ term }) => term));
+const ACCEPTED = new Set(["being", "affiliation"]);
+
+/** Validate a being's map of defining relationships. */
+export function checkSocialTies(note, { index } = {}) {
+    const ties = note.fm?.data?.socialTies;
+    if (ties === undefined || ties === null) return [];
+    const at = (key) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(
+            note.raw ?? "",
+            key ? ["data", "socialTies", key] : ["data", "socialTies"],
+            { key: true },
+        ),
+        severity: "error",
+    });
+    if (typeof ties !== "object" || Array.isArray(ties))
+        return [
+            {
+                ...at(),
+                message: "data.socialTies must be a map of Address keys to relationship terms",
+            },
+        ];
+    const findings = [];
+    for (const [key, term] of Object.entries(ties)) {
+        const tuple = parseAddress(
+            key,
+            {
+                package: index?.contentPackage ?? note.fm?.package,
+                system: "note",
+                types: index?.types,
+                packages: index?.packages,
+            },
+            { declared: true },
+        );
+        if (tuple.reason) {
+            findings.push({
+                ...at(key),
+                message: `data.socialTies key ${JSON.stringify(key)} is not a complete Address (${tuple.reason}); write being or affiliation as its type`,
+            });
+        } else if (!ACCEPTED.has(tuple.type)) {
+            findings.push({
+                ...at(key),
+                message: `data.socialTies accepts being or affiliation, not ${tuple.type}`,
+            });
+        } else if (
+            tuple.package === (index?.contentPackage ?? note.fm?.package) &&
+            tuple.type === "being" &&
+            tuple.shortcode === note.fm?.shortcode
+        ) {
+            findings.push({
+                ...at(key),
+                message: `data.socialTies cannot address this being itself`,
+            });
+        } else if (index?.addressHit && !index.addressHit(renderAddress(tuple))) {
+            findings.push({
+                ...at(key),
+                message: `data.socialTies target ${renderAddress(tuple)} does not resolve`,
+            });
+        }
+        if (!TERMS.has(term))
+            findings.push({
+                ...at(key),
+                message: `data.socialTies value ${JSON.stringify(term)} must be one of ${SOCIAL_TIES.map(({ term: value }) => value).join(", ")}`,
+            });
+    }
+    return findings;
+}

package/engine/sql-tables.mjs

@@ -14,15 +14,8 @@
 /**
  * Content tables written in SQL, queried over the content index.
  *
- * The tables were written in Dataview's query language, chosen when the corpus
- * lived in an Obsidian vault so a table rendered live while authoring. The vault
- * is gone, and what remained was a hand-written parser and evaluator for someone
- * else's language, kept faithful to semantics nothing checked it against.
- *
- * **The query is real SQL, run by DuckDB** — not a dialect maintained here. That
- * is the whole point: a partial reimplementation would accept some valid SQL and
- * silently misread the rest, which is worse than an unfamiliar language, because
- * the boundary is invisible.
+ * **The query is SQL, run by DuckDB.** Its syntax and evaluation follow the
+ * database rather than a separate parser in the toolchain.
  *
  * **What SQL cannot say, the projection says.** Rendering a table is not a
  * relational operation: which column links, and where a section breaks, are
@@ -273,6 +266,8 @@ export async function openNotesDatabase(records, { dir, dependencies = [], addre
             };
         },
         async close() {
+            connection.closeSync();
+            instance.closeSync();
             if (!dir) fs.rmSync(base, { recursive: true, force: true });
         },
     };

package/hm3/actors.mjs

@@ -170,7 +170,7 @@ function defaultActorImg(subType) {
  * and `HM3.defaultPsionicsIconName` in the system's own `config.js` — so a
  * compiled item looks like one created in the client. `weapongear` and
  * `missilegear` need no row here: a reference spelled either resolves through
- * `HM3_DEFAULT_ITEM_ART`'s own `weapongear` key (see #582), and every
+ * `HM3_DEFAULT_ITEM_ART`'s own `weapongear` key, and every
  * predefined weapon and missile in HM3's catalogue carries its own `img`.
  *
  * @type {Readonly<Record<string, string>>}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.14.1",
+    "version": "22.14.3",
     "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",
@@ -147,10 +147,10 @@
         "loglevel": "^1.9.2",
         "loglevel-plugin-prefix": "^0.8.4",
         "markdown-it": "^15.0.0",
-        "markdownlint-cli2": "^0.23.2",
+        "markdownlint-cli2": "^0.23.3",
         "pagefind": "^1.5.2",
         "prettier": "^3.9.6",
-        "smol-toml": "^1.7.0",
+        "smol-toml": "^1.8.0",
         "ssh2-sftp-client": "^12.1.1",
         "typescript": "^6.0.3",
         "unidecode": "^1.1.0",

package/sohl/item-fields.mjs

@@ -140,7 +140,7 @@ const DURATION_BASE = Object.freeze({
 
 /** Aptitude weights per skill selector, validated as whole numbers. */
 const SKILL_APTITUDES = Object.freeze({
-    shape: "map of skill selector → whole number",
+    shape: "map of skill selector > whole number",
     read: (_raw, { fm }) => resolveSkillAptitudes(fm, noteContext(fm, "mystery")),
 });
 
@@ -188,7 +188,7 @@ const SKILL_UUID_ITEMS = Object.freeze({
 
 /** Standings toward other affiliations, validated against the closed list. */
 const RELATION = Object.freeze({
-    shape: "map of affiliation address → standing",
+    shape: "map of affiliation address > standing",
     read: (_raw, { fm }) => resolveRelation(fm, noteContext(fm, "affiliation")),
 });
 

package/types/config.d.mts

@@ -179,6 +179,14 @@ export type AssetSpec = {
      * Destination, relative to the staged package root.
      */
     to: string;
+    /**
+     * The foreign Address each file's basename claims, without its shortcode.
+     */
+    bindsTo?: {
+        package: string;
+        system: string;
+        type: string;
+    } | undefined;
 };
 /**
  * The resolved `packageBuild` section, every optional half filled in.

package/types/content-config.d.mts

@@ -781,7 +781,7 @@ export type ContentBuildConfig = {
      * Derived: the default art
      * of each entry that paired one. Sparse — a
      * type absent here has no default, and a note
-     * of it must carry `img:` (#7).
+     * of it must carry `img:`.
      */
     itemArt: Readonly<Record<string, string>>;
     /**

package/types/engine/address.d.mts

@@ -243,11 +243,9 @@ export function readCanonicalKey(key: unknown): {
  * confidently they mark a value as qualified:
  *
  * - **`type-shortcode`** and its qualified forms — the canonical spelling.
- *   Obsidian reads `/` inside a wikilink as a *path* and resolves it against the
- *   vault's folders, so a slash-qualified link is a broken link in the editor
- *   where the content is authored.
- * - **`type/shortcode`** — resolved so that a link written before the vault
- *   migrated does not silently die. A slash is *unconditionally* a qualifier:
+ *   The hyphenated form is portable across Markdown editors and renderers.
+ * - **`type/shortcode`** — an accepted qualified spelling. A slash is
+ *   *unconditionally* a qualifier:
  *   nothing else uses one, so an unknown type before it is reported rather than
  *   guessed at. The split is at the **last** slash.
  *

package/types/engine/asset-bindings.d.mts

@@ -0,0 +1,6 @@
+/** Check configured foreign Address bindings against fetched indexes. */
+export function checkForeignAssetBindings(config: any, { foreignIndex, assets }?: {}): {
+    file: string;
+    severity: string;
+    message: string;
+}[];

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

@@ -18,6 +18,14 @@ export function worldInvariants(index?: object): {
     yearNote: object | null;
     moonNote: object | null;
 };
+/** Check each authored format slot and every unescaped letter run in it. */
+export function checkCalendarDateFormats(note: any): {
+    severity: any;
+    message: any;
+    line?: number;
+    column?: number;
+    file: any;
+}[];
 /**
  * Check a `place` note's world facts.
  *
@@ -150,6 +158,10 @@ export const CALENDAR_SUBTYPE: "calendar";
  * @type {readonly string[]}
  */
 export const INVARIANT_SUBTYPES: readonly string[];
+/** Calendaria's display locations that a calendar note can format. */
+export const CALENDAR_DATE_FORMAT_KEYS: readonly string[];
+/** Bare date tokens Calendaria substitutes inside authored format strings. */
+export const CALENDAR_FORMAT_TOKENS: Readonly<Set<string>>;
 /**
  * The `data:` keys a calendar note may write — the closed list, in authored
  * order.

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

@@ -121,6 +121,17 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
     bodyLine?: number | undefined;
     manifest?: object | undefined;
 }): Record<string, any>;
+/** Derive every index record belonging to one parsed note. */
+export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, }: {
+    frontmatter: any;
+    body: any;
+    bodyLine: any;
+    relPath: any;
+    absPath: any;
+    contentPackage: any;
+    manifest: any;
+    addressContext: any;
+}): object[];
 /**
  * Read a content tree into index records, in the order they will be written.
  *

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

@@ -20,7 +20,7 @@
  * package below would differ.
  *
  * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration (#2).
+ * needs no configuration.
  *
  * @returns {string} The configured `contentPackage`.
  */
@@ -42,7 +42,7 @@ export function contentPackage(): string;
  * written — fails the build if this value and the manifest's `id` ever drift.
  *
  * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration (#2).
+ * needs no configuration.
  *
  * @returns {string} The configured `foundryPackage`.
  */

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

@@ -2,8 +2,7 @@
  * An authored `parent` with any wikilink brackets and label stripped.
  *
  * The specification types `parent` as an `Address`, written bare — but
- * `[[address]]` is what an author reaches for,
- * and Obsidian wrote that form for years. Accepting both costs one regex and
+ * `[[address]]` is also a recognizable link form. Accepting both costs one regex and
  * removes a failure whose message would have to explain the difference.
  *
  * @param {string|null} value - As authored.

package/types/engine/frontmatter-lint.d.mts

@@ -3,8 +3,7 @@
  *
  * Deliberately lenient about the spellings YAML makes ambiguous: `"12"` is a
  * number, because a quoted scalar is how a number arrives from many editors,
- * and a map authored as an empty list is a map, because Obsidian's property
- * editor serialises an emptied map that way (#8). What it rejects is a value
+ * and a map authored as an empty list has no entries, just like `{}`. What it rejects is a value
  * that cannot mean what the field is for — `weight: heavy`.
  *
  * @param {unknown} value - The authored value.

package/types/engine/frontmatter.d.mts

@@ -89,8 +89,7 @@ export function resolveCharges(fm: object): {
  * 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.
@@ -108,8 +107,7 @@ export function resolveSkillAptitudes(fm: object, ctx?: string): Record<string,
  * 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/types/engine/helpers.d.mts

@@ -72,9 +72,8 @@ export function assertSuppliedCorpus(records: readonly object[] | undefined, 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
@@ -319,7 +318,7 @@ export function statsForPack(packSystem: string | null | undefined, config?: obj
  * 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/types/engine/index.d.mts

@@ -49,6 +49,7 @@ export * as assetIndex from "./asset-index.mjs";
 export * as packages from "./packages.mjs";
 export * as packagebuildIndex from "./packagebuild-index.mjs";
 export * as siteBuild from "./site-build.mjs";
+export * as sitePreview from "./site-preview.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentCharset from "./content-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";

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

@@ -11,7 +11,7 @@
  * 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.
  */
@@ -54,7 +54,7 @@ export function itemFields(type: string, system?: string): readonly object[] | u
  * 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/types/engine/note-vocabulary.d.mts

@@ -36,14 +36,13 @@ export function exclusiveTagGroups(type: string, groups?: object): {
 /**
  * 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.
@@ -279,15 +278,15 @@ export type DataFieldSpec = {
      * value — which is the honest answer wherever the specification's stated
      * shape and the shape notes are authored in today disagree.
      */
-    kind?: "string" | "number" | "boolean" | "map" | "list" | "scalar-or-map" | "address" | "shortcode" | undefined;
+    kind?: "string" | "number" | "boolean" | "map" | "list" | "shortcode" | "scalar-or-map" | "address" | undefined;
     /**
      * - Type of each list or pack-map value.
      */
-    entryKind?: "address" | "shortcode" | undefined;
+    entryKind?: "shortcode" | "address" | undefined;
     /**
      * - Type of each map key.
      */
-    keyKind?: "address" | "shortcode" | undefined;
+    keyKind?: "shortcode" | "address" | undefined;
     /**
      * - An alternative `subType:<skill-subtype>` key.
      */

package/types/engine/pack-config.d.mts

@@ -105,7 +105,7 @@ export function configFromData(data: unknown, configPath: string): import("../co
  *
  * 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/types/engine/pack-router.d.mts

@@ -45,7 +45,7 @@ export function routerFor(config: object): ReturnType<typeof createPackRouter>;
  * 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/types/engine/pdf-render.d.mts

@@ -111,7 +111,7 @@ export function bookTypstPreamble(): string;
 /**
  * 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/types/engine/pdf-toc.d.mts

@@ -67,7 +67,7 @@ export function runTreeFilters(nodes: object[], db: {
  * 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/types/engine/site-build.d.mts

@@ -141,9 +141,8 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * The frontmatter a page publishes with.
  *
  * An authored `aliases` is retired and refused before a build reaches
- * here, which makes this a guard rather than a working path. It was Obsidian's
- * — a list of *names* a reader might call
- * the note, which is vault addressing and stays in the vault. Hugo reads
+ * here, which makes this a guard rather than a working path. It is a list of
+ * names a reader might call the note. Hugo reads
  * `aliases` as **URL redirects**, so passing them through would publish a
  * redirect stub at each name. They are dropped, and this build emits no
  * redirects of its own.
@@ -228,6 +227,38 @@ export function pageFrontmatter(page: object, { decorate, webSrc, artSrc }: {
 export function pageDestination(page: object, { bundle }?: {
     bundle?: boolean | undefined;
 }): string;
+/** Transform one content page without writing the site mount. */
+export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, }: {
+    index: any;
+    foreign: any;
+    universe: any;
+    pass?: {} | undefined;
+    decorate: any;
+    linkable?: ((d: any) => boolean) | undefined;
+    sqlTables: any;
+    config: any;
+    artIndex: any;
+}): {
+    page: any;
+    body: string;
+    data: object;
+    resolved: any[];
+    tableErrors: {
+        source: string;
+        directive: string;
+        reason: string;
+        line: number;
+        column?: number;
+    }[];
+    secretErrors: {
+        file: any;
+        line: number;
+        column: number;
+        message: string;
+    }[];
+    wikiErrors: any[];
+    imageErrors: any[];
+};
 /**
  * Renders and writes every page.
  *
@@ -289,6 +320,8 @@ export function renderPages(pages: object[], options: object): {
 export function resolveSitePass(name: string | undefined, options: object): {
     beforeLinks?: Function;
 };
+/** The site frontmatter decoration shared by the site writer and page preview. */
+export function sitePageDecorator(config: any, index: any): (data: any, page: any) => void;
 /**
  * Builds a Hugo content tree from a content tree, and reports what it found.
  *

package/types/engine/site-preview.d.mts

@@ -0,0 +1,34 @@
+/** Prepare saved project state once, then render live text without writing a site. */
+export function prepareSitePreview({ config }?: {
+    config?: import("../content-config.mjs").ContentBuildConfig | undefined;
+}): Promise<{
+    /** Render the active buffer. Other local and foreign notes remain saved. */
+    render(file: any, text: any): Promise<{
+        ok: boolean;
+        findings: {
+            file: string;
+            severity: string;
+            message: string;
+        }[];
+        markdown?: undefined;
+        frontmatter?: undefined;
+    } | {
+        ok: boolean;
+        findings: {
+            path: string;
+            link: string;
+            file: string;
+            severity: string;
+        }[];
+        markdown?: undefined;
+        frontmatter?: undefined;
+    } | {
+        ok: boolean;
+        markdown: string;
+        frontmatter: any;
+        findings: never[];
+    }>;
+    /** Re-read saved notes and dependency indexes after a save. */
+    refresh(): Promise<void>;
+    close(): Promise<void>;
+}>;

package/types/engine/social-tie-terms.d.mts

@@ -0,0 +1,5 @@
+/** Relationships a being states from its own point of view. */
+export const SOCIAL_TIES: readonly {
+    term: string;
+    meaning: string;
+}[];

package/types/engine/social-ties.d.mts

@@ -0,0 +1,10 @@
+/** Validate a being's map of defining relationships. */
+export function checkSocialTies(note: any, { index }?: {}): {
+    message: string;
+    severity: string;
+    line?: number;
+    column?: number;
+    file: any;
+}[];
+export { SOCIAL_TIES };
+import { SOCIAL_TIES } from "./social-tie-terms.mjs";