@heroiclands/package-build 22.15.1 → 22.16.0

package/bin/{content-build.mjs → content-commands.mjs}

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /*
  * 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>
@@ -13,43 +12,26 @@
  */
 
 /**
- * The `content-build` command line — compile / unpack / clean LevelDB packs.
- *
- * A thin `yargs` front end over `../engine/compendiums.mjs`. **Every side
- * effect the pack pipeline has lives here**: argv parsing, `loglevel`
- * configuration, directory creation, reading the shipped Foundry package
- * manifest, and the process exit code. The library itself is import-safe, so a
- * consuming repository's build — or a test — can call it without any of this
- * happening.
- *
- * The side effects that need *configuration* live inside the command handler,
- * not at module scope, so `--version` and `--help` answer in a directory that
- * has neither a `package-build.config.yaml` nor a package manifest.
- * Running an actual command still resolves both, and still fails loudly when
- * either is missing.
- *
- * Every path and pack name it hands the library comes from the consuming
- * repository's `package-build.config.yaml`, located by
- * `engine/pack-config.mjs`; nothing about any one repository's layout is
- * written here.
+ * Content command modules registered by the `package-build` CLI.
+ * Configuration is read in handlers, so help and version work without a
+ * package configuration. Build inputs come from `package-build.config.yaml`.
  *
  * Usage:
- *   npx content-build package compile [pack]
- *   npx content-build package unpack [pack] [entry]
- *   npx content-build package clean [pack] [entry]
- *   npx content-build docs item-fields [--out <path>] [--title <title>]
- *   npx content-build lint [root] [--no-references]
- *   npx content-build content-format schema --schema <system>=<path>
- *   npx content-build content-format fields [--fields <system>]
- *   npx content-build content-format notes [root] [--strict]
- *   npx content-build links [root] [--manifests <dir>]
- *   npx content-build format [paths..] [--write]
- *   npx content-build markdown [paths..] [--fix]
- *   npx content-build manifest [root] [--out <dir>]
- *   npx content-build site [--out <dir>]
- *   npx content-build map [--tree] [--from <shortcode>] [--chart <shortcode>] [--travel] [--out <dir>]
- *   npx content-build reachability <dir> [file] [--index <shortcode>]
- *   npx content-build addresses diff --from <zip|dir> [--strict]
+ *   npx package-build package compile [pack]
+ *   npx package-build package unpack [pack] [entry]
+ *   npx package-build package clean [pack] [entry]
+ *   npx package-build docs item-fields [--out <path>] [--title <title>]
+ *   npx package-build lint [root] [--no-references]
+ *   npx package-build content-format schema --schema <system>=<path>
+ *   npx package-build content-format fields [--fields <system>]
+ *   npx package-build content-format notes [root] [--strict]
+ *   npx package-build links [root] [--manifests <dir>]
+ *   npx package-build format [paths..] [--write]
+ *   npx package-build markdown [paths..] [--fix]
+ *   npx package-build site [--out <dir>]
+ *   npx package-build map [--tree] [--from <shortcode>] [--chart <shortcode>] [--travel] [--out <dir>]
+ *   npx package-build reachability <dir> [file] [--index <shortcode>]
+ *   npx package-build addresses diff --from <zip|dir> [--strict]
  *
  * In a consuming repository, wrapped as npm scripts — SoHL spells them:
  *   npm run build:compiledb                // → … package compile (all packs)
@@ -61,11 +43,9 @@ import fs from "fs";
 import path from "node:path";
 import log from "loglevel";
 import prefix from "loglevel-plugin-prefix";
-import yargs from "yargs";
-import { hideBin } from "yargs/helpers";
 import { compilePacks, cleanPacks, unpackPacks } from "../engine/compendiums.mjs";
-import { compilesFoundryDocuments } from "../content-config.mjs";
-import { loadPackConfig } from "../engine/pack-config.mjs";
+import { compilesFoundryDocuments, publishesContentPages } from "../content-config.mjs";
+import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { buildPdf } from "../engine/pdf-build.mjs";
 import {
     fetchAllCatalogs,
@@ -76,12 +56,14 @@ import {
 } from "../engine/foreign-catalog.mjs";
 import {
     metadataRelationships,
+    cachedMetadataIndexes,
     cachedIndexPath,
     unaddressableForeignPackages,
     formatUnaddressableFinding,
 } from "../engine/metadata-index.mjs";
 import { fetchNavigation, generateHugoConfig, writeHugoConfig } from "../engine/site-config.mjs";
 import { renderItemFieldReference, renderItemFieldsPage } from "../engine/field-reference.mjs";
+import { checkDocLinks, checkDocIndex } from "../engine/docs-checks.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintNoteStates } from "../engine/stub-lint.mjs";
 import { lintContentCharset } from "../engine/content-charset.mjs";
@@ -115,6 +97,8 @@ import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { schemaSubtypeOf } from "../engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { checkFormatting, checkPrettierConventions, lintMarkdown } from "../engine/prose-lint.mjs";
+import { lintProse } from "../engine/readability-lint.mjs";
+import { loadPackageBuildConfig } from "../config.mjs";
 import {
     authoredFrontmatter,
     emitContentIndex,
@@ -170,21 +154,6 @@ function configuredPacks() {
     return loadPackConfig().packDirectories.map((name) => ({ name }));
 }
 
-/**
- * This package's own version, for `--version`.
- *
- * Read from the package's `package.json` rather than left to yargs, which
- * defaults to the *nearest* `package.json` walking up from the working
- * directory — inside a consuming repository that is the consumer's manifest, so
- * `content-build --version` reported the consumer's version instead of the
- * toolchain's.
- *
- * @returns {string} The `version` field of this package's manifest.
- */
-function ownVersion() {
-    return JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-}
-
 // Configure loglevel
 log.setLevel("info"); // Set desired logging level
 
@@ -246,33 +215,109 @@ function readRawNote(file) {
  */
 const SHIPPED_ITEM_FIELDS = { sohl: ITEM_FIELDS, hm3: HM3_ITEM_FIELDS };
 
-const argv = yargs(hideBin(process.argv))
-    .command(packageCommand())
-    .command(depsCommand())
-    .command(docsCommand())
-    .command(lintCommand())
-    .command(contentFormatCommand())
-    .command(linksCommand())
-    .command(formatCommand())
-    .command(markdownCommand())
-    .command(contentIndexCommand())
-    .command(siteCommand())
-    .command(pdfCommand())
-    .command(mapCommand())
-    .command(reachabilityCommand())
-    .command(addressesCommand())
-    .version(ownVersion())
-    .help()
-    .alias("help", "h")
-    // Every invocation this CLI accepts must be one it performs. yargs
-    // gives neither guarantee by default: without `demandCommand` a bare
-    // `content-build` exits 0 in silence, and without `strict` an unknown
-    // command or option is ignored rather than reported. Both would read as
-    // success from a `run-s` chain, so a typo in a build script passed the step
-    // it was meant to run. The sibling toolchain `@heroiclands/package-build`
-    // opts into the same two.
-    .demandCommand(1, "Name a command.")
-    .strict().argv;
+/** Register the content operations on the package command line. */
+export function registerContentCommands(cli) {
+    return cli
+        .command(withIndexPreflight(packageCommand(), (_config, argv) => argv.action === "compile"))
+        .command(depsCommand())
+        .command(docsCommand())
+        .command(withIndexPreflight(lintCommand()))
+        .command(proseCommand())
+        .command(contentFormatCommand())
+        .command(withIndexPreflight(linksCommand()))
+        .command(formatCommand())
+        .command(markdownCommand())
+        .command(contentIndexCommand())
+        .command(withIndexPreflight(siteCommand(), publishesContentPages))
+        .command(
+            withIndexPreflight(
+                pdfCommand(),
+                (config) => config.pdf && publishesContentPages(config),
+            ),
+        )
+        .command(withIndexPreflight(mapCommand()))
+        .command(withIndexPreflight(reachabilityCommand()))
+        .command(addressesCommand());
+}
+
+/** Opt-in readability and plain-language suggestions for Markdown notes. */
+function proseCommand() {
+    return {
+        command: "prose <action> [path]",
+        describe: "Analyze note prose on demand",
+        builder: (yargs) =>
+            yargs
+                .positional("action", { choices: ["lint"], describe: "Analyze prose" })
+                .positional("path", {
+                    type: "string",
+                    describe: "One Markdown file or a content tree",
+                })
+                .option("age", { type: "number", describe: "Reader age" })
+                .option("threshold", {
+                    type: "number",
+                    describe: "Readability algorithms required (1–7)",
+                })
+                .option("min-words", { type: "number", describe: "Minimum words per sentence" }),
+        handler: async (argv) => {
+            try {
+                const config = loadPackConfig();
+                const defaults = loadPackageBuildConfig().proseLint;
+                const options = {
+                    age: argv.age ?? defaults.age,
+                    threshold: argv.threshold ?? defaults.threshold,
+                    minWords: argv.minWords ?? defaults.minWords,
+                };
+                for (const [key, value] of Object.entries(options)) {
+                    if (
+                        !Number.isInteger(value) ||
+                        value < 1 ||
+                        (key === "threshold" && value > 7)
+                    ) {
+                        throw new TypeError(
+                            `${key} must be ${key === "threshold" ? "an integer from 1 to 7" : "a positive integer"}`,
+                        );
+                    }
+                }
+                const findings = await lintProse(
+                    argv.path ?? config.paths.content,
+                    options,
+                    config.skipDirectories,
+                );
+                for (const finding of findings) emitDiagnostic(finding);
+                log.info(`${findings.length} prose suggestion(s).`);
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
+/** Check declared dependency indexes before an index-consuming command does any work. */
+function withIndexPreflight(command, shouldCheck = () => true) {
+    const handler = command.handler;
+    return {
+        ...command,
+        handler: async (argv) => {
+            let config;
+            try {
+                config = loadPackConfig();
+                if (shouldCheck(config, argv)) cachedMetadataIndexes(config);
+            } catch (err) {
+                if (config) {
+                    emitDiagnostic({
+                        file: packConfigPath(),
+                        severity: "error",
+                        message: err instanceof Error ? err.message : String(err),
+                    });
+                } else reportFailure(err);
+                process.exitCode = 1;
+                return;
+            }
+            return handler(argv);
+        },
+    };
+}
 
 /**
  * `docs item-fields` — render this repository's item-frontmatter reference.
@@ -309,16 +354,21 @@ const argv = yargs(hideBin(process.argv))
 function docsCommand() {
     return {
         command: "docs <action>",
-        describe: "Generate documentation from the configured registries",
+        describe: "Generate and check project documentation",
         builder: (yargs) => {
             // Required and honoured, not optional and unread:
             // the handler rendered the item-field reference whatever it was
             // given, so the positional constrained what could be typed and
             // selected nothing.
             yargs.positional("action", {
-                describe: "The document to render.",
+                describe: "The documentation action.",
                 type: "string",
-                choices: ["item-fields"],
+                choices: ["item-fields", "links", "index"],
+            });
+            yargs.option("root", {
+                describe: "Documentation root for the links and index checks.",
+                type: "string",
+                default: "docs",
             });
             yargs.option("out", {
                 describe: "Write to this file instead of the configured location.",
@@ -337,6 +387,26 @@ function docsCommand() {
         handler: (argv) => {
             try {
                 const { action, title, check } = argv;
+                if (action === "links" || action === "index") {
+                    const requestedRoot = path.resolve(argv.root);
+                    const root =
+                        fs.existsSync(requestedRoot) ?
+                            fs.realpathSync(requestedRoot)
+                        :   requestedRoot;
+                    const findings = action === "links" ? checkDocLinks(root) : checkDocIndex(root);
+                    for (const finding of findings) {
+                        emitDiagnostic({
+                            ...finding,
+                            file: path.relative(process.cwd(), finding.file),
+                        });
+                    }
+                    if (findings.length) process.exitCode = 1;
+                    else
+                        log.info(
+                            `Documentation ${action} check passed for ${path.relative(process.cwd(), root) || "."}.`,
+                        );
+                    return;
+                }
                 // Dispatched on, so a second document added here cannot
                 // silently render the first. yargs' `choices` has already
                 // rejected anything unlisted, so the default is unreachable by
@@ -354,7 +424,7 @@ function docsCommand() {
                 const body = `${renderItemFieldReference({
                     title: pageTitle,
                     ...(spec.preamble ? { preamble: spec.preamble } : {}),
-                    generatedBy: "`content-build docs item-fields`",
+                    generatedBy: "`package-build docs item-fields`",
                     config,
                 })}\n`;
                 // A page filed under the content tree is walked for its
@@ -395,7 +465,7 @@ function docsCommand() {
                             severity: "error",
                             message:
                                 "out of date with the item-field declarations " +
-                                "— run `content-build docs item-fields` and " +
+                                "— run `package-build docs item-fields` and " +
                                 "commit the regenerated file",
                         });
                         process.exitCode = 1;
@@ -423,7 +493,7 @@ function docsCommand() {
 }
 
 /**
- * `content-build content-format` — check the format specification itself.
+ * `package-build content-format` — check the format specification itself.
  *
  * Two checks, because the specification makes claims about two different
  * worlds, and they fail for different reasons and at different times:
@@ -431,15 +501,11 @@ function docsCommand() {
  * - `schema` compares every `system.*` target the document names against the
  *   naming system's published `schema.json`. A failure means the specification
  *   and the system disagree, which is a defect in one of the two.
- * - `fields` compares the per-type tables against the field declarations that
- *   compile them, so the hand-written half cannot drift from the generated one.
- * - `notes` measures a content tree against the vocabulary the document
- *   declares per type. During the migration it is the progress bar rather
- *   than a gate, so it **reports** by default and `--strict` makes it fatal —
- *   turned on one class at a time as each slice lands.
+ * - `fields` compares declared field mappings with compiler declarations.
+ * - `notes` measures authored notes against the declared vocabulary.
  *
- * Both read the committed document rather than a transcription of it, so
- * editing `docs/content-format.md` changes what they assert.
+ * The shipped contract is `engine/content-format.yaml`; guide layout does not
+ * participate in validation.
  *
  * @returns {object} The yargs command module.
  */
@@ -489,7 +555,7 @@ function contentFormatSchemaCommand() {
         builder: (yargs) => {
             yargs.option("spec", {
                 describe:
-                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                    "The format contract to read. Defaults to the engine/content-format.yaml this package ships.",
                 type: "string",
             });
             yargs.option("schema", {
@@ -597,7 +663,7 @@ function contentFormatFieldsCommand() {
         builder: (yargs) => {
             yargs.option("spec", {
                 describe:
-                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                    "The format contract to read. Defaults to the engine/content-format.yaml this package ships.",
                 type: "string",
             });
             yargs.option("fields", {
@@ -686,7 +752,7 @@ function contentFormatNotesCommand() {
             });
             yargs.option("spec", {
                 describe:
-                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                    "The format contract to read. Defaults to the engine/content-format.yaml this package ships.",
                 type: "string",
             });
             yargs.option("strict", {
@@ -754,7 +820,7 @@ function contentFormatNotesCommand() {
 }
 
 /**
- * `content-build lint` — check a content tree's addresses.
+ * `package-build lint` — check a content tree's addresses.
  *
  * Deliberately independent of the pack pipeline: it compiles nothing, opens no
  * LevelDB and needs no Foundry manifest, so it runs in a second and can gate a
@@ -910,7 +976,7 @@ function lintCommand() {
                             `@${config.stats.systemVersion ?? "?"}, so emitted ` +
                             `\`system\` fields are unchecked. A system ` +
                             `generates its own; a module gets one from ` +
-                            `\`content-build deps fetch\`.`,
+                            `\`package-build deps fetch\`.`,
                     );
                 }
                 const fieldSpecs = config.itemFields ?? {};
@@ -1061,7 +1127,7 @@ function lintCommand() {
 }
 
 /**
- * `content-build format` — Prettier, with the shared configuration.
+ * `package-build format` — Prettier, with the shared configuration.
  *
  * Deliberately **not** scoped to the content tree, and deliberately free of the
  * pack configuration: a repository's formatting covers everything it holds, and
@@ -1167,7 +1233,7 @@ function formatCommand() {
 }
 
 /**
- * `content-build markdown` — markdownlint, with the shared rule set.
+ * `package-build markdown` — markdownlint, with the shared rule set.
  *
  * The structural checks Prettier cannot make: a heading level that skips, two
  * sibling headings claiming one anchor, a reversed link, an emphasis marker
@@ -1215,7 +1281,7 @@ function markdownCommand() {
 }
 
 /**
- * `content-build links` — check that every link in a content tree lands.
+ * `package-build links` — check that every link in a content tree lands.
  *
  * Reports a dead `#anchor`, a dead qualified address, and a wikilink authored
  * in frontmatter, plus a vendored manifest that has drifted out of reach. All
@@ -1278,7 +1344,7 @@ function linksCommand() {
                             message: `unusable content index: ${s.reason}`,
                         });
                     }
-                    log.error("Re-run `content-build deps fetch`.");
+                    log.error("Re-run `package-build deps fetch`.");
                     process.exitCode = 1;
                     return;
                 }
@@ -1385,7 +1451,7 @@ function linksCommand() {
 }
 
 /**
- * `content-build content-index` — emit this package's note index.
+ * `package-build content-index` — emit this package's note index.
  *
  * Every build already walks the tree and parses every note's frontmatter, then
  * throws the result away, so nothing outside a build can ask a question about
@@ -1438,7 +1504,7 @@ function contentIndexCommand() {
 }
 
 /**
- * `content-build pdf` — build the book the content tree publishes as.
+ * `package-build pdf` — build the book the content tree publishes as.
  *
  * The third surface, beside `package compile` and `site`. It takes the same
  * `--out` override the site command does, and reports what it found in the same
@@ -1490,6 +1556,9 @@ function pdfCommand() {
                 // resolve is an error, because the same statement is wrong in
                 // Foundry and on the website too.
                 const errors = reportFindings(result.findings, {});
+                for (const report of result.imageReports ?? []) {
+                    log.info(`${report.file}: ${report.message}`);
+                }
 
                 if (!result.built) {
                     // A reason is a deliberate no-op — the fence, an absent
@@ -1523,7 +1592,7 @@ function pdfCommand() {
 }
 
 /**
- * `content-build site` — publish the content tree as a website.
+ * `package-build site` — publish the content tree as a website.
  *
  * The sibling of `package compile`: the same tree, rendered as pages instead of
  * compiled into packs. Everything a consumer would otherwise write for itself —
@@ -1567,6 +1636,8 @@ function siteCommand() {
                     config,
                     sqlTables: await prepareTreeSqlTables(config.paths.content, {
                         skipDirectories: config.skipDirectories,
+                        config,
+                        audience: "public",
                     }),
                 });
                 const { gates } = result;
@@ -1627,9 +1698,15 @@ function siteCommand() {
                         message: e.reason,
                     });
                 }
+                for (const e of result.expressionErrors) {
+                    emitDiagnostic(e);
+                }
                 for (const e of result.secretErrors) {
                     emitDiagnostic({ ...e, severity: "error" });
                 }
+                for (const e of result.captionErrors) {
+                    emitDiagnostic({ ...e, severity: "error" });
+                }
                 // Reported the way the pack build reports the very same
                 // finding: `file:line:column: error: message`, path first, and
                 // the message from the shared table, not a
@@ -1666,7 +1743,9 @@ function siteCommand() {
                 }
                 if (
                     result.tableErrors.length ||
+                    result.expressionErrors.length ||
                     result.secretErrors.length ||
+                    result.captionErrors.length ||
                     result.wikiErrors.length ||
                     result.imageErrors.length
                 ) {
@@ -1695,7 +1774,7 @@ function siteCommand() {
 }
 
 /**
- * `content-build map` — draw what the place notes state.
+ * `package-build map` — draw what the place notes state.
  *
  * Reads the content index — this package's and every declared dependency's —
  * so a consumer's map draws its dependencies' places beside its own, and
@@ -1814,7 +1893,7 @@ function mapCommand() {
                     });
                 }
                 if (world.stale.length) {
-                    log.error("Re-run `content-build deps fetch`.");
+                    log.error("Re-run `package-build deps fetch`.");
                     process.exitCode = 1;
                     return;
                 }
@@ -1851,14 +1930,14 @@ function mapCommand() {
 }
 
 /**
- * `content-build reachability <dir> [file]` — check that a corpus reads through.
+ * `package-build reachability <dir> [file]` — check that a corpus reads through.
  *
  * The corpus is named on the command line rather than declared in code, because
  * it never changes for a given repository: a consumer hardcodes the invocation
  * in `package.json` and gets the check without writing a script.
  *
- *   content-build reachability Rules --index glossary
- *   content-build reachability User_Guide --index glossary
+ *   package-build reachability Rules --index glossary
+ *   package-build reachability User_Guide --index glossary
  *
  * @returns {object} The yargs command module.
  */
@@ -2118,7 +2197,7 @@ function depsCommand() {
  *
  * ```sh
  * gh release download v0.8.2 -p system.zip -D build/baseline
- * npx content-build addresses diff --from build/baseline/system.zip
+ * npx package-build addresses diff --from build/baseline/system.zip
  * ```
  *
  * @param {object} config - The resolved build configuration.
@@ -2261,10 +2340,10 @@ function addressesCommand() {
 function packageCommand() {
     return {
         command: "package <action> [pack] [entry]",
-        describe: "Manage packages",
+        describe: "Compile, unpack, or clean compendium packs",
         builder: (yargs) => {
             // Required, not optional: the action *is* the work, and an
-            // optional one meant `content-build package` fell through the
+            // optional one meant `package-build package` fell through the
             // switch below and exited 0 having compiled nothing.
             yargs.positional("action", {
                 describe: "The action to perform.",
@@ -2296,8 +2375,8 @@ function packageCommand() {
                     throw new Error(
                         `\`packageKind: ${config.packageKind}\` compiles no ` +
                             `compendium, so there is nothing to ${action}. Build ` +
-                            `its site with \`content-build site\` and its book ` +
-                            `with \`content-build pdf\`.`,
+                            `its site with \`package-build site\` and its book ` +
+                            `with \`package-build pdf\`.`,
                     );
                 }
                 // The one directory the pipeline creates rather than expects: