@heroiclands/package-build 20.4.0 → 20.6.0

package/bin/content-build.mjs

@@ -63,7 +63,9 @@ 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 { buildPdf } from "../engine/pdf-build.mjs";
 import {
     fetchAllCatalogs,
     fetchCatalogFromPath,
@@ -245,6 +247,7 @@ const argv = yargs(hideBin(process.argv))
     .command(markdownCommand())
     .command(contentIndexCommand())
     .command(siteCommand())
+    .command(pdfCommand())
     .command(reachabilityCommand())
     .command(addressesCommand())
     .version(ownVersion())
@@ -349,13 +352,19 @@ function docsCommand() {
                     if (current !== page) {
                         // Staleness belongs to the whole file, so no line is
                         // named — the diagnostics contract drops a field it
-                        // cannot supply rather than guessing one.
-                        log.error(
-                            `${relative}: error: out of date with the ` +
-                                `item-field declarations — run ` +
-                                `\`content-build docs item-fields\` and commit ` +
-                                `the regenerated file`,
-                        );
+                        // cannot supply rather than guessing one. Routed
+                        // through `emitDiagnostic`, not `log.error`, so the
+                        // path starts the line unprefixed by loglevel's
+                        // `[timestamp] [ERROR]:` banner — the same reason
+                        // every other located failure in this file uses it.
+                        emitDiagnostic({
+                            file: relative,
+                            severity: "error",
+                            message:
+                                "out of date with the item-field declarations " +
+                                "— run `content-build docs item-fields` and " +
+                                "commit the regenerated file",
+                        });
                         process.exitCode = 1;
                         return;
                     }
@@ -1363,6 +1372,87 @@ function contentIndexCommand() {
     };
 }
 
+/**
+ * `content-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
+ * `file:line:column: severity: message` shape every other pass here uses — so
+ * one editor, one CI annotator and one `grep` read all three.
+ *
+ * **Not building is a normal outcome, and it exits 0.** A package publishing
+ * only a homepage, a package with no `pdf:` block and a package with no content
+ * tree have each said they publish no book; saying so on stderr and failing the
+ * command would break the release of every package that is not a book.
+ *
+ * @returns {object} The yargs command module.
+ */
+function pdfCommand() {
+    return {
+        command: "pdf",
+        describe: "Build the content tree as a PDF",
+        builder: (yargs) => {
+            yargs
+                .option("out", {
+                    describe: "Write the book here instead of the configured `pdf.out`.",
+                    type: "string",
+                })
+                .option("book-version", {
+                    describe: "Stamp this version on the title page and in the file name.",
+                    type: "string",
+                })
+                // Declared positively so yargs derives `--no-compile` from it;
+                // an option literally named `no-compile` is rejected as unknown
+                // when it is actually passed.
+                .option("compile", {
+                    describe: "Run the Typst compiler. `--no-compile` emits the source and stops.",
+                    type: "boolean",
+                    default: true,
+                });
+        },
+        handler: async (argv) => {
+            try {
+                const result = await buildPdf({
+                    ...(argv.out ? { out: argv.out } : {}),
+                    ...(argv.bookVersion ? { version: String(argv.bookVersion) } : {}),
+                    compile: argv.compile !== false,
+                });
+
+                for (const finding of result.findings) emitDiagnostic(finding);
+
+                if (!result.built) {
+                    // A reason is a deliberate no-op — the fence, an absent
+                    // block, an absent tree. No reason means the findings above
+                    // say what went wrong, and those decide the exit code.
+                    if (result.reason) {
+                        log.info(`No book built: ${result.reason}`);
+                        return;
+                    }
+                    process.exitCode = 1;
+                    return;
+                }
+
+                const { stats } = result;
+                log.info(
+                    `${stats.notes} entr(ies) and ${stats.prose} prose file(s) across ` +
+                        `${stats.sections} section(s)` +
+                        (stats.repeated ?
+                            `, ${stats.repeated} of them printed more than once`
+                        :   ""),
+                );
+                log.info(`Typst source: ${result.typ}`);
+                if (result.pdf) log.info(`Book: ${result.pdf}`);
+                // Findings are reported, never fatal — a filter that selected
+                // nothing is worth fixing and is not worth refusing to publish
+                // the other two thousand entries over.
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
 /**
  * `content-build site` — publish the content tree as a website.
  *
@@ -1611,30 +1701,6 @@ function reachabilityCommand() {
 }
 
 // eslint-disable-next-line
-/**
- * `deps fetch` — fill the caches this build resolves other packages through:
- * the **content index** of every declared dependency, and the **item
- * catalogue** of those additionally declaring `itemCatalog: true`.
- *
- * The two sets differ deliberately. Citing another package's *addresses* and
- * embedding its *items* are separate edges, and a package may have either
- * without the other — `harn-ensemble` cites no foreign address and embeds
- * 324,016 item references.
- *
- * Its own command rather than a step of `package compile`, so that a compile
- * never reaches the network. A build that downloads silently is not
- * reproducible, breaks offline, and hides a dependency's version change behind
- * a passing run.
- *
- * `--from` fills the cache from a locally built artifact instead of a release,
- * which is what makes iterating across packages possible: change the system,
- * build it, and see the effect on every consumer **before** any of it ships.
- * Otherwise testing a dependency change against its consumers costs a release
- * round-trip, which makes releasing a debugging tool rather than a publishing
- * decision.
- *
- * @returns {object} The yargs command module.
- */
 /**
  * Resolve which declared dependency `--from` supplies, and cache it.
  *
@@ -1668,6 +1734,30 @@ async function fetchFromLocalArtifact(config, argv) {
     }
 }
 
+/**
+ * `deps fetch` — fill the caches this build resolves other packages through:
+ * the **content index** of every declared dependency, and the **item
+ * catalogue** of those additionally declaring `itemCatalog: true`.
+ *
+ * The two sets differ deliberately. Citing another package's *addresses* and
+ * embedding its *items* are separate edges, and a package may have either
+ * without the other — `harn-ensemble` cites no foreign address and embeds
+ * 324,016 item references.
+ *
+ * Its own command rather than a step of `package compile`, so that a compile
+ * never reaches the network. A build that downloads silently is not
+ * reproducible, breaks offline, and hides a dependency's version change behind
+ * a passing run.
+ *
+ * `--from` fills the cache from a locally built artifact instead of a release,
+ * which is what makes iterating across packages possible: change the system,
+ * build it, and see the effect on every consumer **before** any of it ships.
+ * Otherwise testing a dependency change against its consumers costs a release
+ * round-trip, which makes releasing a debugging tool rather than a publishing
+ * decision.
+ *
+ * @returns {object} The yargs command module.
+ */
 function depsCommand() {
     return {
         command: "deps <action>",
@@ -1906,11 +1996,24 @@ function packageCommand() {
             // an unhandled-rejection stack trace. Report the message and set a
             // failing exit code, so a build guard reads as a build failure.
             try {
+                const config = loadPackConfig();
+                // The compile passes do not run for a package that declares no
+                // packs by rule. Refused rather than exiting 0 having compiled
+                // nothing: a build that succeeds and produces no documents is
+                // the quiet failure this toolchain reports everywhere else.
+                if (!compilesFoundryDocuments(config)) {
+                    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\`.`,
+                    );
+                }
                 // The one directory the pipeline creates rather than expects:
                 // `unpack` writes the extracted JSON there and `compile` reads
                 // it back. Created here rather than at module scope so that
                 // asking the CLI its version needs no configuration (#2).
-                fs.mkdirSync(loadPackConfig().paths.unpack, {
+                fs.mkdirSync(config.paths.unpack, {
                     recursive: true,
                 });
                 switch (action) {

package/bin/package-build.mjs

@@ -78,6 +78,7 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
+import { compilesFoundryDocuments } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
@@ -413,6 +414,18 @@ function manifestCommand() {
         handler: handler(async () => {
             const config = loadPackageBuildConfig();
             const shared = loadPackConfig();
+            // Refused rather than written: a manifest is the file Foundry reads
+            // to install a package, and a documentation package is not one. An
+            // emitted `module.json` would advertise an installable package with
+            // no packs, no compatibility range and no id — the plausible lie
+            // this toolchain refuses everywhere else.
+            if (!compilesFoundryDocuments(shared)) {
+                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\`.`,
+                );
+            }
             const packageJson = readPackageJson(config);
 
             let flags;
@@ -704,16 +717,6 @@ function langHardcoded(config) {
     );
 }
 
-/**
- * `lang <action>` — the three localization guards.
- *
- * They are three questions about one subject, and each is blind to what the
- * others see: `check` asks whether the file will load at all, `coverage`
- * whether the keys and the code agree, `hardcoded` whether the markup ever
- * asks for a key in the first place.
- *
- * @returns {object} The yargs command module.
- */
 /**
  * `package-build yaml` — lint note frontmatter and every YAML file.
  *
@@ -826,6 +829,16 @@ function labelsCheck(args) {
     console.log(`package-build: registry and §3 agree (${count} labels).`);
 }
 
+/**
+ * `lang <action>` — the three localization guards.
+ *
+ * They are three questions about one subject, and each is blind to what the
+ * others see: `check` asks whether the file will load at all, `coverage`
+ * whether the keys and the code agree, `hardcoded` whether the markup ever
+ * asks for a key in the first place.
+ *
+ * @returns {object} The yargs command module.
+ */
 function langCommand() {
     return {
         command: "lang <action>",
@@ -931,17 +944,37 @@ function releaseCommand() {
     return {
         command: "release",
         describe: "Package the staged build for release",
-        builder: (y) => y,
-        handler: handler(async () => {
+        builder: (y) =>
+            y.option("no-pdf", {
+                describe:
+                    "Skip the content-tree book. A package that publishes no content " +
+                    "already builds none; this is for a release that has a tree and " +
+                    "does not want the book.",
+                type: "boolean",
+            }),
+        handler: handler(async (argv) => {
             const config = loadPackageBuildConfig();
-            const { zip, version, bytes } = await packRelease({
+            const result = await packRelease({
                 artifact: config.artifact,
+                pdf: argv.pdf !== false,
             });
+            const { zip, version, bytes } = result;
             console.log(
                 `✅ Packaged ${version} for release: ` +
                     `${path.relative(config.rootDir, zip)} ` +
                     `(${(bytes / 1024 / 1024).toFixed(1)} MB)`,
             );
+            // Reported, never fatal: the archive above is the release, and a
+            // book that would not set is a problem to fix rather than a reason
+            // to have published nothing.
+            for (const finding of result.pdfFindings ?? []) {
+                console.error(`${finding.file ?? "book"}: ${finding.severity}: ${finding.message}`);
+            }
+            if (result.pdf) {
+                console.log(`📕 Book: ${path.relative(config.rootDir, result.pdf)}`);
+            } else if (result.pdfSkipped) {
+                console.log(`   No book: ${result.pdfSkipped}`);
+            }
         }),
     };
 }