@heroiclands/package-build 22.15.0 → 22.16.0

package/engine/journals.mjs

@@ -42,7 +42,7 @@
  * documentation entry reuses its document's folder verbatim.
  *
  * Not a standalone script — exports the `Journals` compiler class, imported
- * and driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
+ * and driven by `packages/package-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
  * The walk itself — filtering by type, expanding tables, converting
  * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
@@ -57,16 +57,20 @@ import {
     resolveName,
     defaultStats,
     renderFoundryMarkdown,
+    md,
     folderField,
 } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { anchorPageId, resolveReference } from "./wikilinks.mjs";
 import { infoboxesToHtml, linkToUuid } from "./infobox-render.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { JOURNAL_TYPES } from "./ids.mjs";
 import { journalHasContent } from "./note-state.mjs";
 import { draftNoticeFor } from "./draft-notice.mjs";
+import { scanCaptions } from "./content-captions.mjs";
+import { separateFootnotes } from "./content-footnotes.mjs";
 
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
@@ -74,7 +78,7 @@ import { draftNoticeFor } from "./draft-notice.mjs";
  * a split. Content before the first H1 (if non-empty) becomes a leading
  * page. Each H1 yields a page whose name is the heading
  * text (with any `{#anchor-id}` suffix stripped out and surfaced as
- * `anchorId`).
+ * `anchorSlug`).
  *
  * `leadName` names that leading page. A journal note's is "Introduction",
  * because it introduces the pages that follow. An item doc's is the item — a
@@ -82,10 +86,21 @@ import { draftNoticeFor } from "./draft-notice.mjs";
  * calling that page "Introduction" would label the description as a preamble to
  * nothing.
  *
- * Returns an array of `{ name, anchorId, markdown }` in document order.
+ * @param {string} body - Markdown body to split.
+ * @param {string} [leadName] - Name of the page before the first heading.
+ * @returns {Array<{name: string, anchorSlug: string|null, level: number,
+ *   markdown: string}>} Pages in document order.
  */
 export function splitPages(body, leadName = "Introduction") {
-    const lines = body.split("\n");
+    const { markdown, definitions } = separateFootnotes(body);
+    const lines = markdown.split("\n");
+    const captions = scanCaptions(markdown).captions;
+    const captionStarts = new Map(captions.map((caption) => [caption.line - 1, caption]));
+    const captionedHeadings = new Set(
+        captions
+            .filter((caption) => /^\s*#{1,6}\s/.test(lines[caption.blockStart] ?? ""))
+            .map((caption) => caption.blockStart),
+    );
     const pages = [];
     const beforeFirstH1 = [];
     let current = null;
@@ -103,7 +118,7 @@ export function splitPages(body, leadName = "Introduction") {
         current = null;
     };
 
-    for (const line of lines) {
+    for (const [lineIndex, line] of lines.entries()) {
         if (line.trim().startsWith("```")) {
             inCodeBlock = !inCodeBlock;
         }
@@ -118,7 +133,18 @@ export function splitPages(body, leadName = "Introduction") {
         const rawHeading = headingMatch?.[2]?.trim();
         const anchorMatch = rawHeading?.match(/^(.*?)\s*\{#([^}]+)\}\s*$/);
         const startsPage = headingMatch && (headingMatch[1].length === 1 || anchorMatch);
-        if (startsPage) {
+        const caption = !inCodeBlock && !inSecret ? captionStarts.get(lineIndex) : null;
+        if (caption) {
+            closeCurrent();
+            current = {
+                name: caption.label,
+                anchorSlug: caption.id,
+                level: 1,
+                lines: [line],
+            };
+            continue;
+        }
+        if (startsPage && !captionedHeadings.has(lineIndex)) {
             closeCurrent();
             current = {
                 name: (anchorMatch ? anchorMatch[1] : rawHeading).trim(),
@@ -147,6 +173,9 @@ export function splitPages(body, leadName = "Introduction") {
         });
     }
 
+    if (definitions) {
+        for (const page of pages) page.markdown += `\n\n${definitions}`;
+    }
     return pages;
 }
 
@@ -214,7 +243,7 @@ export function assertUniqueAnchors(rawPages, noteName) {
  * An anchored page takes the id its inbound links compute from the note id and
  * the slug, so link and page agree without shared state. Every other page is
  * keyed by its **name**, which is what lets the items pass address an item
- * doc's first page without having compiled it (see
+ * doc's selected page without having compiled it (see
  * {@link sohl.utils.packs.itemDocPointer}).
  *
  * **It takes no index**. Keying a page by position *and* name,
@@ -250,13 +279,21 @@ export function journalPageId(entryId, page) {
  *   documents, in order.
  * @throws {Error} When the note has no content at all, or repeats an anchor.
  */
-export function buildPages(rawPages, entryId, noteName) {
+export function buildPages(rawPages, entryId, noteName, captions) {
     if (rawPages.length === 0) {
         throw new Error(
             `note "${noteName}" has no Introduction content and no H1 headings — nothing to compile`,
         );
     }
     assertUniquePages(rawPages, noteName);
+    const footnoteNumbers = new Map();
+    for (const page of rawPages) {
+        const env = {};
+        md.parse(page.markdown ?? "", env);
+        for (const { label } of env.footnotes?.list ?? []) {
+            if (!footnoteNumbers.has(label)) footnoteNumbers.set(label, footnoteNumbers.size + 1);
+        }
+    }
     return rawPages.map((page) => {
         const pageId = journalPageId(entryId, page);
         return {
@@ -266,7 +303,10 @@ export function buildPages(rawPages, entryId, noteName) {
             title: { show: true, level: page.level ?? 1 },
             text: {
                 format: 1,
-                content: page.markdown ? renderFoundryMarkdown(page.markdown) : "",
+                content:
+                    page.markdown ?
+                        renderFoundryMarkdown(page.markdown, captions, footnoteNumbers, pageId)
+                    :   "",
             },
             _key: `!journal.pages!${entryId}.${pageId}`,
         };
@@ -321,7 +361,7 @@ export function buildJournalEntry({
     notice = "",
 }) {
     const rawPages = splitPages(markdown, leadName);
-    const pages = buildPages(rawPages, id, name);
+    const pages = buildPages(rawPages, id, name, scanCaptions(markdown).captions);
     if (infobox.trim() && pages.length) {
         pages[0].text.content = `${infobox}\n${pages[0].text.content}`;
     }
@@ -475,6 +515,7 @@ export class Journals extends BasePackCompiler {
             // This compile's own router, so the panel's `available` is decided
             // by the pack list this build is being driven by.
             router: this.router,
+            dates: reckoningContext(this.linkIndex),
         });
 
         return buildJournalEntry({

package/engine/macros.mjs

@@ -42,7 +42,7 @@
  * Nothing here evaluates, compiles, or revives anything.
  *
  * Not a standalone script — exports the `Macros` compiler class, imported and
- * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
+ * driven by `packages/package-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
  * The walk itself — filtering by type, expanding tables, converting
  * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module

package/engine/map-build.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * `content-build map`: the drawings, written under `build/map/`.
+ * `package-build map`: the drawings, written under `build/map/`.
  *
  * Four modes, each a function of the world the content index describes:
  *

package/engine/map-dot.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The drawings of `content-build map`, as DOT.
+ * The drawings of `package-build map`, as DOT.
  *
  * Every drawing is emitted as DOT text and kept beside its rendering, so a
  * picture can be re-rendered, diffed or read without the content index.

package/engine/map-raster.mjs

@@ -5,10 +5,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Resvg } from "@resvg/resvg-js";
+import { resolvePackageBuildConfig } from "../config.mjs";
 
 /** Rasterize an authored SVG map into the staged Foundry package. */
 export function rasterizeMapSvg({ foundryPath, width, height, sceneId, config }) {
     if (!config) throw new Error("SVG map rasterization requires the package build configuration");
+    const buildConfig = resolvePackageBuildConfig(config);
     if (![width, height].every((value) => Number.isInteger(value) && value > 0)) {
         throw new Error("an SVG map needs `sohl.dimensions: [width, height]` in whole pixels");
     }
@@ -25,7 +27,7 @@ export function rasterizeMapSvg({ foundryPath, width, height, sceneId, config })
     }
     const staged = path.resolve(
         config.rootDir,
-        config.packageBuild.stageDir,
+        buildConfig.stageDir,
         "assets/maps/rasterized",
         `${sceneId}.png`,
     );
@@ -45,5 +47,5 @@ export function rasterizeMapSvg({ foundryPath, width, height, sceneId, config })
             cause: error,
         });
     }
-    return `${config.packageKind}/${config.foundryPackage.id}/assets/maps/rasterized/${sceneId}.png`;
+    return `${buildConfig.packageKind}/${buildConfig.packageId}/assets/maps/rasterized/${sceneId}.png`;
 }

package/engine/markdown-expressions.mjs

@@ -0,0 +1,117 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+import Handlebars from "handlebars";
+
+import { isAddressTuple, renderAddress } from "./address.mjs";
+import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
+import { formatDateInCalendar, parseNoteDate } from "./note-dates.mjs";
+import { numberWords, numberDigits } from "./number-words.mjs";
+
+// Hugo shortcodes begin `{{<` or `{{%` and stay in the source for Hugo.
+const EXPRESSION = /(?<![\\{])\{\{(?![{<%])([^{}\n]+)\}\}(?!\})/g;
+
+/** Find SQL helper calls, including calls nested inside Boolean expressions. */
+export function sqlQueriesInMarkdown(body, fm = {}) {
+    const queries = [];
+    const queryValue = (parameter) => {
+        if (parameter?.type === "StringLiteral") return parameter.value;
+        if (parameter?.type !== "PathExpression") return null;
+        return parameter.parts.reduce((value, part) => value?.[part], fm);
+    };
+    const visit = (node) => {
+        if (!node || typeof node !== "object") return;
+        if (node.path?.original === "sql") {
+            const query = queryValue(node.params?.[0]);
+            if (typeof query === "string") queries.push(query);
+        }
+        for (const parameter of node.params ?? []) visit(parameter);
+    };
+    for (const match of matchAllOutsideCode(body, EXPRESSION)) {
+        try {
+            for (const node of Handlebars.parse(match[0]).body) visit(node);
+        } catch {
+            // The render pass reports the malformed expression at its source position.
+        }
+    }
+    return queries;
+}
+
+/**
+ * Expand scalar frontmatter references and registered functions in Markdown prose.
+ * @param {string} body
+ * @param {{fm?: object, dates?: object, sqlResults?: Map<string, object>, file?: string, bodyLine?: number}} [options]
+ */
+export function renderMarkdownExpressions(
+    body,
+    { fm, dates, sqlResults, file, bodyLine = 1 } = {},
+) {
+    const findings = [];
+    const engine = Handlebars.create();
+    const numeric = (name, left, right) => {
+        if (
+            !["number", "bigint"].includes(typeof left) ||
+            !["number", "bigint"].includes(typeof right) ||
+            (typeof left === "number" && !Number.isFinite(left)) ||
+            (typeof right === "number" && !Number.isFinite(right))
+        )
+            throw new TypeError(`${name} needs two finite numbers`);
+    };
+    for (const [name, compare] of Object.entries({
+        gt: (a, b) => a > b,
+        gte: (a, b) => a >= b,
+        lt: (a, b) => a < b,
+        lte: (a, b) => a <= b,
+    }))
+        engine.registerHelper(name, (left, right) => {
+            numeric(name, left, right);
+            return compare(left, right);
+        });
+    engine.registerHelper("eq", (left, right) => left === right);
+    engine.registerHelper("not", (value) => !value);
+    engine.registerHelper("and", (...args) => args.slice(0, -1).every(Boolean));
+    engine.registerHelper("or", (...args) => args.slice(0, -1).some(Boolean));
+    engine.registerHelper("words", (value) => numberWords(value));
+    engine.registerHelper("digits", (value) => numberDigits(value));
+    engine.registerHelper("sql", (query) => {
+        if (typeof query !== "string" || !query.trim())
+            throw new TypeError("sql needs a nonempty query string");
+        const result = sqlResults?.get(query);
+        if (!result) throw new RangeError(`SQL expression has no prepared result: ${query}`);
+        if (result.error) throw new RangeError(`SQL expression failed: ${result.error}`);
+        return result.value;
+    });
+    engine.registerHelper("dateformat", (calendar, authored) => {
+        if (
+            !(typeof calendar === "string" || isAddressTuple(calendar)) ||
+            !["string", "number"].includes(typeof authored)
+        )
+            throw new TypeError("dateformat needs a calendar Address and a date");
+        const parsed = parseNoteDate(authored, { ...dates, allowUnknown: false });
+        const error = parsed.findings.find((item) => item.severity === "error");
+        if (error || !parsed.date) throw new RangeError(error?.message ?? "date does not resolve");
+        const printable = formatDateInCalendar(
+            parsed.date,
+            isAddressTuple(calendar) ? renderAddress(calendar) : calendar,
+            dates,
+        );
+        if (!printable) throw new RangeError(`date cannot be printed in calendar ${calendar}`);
+        return printable.prose ?? printable.text;
+    });
+    const markdown = replaceOutsideCode(body, EXPRESSION, (source, _inside, offset) => {
+        try {
+            return engine.compile(source, { strict: true })(fm ?? {});
+        } catch (error) {
+            const before = String(body).slice(0, offset);
+            const lines = before.split("\n");
+            findings.push({
+                ...(file ? { file } : {}),
+                line: bodyLine + lines.length - 1,
+                column: lines.at(-1).length + 1,
+                severity: "error",
+                message: `Markdown expression ${source} failed: ${error.message}`,
+            });
+            return source;
+        }
+    });
+    return { markdown, findings };
+}

package/engine/metadata-index.mjs

@@ -61,6 +61,7 @@ import {
     resolvePackageUrl,
 } from "./content-address.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
+import { isGmNote } from "./note-vocabulary.mjs";
 
 /**
  * Written once a fetch completes, so a half-finished cache is never used.
@@ -236,7 +237,7 @@ export function cachedMetadataIndexes(config) {
         if (!cached.length) {
             throw new Error(
                 `${rel.id} is a declared dependency but its content index has ` +
-                    `not been fetched. Run \`content-build deps fetch\` first.`,
+                    `not been fetched. Run \`package-build deps fetch\` first.`,
             );
         }
         files.push({ id: rel.id, file: newestIndex(cached) });
@@ -401,7 +402,7 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 // must tolerate that rather than invent an href, exactly as it
                 // already tolerates an entry with no `uuid`.
                 url:
-                    !web || !record.address.slug ? undefined
+                    !web || !record.address.slug || isGmNote(record) ? undefined
                         // A package's homepage is its root: the note is the
                         // mount's `_index.md`, so `[[thalorna-homepage-root]]`
                         // lands on `/thalorna/`, not on a page below it.
@@ -411,6 +412,7 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 doc: record.documentation ?? undefined,
                 anchors: foundry?.anchors,
                 type: parts.type,
+                gm: isGmNote(record),
                 // What the note *is*, not only where it lives. A consumer
                 // grouping a reference by the family its target declares —
                 // an infobox sorting a being's skills — has no other way to
@@ -426,11 +428,13 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 // checks a border across the package boundary from both ends,
                 // a consumer's map draws the dependency's places beside its
                 // own, and a consumer's pages list what a dependency's
-                // affiliation holds and what lies within its regions.
+                // affiliation holds and what lies within its regions. A
+                // population lets the same checks include dependency figures.
                 borders: record.data?.borders ?? undefined,
                 routes: record.data?.routes ?? undefined,
                 parents: record.data?.parents ?? undefined,
                 domains: record.data?.domains ?? undefined,
+                population: record.data?.population ?? undefined,
                 package: pkg,
             });
             const entry = index.get(key);

package/engine/note-addresses.mjs

@@ -296,6 +296,7 @@ export function noteAddressContext(config) {
     return {
         package: config.contentPackage,
         system: "note",
+        types: new Set(Object.keys(NOTE_VOCABULARY)),
         systemBlocks,
     };
 }