@documentation-robotics/cli 0.2.0 → 0.3.0

package/dist/commands/changeset.js

@@ -4,12 +4,14 @@ import { StagingAreaManager } from "../core/staging-area.js";
 import { ChangesetExporter } from "../core/changeset-exporter.js";
 import { StagedChangesetStorage } from "../core/staged-changeset-storage.js";
 import { ValidationFormatter } from "../validators/validation-formatter.js";
+import { Option } from "commander";
 import * as prompts from "@clack/prompts";
 import path from "path";
 import { isTelemetryEnabled, startSpan, endSpan, startActiveSpan } from "../telemetry/index.js";
 import { getErrorMessage, handleSuccess, handleInfo, handleWarning } from "../utils/errors.js";
 import { isJson } from "../utils/globals.js";
 import { findElementLayer } from "../utils/element-utils.js";
+import { changesetVerifyCommand } from "./changeset-verify.js";
 function generateImportedChangesetId() {
   return `imported-${Date.now()}`;
 }
@@ -19,7 +21,7 @@ async function changesetCreateCommand(name, options) {
     "changeset.hasDescription": !!options.description
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model);
+    const model = await Model.load(options.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model);
     await manager.load(name) && (isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: `Changeset '${name}' already exists` })) : console.error(ansis.red(`Error: Changeset '${name}' already exists`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset already exists" }), endSpan(span), process.exit(1));
     let description = options.description;
     if (!description) {
@@ -55,7 +57,7 @@ async function changesetCreateCommand(name, options) {
 async function changesetListCommand(options = {}) {
   const span = isTelemetryEnabled ? startSpan("changeset.list") : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), changesets = await new StagingAreaManager(model.rootPath, model).list();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), changesets = await new StagingAreaManager(model.rootPath, model).list();
     if (isTelemetryEnabled && span && span.setAttribute("changeset.count", changesets.length), changesets.length === 0) {
       console.log(ansis.yellow("No changesets found")), console.log(), isTelemetryEnabled && span && span.setStatus({ code: 0 }), endSpan(span);
       return;
@@ -83,6 +85,14 @@ Changesets (${changesets.length}):
     endSpan(span);
   }
 }
+function reportCommitValidation(result, details) {
+  if (result.validation.ran === !1) {
+    delete details.validationPassed, details.validationSkipped = !0, isJson() || console.log(ansis.yellow("\u26A0 Validation skipped (--no-validate); run 'dr validate' to check the result"));
+    return;
+  }
+  const preExisting = result.validation.preExistingErrors ?? 0;
+  details.preExistingErrors = preExisting, preExisting > 0 && (details.preExistingSample = result.validation.preExistingSample ?? [], isJson() || console.log(ansis.yellow(`\u26A0 ${preExisting} validation error(s) already in the base model were ignored; the changeset introduced none. Run 'dr validate' to see them.`)));
+}
 async function changesetApplyCommand(name, options) {
   const span = isTelemetryEnabled ? startSpan("changeset.apply", {
     "changeset.name": name,
@@ -90,7 +100,7 @@ async function changesetApplyCommand(name, options) {
     "apply.force": options?.force === !0
   }) : null;
   try {
-    const model = await Model.load(options?.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
+    const model = await Model.load(options?.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
     if (changeset || (isJson() ? console.log(JSON.stringify({ status: "error", code: 2, message: `Changeset '${name}' not found` })) : console.error(ansis.red(`Error: Changeset '${name}' not found`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset not found" }), endSpan(span), process.exit(1)), isTelemetryEnabled && span && (span.setAttribute("changeset.id", changeset.id), span.setAttribute("changeset.changeCount", changeset.changes.length)), !isJson()) {
       console.log(ansis.bold(`
 Applying changeset: ${ansis.cyan(name)}
@@ -120,7 +130,7 @@ Applying changeset: ${ansis.cyan(name)}
       failed: result.failed,
       validationPassed: result.validation.passed
     };
-    if (result.failed > 0 && (applyDetails.errors = result.validation.errors, !isJson())) {
+    if (reportCommitValidation(result, applyDetails), result.failed > 0 && (applyDetails.errors = result.validation.errors, !isJson())) {
       handleInfo(ansis.red(`\u2717 Failed to apply ${result.failed} change(s):`));
       for (const error of result.validation.errors)
         handleInfo(ansis.dim(`  - ${error}`));
@@ -144,7 +154,7 @@ async function changesetRevertCommand(name, options = {}) {
     "changeset.name": name
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
+    const model = await Model.load(options.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
     changeset || (isJson() ? console.log(JSON.stringify({ status: "error", code: 2, message: `Changeset '${name}' not found` })) : console.error(ansis.red(`Error: Changeset '${name}' not found`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset not found" }), endSpan(span), process.exit(1)), isTelemetryEnabled && span && (span.setAttribute("changeset.id", changeset.id), span.setAttribute("changeset.changeCount", changeset.changes.length)), isJson() || (console.log(ansis.bold(`
 Reverting changeset: ${ansis.cyan(name)}
 `)), console.log(ansis.dim(`Changes to discard: ${changeset.changes.length}`)));
@@ -173,7 +183,7 @@ async function changesetActivateCommand(name, options = {}) {
     "changeset.name": name
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
     changeset || (isJson() ? console.log(JSON.stringify({ status: "error", code: 2, message: `Changeset '${name}' not found` })) : console.error(ansis.red(`Error: Changeset '${name}' not found`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset not found" }), endSpan(span), process.exit(1)), await manager.setActive(name), handleSuccess(`Activated changeset: ${ansis.bold(name)}`, {
       changesetName: name,
       changesetId: changeset.id
@@ -190,7 +200,7 @@ async function changesetActivateCommand(name, options = {}) {
 async function changesetDeactivateCommand(options = {}) {
   const span = isTelemetryEnabled ? startSpan("changeset.deactivate") : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), active = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), active = await manager.getActiveId();
     if (!active) {
       handleInfo(ansis.yellow("No active changeset")), isTelemetryEnabled && span && (span.setAttribute("changeset.wasActive", !1), span.setStatus({ code: 0 })), endSpan(span);
       return;
@@ -216,7 +226,7 @@ async function changesetDeleteCommand(name, options) {
     "delete.force": options.force === !0
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), changeset = await manager.load(name);
     if (changeset || (isJson() ? console.log(JSON.stringify({ status: "error", code: 2, message: `Changeset '${name}' not found` })) : console.error(ansis.red(`Error: Changeset '${name}' not found`)), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Changeset not found" }), endSpan(span), process.exit(1)), await manager.getActiveId() === changeset.id && (isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: `Cannot delete active changeset '${name}'` })) : (console.error(ansis.red(`Error: Cannot delete active changeset '${name}'`)), console.log(ansis.dim("  Run `dr changeset deactivate` first"))), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "Cannot delete active changeset" }), endSpan(span), process.exit(1)), !options.force) {
       const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
       if (isTelemetryEnabled && span && span.setAttribute("cli.interactive", isInteractive), isInteractive) {
@@ -248,7 +258,7 @@ async function changesetDeleteCommand(name, options) {
 async function changesetStatusCommand(options = {}) {
   const span = isTelemetryEnabled ? startSpan("changeset.status") : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), active = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), active = await manager.getActiveId();
     if (!active) {
       console.log(ansis.dim("No active changeset")), isTelemetryEnabled && span && (span.setAttribute("changeset.hasActive", !1), span.setStatus({ code: 0 })), endSpan(span);
       return;
@@ -277,7 +287,7 @@ async function changesetStagedCommand(options) {
     "staged.layer": options.layer
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangeset = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangeset = await manager.getActiveId();
     if (!activeChangeset) {
       isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -327,7 +337,7 @@ Staged Changes (${changes.length}):
 async function changesetExplicitStageCommand(elementId, options = {}) {
   const span = isTelemetryEnabled ? startSpan("changeset.stage-explicit", { "stage.elementId": elementId }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -361,7 +371,7 @@ async function changesetUnstageCommand(elementId, options = {}) {
     "unstage.elementId": elementId
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -395,7 +405,7 @@ async function changesetDiscardCommand(elementId, options = {}) {
     "discard.all": !elementId
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !0 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -445,7 +455,7 @@ async function changesetPreviewCommand(options) {
     "preview.layer": options.layer
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -498,7 +508,7 @@ async function changesetDiffCommand(options) {
     "diff.layer": options.layer
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
+    const model = await Model.load(options.model, { lazyLoad: !1 }), manager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await manager.getActiveId();
     if (!activeChangesetId) {
       console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span && span.setStatus({ code: 2, message: "No active changeset" }), endSpan(span);
       return;
@@ -536,7 +546,7 @@ Diff: Base Model vs Staged Changes
 async function changesetCommitCommand(options) {
   await startActiveSpan("changeset.commit", async (span) => {
     try {
-      const model = await Model.load(options?.model || process.cwd(), { lazyLoad: !1 }), stagingManager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await stagingManager.getActiveId();
+      const model = await Model.load(options?.model, { lazyLoad: !1 }), stagingManager = new StagingAreaManager(model.rootPath, model), activeChangesetId = await stagingManager.getActiveId();
       if (!activeChangesetId) {
         isJson() ? console.log(JSON.stringify({ status: "error", code: 1, message: "No active changeset" })) : console.error(ansis.red("Error: No active changeset")), isTelemetryEnabled && span.setStatus({ code: 2, message: "No active changeset" });
         return;
@@ -567,7 +577,7 @@ Committing changeset: ${ansis.cyan(changeset.name)}`)), console.log(ansis.dim(`S
           stagedChanges: changeCount,
           validationPassed: result.validation.passed
         };
-        (result.skipped ?? 0) > 0 && (commitDetails.skipped = result.skipped, commitDetails.skippedDetails = (result.skippedDetails ?? []).slice(0, 10)), result.failed > 0 && (commitDetails.failed = result.failed);
+        reportCommitValidation(result, commitDetails), (result.skipped ?? 0) > 0 && (commitDetails.skipped = result.skipped, commitDetails.skippedDetails = (result.skippedDetails ?? []).slice(0, 10)), result.failed > 0 && (commitDetails.failed = result.failed);
         const accountedFor = result.committed + (result.skipped ?? 0) + result.failed;
         if (accountedFor < changeCount) {
           const unaccounted = changeCount - accountedFor;
@@ -594,7 +604,7 @@ async function changesetExportCommand(changesetId, options) {
     "export.format": format
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !0 }), exporter = new ChangesetExporter(model.rootPath), ext = format === "patch" ? "patch" : format, outputPath = options.output || `${changesetId}.${ext}`, absolutePath = path.isAbsolute(outputPath) ? outputPath : path.join(process.cwd(), outputPath);
+    const model = await Model.load(options.model, { lazyLoad: !0 }), exporter = new ChangesetExporter(model.rootPath), ext = format === "patch" ? "patch" : format, outputPath = options.output || `${changesetId}.${ext}`, absolutePath = path.isAbsolute(outputPath) ? outputPath : path.join(process.cwd(), outputPath);
     isTelemetryEnabled && span && span.setAttribute("export.outputPath", outputPath), await exporter.exportToFile(changesetId, absolutePath, format), handleSuccess(`Exported changeset to ${outputPath}`, {
       changesetId,
       outputPath,
@@ -615,7 +625,7 @@ async function changesetImportCommand(file, options = {}) {
     "import.force": options.force === !0
   }) : null;
   try {
-    const model = await Model.load(options.model || process.cwd(), { lazyLoad: !1 }), exporter = new ChangesetExporter(model.rootPath), absolutePath = path.isAbsolute(file) ? file : path.join(process.cwd(), file), imported = await exporter.importFromFile(absolutePath);
+    const model = await Model.load(options.model, { lazyLoad: !1 }), exporter = new ChangesetExporter(model.rootPath), absolutePath = path.isAbsolute(file) ? file : path.join(process.cwd(), file), imported = await exporter.importFromFile(absolutePath);
     isTelemetryEnabled && span && (span.setAttribute("changeset.name", imported.name), span.setAttribute("changeset.changeCount", imported.changes.length));
     const compatibility = await exporter.validateCompatibility(imported, model);
     if (isTelemetryEnabled && span && (span.setAttribute("import.compatible", compatibility.compatible), span.setAttribute("import.baseSnapshotMatch", compatibility.baseSnapshotMatch)), !compatibility.compatible) {
@@ -734,11 +744,15 @@ Examples:
   $ dr changeset diff
   $ dr changeset diff --layer api`).action(async (options) => {
     await changesetDiffCommand(options);
-  }), changesetGroup.command("commit").description("Apply staged changes to the base model").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--validate", "Run validation before commit (default: true)", !0).option("--force", "Commit despite drift warnings", !1).addHelpText("after", `
+  }), changesetGroup.command("commit").description("Apply the active changeset's staged changes to the base model").allowExcessArguments(!1).option("--model <path>", "Path to model root (contains model/manifest.yaml)").addOption(new Option("--validate", "Run validation before commit (default)").hideHelp()).option("--no-validate", "Skip validation before commit (validation runs by default; only errors the changeset introduces block, errors already in the base model are reported as a count)").option("--force", "Commit despite drift warnings (does not skip validation)", !1).addHelpText("after", `
+Validation compares the model with and without the changeset. Errors the
+changeset introduces block the commit; errors the base model already had are
+not counted against it, and the output says how many there were.
+
 Examples:
   $ dr changeset commit
-  $ dr changeset commit --validate
-  $ dr changeset commit --force`).action(async (options) => {
+  $ dr changeset commit --force          # commit despite drift
+  $ dr changeset commit --no-validate    # skip validation entirely`).action(async (options) => {
     await changesetCommitCommand(options);
   }), changesetGroup.command("export <changeset-id>").description("Export changeset to portable file").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("-o, --output <file>", "Output file path").option("-f, --format <format>", "Export format (yaml|json|patch)", "yaml").addHelpText("after", `
 Examples:
@@ -753,6 +767,13 @@ Examples:
   $ dr changeset import ../team-changes.json
   $ dr changeset import changes.yaml --force`).action(async (file, options) => {
     await changesetImportCommand(file, options);
+  }), changesetGroup.command("verify [planned]").description("Compare a planned changeset with what was built (an as-built changeset, or the base model)").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--against <changeset>", "As-built changeset (ID or name) to compare with").option("--base", "Compare with the base model").option("--no-match-by-source", "Do not match elements by shared source file").option("--json", "Output as JSON").addHelpText("after", `
+The planned changeset defaults to the active one.
+
+Examples:
+  $ dr changeset verify export-orders --against export-orders-as-built
+  $ dr changeset verify export-orders --base --json`).action(async (planned, options) => {
+    await changesetVerifyCommand(planned, options);
   }), changesetGroup.showSuggestionAfterError();
 }
 export {