@heroiclands/package-build 22.15.1 → 22.16.0

package/engine/site-build.mjs

@@ -14,7 +14,7 @@
 /**
  * Publishing a content tree as a website.
  *
- * Compiling a content tree into compendium packs is `content-build package
+ * Compiling a content tree into compendium packs is `package-build package
  * compile`. Publishing the *same tree* as a website was a script each consumer
  * wrote for itself — 473 code lines in `sohl` and 462 in `sohl-thalorna`, 87 of
  * them identical — and the copies drifted in ways neither repository could see.
@@ -60,8 +60,11 @@ import matter from "gray-matter";
 
 import { addressSlug } from "./content-address.mjs";
 import { protectCode } from "./code-fences.mjs";
+import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { renderSecretBlocks } from "./content-secrets.mjs";
+import { renderAdmonitions, scanAdmonitions } from "./content-admonitions.mjs";
+import { renderCaptionBlocks, scanCaptions } from "./content-captions.mjs";
 import { renderImageFigures } from "./content-images.mjs";
 import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
 import { buildSiteIndex, resolveInfoboxRef, wikiContext } from "./site-index.mjs";
@@ -69,7 +72,6 @@ import { frontmatterWikilinks, resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { loadForeignIndexes, noContentIndexPackages } from "./metadata-index.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
 import { formatUnaddressableFinding, unaddressableForeignPackages } from "./metadata-index.mjs";
-import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
@@ -79,9 +81,11 @@ import { indexRecordsFor } from "./content-index.mjs";
 // reuses `collectContentPages`'s pages, so wiring it here reaches the book too.
 import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
+import { resolvedDateFields } from "./note-dates.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 // The one statement of what an empty body means, shared with the index.
 import { isStubNote } from "./note-state.mjs";
+import { isGmNote } from "./note-vocabulary.mjs";
 import { ART_SLOTS, artPathname, assetAddressIndex } from "./art-fields.mjs";
 import {
     HOMEPAGE_DESTINATION,
@@ -226,7 +230,7 @@ export function collectContentPages(contentBase, ctx) {
         // the index apply one rule from one module and a note that cannot be
         // addressed for some *other* reason still reaches the finding below
         // that says so.
-        if (isStubNote(fm, body)) continue;
+        if (isStubNote(fm, body) || isGmNote(fm)) continue;
 
         for (const hit of frontmatterWikilinks(fm)) {
             fmLinkFindings.push({ file, ...hit });
@@ -286,11 +290,8 @@ export function collectContentPages(contentBase, ctx) {
 /**
  * The package's homepage notes — the authored page at `/<contentPackage>/`.
  *
- * A separate walk from {@link collectContentPages} rather than a branch inside
- * it, because in homepage-only mode it is the **whole** of the site build: the
- * content tree is never read for pages at all, so the licensing constraint two
- * packages ship under is a property of the code path rather than of a
- * configuration that happens to be empty.
+ * A separate collection from {@link collectContentPages} keeps the homepage
+ * at the package root and leaves content pages at their note addresses.
  *
  * Returned as a list rather than as the one note there should be, because the
  * count is what {@link checkHomepageCount} judges — this walk reports
@@ -298,8 +299,7 @@ export function collectContentPages(contentBase, ctx) {
  *
  * A homepage that declares no `shortcode` has no address, and is
  * reported rather than written: it is the same finding a content page's missing
- * shortcode produces, and it has to be available in homepage-only mode, where
- * no other gate runs.
+ * shortcode produces, and it is reported even when the tree has no other notes.
  *
  * **It is still counted.** An unaddressable homepage is a homepage — dropping
  * it from the list would make {@link checkHomepageCount} report a tree with one
@@ -317,6 +317,10 @@ export function collectHomepages(contentBase, ctx) {
     for (const file of siteCorpusFiles(contentBase, ctx)) {
         const note = readNote(file, ctx);
         if (!note || !isHomepage(note.fm)) continue;
+        if (isGmNote(note.fm)) {
+            addressFindings.push({ file, reason: "a GM-tagged homepage cannot publish publicly" });
+            continue;
+        }
         try {
             addressSlug(note.fm);
         } catch (err) {
@@ -332,13 +336,10 @@ export function collectHomepages(contentBase, ctx) {
  *
  * Its own writer, deliberately small. A homepage is authored markdown published
  * verbatim — no table expansion and no link resolution — so routing it through
- * {@link renderPages} would buy it a pipeline it has no input for, and would
- * make homepage-only mode depend on the index, the foreign manifests and the
- * table universe that mode exists to not build.
+ * {@link renderPages} would give it a pipeline it does not use.
  *
  * **Verbatim is the answer, not a gap.** A homepage's links could not be
- * *resolved* here without giving `homepage` mode the index its licensing fence
- * exists to not build, so they are **checked** instead:
+ * *resolved* here, so they are **checked** instead:
  * {@link auditHomepageLinks} reads the body's markdown links, and reports a
  * wikilink on the page rather than resolving one.
  *
@@ -351,8 +352,8 @@ export function collectHomepages(contentBase, ctx) {
  * both sides of the link graph: a content page reaches it through
  * `[[homepage-root|Text]]`, and its own markdown links name content pages. So
  * it carries the same `related` block every content page does — handed in by
- * the caller, since the graph is read off the content render and homepage-only
- * mode has none.
+ * the caller, since the graph is read off the content render and a tree with
+ * only a homepage has no such graph.
  *
  * @param {string} outRoot - The package's site root — the content mount's
  *   root, `build/hugo/content`, one level above the mount itself.
@@ -362,7 +363,7 @@ export function collectHomepages(contentBase, ctx) {
  * @param {object} [options] - Options.
  * @param {import("./related-pages.mjs").Related} [options.related] - The
  *   homepage's backlinks and mentions. Absent where nothing connects to it,
- *   and in homepage-only mode, where no link resolves.
+ *   and when the tree contains only a homepage, where no content link resolves.
  * @returns {number} How many pages were written.
  */
 export function writeHomepages(outRoot, pages, config, { related } = {}) {
@@ -402,6 +403,7 @@ export function writeHomepages(outRoot, pages, config, { related } = {}) {
  *   collection.
  * @param {object} options
  * @param {object} options.config - The resolved build configuration.
+ * @param {object[]} options.records - Content-index records.
  * @returns {object} The gate results and, when they pass, the built index.
  */
 export function siteGates(pages, findings, { config, records }) {
@@ -469,7 +471,13 @@ export function emptyGates() {
     };
 }
 
-/** Whether any gate produced a finding. */
+/**
+ * Whether any gate produced a finding.
+ * @param {{homepages: unknown[], frontmatterLinks: unknown[],
+ *   addressErrors: unknown[], staleManifests: unknown[],
+ *   unaddressable: unknown[]}} gates - Results of the site checks.
+ * @returns {boolean} Whether at least one check found an error.
+ */
 export function gatesFailed(gates) {
     return Boolean(
         gates.homepages.length ||
@@ -668,7 +676,7 @@ function isPlainObject(value) {
  * `_index.md`, and the page's stated `url` keeps its address exactly where the
  * flat file's was.
  *
- * @param {object} page - The page.
+ * @param {{slug: string}} page - The page.
  * @param {object} [opts]
  * @param {boolean} [opts.bundle=false] - Whether the page carries a resource.
  * @returns {string} The file, relative to the mount.
@@ -693,7 +701,9 @@ export function renderSitePage(
     },
 ) {
     const tableErrors = [];
+    const expressionErrors = [];
     const secretErrors = [];
+    const captionErrors = [];
     const wikiErrors = [];
     const imageErrors = [];
     const resolved = [];
@@ -738,7 +748,7 @@ export function renderSitePage(
         return renderImageFigures(transformed, webSrc);
     };
 
-    const { markdown, errors } = expandContentTables(page.body, {
+    const { markdown, errors, lineMap } = expandContentTables(page.body, {
         docs: universe.get(page.pkg) ?? [],
         linkable,
         source: src,
@@ -746,8 +756,27 @@ export function renderSitePage(
         self: { fm: searchableFrontmatter(page.fm, page.pkg), path: page.relPath },
     });
     tableErrors.push(...errors);
+    const captionScan = scanCaptions(markdown);
+    ctx.captionLabels = new Map(captionScan.captions.map((caption) => [caption.id, caption.label]));
+    const expressions = renderMarkdownExpressions(markdown, {
+        fm: page.fm,
+        dates: index.dateContext,
+        file: page.file,
+        bodyLine: page.bodyLine,
+        sqlResults: sqlTables?.inline?.get(page.file),
+    });
+    expressionErrors.push(...expressions.findings);
     const data = pageFrontmatter(page, { decorate, webSrc, artSrc });
-    const secrets = renderSecretBlocks(protectCode(markdown, resolve), "web");
+    const secrets = renderSecretBlocks(protectCode(expressions.markdown, resolve), "web");
+    const admonitions = renderAdmonitions(secrets.markdown);
+    const captioned = renderCaptionBlocks(admonitions.markdown);
+    for (const error of captionScan.errors)
+        captionErrors.push({
+            file: page.file,
+            line: (page.bodyLine ?? 1) + (lineMap[error.line - 1]?.line ?? error.line - 1),
+            column: error.column,
+            message: error.message,
+        });
     for (const error of renderSecretBlocks(page.body, "book").errors)
         secretErrors.push({
             file: page.file,
@@ -755,13 +784,22 @@ export function renderSitePage(
             column: error.column,
             message: error.message,
         });
+    for (const error of scanAdmonitions(page.body).errors)
+        secretErrors.push({
+            file: page.file,
+            line: (page.bodyLine ?? 1) + error.line - 1,
+            column: error.column,
+            message: error.message,
+        });
     return {
         page,
-        body: secrets.markdown,
+        body: captioned.markdown,
         data,
         resolved,
         tableErrors,
+        expressionErrors,
         secretErrors,
+        captionErrors,
         wikiErrors,
         imageErrors,
     };
@@ -774,7 +812,7 @@ export function renderSitePage(
  * compilers use:
  *
  * 1. **Tables expand first**, and outside code-fence protection. A table is
- *    authored as a fenced `dataview` block, which `protectCode` would otherwise
+ *    authored as a fenced `sql` block, which `protectCode` would otherwise
  *    stash away before the expander saw it. Expanding first leaves an ordinary
  *    markdown table to walk, with every other fence still protected.
  * 2. **Then, inside protection**: the consumer's `beforeLinks` pass, then
@@ -836,7 +874,9 @@ export function renderPages(pages, options) {
     });
 
     const tableErrors = [];
+    const expressionErrors = [];
     const secretErrors = [];
+    const captionErrors = [];
     const wikiErrors = [];
     const imageErrors = [];
     const byKind = {};
@@ -877,7 +917,9 @@ export function renderPages(pages, options) {
             artIndex,
         });
         tableErrors.push(...result.tableErrors);
+        expressionErrors.push(...result.expressionErrors);
         secretErrors.push(...result.secretErrors);
+        captionErrors.push(...result.captionErrors);
         wikiErrors.push(...result.wikiErrors);
         imageErrors.push(...result.imageErrors);
         rendered.push({ page, body: result.body, data: result.data });
@@ -918,7 +960,9 @@ export function renderPages(pages, options) {
         written: pages.length,
         byKind,
         tableErrors,
+        expressionErrors,
         secretErrors,
+        captionErrors,
         wikiErrors,
         imageErrors,
         related,
@@ -940,6 +984,7 @@ export function renderPages(pages, options) {
  */
 const SITE_PASSES = Object.freeze({
     sohlKb: () => require("../sohl/kb-passes.mjs").sohlKbPass,
+    packageDocs: () => require("./documentation-links.mjs").documentationLinksPass,
 });
 
 /**
@@ -965,10 +1010,12 @@ export function resolveSitePass(name, options) {
 export function sitePageDecorator(config, index) {
     const router = routerFor(config);
     return (data, page) => {
-        if (isBeing(page.fm)) data.sohl = deriveBeingInfo(page.fm.sohl, index.refIndex);
+        const resolvedDates = resolvedDateFields(page.fm, index.dateContext);
+        if (Object.keys(resolvedDates).length) data.resolvedDates = resolvedDates;
         data.infoboxes = noteInfoboxes(page.fm, {
             resolve: (ref, hint) => resolveInfoboxRef(index, ref, hint),
             router,
+            dates: index.dateContext,
         });
     };
 }
@@ -998,9 +1045,7 @@ export function buildSite({ config, sqlTables } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
-    // Homepage-only or homepage-plus-content. The floor is the homepage,
-    // so this decides whether the *content* surfaces are published, never
-    // whether anything is.
+    // A tree containing only the homepage has no content pages to publish.
     const publishesContent = publishesContentPages(resolved);
 
     // Where the package is served, and where its content mounts inside it. The
@@ -1023,12 +1068,12 @@ export function buildSite({ config, sqlTables } = {}) {
     const out =
         publishesContent ?
             path.join(outBase, scheme.prefix.replace(/\/$/, ""))
-            // Homepage-only has no content mount, so the package's root *is*
+            // A tree containing only the homepage has no content mount, so its root is
             // the output root.
         :   outBase;
     // The homepage publishes at `/<contentPackage>/`, so its file goes at the
     // package's own root — one level above the content mount, and the same
-    // directory in homepage-only mode.
+    // directory when the tree contains only a homepage.
     const homeRoot = publishesContent ? outBase : out;
 
     const packages = new Set(site.packages.length ? site.packages : [resolved.contentPackage]);
@@ -1059,12 +1104,8 @@ export function buildSite({ config, sqlTables } = {}) {
     const collected = collectHomepages(resolved.paths.content, ctx);
     const homepages = collected.pages;
 
-    // Exactly one homepage, and checked here — before the output tree is
-    // cleared and before either mode branches. Before the clear, because
-    // a gate that fired after it would have destroyed a good site to report a
-    // bad tree. Before the branch, because the requirement does not vary by
-    // mode: `publish.site` chooses whether the *content* surfaces are
-    // published, and the homepage is the floor beneath both.
+    // Check for exactly one homepage before clearing the output tree, so a
+    // malformed tree does not destroy the last good site.
     //
     // The count is judged first, and alone when it fires: a tree with two
     // homepages does not need to be told about each one's address as well, and
@@ -1074,7 +1115,7 @@ export function buildSite({ config, sqlTables } = {}) {
         contentPackage: resolved.contentPackage,
     });
     // A homepage that cannot be addressed is reported in the same place, and
-    // reaches homepage-only mode — which runs no other gate at all.
+    // also applies when the tree contains only a homepage.
     const homepageFindings =
         counted.length ? counted : (
             collected.addressFindings.map((f) => ({
@@ -1088,7 +1129,9 @@ export function buildSite({ config, sqlTables } = {}) {
             gates: { ...emptyGates(), homepages: homepageFindings },
             manifests: null,
             tableErrors: [],
+            expressionErrors: [],
             secretErrors: [],
+            captionErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1108,7 +1151,9 @@ export function buildSite({ config, sqlTables } = {}) {
             gates: emptyGates(),
             manifests: null,
             tableErrors: [],
+            expressionErrors: [],
             secretErrors: [],
+            captionErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1154,7 +1199,9 @@ export function buildSite({ config, sqlTables } = {}) {
             gates,
             stats: null,
             tableErrors: [],
+            expressionErrors: [],
             secretErrors: [],
+            captionErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1164,6 +1211,7 @@ export function buildSite({ config, sqlTables } = {}) {
     const pass = resolveSitePass(site.pass, {
         ...site.passOptions,
         repoRoot: resolved.rootDir,
+        config: resolved,
     });
 
     // The map from each related place, drawn now that every page is known to
@@ -1209,7 +1257,9 @@ export function buildSite({ config, sqlTables } = {}) {
     return {
         gates,
         tableErrors: rendered.tableErrors,
+        expressionErrors: rendered.expressionErrors,
         secretErrors: rendered.secretErrors,
+        captionErrors: rendered.captionErrors,
         wikiErrors: rendered.wikiErrors,
         imageErrors: rendered.imageErrors,
         mapFindings: drawn.findings,

package/engine/site-config.mjs

@@ -14,7 +14,7 @@
 /**
  * The Hugo configuration a site build generates.
  *
- * `content-build site` writes the whole Hugo source tree under `build/hugo/`
+ * `package-build site` writes the whole Hugo source tree under `build/hugo/`
  * — `hugo.toml`, the content mount, Hugo's own cache — as a sibling of the
  * deployment root `build/site/`, so nothing Hugo reads lands in what is
  * published. The consumer's script runs Hugo over it; the toolchain never
@@ -50,7 +50,7 @@ import { slugify } from "./content-slug.mjs";
 /** The Hugo source directory, relative to the repository root. */
 export const HUGO_SOURCE = "build/hugo";
 
-/** The content mount `content-build site` writes, relative to the repository root. */
+/** The content mount `package-build site` writes, relative to the repository root. */
 export const HUGO_CONTENT = `${HUGO_SOURCE}/content`;
 
 /**
@@ -255,7 +255,7 @@ export function readCachedNavigation(config) {
     const file = path.join(dir, NAVIGATION_FILE);
     if (!fs.existsSync(path.join(dir, STAMP)) || !fs.existsSync(file)) {
         throw new Error(
-            "the site navigation has not been fetched. Run `content-build deps fetch` first.",
+            "the site navigation has not been fetched. Run `package-build deps fetch` first.",
         );
     }
     return checkNavigation(JSON.parse(fs.readFileSync(file, "utf8")), file);
@@ -364,17 +364,17 @@ function deepMerge(base, overrides) {
  * @param {string} options.themesDir - From {@link resolveThemesDir}.
  * @returns {Record<string, any>} The configuration Hugo reads.
  * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
- *   configuration declares no `packageBuild.manifest.title`, no
+ *   configuration declares no `site.title` or `packageBuild.manifest.title`, no
  *   `site.description`, or no `site.assets`.
  */
 export function hugoConfig({ config, navigation, themesDir }) {
     checkHomepage(config.homepage, config.contentPackage);
 
-    const title = config.packageBuild?.manifest?.title;
+    const title = config.site.title || config.packageBuild?.manifest?.title;
     if (typeof title !== "string" || !title.trim()) {
         throw new TypeError(
-            "package-build config: `packageBuild.manifest.title` is not declared, " +
-                "and the site's `title` reads from it.",
+            "package-build config: declare `site.title` or " +
+                "`packageBuild.manifest.title` for the site's title.",
         );
     }
     if (!config.site.description) {
@@ -423,7 +423,7 @@ export function hugoConfig({ config, navigation, themesDir }) {
  */
 export function hugoToml(generated) {
     return (
-        "# Generated by `content-build site` from package.json and " +
+        "# Generated by `package-build site` from package.json and " +
         "package-build.config.yaml.\n# Every value here has a source there; edit " +
         "the source, not this file.\n\n" +
         `${stringifyToml(generated)}\n`

package/engine/site-index.mjs

@@ -65,6 +65,7 @@ import {
 } from "./address.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
 import { contentPackage } from "./content-package.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 // The declared tag vocabulary, which is where `draft` is stated.
 import { isDraftNote } from "./note-vocabulary.mjs";
 
@@ -160,6 +161,8 @@ function mergeForeign(index, foreignIndex) {
  *   `contentIndex: false` — a Foundry dependency only, with no fetched index.
  *   A link naming one fails naming the key, rather than reading as prose or an
  *   ordinary dead address.
+ * @param {object[]} [options.records] - Content-index records.
+ * @param {Map<string, object>} [options.foreignReferences] - Foreign reference targets.
  * @returns {SiteIndex} The index, and what could not be addressed unambiguously.
  */
 export function buildSiteIndex(
@@ -252,6 +255,7 @@ export function buildSiteIndex(
 
     return {
         contentPackage: ownPackage,
+        dateContext: reckoningContext({ notes: records }),
         referenceTargets: buildReferenceTargets(records, new Map([...foreignReferences, ...index])),
         index,
         ambiguous,

package/engine/site-maps.mjs

@@ -15,7 +15,7 @@
  * The maps a site build writes into its place pages.
  *
  * A place that states, or is named in, a border or a route has a map from it
- * — the drawing `content-build map --from` makes — and the site build draws
+ * — the drawing `package-build map --from` makes — and the site build draws
  * that map for every such place of this package and hands each one to the
  * page writer, which lays it beside the page as `from-<shortcode>.svg` and
  * names it in the front matter as `map`. The theme inlines it, so its place

package/engine/site-preview.mjs

@@ -18,6 +18,7 @@ import { reckoningContext } from "./reckoning-markers.mjs";
 import { cachedMetadataIndexes, noContentIndexPackages } from "./metadata-index.mjs";
 import { buildSiteIndex } from "./site-index.mjs";
 import { openNotesDatabase, prepareSqlTables, findSqlBlocks } from "./sql-tables.mjs";
+import { isGmNote } from "./note-vocabulary.mjs";
 import { relatedPages } from "./related-pages.mjs";
 import { holdingsNode, holdingsPages, foreignHoldingsNodes } from "./holdings.mjs";
 import { assetAddressIndex } from "./art-fields.mjs";
@@ -79,10 +80,14 @@ export async function prepareSitePreview({ config = loadPackConfig() } = {}) {
         const gates = siteGates([...pages, ...homeEntries], findings, { config, records });
         if (gatesFailed(gates))
             throw new Error("site preview cannot prepare: site integrity gates failed");
-        const db = await openNotesDatabase(records, {
-            dependencies,
-            addressContext: noteAddressContext(config),
-        });
+        const db = await openNotesDatabase(
+            records.filter((record) => !isGmNote(record)),
+            {
+                dependencies,
+                addressContext: noteAddressContext(config),
+                audience: "public",
+            },
+        );
         try {
             const sources = pages
                 .filter((page) => findSqlBlocks(page.body).length)
@@ -200,10 +205,14 @@ export async function prepareSitePreview({ config = loadPackConfig() } = {}) {
                         records,
                         noIndexPackages: noContentIndexPackages(config),
                     });
-                    db = await openNotesDatabase(records, {
-                        dependencies,
-                        addressContext: noteAddressContext(config),
-                    });
+                    db = await openNotesDatabase(
+                        records.filter((record) => !isGmNote(record)),
+                        {
+                            dependencies,
+                            addressContext: noteAddressContext(config),
+                            audience: "public",
+                        },
+                    );
                 }
                 const sqlTables = await prepareSqlTables(db, [
                     { source: absolute, markdown: body },
@@ -235,6 +244,8 @@ export async function prepareSitePreview({ config = loadPackConfig() } = {}) {
                     });
                 for (const error of result.secretErrors)
                     findings.push({ ...error, severity: "error" });
+                for (const error of result.captionErrors)
+                    findings.push({ ...error, severity: "error" });
                 for (const error of result.wikiErrors) {
                     const pos = positionOfLiteral(text, error.link, error.occurrence);
                     findings.push({

package/engine/social-ties.mjs

@@ -16,7 +16,11 @@ export { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES };
 
 const TERMS = new Set(SOCIAL_TIES.map(({ term }) => term));
 
-/** Validate a being's map of defining relationships. */
+/**
+ * Validate a being's map of defining relationships.
+ * @param {object} note
+ * @param {{index?: object}} [options]
+ */
 export function checkSocialTies(note, { index } = {}) {
     const ties = note.fm?.data?.socialTies;
     if (ties === undefined || ties === null) return [];