@heroiclands/package-build 22.21.0 → 22.23.0

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

@@ -24,6 +24,60 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
     records?: object[] | undefined;
     foreignReferences?: Map<string, object> | undefined;
 }): SiteIndex;
+/**
+ * The address keys one page's figures are reachable by — the same two forms
+ * {@link buildSiteIndex} assigns the page itself, so a `ref` crossing into it
+ * resolves by exactly the address a wikilink would use.
+ *
+ * @param {string} pkg - The page's own content package.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {Set<string>} The short `type/shortcode` key and the canonical
+ *   `package-system-type-shortcode` one.
+ */
+export function figureIndexKeys(pkg: string, type: string, shortcode: string): Set<string>;
+/**
+ * Resolve a `ref` call's cross-note address to the target's own figures and
+ * its own address — the `figures.note` a `ref` helper's render context reads,
+ * built once and threaded into every page.
+ *
+ * Reads the written address exactly as a wikilink does
+ * ({@link readQualifier}, {@link expandAddress}), so a `ref` crossing into
+ * another note and a `[[…]]` link to the same note agree on what resolves and
+ * what does not: a target naming no known type or no fetched package's index
+ * is unresolved for both, and one address names one note for both.
+ *
+ * @param {string} target - The address as written, anchor already removed —
+ *   {@link module:engine/wikilink-syntax.ParsedWikilink.target}.
+ * @param {object} options
+ * @param {Set<string>} options.contentTypes - Every type this build reads as
+ *   an address qualifier.
+ * @param {Set<string>} options.packages - Every package an address may name.
+ * @param {Set<string>} options.noIndexPackages - Packages declared
+ *   `contentIndex: false`.
+ * @param {string} options.contentPackage - The package a target with no
+ *   package segment defaults to.
+ * @param {Map<string, {url: string}>} options.siteIndexMap - {@link SiteIndex}'s
+ *   own `index`, read for the target's existence and its URL.
+ * @param {Map<string, Map<string, object>>} options.figuresByAddress - Every
+ *   note's figures, by id, keyed as {@link figureIndexKeys} keys the note.
+ * @returns {{url: string, figures: Map<string, object>}|undefined} The
+ *   target's own address and figures, or `undefined` when the address names
+ *   no note this build resolves.
+ */
+export function resolveCrossNoteFigures(target: string, { contentTypes, packages, noIndexPackages, contentPackage, siteIndexMap, figuresByAddress }: {
+    contentTypes: Set<string>;
+    packages: Set<string>;
+    noIndexPackages: Set<string>;
+    contentPackage: string;
+    siteIndexMap: Map<string, {
+        url: string;
+    }>;
+    figuresByAddress: Map<string, Map<string, object>>;
+}): {
+    url: string;
+    figures: Map<string, object>;
+} | undefined;
 /**
  * The per-page context a wikilink resolver takes.
  *
@@ -106,6 +160,12 @@ export type SiteEntry = {
      * The page's published address.
      */
     url: string;
+    /**
+     * The note's markdown body, for its anchors. A
+     *  content entry always carries one; absent, the
+     *  page is indexed as declaring none.
+     */
+    body?: string | undefined;
 };
 /**
  * The resolved index and everything a wikilink resolver reads beside it.
@@ -114,12 +174,18 @@ export type SiteIndex = {
     /**
      *                                       Address → page. `draft` says the page
      *                                       carries the `draft` tag, which marks a
-     *                                       link *into* it.
+     *                                       link *into* it. `anchors` names the
+     *                                       `{#slug}` sections it declares — a
+     *                                       `Set` for a local page, or the
+     *                                       `{slug: uuid}` map a foreign manifest
+     *                                       publishes — and is absent where
+     *                                       neither build recorded one.
      */
     index: Map<string, {
         url: string;
         name?: string;
         draft?: boolean;
+        anchors?: Set<string> | Record<string, string>;
     }>;
     /**
      * Short addresses claimed by two

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

@@ -24,7 +24,7 @@ export function prepareSitePreview({ config }?: {
         frontmatter?: undefined;
     } | {
         ok: boolean;
-        markdown: any;
+        markdown: string;
         frontmatter: any;
         findings: never[];
     }>;

package/types/engine/sql-tables.d.mts

@@ -142,6 +142,10 @@ export function renderSqlTable(result: {
  * @param {object} [opts]
  * @param {(ref: string) => boolean} [opts.linkable] - Passed to
  *   {@link renderSqlTable}.
+ * @param {object[]} [opts.records] - Content-index records, narrowed to the
+ *   audience this surface publishes to. Given them, the result also carries
+ *   `pageLists`, so one prepared object answers every corpus-reading directive
+ *   a body can hold and a caller looks results up in one place.
  * **Keyed by note, then by the directive's ordinal within it** — not by its
  * line. The passes do not agree on what a body is: `walkMarkdownTree` trims it,
  * while the link checker strips the frontmatter fence and leaves the newlines
@@ -154,8 +158,9 @@ export function renderSqlTable(result: {
 export function prepareSqlTables(db: object, sources: Array<{
     source: string;
     markdown: string;
-}>, { linkable }?: {
+}>, { linkable, records }?: {
     linkable?: ((ref: string) => boolean) | undefined;
+    records?: object[] | undefined;
 }): Promise<Map<string, object[]>>;
 /** Evaluate scalar SQL calls before synchronous Markdown renderers run. */
 export function prepareInlineSqlExpressions(db: any, sources: any): Promise<Map<any, any>>;
@@ -167,10 +172,14 @@ export function prepareInlineSqlExpressions(db: any, sources: any): Promise<Map<
  * shared index
  * describes, where N passes each derive the corpus their own way.
  *
- * **Nothing is opened for a tree with no `sql` directive.** The corpus is still
- * written entirely in the retiring language, so until a table is converted this
- * costs one walk and no database at all — which is what lets every pass call it
- * unconditionally.
+ * **Every corpus-reading directive is answered here**, which is why one call
+ * precedes every pass: the `sql` tables, the inline scalar queries, and the
+ * page lists, whose results ride on the same object as `pageLists`.
+ *
+ * **Nothing is opened for a tree that asks no query.** A tree with no `sql`
+ * directive costs one walk and no database at all, and so does one whose only
+ * directive is a page list — a page list is a filter over the records. That is
+ * what lets every pass call this unconditionally.
  *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
@@ -180,8 +189,9 @@ export function prepareInlineSqlExpressions(db: any, sources: any): Promise<Map<
  *   A command that also builds a link index holds them already, and deriving
  *   them twice is the duplicated-corpus failure this closes.
  * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes.
- * @returns {Promise<Map<string, object[]>|undefined>} Results by note path, or
- *   nothing when the tree has no such directive.
+ * @returns {Promise<Map<string, object[]>|undefined>} Results by note path,
+ *   carrying `inline` and `pageLists` beside them, or nothing when the tree
+ *   holds no such directive.
  */
 export function prepareTreeSqlTables(contentBase: string, { config, skipDirectories, records, audience }?: {
     config?: object | undefined;
@@ -200,3 +210,17 @@ export const RENDER_ALIASES: Readonly<{
     ref: "_ref";
     section: "_section";
 }>;
+/**
+ * The attributes an SQL fence takes, with what each one is for.
+ *
+ * **This is the one list.** The fence is validated against it and the authoring
+ * document is checked against it, so an attribute added here is one the document
+ * must describe, and anything else an author writes is reported by name.
+ *
+ * @type {Readonly<Record<string, Readonly<{value: string, default: string, summary: string}>>>}
+ */
+export const SQL_FENCE_ATTRIBUTES: Readonly<Record<string, Readonly<{
+    value: string;
+    default: string;
+    summary: string;
+}>>>;

package/types/engine/standings.d.mts

@@ -37,6 +37,10 @@ export function readStandings(value: unknown): {
  * than by its position in the list: a body may write its rungs in any order,
  * and several start at zero.
  *
+ * One title per level, which is what the rung check holds a ladder to: two
+ * rungs claiming one level is a finding on the second, so a ladder that reaches
+ * here carries at most one title for any number a member's `rank` can hold.
+ *
  * @param {unknown} ranks - An affiliation's `data.governance.ranks`.
  * @returns {Map<number, string>} Level → the title that level is called.
  */
@@ -66,6 +70,18 @@ export function officeRoster(offices: unknown): Map<string, string>;
  * @returns {string} The anchor, or `""` where the name carries nothing.
  */
 export function officeAnchor(office: string): string;
+/**
+ * The anchor a rung's row is addressed by.
+ *
+ * The ladder's parallel to {@link officeAnchor}, prefixed apart from it so a
+ * body naming an office the same word as one of its ranks still gets two
+ * destinations rather than one row answering for both.
+ *
+ * @param {string} title - The rung's title, as the body wrote it.
+ * @returns {string} The anchor, or `""` where the title carries nothing
+ *   URL-safe.
+ */
+export function rankAnchor(title: string): string;
 /**
  * What an affiliation lends to a reference to it.
  *
@@ -106,12 +122,14 @@ export function standingPhrase(standing: object, body: string, digest?: {
 /**
  * Validate a being's memberships and the standing it holds in each.
  *
- * Four questions, and the last two are what keying the entry by its body buys:
+ * Five questions, and the last three are what keying the entry by its body
+ * buys:
  *
  * 1. the value is a map keyed by Address (or the list this window still takes);
  * 2. every key names an affiliation that resolves, once;
- * 3. a `rank` is a level the named body's `governance.ranks` declares;
- * 4. an `office` is a key of that body's `governance.offices`.
+ * 3. the entry states a `rank`;
+ * 4. a `rank` is a level the named body's `governance.ranks` declares;
+ * 5. an `office` is a key of that body's `governance.offices`.
  *
  * Both of the last two are read from the named body's own frontmatter as the
  * lint runs, so a renamed rung or a renamed post fails on every being pointing

package/types/engine/system-block.d.mts

@@ -79,23 +79,48 @@ export function blockField(fm: object, block: string, key: string, defaultValue?
  */
 export function sharedProperty(fm: object, source: string, defaultValue?: any): any;
 /**
- * A property a system block may override, else the shared top-level one.
+ * A property a system block declares, else the default.
  *
- * This is what gives `pack`, `effects`, `flags` and `img` their per-system form
- * without inventing a mechanism for each: a note that wants one value for both
- * systems says it once at the top, and a note that needs them to differ says so
- * in the block that differs.
+ * This is what gives `effects` and `flags` their per-system form without
+ * inventing a mechanism for each: a note states them inside the block whose
+ * document carries them, which is the only position the format accepts for
+ * either. A note needing one value for both systems writes it in both blocks —
+ * they are properties of a document, and there are two documents.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The block key.
  * @param {string} key - The property.
- * @param {any} [defaultValue] - Returned when neither declares it.
+ * @param {any} [defaultValue] - Returned when the block does not declare it.
  * @returns {any} The value.
  */
 export function blockProperty(fm: object, block: string, key: string, defaultValue?: any): any;
 /**
- * A system override followed by a shared `data:` value. The top-level value
- * remains readable while content repositories move their authored fields.
+ * A system override followed by a shared `data:` value followed by the
+ * retiring top-level spelling `data:` gathered it off, reporting which one
+ * answered.
+ *
+ * {@link module:engine/field-spec.resolveFieldValue}'s counterpart for a
+ * universal `data:` key — `pack` and `packFolder`, declared for every note
+ * type rather than per type, so neither is a `FieldSpec` that resolver takes.
+ * The order is the same shape: a system's own override, then the shared
+ * `data:` position, then the bare top-level key a tree authored before
+ * `data:` existed. The top-level value stays readable while a tree still on
+ * it moves its authored fields.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {{value: any, from: FieldSource}} The value, and where it came
+ *   from.
+ */
+export function resolveDataProperty(fm: object, block: string, key: string, defaultValue?: any): {
+    value: any;
+    from: FieldSource;
+};
+/**
+ * {@link resolveDataProperty}'s value alone, for a caller that only compiles
+ * a document and has no use for which position answered.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The system block key.
@@ -128,12 +153,10 @@ export function legacyKeyOf(field: {
 /**
  * The bare top-level key a `data:`-sourced field is being swept off — step 3b.
  *
- * `data:` did not invent the facts it holds; it *gathered* them, out of
- * the note's open top level where each was a sibling of `img` and `shortcode`.
- * So the retiring spelling of `data.portrait` is not a second declaration
- * anyone has to write — it is `portrait`, mechanically, and the same holds for
- * every other key that move relocated. Deriving it is what keeps the two
- * spellings of one field from disagreeing the way two declarations would.
+ * The retiring spelling of `data.portrait` is not a second declaration anyone
+ * has to write — it is `portrait`, mechanically, and the same holds for every
+ * other key the container gathered. Deriving it is what keeps the two spellings
+ * of one field from disagreeing the way two declarations would.
  *
  * **Only a `data.` source has one.** `protection.blunt` and `impact.die` are
  * paths into containers a note has always written at the top level; they were

package/types/engine/web-wikilinks.d.mts

@@ -97,7 +97,9 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
  *   stands in. `resolved`, when supplied, is the array every resolved
- *   target's index entry is appended to.
+ *   target's index entry is appended to. `anchors` is the `{#slug}` set
+ *   *this* page declares, which a `[[#slug]]` self-link is checked against;
+ *   absent, a self-link is not checked, exactly as before this existed.
  * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body: string, ctx: object): string;

package/types/hm3/actors.d.mts

@@ -1,3 +1,21 @@
+/**
+ * Native HM3 facts shared by its actor subtypes.
+ *
+ * Species is native text. The note's lore Address in `data.species` is
+ * independent and supplies no native value.
+ *
+ * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
+ */
+export const ACTOR_FIELDS: readonly import("../engine/field-spec.mjs").FieldSpec[];
+/**
+ * The two `data:` facts HM3 declares on a `character` and not on a `creature`.
+ *
+ * Both name their shared source and their legacy in-block key, for the reason
+ * {@link ACTOR_FIELDS} does.
+ *
+ * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
+ */
+export const CHARACTER_FIELDS: readonly import("../engine/field-spec.mjs").FieldSpec[];
 /**
  * HM3's Actor compile pass.
  *
@@ -27,9 +45,9 @@ export class Hm3Actors extends SystemActorCompiler {
     /**
      * Build every embedded item an HM3 actor carries, from `hm3.items`.
      *
-     * One list, not two: HM3 keeps a character's abilities in `system.abilities`
-     * rather than as embedded documents, so there is no attributes map to
-     * expand the way SoHL's pass expands `sohl.attributes`.
+     * HM3 keeps a character's abilities in `system.abilities` rather than as
+     * embedded documents, so an ability reaches the document through the
+     * `hm3.system` passthrough and never through this list.
      *
      * @param {Map<string, object>} itemsMap - The predefined items, by address.
      * @param {string} actorId - The owning actor's id, seeding embedded ids.

package/types/manifest.d.mts

@@ -267,29 +267,25 @@ export const ARTIFACTS: readonly string[];
  */
 export const HOMEPAGE_ORIGIN: string;
 /**
- * Relationship keys that direct the **build**, rather than describe the
- * package.
- *
- * `relationships` is the one manifest block with a second reader.
- * `@heroiclands/package-build` consumes it too, and v1.8.0 added
- * `itemCatalog: true` as an opt-in on a declared dependency: it selects that
- * package's Item packs as a resolution
- * source for the actors pass. That is an instruction to the build, not a fact
- * about the shipped package — Foundry's relationship schema does not define
- * it, and someone reading a published manifest cannot tell a build directive
- * from a declaration about what the package needs.
- *
- * So the block is filtered rather than copied whole. The rule is the
- * distinction, not the name: a key listed here answers *how is this built?*,
- * and every key that survives answers *what does this package depend on?*.
- * `itemCatalog` is the first build-time key to land on a relationship and is
- * unlikely to be the last.
- *
- * A list is enough, and needs no prefix agreed between the two packages,
- * because the input is already closed: package-build normalises a relationship
- * to `id`, `type`, `manifest`, `compatibility` and its own build keys, and
- * rejects anything else at configuration time. A key that reaches here is one
- * the toolchain itself put there.
+ * The relationship keys Foundry's own schema names.
+ *
+ * `RelatedPackage` declares exactly these (`common/packages/base-package.mjs`),
+ * so a key outside them is one the build put there for itself.
+ *
+ * @type {readonly string[]}
+ */
+export const FOUNDRY_RELATIONSHIP_KEYS: readonly string[];
+/**
+ * The relationship keys the published manifest drops.
+ *
+ * Derived rather than listed: every key this package accepts on a relationship
+ * that Foundry's schema does not name is one the build reads for itself, so a
+ * key added to the configuration is dropped from the manifest without a second
+ * list being kept in step.
+ *
+ * The filter stays a denylist for the reason the pass-through below gives — a
+ * key Foundry adds later reaches the manifest unread rather than being stripped
+ * by an allowlist that has not heard of it.
  *
  * @type {readonly string[]}
  */

package/types/sohl/actors.d.mts

@@ -2,9 +2,8 @@
  * SoHL's Actor compile pass.
  *
  * Declares SoHL's note-type → document-subtype map and builds a `being` note's
- * document: the body structure and its movement profiles, the embedded
- * attribute and item documents the frontmatter names, and the `system` block.
- * Everything else is {@link module:engine/actor-compiler}'s.
+ * document: the embedded item documents the frontmatter names, and the `system`
+ * block. Everything else is {@link module:engine/actor-compiler}'s.
  */
 export class Actors extends SystemActorCompiler {
     /**
@@ -17,8 +16,8 @@ export class Actors extends SystemActorCompiler {
      */
     static documentSubtypes: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;
     /**
-     * Build all embedded items for an actor: one per `sohl.attributes`
-     * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
+     * Build all embedded items for an actor: one per `sohl.items` entry, plus
+     * one per body the being belongs to.
      */
     buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): object[];
     /**
@@ -57,8 +56,8 @@ export class Actors extends SystemActorCompiler {
      *
      * **The scores used are the ones just written.** `SkillLogic` resolves
      * `attr.<code>` to an attribute's *effective* score, after active effects;
-     * all this pass has is the `scoreBase` it set from `sohl.attributes`. For a
-     * compiled being carrying no attribute-altering effects the two agree,
+     * all this pass has is the `scoreBase` on each embedded attribute item. For
+     * a compiled being carrying no attribute-altering effects the two agree,
      * which is every being in content today. One that did carry such an effect
      * would bake a Skill Base its client then disagrees with — that is the
      * limit of doing this at build time, and the point to revisit if it bites.

package/engine/content-admonitions.mjs

@@ -1,114 +0,0 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
-
-import MarkdownIt from "markdown-it";
-import footnotePlugin from "markdown-it-footnote";
-import deflistPlugin from "markdown-it-deflist";
-import { parseExtensionAttributes } from "./extension-attributes.mjs";
-
-const parser = new MarkdownIt({ html: true }).use(footnotePlugin).use(deflistPlugin);
-const OPEN = /^:::(info|warn)(?:\s+(.*))?\s*$/;
-const CLOSE = /^:::\s*$/;
-const STYLES = Object.freeze({
-    info: { label: "Info", icon: "ℹ", color: "#2f6f9f", background: "#eef6fb" },
-    warn: { label: "Warning", icon: "⚠", color: "#9a6700", background: "#fff5db" },
-});
-
-/** Find inline info and warning blocks without interpreting code examples. */
-export function scanAdmonitions(source) {
-    const lines = String(source ?? "").split("\n");
-    const blocks = [];
-    const errors = [];
-    let opening = null;
-    let codeFence = null;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
-        if (codeFence) {
-            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length)
-                codeFence = null;
-            continue;
-        }
-        if (fence) {
-            codeFence = fence[1];
-            continue;
-        }
-        const open = OPEN.exec(line);
-        if (open) {
-            if (opening) {
-                errors.push({
-                    line: i + 1,
-                    column: 1,
-                    message: "nested info and warning blocks are not supported",
-                });
-                continue;
-            }
-            const raw = open[2]?.trim() ?? "";
-            let id = "";
-            if (raw) {
-                if (!/^\{[^}\n]*\}$/.test(raw))
-                    errors.push({
-                        line: i + 1,
-                        column: 1,
-                        message: "block attributes need {#id} syntax",
-                    });
-                else {
-                    const attrs = parseExtensionAttributes(raw.slice(1, -1));
-                    id = attrs.id;
-                    for (const message of attrs.problems)
-                        errors.push({ line: i + 1, column: 1, message });
-                    if (attrs.classes.length || Object.keys(attrs.values).length)
-                        errors.push({
-                            line: i + 1,
-                            column: 1,
-                            message: "info and warn accept only an id",
-                        });
-                }
-            }
-            opening = { start: i, kind: open[1], id };
-            continue;
-        }
-        if (CLOSE.test(line) && opening) {
-            const body = lines
-                .slice(opening.start + 1, i)
-                .join("\n")
-                .trim();
-            if (!body)
-                errors.push({
-                    line: opening.start + 1,
-                    column: 1,
-                    message: `${opening.kind} block is empty`,
-                });
-            blocks.push({ ...opening, end: i, body });
-            opening = null;
-        }
-    }
-    if (opening)
-        errors.push({
-            line: opening.start + 1,
-            column: 1,
-            message: `${opening.kind} block needs a closing ::: line`,
-        });
-    return { blocks, errors };
-}
-
-/** Render info and warning blocks as styled, labelled HTML. */
-export function renderAdmonitions(source, renderMarkdown = parser.render.bind(parser)) {
-    const { blocks, errors } = scanAdmonitions(source);
-    if (errors.length) return { markdown: source, errors };
-    const lines = String(source ?? "").split("\n");
-    const output = [];
-    let cursor = 0;
-    for (const block of blocks) {
-        const style = STYLES[block.kind];
-        output.push(...lines.slice(cursor, block.start));
-        output.push(
-            `<aside${block.id ? ` id="${block.id}"` : ""} class="sohl-admonition sohl-admonition-${block.kind}" style="border-left: 3px solid ${style.color}; background: ${style.background}; padding: 0.5em 0.8em; margin: 0.75em 0;">`,
-            `<p><strong><span aria-hidden="true">${style.icon}</span> ${style.label}</strong></p>`,
-            renderMarkdown(block.body).trim(),
-            "</aside>",
-        );
-        cursor = block.end + 1;
-    }
-    output.push(...lines.slice(cursor));
-    return { markdown: output.join("\n"), errors: [] };
-}