@heroiclands/package-build 9.0.0 → 10.0.1

package/bin/content-build.mjs

@@ -39,6 +39,9 @@
  *   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]
@@ -69,6 +72,12 @@ import {
 import { renderItemFieldReference } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
+import { loadContentFormat } from "../engine/content-format.mjs";
+import {
+    checkDeclaredFields,
+    checkSchemaTargets,
+    measureCorpus,
+} from "../engine/content-format-check.mjs";
 import {
     compareFields,
     resolveSchemaArtifact,
@@ -79,9 +88,13 @@ import {
 // set — an adventure module ships skills, beings and magic swords — so no
 // consumer gets a subset (#19, #20).
 import { NOTE_SCHEMAS } from "../sohl/note-schemas.mjs";
+// The shipped declarations, so this repository can check its own specification
+// against them without standing up a consumer's configuration (#136).
+import { ITEM_FIELDS } from "../sohl/item-fields.mjs";
 // The engine's own types, merged under the registry's so the vocabulary stands
 // in a package that configures no `itemBuilders` at all (#51).
 import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
+import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { checkFormatting, lintMarkdown } from "../engine/prose-lint.mjs";
 import { emitLinkManifest } from "../engine/manifest-emit.mjs";
 import {
@@ -90,7 +103,12 @@ import {
     formatUnaddressableFinding as formatUnaddressable,
 } from "../engine/site-build.mjs";
 import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
-import { emitDiagnostic, positionOfLiteral } from "../engine/diagnostics.mjs";
+import {
+    emitDiagnostic,
+    positionInFrontmatter,
+    positionOfLiteral,
+} from "../engine/diagnostics.mjs";
+import { reportFindings } from "./report.mjs";
 import {
     readItemAddresses,
     diffItemAddresses,
@@ -99,6 +117,7 @@ import {
     addressFindingMessage,
 } from "../engine/address-diff.mjs";
 import { itemPackJsonDirs } from "../engine/generate.mjs";
+import { walkMarkdownTree } from "../engine/helpers.mjs";
 import {
     formatUnaddressableFinding,
     unaddressableForeignPackages,
@@ -170,11 +189,19 @@ function reportFailure(err) {
     else log.error(message);
 }
 
+/**
+ * The declaration sets this package ships, addressable by system id.
+ *
+ * @type {Record<string, Record<string, readonly object[]>>}
+ */
+const SHIPPED_ITEM_FIELDS = { sohl: ITEM_FIELDS };
+
 const argv = yargs(hideBin(process.argv))
     .command(packageCommand())
     .command(depsCommand())
     .command(docsCommand())
     .command(lintCommand())
+    .command(contentFormatCommand())
     .command(linksCommand())
     .command(formatCommand())
     .command(markdownCommand())
@@ -315,6 +342,319 @@ function docsCommand() {
     };
 }
 
+/**
+ * `content-build content-format` — check the format specification itself (#130).
+ *
+ * Two checks, because the specification makes claims about two different
+ * worlds, and they fail for different reasons and at different times:
+ *
+ * - `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
+ *   (#136).
+ * - `notes` measures a content tree against the vocabulary the document
+ *   declares per type. During #127 it is the migration's 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.
+ *
+ * Both read the committed document rather than a transcription of it, so
+ * editing `docs/content-format.md` changes what they assert.
+ *
+ * @returns {object} The yargs command module.
+ */
+// eslint-disable-next-line
+function contentFormatCommand() {
+    return {
+        command: "content-format <action>",
+        describe: "Check the content format specification against schemas and notes",
+        builder: (yargs) =>
+            yargs
+                .command(contentFormatSchemaCommand())
+                .command(contentFormatFieldsCommand())
+                .command(contentFormatNotesCommand())
+                .demandCommand(1, "Name an action.")
+                .strict(),
+        handler: () => {},
+    };
+}
+
+/**
+ * The parsed specification a `content-format` action should read.
+ *
+ * @param {object} argv - The parsed command line.
+ * @returns {import("../engine/content-format.mjs").ContentFormat} The document.
+ */
+function specFrom(argv) {
+    return argv.spec ? loadContentFormat(path.resolve(argv.spec)) : loadContentFormat();
+}
+
+/**
+ * `content-format schema` — every `system.*` target, against a published schema.
+ *
+ * The schemas are named on the command line as `<system>=<path>`, because a
+ * consumer holds one and this repository holds a committed fixture, and neither
+ * arrangement should be the one the other has to pretend to. A system the
+ * document maps onto but no schema was supplied for is reported as unchecked —
+ * HM3 publishes no artifact today, so that is the ordinary case for a fifth of
+ * the claims, and a check that quietly skipped them would read as one that
+ * passed.
+ *
+ * @returns {object} The yargs command module.
+ */
+function contentFormatSchemaCommand() {
+    return {
+        command: "schema",
+        describe: "Check every `system.*` target the format names against a published schema.json",
+        builder: (yargs) => {
+            yargs.option("spec", {
+                describe:
+                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                type: "string",
+            });
+            yargs.option("schema", {
+                describe:
+                    "A published schema, as `<system>=<path>`. Repeatable; a system with none is reported unchecked.",
+                type: "string",
+                array: true,
+                demandOption: true,
+            });
+        },
+        handler: (argv) => {
+            try {
+                const format = specFrom(argv);
+                /** @type {Record<string, object>} */
+                const schemas = {};
+                for (const entry of argv.schema) {
+                    const at = String(entry).indexOf("=");
+                    if (at <= 0) {
+                        log.error(`--schema takes \`<system>=<path>\`, not "${entry}".`);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    const system = entry.slice(0, at);
+                    const file = path.resolve(entry.slice(at + 1));
+                    schemas[system] = JSON.parse(fs.readFileSync(file, "utf8"));
+                }
+
+                const { findings, checked, unchecked } = checkSchemaTargets({ format, schemas });
+                for (const finding of findings) emitDiagnostic(finding);
+                for (const [system, count] of Object.entries(unchecked)) {
+                    log.info(
+                        `${count} claim(s) about ${system} are unchecked — no ` +
+                            `schema was supplied for it, so nothing here confirms them.`,
+                    );
+                }
+                if (findings.length) {
+                    log.error(
+                        `${findings.length} of ${checked} checked claim(s) name a ` +
+                            `field no schema declares.`,
+                    );
+                    process.exitCode = 1;
+                } else {
+                    log.info(`${checked} mapping claim(s) confirmed against the supplied schemas.`);
+                }
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
+/**
+ * The field declarations a `content-format fields` run should compare against.
+ *
+ * Either this package's own shipped registry, named on the command line, or the
+ * consuming repository's resolved configuration. Both are real arrangements and
+ * neither should have to pretend to be the other: this repository ships the
+ * specification *and* the SoHL declarations and configures no content tree,
+ * while a consumer configures `itemBuilders` and resolves the specification
+ * from its toolchain.
+ *
+ * @param {object} argv - The parsed command line.
+ * @returns {{itemFields: Record<string, readonly object[]>, system: string}}
+ *   The declarations, and the system column of the mapping tables they compile.
+ */
+function declarationsFrom(argv) {
+    if (argv.fields) return { itemFields: SHIPPED_ITEM_FIELDS[argv.fields], system: argv.fields };
+    const config = loadPackConfig();
+    const system = config.stats?.systemId;
+    if (!system) {
+        throw new Error(
+            "package-build: this repository's configuration names no system, so " +
+                "nothing says which column of the format's mapping tables its " +
+                "`itemBuilders` declarations compile. Name a shipped set with " +
+                "`--fields <system>` instead.",
+        );
+    }
+    return { itemFields: config.itemFields ?? {}, system };
+}
+
+/**
+ * `content-format fields` — the per-type tables, against the declarations.
+ *
+ * The specification hand-writes a `data` table under most of its type sections,
+ * covering ground {@link module:engine/field-reference} already generates from
+ * the `fields` on each `itemBuilders` entry — the duplication that module exists
+ * to prevent, one document over (#136).
+ *
+ * **Checked, not merged.** The document's vocabulary spans note types that
+ * produce Scenes, Macros and JournalEntries, which no item registry covers, so
+ * there is no wholesale generation to fall back on. What the two *can* be held
+ * to is agreement where they both speak: a mapping row saying `data.weight`
+ * reaches `system.weightBase` and a declaration writing `weight` to `weightBase`
+ * are one statement made twice, and a rename that moves only one of them is a
+ * defect. A type only one side describes is named as out of reach rather than
+ * skipped in silence.
+ *
+ * @returns {object} The yargs command module.
+ */
+function contentFormatFieldsCommand() {
+    return {
+        command: "fields",
+        describe: "Check the format's per-type tables against the field declarations",
+        builder: (yargs) => {
+            yargs.option("spec", {
+                describe:
+                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                type: "string",
+            });
+            yargs.option("fields", {
+                describe:
+                    "A declaration set this package ships, by system id. Defaults to the consuming repository's own `itemBuilders`.",
+                type: "string",
+                choices: Object.keys(SHIPPED_ITEM_FIELDS),
+            });
+            yargs.option("coverage", {
+                describe:
+                    "List, per type, the fields only one side names. They are not findings — the two vocabularies differ by design until #127 lands.",
+                type: "boolean",
+                default: false,
+            });
+        },
+        handler: (argv) => {
+            try {
+                const format = specFrom(argv);
+                const { itemFields, system } = declarationsFrom(argv);
+                const result = checkDeclaredFields({ format, itemFields, system });
+                for (const finding of result.findings) emitDiagnostic(finding);
+
+                // Named rather than left implicit: a check that silently
+                // compared nine of twenty-two types would read as one that
+                // covered them all.
+                log.info(
+                    `${result.checked.length} type(s) compared against ${system}'s ` +
+                        `declarations (${result.fields} field pair(s)).`,
+                );
+                log.info(
+                    `${result.skipped.spec.length} type(s) the format declares are ` +
+                        `out of reach — no \`itemBuilders\` entry covers them: ` +
+                        `${result.skipped.spec.join(", ")}.`,
+                );
+                if (result.skipped.registry.length) {
+                    log.info(
+                        `${result.skipped.registry.length} declared type(s) the ` +
+                            `format names no section for: ` +
+                            `${result.skipped.registry.join(", ")}.`,
+                    );
+                }
+                if (argv.coverage) {
+                    for (const entry of result.coverage) {
+                        log.info(
+                            `${entry.type}: format only [${entry.specOnly.join(", ")}], ` +
+                                `declaration only [${entry.registryOnly.join(", ")}]`,
+                        );
+                    }
+                }
+
+                if (result.findings.length) {
+                    log.error(
+                        `${result.findings.length} of ${result.fields} compared field ` +
+                            `pair(s) disagree between the specification and the ` +
+                            `declaration that compiles them.`,
+                    );
+                    process.exitCode = 1;
+                }
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
+/**
+ * `content-format notes` — a content tree, against the declared vocabulary.
+ *
+ * **A report, not a gate.** Every authored note predates the format, so a
+ * failing check would be red in every repository from the day it lands and
+ * would stay red for the length of #127 — which is a check nobody can act on.
+ * `--strict` raises the findings to errors, and #127 turns it on slice by
+ * slice as each class of finding reaches zero.
+ *
+ * @returns {object} The yargs command module.
+ */
+function contentFormatNotesCommand() {
+    return {
+        command: "notes [root]",
+        describe: "Measure a content tree against the vocabulary the format declares (a report)",
+        builder: (yargs) => {
+            yargs.positional("root", {
+                describe: "Content tree to measure. Defaults to the configured contentBase.",
+                type: "string",
+            });
+            yargs.option("spec", {
+                describe:
+                    "The specification to read. Defaults to the docs/content-format.md this package ships.",
+                type: "string",
+            });
+            yargs.option("strict", {
+                describe:
+                    "Fail on the findings instead of reporting them. Turned on per slice of #127, as each class reaches zero.",
+                type: "boolean",
+                default: false,
+            });
+        },
+        handler: (argv) => {
+            try {
+                const config = loadPackConfig();
+                const root = argv.root ?? config.paths.content;
+                const format = specFrom(argv);
+
+                const notes = [];
+                for (const { frontmatter, absPath } of walkMarkdownTree(root, {
+                    skipDirectories: config.skipDirectories,
+                })) {
+                    if (!frontmatter || typeof frontmatter.type !== "string") continue;
+                    notes.push({
+                        file: absPath,
+                        fm: frontmatter,
+                        raw: fs.readFileSync(absPath, "utf8"),
+                    });
+                }
+
+                const { findings, byClass } = measureCorpus(notes, format, {
+                    strict: argv.strict,
+                });
+                for (const finding of findings) emitDiagnostic(finding);
+
+                const counts = Object.entries(byClass).sort(([a], [b]) => (a < b ? -1 : 1));
+                for (const [cls, count] of counts) log.info(`${cls}: ${count}`);
+                log.info(
+                    `${findings.length} finding(s) across ${notes.length} note(s) ` +
+                        `measured against ${format.file}.`,
+                );
+                if (argv.strict && findings.length) process.exitCode = 1;
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
 /**
  * `content-build lint` — check a content tree's addresses.
  *
@@ -368,6 +708,11 @@ function lintCommand() {
                 });
                 const frontmatter = lintFrontmatter(index, {
                     schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
+                    // The closed frontmatter regions (#128). Passed in rather
+                    // than reached for, so the linter stays a checker of
+                    // whatever it is handed and this stays the one place that
+                    // decides which vocabulary a tree is held to.
+                    vocabulary: NOTE_VOCABULARY,
                     references: argv.references,
                 });
 
@@ -445,10 +790,23 @@ function lintCommand() {
                     ...frontmatter.findings,
                     ...schemaFindings,
                 ];
-                for (const finding of findings) emitDiagnostic(finding);
-                if (findings.length) {
+                // Only an **error** fails the run. Every finding was an error
+                // until #142, so this changed nothing on the day it landed —
+                // but a field retired in favour of another is reported while
+                // both spellings still compile, and failing a build over a note
+                // that produces the correct document would red a tree that has
+                // done nothing wrong. `reportFindings` already draws exactly
+                // that line, so the rule is the shared one rather than a second
+                // copy here. Each finding names its own file.
+                const errors = reportFindings(findings, {});
+                if (errors) {
                     log.error(`${findings.length} finding(s) across ${addresses.notes} note(s).`);
                     process.exitCode = 1;
+                } else if (findings.length) {
+                    log.warn(
+                        `${findings.length} advisory finding(s) across ` +
+                            `${addresses.notes} note(s); none fails the build.`,
+                    );
                 } else {
                     log.info(
                         `Addresses and frontmatter are well-formed ` +
@@ -521,6 +879,17 @@ function formatCommand() {
                             `Formatted ${written.length} of ${checked} file(s).`
                         :   `Already formatted (${checked} file(s)).`,
                     );
+                    // `--write` collects findings too — a file Prettier cannot
+                    // parse, or one that will not format to a fixpoint — and
+                    // used to discard them, so a run that had left files
+                    // unformatted still reported success and exited 0 (#125).
+                    for (const finding of findings) emitDiagnostic(finding);
+                    if (findings.length) {
+                        log.error(
+                            `${findings.length} of ${checked} file(s) could not be formatted.`,
+                        );
+                        process.exitCode = 1;
+                    }
                     return;
                 }
                 for (const finding of findings) emitDiagnostic(finding);
@@ -653,6 +1022,8 @@ function linksCommand() {
                 const {
                     deadAnchors,
                     deadAddresses,
+                    deadAliases,
+                    aliasCollisions,
                     frontmatterLinks,
                     homepageLinks,
                     usedManifest,
@@ -668,14 +1039,62 @@ function linksCommand() {
                             `heading in ${d.dest.rel} declares`,
                     });
                 }
+                // The pipe says the author meant an address (#131), so all
+                // three of these are errors — but they read differently
+                // because the corrections differ.
                 for (const d of deadAddresses) {
                     emitDiagnostic({
                         file: d.note.file,
                         ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
                         severity: "error",
-                        message: `dead address [[${d.target}]] — no document has that identity`,
+                        message:
+                            d.reason === "not-an-address" ?
+                                `"${d.target}" is written as an address — the ` +
+                                `"|" says so — but it is not one; write ` +
+                                `[[type-shortcode|Text]], or drop the "|" to ` +
+                                `name it as an alias within this note's type`
+                            : d.reason === "unknown-type" ?
+                                `address [[${d.target}]] names no known ` + `content type`
+                            :   `dead address [[${d.target}]] — no document ` + `has that identity`,
+                    });
+                }
+                // An alias that names nothing may be a worldbuilding
+                // placeholder — a long-standing convention in the setting
+                // trees — so it is reported and does not fail the build. The
+                // ambiguous case is the collision below, reported at its
+                // claimants rather than here.
+                for (const d of deadAliases) {
+                    emitDiagnostic({
+                        file: d.note.file,
+                        ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
+                        severity: "warning",
+                        message:
+                            d.ambiguous ?
+                                `alias [[${d.target}]] is claimed by ` +
+                                `${d.claimants.length} ${d.note.type} notes, ` +
+                                `so it names none of them; address the ` +
+                                `intended one as [[type-shortcode|Text]]`
+                            :   `unresolved alias [[${d.target}]] — no ` +
+                                `${d.note.type} note claims that name`,
                     });
                 }
+                // Reported once per claimant, at the claimant, because the
+                // note that merely cites an ambiguous alias is innocent (#13).
+                for (const c of aliasCollisions) {
+                    const others = c.claimants.map((n) => n.rel).join(", ");
+                    for (const claimant of c.claimants) {
+                        emitDiagnostic({
+                            file: claimant.file,
+                            ...positionInFrontmatter(claimant.raw, "aliases", c.alias),
+                            severity: "error",
+                            message:
+                                `alias "${c.alias}" is claimed by ` +
+                                `${c.claimants.length} ${c.type} notes ` +
+                                `(${others}), so [[${c.alias}]] names none of ` +
+                                `them; rename all but one`,
+                        });
+                    }
+                }
                 for (const f of frontmatterLinks) {
                     emitDiagnostic({
                         file: f.note.file,
@@ -700,9 +1119,12 @@ function linksCommand() {
                     });
                 }
 
+                // Warnings are reported and do not fail: a dead alias may be a
+                // note not yet written, which is the placeholder convention.
                 const failures =
                     deadAnchors.length +
                     deadAddresses.length +
+                    aliasCollisions.reduce((n, c) => n + c.claimants.length, 0) +
                     frontmatterLinks.length +
                     homepageLinks.length;
                 if (failures) {
@@ -711,10 +1133,18 @@ function linksCommand() {
                 } else {
                     log.info(
                         `${index.notes.length} notes: every anchor link lands ` +
-                            `and every qualified address resolves ` +
+                            `and every address resolves ` +
                             `(${usedManifest.size} cross-package reference(s) ` +
-                            `via manifest), no wikilink in frontmatter, ` +
-                            `every homepage address resolvable.`,
+                            `via manifest), no alias claimed twice, no ` +
+                            `wikilink in frontmatter, every homepage address ` +
+                            `resolvable.`,
+                    );
+                }
+                if (deadAliases.length) {
+                    log.warn(
+                        `${deadAliases.length} unresolved alias(es) — a bare ` +
+                            `[[Name]] naming no note may be a placeholder, so ` +
+                            `these are reported rather than failed.`,
                     );
                 }
             } catch (err) {