@documentation-robotics/cli 0.2.0 → 0.3.0

package/dist/core/staging-area.js

@@ -2,11 +2,14 @@ import path from "path";
 import ansis from "ansis";
 import { StagedChangesetStorage } from "./staged-changeset-storage.js";
 import { BaseSnapshotManager } from "./base-snapshot-manager.js";
+import { withSequenceNumbers } from "./changeset.js";
 import { ChangesetValidator } from "./changeset-validator.js";
 import { fileExists } from "../utils/file-io.js";
 import { createSha256Hash } from "../types/index.js";
 import { getErrorMessage } from "../utils/errors.js";
 import { Layer } from "./layer.js";
+import { canonicalStagedSnapshot } from "./staged-source-reference.js";
+import { elementIdentifiers } from "./relationships.js";
 import { isValidLayerName } from "./layers.js";
 import { isTelemetryEnabled, startSpan, startActiveSpan, endSpan, emitLog, SeverityNumber } from "../telemetry/index.js";
 import { ModelReportOrchestrator } from "../reports/model-report-orchestrator.js";
@@ -49,7 +52,7 @@ class StagingAreaManager {
    * @returns VirtualProjectionEngine instance for computing merged model views
    */
   async getProjectionEngine() {
-    if (!this.projectionEngine) {
+    if (!this.projectionEngine && typeof this.model?.getVirtualProjectionEngine == "function" && (this.projectionEngine = this.model.getVirtualProjectionEngine()), !this.projectionEngine) {
       const { VirtualProjectionEngine } = await import("./virtual-projection.js");
       this.projectionEngine = new VirtualProjectionEngine(this.rootPath);
     }
@@ -62,7 +65,14 @@ class StagingAreaManager {
     if (!this.model)
       throw new Error("Model required for creating changesets");
     const id = this.generateChangesetId(), baseSnapshotId = await this.snapshotManager.captureSnapshot(this.model), changeset = await this.storage.create(id, name, description, baseSnapshotId);
-    return changeset.id = id, changeset.markStaged(), await this.storage.save(changeset), changeset;
+    changeset.id = id, changeset.markStaged(), await this.storage.save(changeset);
+    try {
+      const { captureBaseIndex, writeBaseIndex } = await import("./changeset-base-index.js");
+      await writeBaseIndex(this.rootPath, changeset.id, await captureBaseIndex(this.model));
+    } catch (error) {
+      console.warn(`Warning: could not record the base index for changeset '${name}': ${getErrorMessage(error)}. Verify and brief will fall back to what they can tell without it.`);
+    }
+    return changeset;
   }
   /**
    * Load a changeset by name or ID
@@ -91,6 +101,30 @@ class StagingAreaManager {
     const activeChangeset = await this.getActive();
     activeChangeset && activeChangeset.id === changeset.id && await this.clearActive(), await this.storage.delete(changeset.id);
   }
+  /**
+   * Rename a changeset and/or change its description (its stated intent). Staged changes,
+   * status and the active marker are untouched. Names stay unique: renaming to a name another
+   * changeset already has is refused.
+   *
+   * @param nameOrId - Changeset ID or current name
+   * @param patch - Fields to change; an empty description clears it
+   * @throws Error if the changeset is not found, or the new name is taken
+   */
+  async update(nameOrId, patch) {
+    const changeset = await this.load(nameOrId);
+    if (!changeset || !changeset.id)
+      throw new Error(`Changeset '${nameOrId}' not found`);
+    if (patch.name !== void 0) {
+      const name = patch.name.trim();
+      if (!name)
+        throw new Error("Changeset name cannot be empty");
+      const clash = (await this.storage.list()).find((cs) => cs.name === name && cs.id !== changeset.id);
+      if (clash)
+        throw new Error(`Another changeset (${clash.id}) is already named '${name}'`);
+      patch = { ...patch, name };
+    }
+    return this.storage.updateMetadata(changeset.id, patch);
+  }
   /**
    * Stage a change in the changeset.
    * Records the change in the staging area without applying to the base model.
@@ -111,7 +145,26 @@ class StagingAreaManager {
       ...change,
       timestamp: change.timestamp || (/* @__PURE__ */ new Date()).toISOString()
     };
-    await this.storage.addChange(changesetId, stagedChange), (await this.getProjectionEngine()).invalidateOnStage(changesetId, change.layerName);
+    await this.storage.addChange(changesetId, stagedChange), !change.type.startsWith("relationship-") && typeof this.model?.noteStagedLayer == "function" && this.model.noteStagedLayer(changesetId, change.layerName), (await this.getProjectionEngine()).invalidateOnStage(changesetId, change.layerName);
+  }
+  /**
+   * Rewrite a staged change in place, keeping its sequence number: e.g. to fold an update of an
+   * element into the changeset's add of it. The changeset must be in 'staged' status.
+   *
+   * @param elementId - The key (`elementId`) of the change to rewrite
+   * @throws Error if the changeset is not found, not staged, or has no change with that key
+   */
+  async restage(changesetId, elementId, change) {
+    this.validateChangesetId(changesetId);
+    const changeset = await this.load(changesetId);
+    if (!changeset)
+      throw new Error(`Changeset '${changesetId}' not found`);
+    if (changeset.status !== "staged")
+      throw new Error(`Cannot change staged changes on changeset with status '${changeset.status}'. Changeset must have status 'staged'.`);
+    await this.storage.updateChange(changesetId, elementId, {
+      ...change,
+      timestamp: change.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+    }), (await this.getProjectionEngine()).invalidateOnStage(changesetId, change.layerName);
   }
   /**
    * Unstage a specific element from the changeset.
@@ -144,7 +197,7 @@ class StagingAreaManager {
     const changeset = await this.load(changesetId);
     if (!changeset)
       throw new Error(`Changeset '${changesetId}' not found`);
-    changeset.changes = [], changeset.status = "discarded", changeset.updateModified(), await this.storage.save(changeset), (await this.getProjectionEngine()).invalidateOnDiscard(changesetId);
+    changeset.changes = [], changeset.unstaged = [], changeset.status = "discarded", changeset.updateModified(), await this.storage.save(changeset), (await this.getProjectionEngine()).invalidateOnDiscard(changesetId);
   }
   /**
    * Capture a base snapshot of the current model state for drift detection.
@@ -251,21 +304,32 @@ class StagingAreaManager {
         failed: 0,
         validation: {
           passed: !0,
-          errors: []
+          errors: [],
+          ran: shouldValidate
         }
       };
       if (shouldValidate && await startActiveSpan("staging.validate", async (validationSpan) => {
-        const validation = await this.validator.validateChangeset(model, changesetId);
-        if (validationSpan.setAttribute("validation.passed", validation.isValid()), validationSpan.setAttribute("validation.errorCount", validation.errors.length), validationSpan.setStatus({ code: 0 }), !validation.isValid())
-          throw result.validation.passed = !1, result.validation.errors = validation.errors.map((e) => e.message), emitLog(SeverityNumber.ERROR, "Validation failed", {
+        const report = await this.validator.validateChangesetReport(model, changesetId), validation = report.result;
+        if (result.validation.preExistingErrors = report.preExistingErrors.length, report.preExistingErrors.length > 0 && (result.validation.preExistingSample = report.preExistingErrors.slice(0, 10).map((e) => e.message), emitLog(SeverityNumber.WARN, "Pre-existing validation errors not counted against the changeset", {
+          "validation.preExistingErrorCount": report.preExistingErrors.length
+        })), report.baseValidationFailure && (result.validation.baseValidationFailure = report.baseValidationFailure, emitLog(SeverityNumber.WARN, "Base model could not be validated; every error counts", {
+          "validation.baseValidationFailure": report.baseValidationFailure
+        })), validationSpan.setAttribute("validation.passed", validation.isValid()), validationSpan.setAttribute("validation.errorCount", validation.errors.length), validationSpan.setAttribute("validation.preExistingErrorCount", report.preExistingErrors.length), validationSpan.setStatus({ code: 0 }), !validation.isValid()) {
+          result.validation.passed = !1, result.validation.errors = validation.errors.map((e) => e.message), emitLog(SeverityNumber.ERROR, "Validation failed", {
             "validation.errorCount": result.validation.errors.length,
             "validation.errors": result.validation.errors.slice(0, 10)
             // First 10 errors
-          }), new Error(`Validation failed with ${result.validation.errors.length} error(s):
+          });
+          const notes = [];
+          throw report.preExistingErrors.length > 0 && notes.push(`${report.preExistingErrors.length} pre-existing error(s) in the base model were not counted against this changeset.`), report.baseValidationFailure && notes.push(`The base model could not be validated (${report.baseValidationFailure}), so every error was counted.`), new Error(`Validation failed with ${result.validation.errors.length} error(s) introduced by this changeset:
 ` + result.validation.errors.map((e) => `  - ${e}`).join(`
-`) + `
+`) + (notes.length > 0 ? `
+
+${notes.join(`
+`)}` : "") + `
 
-Fix these validation errors before committing.`);
+Fix these validation errors before committing, or skip validation with --no-validate.`);
+        }
       }), isDryRun)
         return result.committed = changeset.changes.length, drift.isDrifted && (result.driftWarning = drift), result;
       let backup;
@@ -274,7 +338,8 @@ Fix these validation errors before committing.`);
       } catch (backupError) {
         throw new Error(`Failed to create backup before commit. No changes have been applied. ${backupError instanceof Error ? backupError.message : String(backupError)}`);
       }
-      const sortedChanges = [...changeset.changes].sort((a, b) => a.sequenceNumber - b.sequenceNumber);
+      const sortedChanges = withSequenceNumbers(changeset.changes).sort((a, b) => a.sequenceNumber - b.sequenceNumber);
+      let relationshipsPurged = !1;
       try {
         const applySpan = isTelemetryEnabled ? startSpan("staging.apply", {
           "apply.changeCount": changeset.changes.length
@@ -309,19 +374,19 @@ Fix these validation errors before committing.`);
                     "change.layer": change.layerName
                   });
                 else {
-                  const element = new Element(elementData);
+                  const element = new Element(canonicalStagedSnapshot(elementData).data);
                   layer.addElement(element), result.committed++;
                 }
               } else if (change.type === "update" && change.after) {
                 const element = layer.getElement(change.elementId);
                 if (element) {
-                  const elementData = change.after;
-                  Object.assign(element, elementData), layer.updateElement(element), result.committed++;
+                  const { data: elementData, sourceReference } = canonicalStagedSnapshot(change.after);
+                  Object.assign(element, elementData), sourceReference.present && element.setSourceReference(sourceReference.value), layer.updateElement(element), result.committed++;
                 } else
                   result.failed++, result.validation.passed = !1, result.validation.errors.push(`Cannot update '${change.elementId}' in '${change.layerName}': element not found in base model`);
               } else if (change.type === "delete") {
-                const element = layer.getElement(change.elementId);
-                element ? (layer.deleteElement(element.path || element.id), result.committed++) : (result.skipped = (result.skipped ?? 0) + 1, result.skippedDetails = result.skippedDetails ?? [], result.skippedDetails.push(`'${change.elementId}' in '${change.layerName}' not found \u2014 already deleted`));
+                const element = layer.getElement(change.elementId), before = change.before ?? {};
+                model.relationships.deleteForElement(elementIdentifiers(element ?? before, before.id, before.path, change.elementId)) > 0 && (relationshipsPurged = !0), element ? (layer.deleteElement(element.path || element.id), result.committed++) : (result.skipped = (result.skipped ?? 0) + 1, result.skippedDetails = result.skippedDetails ?? [], result.skippedDetails.push(`'${change.elementId}' in '${change.layerName}' not found \u2014 already deleted`));
               } else
                 result.failed++, result.validation.passed = !1, result.validation.errors.push(`Cannot apply change '${change.type}' for '${change.elementId}': missing payload or unrecognised type`);
             } catch (error) {
@@ -346,7 +411,7 @@ Fix these validation errors before committing.`);
           } catch (error) {
             throw new Error(`Failed to save layer '${layerName}': ${getErrorMessage(error)}`);
           }
-        if (hasRelationshipChanges)
+        if (hasRelationshipChanges || relationshipsPurged)
           try {
             await model.saveRelationships();
           } catch (error) {