@heroiclands/package-build 17.1.0 → 18.0.0

package/bin/content-build.mjs

@@ -67,8 +67,16 @@ import { loadPackConfig } from "../engine/pack-config.mjs";
 import {
     fetchAllCatalogs,
     fetchCatalogFromPath,
+    fetchAllMetadata,
+    fetchMetadataFromPath,
     itemCatalogRelationships,
 } from "../engine/foreign-catalog.mjs";
+import {
+    metadataRelationships,
+    cachedIndexPath,
+    unaddressableForeignPackages,
+    formatUnaddressableFinding,
+} from "../engine/metadata-index.mjs";
 import { renderItemFieldReference } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
@@ -91,19 +99,27 @@ 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";
+import { HM3_ITEM_FIELDS } from "../hm3/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 { schemaSubtypeOf } from "../engine/subtype-registry.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 { emitContentIndex } from "../engine/content-index.mjs";
+import {
+    authoredFrontmatter,
+    emitContentIndex,
+    indexRecordsFor,
+    isNoteRecord,
+    noteFile,
+} from "../engine/content-index.mjs";
 import {
     buildSite,
     gatesFailed,
     formatUnaddressableFinding as formatUnaddressable,
 } from "../engine/site-build.mjs";
 import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
+import { prepareTreeSqlTables } from "../engine/sql-tables.mjs";
 // The one place a link finding is worded, shared with both builds (#184).
 import { linkFindingMessage } from "../engine/wikilink-syntax.mjs";
 import {
@@ -115,16 +131,12 @@ import { reportFindings } from "./report.mjs";
 import {
     readItemAddresses,
     diffItemAddresses,
+    declaredPredecessors,
     noteFilesById,
     locateAddressFinding,
     addressFindingMessage,
 } from "../engine/address-diff.mjs";
 import { itemPackJsonDirs } from "../engine/generate.mjs";
-import { walkMarkdownTree } from "../engine/helpers.mjs";
-import {
-    formatUnaddressableFinding,
-    unaddressableForeignPackages,
-} from "../engine/foreign-manifests.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -217,7 +229,7 @@ function readRawNote(file) {
  *
  * @type {Record<string, Record<string, readonly object[]>>}
  */
-const SHIPPED_ITEM_FIELDS = { sohl: ITEM_FIELDS };
+const SHIPPED_ITEM_FIELDS = { sohl: ITEM_FIELDS, hm3: HM3_ITEM_FIELDS };
 
 const argv = yargs(hideBin(process.argv))
     .command(packageCommand())
@@ -228,7 +240,6 @@ const argv = yargs(hideBin(process.argv))
     .command(linksCommand())
     .command(formatCommand())
     .command(markdownCommand())
-    .command(manifestCommand())
     .command(contentIndexCommand())
     .command(siteCommand())
     .command(reachabilityCommand())
@@ -647,14 +658,33 @@ function contentFormatNotesCommand() {
                 const root = argv.root ?? config.paths.content;
                 const format = specFrom(argv);
 
-                const notes = [];
-                for (const { frontmatter, absPath } of walkMarkdownTree(root, {
+                // The corpus from the index, like every other check (#243).
+                // A report measuring the tree against the declared vocabulary
+                // has to be looking at the same tree the compile will, or its
+                // counts describe a corpus nobody builds.
+                const corpusProblems = [];
+                const records = indexRecordsFor({
+                    contentBase: root,
+                    config,
                     skipDirectories: config.skipDirectories,
-                })) {
-                    if (!frontmatter || typeof frontmatter.type !== "string") continue;
+                    problems: corpusProblems,
+                });
+                for (const problem of corpusProblems) emitDiagnostic(problem);
+                if (corpusProblems.length) process.exitCode = 1;
+
+                const notes = [];
+                for (const record of records) {
+                    // A documentation journal is a document this tree emits,
+                    // not a note in it, and has no authored frontmatter to
+                    // measure.
+                    if (!isNoteRecord(record) || typeof record.type !== "string") continue;
+                    const absPath = noteFile(root, record);
                     notes.push({
                         file: absPath,
-                        fm: frontmatter,
+                        // What the author wrote, never the keys the index
+                        // derived — this measures a note against a vocabulary,
+                        // and `address:` is in no vocabulary.
+                        fm: authoredFrontmatter(record),
                         raw: fs.readFileSync(absPath, "utf8"),
                     });
                 }
@@ -706,29 +736,56 @@ function lintCommand() {
                 type: "boolean",
                 default: true,
             });
-            yargs.option("manifests", {
-                describe:
-                    "Directory of vendored foreign link manifests, for the reference check. Defaults to the configured `paths.manifests`.",
-                type: "string",
-            });
         },
-        handler: (argv) => {
+        handler: async (argv) => {
             try {
                 const config = loadPackConfig();
                 const root = argv.root ?? config.paths.content;
-                const manifestDir = argv.manifests ?? config.paths.manifests;
+
+                // The corpus, enumerated once for this command and handed to
+                // every pass below, rather than derived again by each (#243).
+                // The address lint reads it, the `sql` tables select over it
+                // and the link index is built from it, so no two findings this
+                // command reports can be drawn from different ideas of which
+                // files the content is.
+                //
+                // A note the index cannot record is reported like any other
+                // finding rather than thrown (#243): one malformed note must
+                // not take every other finding in the tree with it, and the
+                // reader needs a line to open, not a stack.
+                const corpusProblems = [];
+                const records = indexRecordsFor({
+                    contentBase: root,
+                    config,
+                    skipDirectories: config.skipDirectories,
+                    problems: corpusProblems,
+                });
+                for (const problem of corpusProblems) emitDiagnostic(problem);
+                // An error whatever the command's own strictness: the note is
+                // absent from every answer below, so reporting it and exiting 0
+                // would call the tree clean while silently omitting a note.
+                if (corpusProblems.length) process.exitCode = 1;
 
                 // The package is passed for the homepage rule (#52), which
                 // names the address a tree with no front page fails to serve.
                 const addresses = lintContentTree(root, {
                     contentPackage: config.contentPackage,
+                    skipDirectories: config.skipDirectories,
+                    config,
+                    records,
                 });
                 // One index, built once, for the reference check. It is the
                 // same resolver the wikilink audit uses, so a frontmatter
                 // reference and a body link answer the same way.
                 const index = buildLinkIndex(root, {
-                    manifestDir,
+                    config,
+                    records,
                     skipDirectories: config.skipDirectories,
+                    sqlTables: await prepareTreeSqlTables(root, {
+                        config,
+                        records,
+                        skipDirectories: config.skipDirectories,
+                    }),
                 });
                 const frontmatter = lintFrontmatter(index, {
                     schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
@@ -737,6 +794,11 @@ function lintCommand() {
                     // whatever it is handed and this stays the one place that
                     // decides which vocabulary a tree is held to.
                     vocabulary: NOTE_VOCABULARY,
+                    // The pack names, for a `data:` field keyed by pack — a
+                    // folder's `parent` is one (#288). Companions included:
+                    // the compile asks the map for whichever pack it is
+                    // writing, and a companion is a pack it writes.
+                    packs: config.packDirectories,
                     references: argv.references,
                 });
 
@@ -789,6 +851,12 @@ function lintCommand() {
                     const { undeclared, unemitted } = compareFields({
                         builders: fieldSpecs,
                         artifact: schema.artifact,
+                        // A schema is keyed by document subtype and a field
+                        // declaration by note type. Those were one string until
+                        // #78 renamed three of them, and joining them by name
+                        // after that would drop `armorgear`'s findings without
+                        // saying so — the seam exists for exactly this.
+                        subtypeOf: (type) => schemaSubtypeOf(config.stats?.systemId, type),
                     });
                     for (const f of undeclared) {
                         schemaFindings.push({
@@ -1000,20 +1068,37 @@ function linksCommand() {
                 describe: "Content tree to check. Defaults to the configured contentBase.",
                 type: "string",
             });
-            yargs.option("manifests", {
-                describe:
-                    "Directory of vendored foreign link manifests. Defaults " +
-                    "to the configured `paths.manifests`.",
-                type: "string",
-            });
         },
-        handler: (argv) => {
+        handler: async (argv) => {
             try {
                 const config = loadPackConfig();
                 const contentBase = argv.root ?? config.paths.content;
-                const manifestDir = argv.manifests ?? config.paths.manifests;
 
-                const index = buildLinkIndex(contentBase, { manifestDir });
+                const scope = { skipDirectories: config.skipDirectories };
+                // Enumerated once and shared, as in `lint` (#243), and a note
+                // it cannot record is reported rather than thrown.
+                const corpusProblems = [];
+                const records = indexRecordsFor({
+                    contentBase,
+                    config,
+                    ...scope,
+                    problems: corpusProblems,
+                });
+                for (const problem of corpusProblems) emitDiagnostic(problem);
+                // An error whatever the command's own strictness: the note is
+                // absent from every answer below, so reporting it and exiting 0
+                // would call the tree clean while silently omitting a note.
+                if (corpusProblems.length) process.exitCode = 1;
+                const index = buildLinkIndex(contentBase, {
+                    config,
+                    records,
+                    ...scope,
+                    sqlTables: await prepareTreeSqlTables(contentBase, {
+                        config,
+                        records,
+                        ...scope,
+                    }),
+                });
 
                 // An unusable manifest would otherwise surface as a pile of
                 // dead addresses pointing at the notes that cite it, rather
@@ -1021,12 +1106,12 @@ function linksCommand() {
                 if (index.foreign.stale.length) {
                     for (const s of index.foreign.stale) {
                         emitDiagnostic({
-                            file: path.join(manifestDir, `${s.package}.json`),
+                            file: cachedIndexPath(config, s.package),
                             severity: "error",
-                            message: `unusable link manifest: ${s.reason}`,
+                            message: `unusable content index: ${s.reason}`,
                         });
                     }
-                    log.error("Refresh the vendored copy from that package's own build.");
+                    log.error("Re-run `content-build deps fetch`.");
                     process.exitCode = 1;
                     return;
                 }
@@ -1037,7 +1122,7 @@ function linksCommand() {
                 const drifted = unaddressableForeignPackages(index.foreign.index);
                 if (drifted.length) {
                     for (const f of drifted) {
-                        console.error(formatUnaddressableFinding(f, manifestDir));
+                        console.error(formatUnaddressableFinding(f, config));
                     }
                     process.exitCode = 1;
                     return;
@@ -1126,77 +1211,6 @@ function linksCommand() {
     };
 }
 
-/**
- * `content-build manifest` — emit this package's cross-package link manifest.
- *
- * The last capability the library exposed without a command (#58). Every
- * consumer that publishes a manifest had to write the walk, the address
- * derivation, the anchor pass and the entry assembly for itself, and the two
- * that did drifted apart: one routed its UUIDs through the pack router and one
- * did not, so a repository shipping several packs of a type published UUIDs
- * naming the wrong one.
- *
- * Takes no paths. The content tree, the output directory, the content and
- * Foundry package identities and the address scheme all come from
- * `package-build.config.yaml`; `[root]` and `--out` exist to point the same
- * derivation at a scratch tree, not because a build needs to name them.
- *
- * @returns {object} The yargs command module.
- */
-// eslint-disable-next-line
-function manifestCommand() {
-    return {
-        command: "manifest [root]",
-        describe: "Emit this package's cross-package link manifest",
-        builder: (yargs) => {
-            yargs.positional("root", {
-                describe: "Content tree to read. Defaults to the configured contentBase.",
-                type: "string",
-            });
-            yargs.option("out", {
-                describe:
-                    "Directory to write into. Defaults to the configured " + "`paths.manifestOut`.",
-                type: "string",
-            });
-        },
-        handler: (argv) => {
-            try {
-                const config = loadPackConfig();
-                const { written, notes, skipped } = emitLinkManifest({
-                    config,
-                    ...(argv.root ? { contentBase: argv.root } : {}),
-                    ...(argv.out ? { outDir: argv.out } : {}),
-                });
-
-                for (const { package: pkg, file, count } of written) {
-                    log.info(
-                        `${pkg} → ${path.relative(process.cwd(), file)} ` +
-                            `(${count} entries, from ${notes} addressable ` +
-                            `note(s))`,
-                    );
-                }
-
-                // Reported rather than fatal: a note with no address is
-                // ordinary — a template, a stub, a `doc` with no category —
-                // and failing the build on one would make the manifest
-                // unemittable for a reason that is not about the manifest.
-                // Silence is the thing to avoid, since a note that quietly
-                // lost its address becomes a dead link in every consumer.
-                for (const s of skipped) {
-                    emitDiagnostic({
-                        file: path.join(argv.root ?? config.paths.content, s.file),
-                        severity: "warning",
-                        message: `no address, so it is absent from the manifest: ${s.reason}`,
-                    });
-                }
-            } catch (err) {
-                reportFailure(err);
-                process.exitCode = 1;
-            }
-        },
-    };
-}
-
 /**
  * `content-build content-index` — emit this package's note index.
  *
@@ -1276,9 +1290,12 @@ function siteCommand() {
                 type: "string",
             });
         },
-        handler: (argv) => {
+        handler: async (argv) => {
             try {
                 const result = buildSite({
+                    sqlTables: await prepareTreeSqlTables(loadPackConfig().paths.content, {
+                        skipDirectories: loadPackConfig().skipDirectories,
+                    }),
                     ...(argv.out ? { outRoot: argv.out } : {}),
                 });
                 const { gates } = result;
@@ -1307,13 +1324,13 @@ function siteCommand() {
                 }
                 for (const s of gates.staleManifests) {
                     emitDiagnostic({
-                        file: path.join(loadPackConfig().paths.manifests, `${s.package}.json`),
+                        file: cachedIndexPath(loadPackConfig(), s.package),
                         severity: "error",
-                        message: `unusable link manifest: ${s.reason}`,
+                        message: `unusable content index: ${s.reason}`,
                     });
                 }
                 for (const f of gates.unaddressable) {
-                    console.error(formatUnaddressable(f, loadPackConfig().paths.manifests));
+                    console.error(formatUnaddressable(f, loadPackConfig()));
                 }
                 for (const c of gates.conflicts) {
                     log.error(`address ${c.key} is also published by ${c.package}`);
@@ -1327,8 +1344,20 @@ function siteCommand() {
                 // failures of individual notes, and stopping the whole build
                 // before anything is emitted would make a single bad table
                 // hide every other problem in the tree.
+                // `file:line:column: error: message`, path first — the same
+                // shape the pack build and the wikilink findings below use. It
+                // was prose with a timestamp where a parser reads the path,
+                // which made one authored table produce a machine-readable
+                // diagnostic from one build and something ungreppable from the
+                // other (#223).
                 for (const e of result.tableErrors) {
-                    log.error(`bad content table: ${e.reason}  (${e.source})`);
+                    emitDiagnostic({
+                        file: e.source,
+                        line: typeof e.line === "number" ? e.line + 1 : undefined,
+                        column: e.column,
+                        severity: "error",
+                        message: e.reason,
+                    });
                 }
                 // Reported the way the pack build reports the very same
                 // finding: `file:line:column: error: message`, path first, and
@@ -1351,20 +1380,6 @@ function siteCommand() {
                     return;
                 }
 
-                if (result.manifests && !result.manifests.complete) {
-                    // Not a softening any more (#184): an address into one of
-                    // these packages fails like any other that resolves
-                    // nowhere. The warning names them so an author meeting that
-                    // failure knows the fix may be to vendor a manifest rather
-                    // than to correct a shortcode.
-                    log.warn(
-                        `no link manifest vendored for ` +
-                            `${result.manifests.missing.join(", ")} — an ` +
-                            `address into one of those packages resolves ` +
-                            `nowhere and fails the build.`,
-                    );
-                }
-
                 const s = result.stats;
                 log.info(
                     `wrote ${s.homepages ?? 0} homepage(s) + ` +
@@ -1421,11 +1436,37 @@ function reachabilityCommand() {
                 type: "string",
             });
         },
-        handler: (argv) => {
+        handler: async (argv) => {
             try {
-                const contentBase = argv.root ?? loadPackConfig().paths.content;
+                // Resolved once and passed on, so every pass below runs
+                // against the configuration this command resolved rather than
+                // whichever one the working directory answers with (#243).
+                const config = loadPackConfig();
+                const contentBase = argv.root ?? config.paths.content;
                 const dir = String(argv.dir).replace(/\/+$/, "");
-                const index = buildLinkIndex(contentBase);
+                const scope = { skipDirectories: config.skipDirectories };
+                const corpusProblems = [];
+                const records = indexRecordsFor({
+                    contentBase,
+                    config,
+                    ...scope,
+                    problems: corpusProblems,
+                });
+                for (const problem of corpusProblems) emitDiagnostic(problem);
+                // An error whatever the command's own strictness: the note is
+                // absent from every answer below, so reporting it and exiting 0
+                // would call the tree clean while silently omitting a note.
+                if (corpusProblems.length) process.exitCode = 1;
+                const index = buildLinkIndex(contentBase, {
+                    config,
+                    records,
+                    ...scope,
+                    sqlTables: await prepareTreeSqlTables(contentBase, {
+                        config,
+                        records,
+                        ...scope,
+                    }),
+                });
                 const indexes = new Set(argv.index.map(String));
 
                 const { orphans } = walkReachability(index, {
@@ -1471,8 +1512,14 @@ function reachabilityCommand() {
 
 // eslint-disable-next-line
 /**
- * `deps fetch` — fill the item-catalogue cache for every dependency that
- * declares `itemCatalog: true`.
+ * `deps fetch` — fill the caches this build resolves other packages through:
+ * the **content index** of every declared dependency (#239), 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
@@ -1496,7 +1543,11 @@ function reachabilityCommand() {
  * @returns {Promise<void>}
  */
 async function fetchFromLocalArtifact(config, argv) {
-    const rels = itemCatalogRelationships(config);
+    // Two caches, two dependency sets: an index is fetched for every declared
+    // dependency, a catalogue only for those declaring `itemCatalog: true`
+    // (#239). `--from` fills whichever of them this dependency belongs to, so
+    // that testing against an unreleased build behaves like a release would.
+    const rels = metadataRelationships(config);
     const named = rels.map((r) => r.id).join(", ") || "none";
     const rel =
         argv.id ? rels.find((r) => r.id === argv.id)
@@ -1507,11 +1558,14 @@ async function fetchFromLocalArtifact(config, argv) {
         // config is the only place that says which those are.
         throw new Error(
             argv.id ?
-                `no dependency "${argv.id}" declares \`itemCatalog: true\` (declared: ${named})`
-            :   `--from needs --id when several dependencies declare \`itemCatalog: true\` (declared: ${named})`,
+                `no declared dependency "${argv.id}" (declared: ${named})`
+            :   `--from needs --id when a package declares several dependencies (declared: ${named})`,
         );
     }
-    await fetchCatalogFromPath(config, rel, argv.from);
+    await fetchMetadataFromPath(config, rel, argv.from);
+    if (itemCatalogRelationships(config).some((r) => r.id === rel.id)) {
+        await fetchCatalogFromPath(config, rel, argv.from);
+    }
 }
 
 function depsCommand() {
@@ -1537,7 +1591,7 @@ function depsCommand() {
             yargs.option("id", {
                 describe:
                     "Which declared dependency `--from` supplies. Only needed " +
-                    "when more than one declares `itemCatalog: true`.",
+                    "when a package declares more than one.",
                 type: "string",
             });
         },
@@ -1548,8 +1602,11 @@ function depsCommand() {
                     await fetchFromLocalArtifact(config, argv);
                     return;
                 }
+                const indexes = await fetchAllMetadata(config);
+                if (indexes) log.info(`Fetched ${indexes} dependency content index(es).`);
                 const count = await fetchAllCatalogs(config);
                 if (count) log.info(`Fetched ${count} dependency catalogue(s).`);
+                if (!indexes && !count) log.info("This package declares no dependencies.");
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -1613,10 +1670,34 @@ async function diffAddresses(config, argv) {
         );
     }
 
+    // Stated by the caller, like every other corpus read in this file (#243):
+    // the two tree reads below must agree with each other and with the compile
+    // about which files are the corpus. They now do so by construction — the
+    // corpus is derived once, here, and handed to both.
+    const scope = { skipDirectories: config.skipDirectories };
+    const corpusProblems = [];
+    const records = indexRecordsFor({
+        contentBase: config.paths.content,
+        config,
+        ...scope,
+        problems: corpusProblems,
+    });
+    for (const problem of corpusProblems) emitDiagnostic(problem);
+    // An error whatever `--strict` says: the note is in none of the answers
+    // below, so exiting 0 would call the tree clean while omitting a note.
+    if (corpusProblems.length) process.exitCode = 1;
+    const corpus = { config, records, ...scope };
+
     const findings = diffItemAddresses(
         readItemAddresses(baselineDirs),
         readItemAddresses(currentDirs),
-        { baseline: label },
+        {
+            baseline: label,
+            // Read whether or not anything departed: an id match needs no tree,
+            // but the diff decides rename-versus-withdrawal as it walks the
+            // baseline, so the declarations have to be in hand before it does.
+            predecessors: declaredPredecessors(config.paths.content, corpus),
+        },
     );
     if (!findings.length) {
         log.info(`Every address ${label} published is still published.`);
@@ -1626,7 +1707,7 @@ async function diffAddresses(config, argv) {
     // A rename is fixed in the note that made it, so findings are placed
     // against the tree rather than against the compiled output they were read
     // from.
-    const noteFiles = noteFilesById(config.paths.content);
+    const noteFiles = noteFilesById(config.paths.content, corpus);
     const severity = argv.strict ? "error" : "warning";
     for (const finding of findings) {
         emitDiagnostic({

package/bin/package-build.mjs

@@ -84,6 +84,7 @@ import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
 import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
 import { validateLangSource } from "../lang.mjs";
 import { checkLabelRegistry } from "../labels.mjs";
+import { lintYaml } from "../engine/yaml-lint.mjs";
 import {
     analyzeCoverage,
     collectScriptReferences,
@@ -713,6 +714,47 @@ function langHardcoded(config) {
  *
  * @returns {object} The yargs command module.
  */
+/**
+ * `package-build yaml` — lint note frontmatter and every YAML file.
+ *
+ * Frontmatter carries a note's type, shortcode, address and system blocks, and
+ * until this command existed nothing checked it *as YAML*: a duplicate key was
+ * caught during the parse, logged at `warn`, and turned into a note with no
+ * frontmatter, which every later pass then skipped while the build reported
+ * success.
+ *
+ * It ships as a command rather than as a configuration to adopt, so a consumer
+ * needs no ESLint and no `eslint.config.js` of its own — and a repository that
+ * has one, as `Song-of-Heroic-Lands-FoundryVTT` does for `src/`, keeps it
+ * untouched and unconsulted.
+ *
+ * @returns {object} The yargs command module.
+ */
+function yamlCommand() {
+    return {
+        command: "yaml [paths..]",
+        describe: "Lint YAML — note frontmatter, and every YAML file in the repository",
+        builder: (y) =>
+            y.positional("paths", {
+                describe:
+                    "Files or globs to lint. Defaults to every YAML file and " +
+                    "markdown frontmatter git would consider — tracked, plus " +
+                    "untracked and not ignored.",
+                type: "string",
+            }),
+        handler: handler(async (args) => {
+            const { findings, checked } = await lintYaml(process.cwd(), { paths: args.paths });
+            const errors = reportFindings(findings, {});
+            const warnings = findings.length - errors;
+            console.log(
+                `package-build: ${checked} file(s) checked · ` +
+                    `${errors} error(s) · ${warnings} warning(s)`,
+            );
+            if (errors) process.exitCode = 1;
+        }),
+    };
+}
+
 /**
  * `labels check` — do the machine registry and the documented table agree?
  *
@@ -1065,6 +1107,7 @@ yargs(hideBin(process.argv))
     .command(schemaCommand())
     .command(langCommand())
     .command(labelsCommand())
+    .command(yamlCommand())
     .command(bundleCommand())
     .command(releaseCommand())
     .command(deployCommand())