@heroiclands/package-build 22.15.1 → 22.17.0

package/bin/package-build.mjs

@@ -50,6 +50,8 @@
  *   npx package-build clean [--distclean]
  *   npx package-build assets
  *   npx package-build calendars --calendaria-version <version>
+ *   npx package-build datefrom <calendar> <date>
+ *   npx package-build dateto <calendar> <canonical-date>
  *   npx package-build manifest
  *   npx package-build lang check
  *   npx package-build lang coverage [--unused]
@@ -76,6 +78,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 import { globSync } from "glob";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
@@ -87,9 +92,12 @@ import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
-import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
+import { cleanBuildArtifacts, resetStage, stageAssets } from "../stage.mjs";
 import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
 import { emitCalendarArtifacts } from "../engine/calendar-artifacts.mjs";
+import { dateFromCalendar, dateToCalendar } from "../engine/date-conversion.mjs";
+import { walkMarkdownTree } from "../engine/helpers.mjs";
+import { reckoningContext } from "../engine/reckoning-markers.mjs";
 import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
 import { validateLangSource } from "../lang.mjs";
 import { checkLabelRegistry } from "../labels.mjs";
@@ -112,6 +120,14 @@ import { deployStage } from "../deploy.mjs";
 import { CONTAINER_ACTIONS, containerAction } from "../container.mjs";
 import { E2E_MODES, e2eFast, e2eRun, e2eSweep, seedTestWorld } from "../e2e.mjs";
 import { reportFindings } from "./report.mjs";
+import { formatGenerated } from "../engine/format-generated.mjs";
+import {
+    checkProject,
+    initializeProject,
+    INIT_KINDS,
+    INIT_LICENSES,
+} from "../engine/project-init.mjs";
+import { registerContentCommands } from "./content-commands.mjs";
 
 /**
  * How many unreferenced keys a run prints before it summarizes the rest.
@@ -121,6 +137,143 @@ import { reportFindings } from "./report.mjs";
  */
 const ADVISORY_PREVIEW = 20;
 
+/** Replay pull-request workflow commands in Docker or on the host. */
+function ciCommand() {
+    return {
+        command: "ci",
+        describe: "Replay pull-request workflow commands",
+        builder: (y) =>
+            y.option("native", {
+                type: "boolean",
+                default: false,
+                describe: "Run in the current working tree without Docker",
+            }),
+        handler: handler(async (args) => {
+            const script = fileURLToPath(
+                new URL(
+                    args.native ? "../ci/ci-steps.mjs" : "../ci/ci-docker.mjs",
+                    import.meta.url,
+                ),
+            );
+            const top = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+                encoding: "utf8",
+            });
+            const root = top.status === 0 ? top.stdout.trim() : process.cwd();
+            const result = spawnSync(process.execPath, [script], {
+                cwd: root,
+                stdio: "inherit",
+            });
+            if (result.error) throw result.error;
+            if (result.status !== 0) process.exitCode = 1;
+        }),
+    };
+}
+
+/** Initialize a repository from anywhere, including outside a Git checkout. */
+function initCommand() {
+    return {
+        command: "init [directory]",
+        describe: "Create or check a content package with site and book targets",
+        builder: (y) =>
+            y
+                .positional("directory", {
+                    type: "string",
+                    describe: "Directory to initialize or check (default: current directory)",
+                })
+                .option("check", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Check an existing package without writing files",
+                })
+                .option("kind", {
+                    type: "string",
+                    choices: INIT_KINDS,
+                    describe: "Package kind",
+                })
+                .option("name", { type: "string", describe: "npm and Foundry package name" })
+                .option("title", { type: "string", describe: "Human-readable package title" })
+                .option("description", { type: "string", describe: "Package and site description" })
+                .option("author", { type: "string", describe: "Author credited in the package" })
+                .option("license", {
+                    type: "string",
+                    choices: INIT_LICENSES,
+                    describe: "Original or unofficial fan-material license template",
+                })
+                .option("core-minimum", {
+                    type: "string",
+                    default: "14.359",
+                    describe: "Minimum Foundry core version for a Foundry package",
+                })
+                .option("core-verified", {
+                    type: "string",
+                    default: "14.364",
+                    describe: "Verified Foundry core version for a Foundry package",
+                }),
+        handler: handler(async (args) => {
+            const root = path.resolve(args.directory ?? process.cwd());
+            if (args.check) {
+                const findings = checkProject(root);
+                for (const { file, message } of findings) {
+                    console.error(`${path.join(root, file)}: error: ${message}`);
+                }
+                if (findings.length) process.exitCode = 1;
+                else console.log(`package-build: ${root} is ready to build.`);
+                return;
+            }
+            const defaults = {
+                name: path.basename(root),
+                title: path
+                    .basename(root)
+                    .replaceAll("-", " ")
+                    .split(" ")
+                    .map((word) => word[0]?.toUpperCase() + word.slice(1))
+                    .join(" "),
+                kind: "modules",
+                license: "original",
+            };
+            const answers = {
+                name: args.name,
+                title: args.title,
+                description: args.description,
+                author: args.author,
+                kind: args.kind,
+                license: args.license,
+            };
+            const questions = ["name", "title", "description", "author", "kind", "license"];
+            if (questions.some((key) => !answers[key])) {
+                if (!process.stdin.isTTY) {
+                    const missing = questions.filter((key) => !answers[key]);
+                    throw new Error(
+                        `init: supply ${missing.map((key) => `--${key}`).join(", ")} when input is not interactive`,
+                    );
+                }
+                const input = createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    for (const key of questions) {
+                        if (answers[key]) continue;
+                        const fallback = defaults[key];
+                        const value = await input.question(
+                            `${key}${fallback ? ` [${fallback}]` : ""}: `,
+                        );
+                        answers[key] = value.trim() || fallback;
+                    }
+                } finally {
+                    input.close();
+                }
+            }
+            const files = await initializeProject(root, {
+                ...answers,
+                version: ownVersion(),
+                coreMinimum: args.coreMinimum,
+                coreVerified: args.coreVerified,
+            });
+            console.log(`package-build: created ${files.length} files in ${root}.`);
+            console.log("Run `npm install`, then `npm run lint`.");
+            console.log("Use `npm run build:site`, `npm run serve:site`, or `npm run build:book`.");
+        }),
+    };
+}
+
 /**
  * This package's own version, for `--version`.
  *
@@ -318,6 +471,24 @@ function assetsCommand() {
     };
 }
 
+/** Clear the package stage before a complete build writes to it. */
+function stageCommand() {
+    return {
+        command: "stage <action>",
+        describe: "Manage the assembled Foundry package stage",
+        builder: (y) =>
+            y.positional("action", {
+                choices: ["reset"],
+                describe: "Remove the configured stage directory",
+            }),
+        handler: handler(() => {
+            const config = loadPackageBuildConfig();
+            const removed = resetStage(config.rootDir, config.stageDir);
+            console.log(removed ? `Removed ${config.stageDir}` : "Stage is already empty.");
+        }),
+    };
+}
+
 /** Emit the package's calendar definitions from its content index. */
 function calendarsCommand() {
     return {
@@ -340,32 +511,122 @@ function calendarsCommand() {
     };
 }
 
-/**
- * Format generated text the way the repository formats everything else.
- *
- * Not cosmetic. A generated file that Prettier would reformat leaves
- * `lint:format` and the generator's own `--check` each demanding what the other
- * forbids, and the repository cannot be made green. Resolving the config from
- * the *output path* is what makes one implementation here serve repositories
- * with different Prettier settings.
- *
- * Imported on use, as `prose-lint.mjs` does, so that commands which never
- * format do not pay to load it.
- *
- * @param {string} text - The unformatted content.
- * @param {string} filepath - Where it will be written.
- * @returns {Promise<string>} The formatted content.
- */
-async function formatGenerated(text, filepath) {
-    const prettier = await import("prettier");
-    const config = await prettier.resolveConfig(filepath);
-    return prettier.format(text, { ...config, filepath });
+/** Read the current content tree so conversion uses its authored calendars. */
+function calendarConversionContext() {
+    const config = loadPackConfig();
+    if (!fs.existsSync(config.paths.content))
+        throw new Error(`no content tree at ${config.paths.content}`);
+    const notes = [
+        ...walkMarkdownTree(config.paths.content, {
+            skipDirectories: config.skipDirectories,
+        }),
+    ].map(({ frontmatter, absPath }) => ({ fm: frontmatter, file: absPath }));
+    const context = reckoningContext({ notes });
+    const error = context.findings.find((finding) => finding.severity === "error");
+    if (error) throw Object.assign(new Error(formatDiagnostic(error)), { located: true });
+    if (!Number.isSafeInteger(context.daysPerYear) || context.daysPerYear < 1)
+        throw new Error("the content tree needs a world with data.year.days");
+    return context;
+}
+
+/** Convert a calendar day to the world's canonical year and day. */
+function datefromCommand() {
+    return {
+        command: "datefrom <calendar> <date>",
+        describe: "Convert a calendar date to its canonical value",
+        builder: (y) =>
+            y
+                .positional("calendar", {
+                    type: "string",
+                    describe: "Calendar Address or shortcode",
+                })
+                .positional("date", {
+                    type: "string",
+                    describe: "Day written in that calendar's std format (or first named format)",
+                }),
+        handler: handler((args) => {
+            console.log(dateFromCalendar(args.calendar, args.date, calendarConversionContext()));
+        }),
+    };
+}
+
+/** Express a canonical day in the covering era of a calendar. */
+function datetoCommand() {
+    return {
+        command: "dateto <calendar> <canonical-date>",
+        describe: "Convert a canonical day to a calendar date",
+        builder: (y) =>
+            y
+                .positional("calendar", {
+                    type: "string",
+                    describe: "Calendar Address or shortcode",
+                })
+                .positional("canonical-date", {
+                    type: "string",
+                    describe: "Canonical <year>.<day>[:HHMMSS]",
+                })
+                .option("format", {
+                    type: "string",
+                    describe: "Named calendar format; defaults to std or the first declared format",
+                }),
+        handler: handler((args) => {
+            console.log(
+                dateToCalendar(
+                    args.calendar,
+                    args.canonicalDate,
+                    calendarConversionContext(),
+                    args.format,
+                ),
+            );
+        }),
+    };
+}
+
+/** Check a project's declarations with library checks enabled. */
+function typesCheckCommand() {
+    return {
+        command: "check",
+        describe: "Check project declaration files with TypeScript library checks enabled",
+        builder: (yargs) =>
+            yargs
+                .option("project", {
+                    describe: "TypeScript project file.",
+                    type: "string",
+                    default: "tsconfig.json",
+                })
+                .option("exports", {
+                    describe: "Include every declaration entry point in package.json exports.",
+                    type: "boolean",
+                    default: false,
+                }),
+        handler: handler(async (args) => {
+            const { checkDeclarations } = await import("../engine/declaration-check.mjs");
+            const findings = checkDeclarations(args.project, { exports: args.exports }).map(
+                (finding) => ({
+                    ...finding,
+                    file: path.relative(process.cwd(), finding.file),
+                }),
+            );
+            if (reportFindings(findings, {}) > 0) process.exitCode = 1;
+            else console.log("Package declarations are valid.");
+        }),
+    };
+}
+
+/** Check project declaration files. */
+function typesCommand() {
+    return {
+        command: "types <action>",
+        describe: "Check TypeScript declarations",
+        builder: (yargs) => yargs.command(typesCheckCommand()).demandCommand(1).strict(),
+        handler: () => {},
+    };
 }
 
 /**
  * `schema` — publish this package's DataModel field sets as `schema.json`.
  *
- * The producing half of the check `content-build lint` runs: Foundry discards
+ * The producing half of the check `package-build lint` runs: Foundry discards
  * an unknown `system` key at construction and says nothing, so a content build
  * needs to know what a document will actually receive. It cannot ask a
  * running Foundry, and it cannot read `defineSchema()` from a sibling checkout,
@@ -447,7 +708,7 @@ function manifestCommand() {
                 die(
                     `\`packageKind: ${shared.packageKind}\` ships no Foundry ` +
                         `package, so there is no manifest to generate. The site ` +
-                        `and the book are built by \`content-build\`.`,
+                        `and the book are built by \`package-build\`.`,
                 );
             }
             const packageJson = readPackageJson(config);
@@ -1406,27 +1667,39 @@ function bumpCommand() {
     };
 }
 
-yargs(hideBin(process.argv))
-    .scriptName("package-build")
-    .command(cleanCommand())
-    .command(assetsCommand())
-    .command(calendarsCommand())
-    .command(manifestCommand())
-    .command(siteRootCommand())
-    .command(schemaCommand())
-    .command(langCommand())
-    .command(labelsCommand())
-    .command(bumpCommand())
-    .command(yamlCommand())
-    .command(changelogCommand())
-    .command(bundleCommand())
-    .command(releaseCommand())
-    .command(deployCommand())
-    .command(containerCommand())
-    .command(e2eCommand())
+registerContentCommands(
+    yargs(hideBin(process.argv))
+        .scriptName("package-build")
+        .command(initCommand())
+        .command(ciCommand())
+        .command(cleanCommand())
+        .command(assetsCommand())
+        .command(stageCommand())
+        .command(calendarsCommand())
+        .command(datefromCommand())
+        .command(datetoCommand())
+        .command(manifestCommand())
+        .command(siteRootCommand())
+        .command(typesCommand())
+        .command(schemaCommand())
+        .command(langCommand())
+        .command(labelsCommand())
+        .command(bumpCommand())
+        .command(yamlCommand())
+        .command(changelogCommand())
+        .command(bundleCommand())
+        .command(releaseCommand())
+        .command(deployCommand())
+        .command(containerCommand())
+        .command(e2eCommand()),
+)
     .demandCommand(1, "Name a command.")
     .strict()
     .version(ownVersion())
     .help()
     .alias("help", "h")
-    .fail((message, err) => die(err ?? message)).argv;
+    .epilog("Run package-build <command> --help for that command's actions and options.")
+    .fail((message, err, cli) => {
+        if (!err) cli.showHelp("error");
+        die(err ?? message);
+    }).argv;

package/bin/report.mjs

@@ -104,7 +104,7 @@ export function toDiagnostics(findings, { file }) {
  *   Optional only when every finding carries its own.
  * @param {(d: object) => void} [opts.emit] - How to emit one diagnostic.
  *   Injectable so a test can capture the emitted shape without reaching for
- *   the console; defaults to content-build's `emitDiagnostic`, which writes
+ *   the console; defaults to package-build's `emitDiagnostic`, which writes
  *   both severities to stderr.
  * @returns {number} How many diagnostics were errors — the count a command
  *   turns into its exit code.

package/ci/ci-docker.mjs

@@ -194,7 +194,7 @@ function main() {
         "--rm",
         ...(native ? [] : ["--platform", "linux/amd64"]),
         "-v",
-        `${dir}:/work`,
+        `${dir}:/source:ro`,
         // The step runner comes from this package, not from the export: the
         // repository under test does not carry it, and should not have to.
         "-v",
@@ -202,8 +202,11 @@ function main() {
         "-w",
         "/work",
         image,
-        "node",
-        "/ci/ci-steps.mjs",
+        "sh",
+        "-c",
+        // Run from the container's own filesystem. Some generators create
+        // files that Docker Desktop cannot read back through a macOS mount.
+        "mkdir -p /work && cp -a /source/. /work && exec node /ci/ci-steps.mjs",
     ]);
 
     fs.rmSync(dir, { recursive: true, force: true });

package/ci/ci-steps.mjs

@@ -69,8 +69,8 @@ const WORKFLOW_DIR = path.join(ROOT, ".github/workflows");
 /**
  * The workflow's steps, split into what can be run here and what cannot.
  *
- * @returns {{run: Array<{name: string, run: string}>, skipped: string[]}} The
- *   `run:` steps in workflow order, and the names of the `uses:` steps.
+ * @returns {{run: Array<{name: string, run: string}>, skipped: string[], files: string[]}}
+ *   Workflow files, their `run:` steps in order, and the `uses:` step names.
  * @throws {Error} When the workflow cannot be read or declares no `run:` step.
  */
 export function ciSteps() {
@@ -213,8 +213,10 @@ function main() {
         return 1;
     }
 
-    const { run, skipped } = steps;
-    console.log(`ci-steps: running ${run.length} step(s) from .github/workflows/build.yml`);
+    const { run, skipped, files } = steps;
+    console.log(
+        `ci-steps: running ${run.length} step(s) from ${files.map((file) => path.relative(ROOT, file)).join(", ")}`,
+    );
     if (skipped.length) {
         console.log(`ci-steps: not runnable here (published actions): ${skipped.join(", ")}`);
     }

package/ci/content-format-reference.mjs

@@ -0,0 +1,106 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { formatGenerated } from "../engine/format-generated.mjs";
+import { loadContentFormat } from "../engine/content-format.mjs";
+import { NOTE_VOCABULARY, SHARED_DATA_FIELDS } from "../engine/note-vocabulary.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const output = path.join(root, "docs/reference/note-types.md");
+const contract = loadContentFormat();
+const cell = (value) =>
+    String(value ?? "")
+        .replaceAll("|", "\\|")
+        .replaceAll("\n", " ");
+const fields = (list) =>
+    list.map(
+        (field) =>
+            `| \`data.${cell(field.name)}\` | ${cell(field.shape ?? field.kind ?? "value")} | ${cell(field.describe)} |`,
+    );
+const rows = [
+    "---",
+    "shortcode: referencenotetypes",
+    'name: { full: "Note types and fields" }',
+    "type: doc",
+    "subType: reference",
+    "---",
+    "",
+    "# Note types and fields",
+    "",
+    "Choose a note's `type` for the subject it describes. Use `subType` when its type declares a more specific genre. Field rules are declared in `engine/note-vocabulary.mjs`; mapping claims and closed vocabularies are recorded in `engine/content-format.yaml`. This page is checked against both declarations.",
+    "",
+    "The [first-note guide](../authoring/first-note.md) teaches the shape of a note. [Frontmatter](../authoring/frontmatter.md) explains shared and system-specific values. The [detailed reference](format-details.md) gives the full behavior and examples.",
+    "",
+    "## Shared `data` fields",
+    "",
+    "These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can.",
+    "",
+    "| Field | Shape | Meaning |",
+    "| --- | --- | --- |",
+    ...fields(SHARED_DATA_FIELDS),
+    "",
+    "## Type-specific fields",
+    "",
+];
+for (const [type, spec] of contract.types) {
+    const declared = NOTE_VOCABULARY[type];
+    if (!declared) throw new Error(`No vocabulary for ${type}`);
+    rows.push(`### ${type}`, "");
+    rows.push(
+        `**Subtypes:** ${
+            declared.subTypes === null ? "Open vocabulary"
+            : spec.subTypes.length ? spec.subTypes.map((value) => `\`${value}\``).join(", ")
+            : "None"
+        }.`,
+        "",
+    );
+    if (type === "lore") {
+        rows.push(
+            "Lore records in-world knowledge. A `culture` describes a people; a `custom` describes how they practice a rite, observance, or usage. A `material` describes a physical constituent and its qualities, which may vary by region. See the [lore subtype definitions](format-details.md#type-lore) for the complete vocabulary.",
+            "",
+        );
+    }
+    rows.push("| Field | Shape | Meaning |", "| --- | --- | --- |");
+    rows.push(
+        ...(declared.data?.length ?
+            fields(declared.data)
+        :   ["| — | — | No type-specific `data` fields. |"]),
+    );
+    rows.push("");
+    const claims = contract.claims.filter((claim) => !claim.shared && claim.noteType === type);
+    if (claims.length) {
+        rows.push("**System mappings**", "", "| Source | System | Target |", "| --- | --- | --- |");
+        rows.push(
+            ...claims.map(
+                (claim) =>
+                    `| \`${cell(claim.source)}\` | ${cell(claim.system)} | \`${cell(claim.target)}\` |`,
+            ),
+        );
+        rows.push("");
+    }
+}
+rows.push("## Shared system mappings", "", "| Source | System | Target |", "| --- | --- | --- |");
+rows.push(
+    ...contract.claims
+        .filter((claim) => claim.shared)
+        .map(
+            (claim) =>
+                `| \`${cell(claim.source)}\` | ${cell(claim.system)} | \`${cell(claim.target)}\` |`,
+        ),
+);
+rows.push("");
+const result = await formatGenerated(`${rows.join("\n")}\n`, output);
+if (process.argv.includes("--check")) {
+    if (!fs.existsSync(output) || fs.readFileSync(output, "utf8") !== result) {
+        console.error(
+            `${path.relative(root, output)}: error: run node ci/content-format-reference.mjs to refresh the note-type reference`,
+        );
+        process.exitCode = 1;
+    }
+} else {
+    process.stdout.write(result);
+}

package/config.mjs

@@ -75,6 +75,7 @@ const SECTION_KEYS = [
     "bundle",
     "container",
     "e2e",
+    "proseLint",
 ];
 
 /**
@@ -526,7 +527,8 @@ function normalizeExceptions(value, field, where) {
  * The resolved `packageBuild` section, every optional half filled in.
  *
  * @typedef {object} PackageBuildConfig
- * @property {string} rootDir        The repository root, from content-build.
+ * @property {string} rootDir        The repository root, from package-build.
+ * @property {{age: number, threshold: number, minWords: number}} proseLint Optional prose analysis settings.
  * @property {string} packageKind    `systems` or `modules`.
  * @property {string} packageId      The Foundry package id.
  * @property {string} artifact       Derived: `system` or `module`.
@@ -689,6 +691,23 @@ export function resolvePackageBuildConfig(shared) {
     const section = /** @type {Record<string, unknown>} */ (shared.packageBuild ?? {});
     rejectUnknownKeys(section, SECTION_KEYS, "packageBuild.");
 
+    const proseLint = section.proseLint ?? {};
+    if (!isMapping(proseLint)) fail("packageBuild.proseLint", "must be a mapping");
+    rejectUnknownKeys(proseLint, ["age", "threshold", "minWords"], "packageBuild.proseLint.");
+    const proseOptions = { age: 21, threshold: 5, minWords: 8 };
+    for (const [key, value] of Object.entries(proseLint)) {
+        const upper = key === "threshold" ? 7 : Infinity;
+        if (!Number.isInteger(value) || value < 1 || value > upper) {
+            fail(
+                `packageBuild.proseLint.${key}`,
+                upper === Infinity ?
+                    "must be a positive integer"
+                :   "must be an integer from 1 to 7",
+            );
+        }
+        proseOptions[key] = value;
+    }
+
     if (section.assets !== undefined && !Array.isArray(section.assets)) {
         fail("packageBuild.assets", "must be a list");
     }
@@ -789,6 +808,7 @@ export function resolvePackageBuildConfig(shared) {
 
     return Object.freeze({
         rootDir: shared.rootDir,
+        proseLint: Object.freeze(proseOptions),
         // Where the package is assembled before it is zipped or deployed. Every
         // asset destination is relative to it, so a repository's table says
         // `lang`, not `build/stage/lang` — the latter is what each consumer's
@@ -921,7 +941,7 @@ export function resolvePackageBuildConfig(shared) {
 /**
  * The repository's resolved package-build configuration.
  *
- * Read on call rather than at import, exactly as content-build resolves its
+ * Read on call rather than at import, exactly as package-build resolves its
  * own: importing a module of this package must not require a configuration to
  * exist anywhere above it.
  *