@documentation-robotics/cli 0.2.0 → 0.3.0

package/dist/core/model-upgrade.js

@@ -0,0 +1,102 @@
+import { readdir } from "fs/promises";
+import { Model } from "./model.js";
+import { MigrationRegistry } from "./migration-registry.js";
+import { applyCatalogMigrations } from "./catalog-migration.js";
+import { BaseSnapshotManager } from "./base-snapshot-manager.js";
+import { StagedChangesetStorage } from "./staged-changeset-storage.js";
+import { FileLock } from "../utils/file-lock.js";
+import { getErrorMessage } from "../utils/errors.js";
+async function upgradeModel(startPath, options) {
+  const model = await Model.load(startPath, { lazyLoad: !1 }), baselines = await captureChangesetBaselines(model);
+  let migration;
+  if (options.versionBumpOnly)
+    model.manifest.specVersion = options.toVersion, await model.saveManifest();
+  else if (options.catalogOnly) {
+    const catalog = await applyCatalogMigrations(model);
+    if (catalog.errors.length > 0)
+      throw new Error(`Catalog migration failed: ${catalog.errors.join("; ")}`);
+    migration = {
+      applied: [
+        {
+          from: options.fromVersion,
+          to: options.toVersion,
+          description: `Catalog changes applied (${catalog.summaries.join("; ")})`,
+          changes: {
+            migrationsApplied: 1,
+            filesModified: catalog.filesModified,
+            description: catalog.summaries.join("; "),
+            details: catalog.details
+          }
+        }
+      ],
+      currentVersion: options.fromVersion,
+      targetVersion: options.toVersion,
+      totalChanges: 1
+    }, await model.saveDirtyLayers();
+  } else
+    migration = await new MigrationRegistry().applyMigrations(model, {
+      fromVersion: options.fromVersion,
+      toVersion: options.toVersion,
+      dryRun: !1,
+      validate: options.validate ?? !0
+    }), await model.saveManifest(), await model.saveDirtyLayers();
+  return { migration, changesets: await rebaselineChangesets(startPath, baselines) };
+}
+async function captureChangesetBaselines(model) {
+  if (model.lazyLoad)
+    throw new Error("captureChangesetBaselines needs a model loaded with lazyLoad: false");
+  const { changesets, errors } = await listStagedChangesets(model.rootPath), baselines = { snapshot: null, inStep: [], drifted: [], errors };
+  if (changesets.length === 0)
+    return baselines;
+  const snapshot = await new BaseSnapshotManager().captureSnapshot(model);
+  baselines.snapshot = snapshot;
+  for (const { ref, baseSnapshot } of changesets)
+    baseSnapshot && (baseSnapshot === snapshot ? baselines.inStep : baselines.drifted).push(ref);
+  return baselines;
+}
+async function rebaselineChangesets(startPath, baselines) {
+  const result = {
+    rebaselined: [],
+    drifted: baselines.drifted,
+    errors: [...baselines.errors]
+  };
+  if (baselines.inStep.length === 0)
+    return result;
+  const upgraded = await Model.load(startPath, { lazyLoad: !1 }), snapshot = await new BaseSnapshotManager().captureSnapshot(upgraded), storage = new StagedChangesetStorage(upgraded.rootPath);
+  for (const ref of baselines.inStep)
+    try {
+      await new FileLock(storage.getChangesetPath(ref.id)).withLock(async () => {
+        const changeset = await storage.load(ref.id);
+        !changeset || changeset.status !== "staged" || changeset.baseSnapshot !== baselines.snapshot || (changeset.baseSnapshot = snapshot, changeset.updateModified(), await storage.save(changeset), result.rebaselined.push(ref));
+      });
+    } catch (error) {
+      result.errors.push(`Could not re-baseline changeset '${ref.name}': ${getErrorMessage(error)}; committing it needs --force`);
+    }
+  return result;
+}
+async function listStagedChangesets(rootPath) {
+  const storage = new StagedChangesetStorage(rootPath), changesets = [], errors = [];
+  let ids;
+  try {
+    ids = (await readdir(storage.getChangesetsDir(), { withFileTypes: !0 })).filter((entry) => entry.isDirectory() && !entry.name.endsWith(".lock")).map((entry) => entry.name).sort();
+  } catch (error) {
+    return error.code !== "ENOENT" && errors.push(`Could not list changesets: ${getErrorMessage(error)}`), { changesets, errors };
+  }
+  for (const id of ids)
+    try {
+      const changeset = await storage.load(id);
+      changeset?.status === "staged" && changesets.push({
+        ref: { id, name: changeset.name || id },
+        baseSnapshot: changeset.baseSnapshot
+      });
+    } catch (error) {
+      errors.push(`Could not read changeset '${id}': ${getErrorMessage(error)}`);
+    }
+  return { changesets, errors };
+}
+export {
+  captureChangesetBaselines,
+  rebaselineChangesets,
+  upgradeModel
+};
+//# sourceMappingURL=model-upgrade.js.map

package/dist/core/model-upgrade.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/core/model-upgrade.ts"],
+  "sourcesContent": ["/**\n * Model upgrade - moves a model to a newer spec version and keeps its staged changesets\n * committable.\n *\n * A staged changeset records a hash of the model it was created on (its base snapshot), and\n * committing it fails while the model no longer has that hash. An upgrade always changes the\n * hash: it writes a new spec version into the manifest, and migrations may rewrite element\n * files. So the upgrade re-baselines each staged changeset that was in step with the model\n * before the upgrade onto the upgraded model. A changeset that had drifted before the upgrade\n * keeps its base snapshot, so that drift still blocks its commit.\n */\n\nimport { readdir } from \"fs/promises\";\nimport { Model } from \"./model.js\";\nimport { MigrationRegistry, type ApplyMigrationsResult } from \"./migration-registry.js\";\nimport { applyCatalogMigrations } from \"./catalog-migration.js\";\nimport { BaseSnapshotManager } from \"./base-snapshot-manager.js\";\nimport { StagedChangesetStorage } from \"./staged-changeset-storage.js\";\nimport { FileLock } from \"../utils/file-lock.js\";\nimport { getErrorMessage } from \"../utils/errors.js\";\n\nexport interface ModelUpgradeOptions {\n  fromVersion: string;\n  toVersion: string;\n  /** No migration path exists between the versions: only write the new spec version */\n  versionBumpOnly?: boolean;\n  /**\n   * The model is at the target version but still names retired types or relationships: apply\n   * the catalog migration (element type renames and relationship rewrites) on its own\n   */\n  catalogOnly?: boolean;\n  /** Passed to the migrations (default true) */\n  validate?: boolean;\n}\n\n/** A staged changeset, by directory id and name */\nexport interface ChangesetRef {\n  id: string;\n  name: string;\n}\n\nexport interface ChangesetRebaselineResult {\n  /** Staged changesets now based on the upgraded model */\n  rebaselined: ChangesetRef[];\n  /** Staged changesets that had drifted before the upgrade; they keep their base snapshot */\n  drifted: ChangesetRef[];\n  /** Changesets that could not be read or re-baselined */\n  errors: string[];\n}\n\nexport interface ModelUpgradeResult {\n  /** The migrations applied; absent for a version bump */\n  migration?: ApplyMigrationsResult;\n  changesets: ChangesetRebaselineResult;\n}\n\n/** Staged changesets sorted by whether they match the model before an upgrade */\nexport interface ChangesetBaselines {\n  /** Snapshot of the model before the upgrade; null when there is no staged changeset */\n  snapshot: string | null;\n  inStep: ChangesetRef[];\n  drifted: ChangesetRef[];\n  errors: string[];\n}\n\n/**\n * Upgrade the model at startPath to options.toVersion and save it, then re-baseline its\n * staged changesets on the upgraded model.\n */\nexport async function upgradeModel(\n  startPath: string,\n  options: ModelUpgradeOptions\n): Promise<ModelUpgradeResult> {\n  // Load every layer, as `dr changeset commit` does before it checks for drift\n  const model = await Model.load(startPath, { lazyLoad: false });\n  const baselines = await captureChangesetBaselines(model);\n\n  let migration: ApplyMigrationsResult | undefined;\n  if (options.versionBumpOnly) {\n    model.manifest.specVersion = options.toVersion;\n    await model.saveManifest();\n  } else if (options.catalogOnly) {\n    const catalog = await applyCatalogMigrations(model);\n    if (catalog.errors.length > 0) {\n      throw new Error(`Catalog migration failed: ${catalog.errors.join(\"; \")}`);\n    }\n    migration = {\n      applied: [\n        {\n          from: options.fromVersion,\n          to: options.toVersion,\n          description: `Catalog changes applied (${catalog.summaries.join(\"; \")})`,\n          changes: {\n            migrationsApplied: 1,\n            filesModified: catalog.filesModified,\n            description: catalog.summaries.join(\"; \"),\n            details: catalog.details,\n          },\n        },\n      ],\n      currentVersion: options.fromVersion,\n      targetVersion: options.toVersion,\n      totalChanges: 1,\n    };\n    await model.saveDirtyLayers();\n  } else {\n    migration = await new MigrationRegistry().applyMigrations(model, {\n      fromVersion: options.fromVersion,\n      toVersion: options.toVersion,\n      dryRun: false,\n      validate: options.validate ?? true,\n    });\n    await model.saveManifest();\n    await model.saveDirtyLayers();\n  }\n\n  return { migration, changesets: await rebaselineChangesets(startPath, baselines) };\n}\n\n/**\n * Hash the model and sort its staged changesets into those whose base snapshot matches it\n * and those that had drifted from it. Call before the model changes.\n *\n * @param model - loaded with lazyLoad: false, as `dr changeset commit` loads it, because the\n *   snapshot hashes every loaded layer\n */\nexport async function captureChangesetBaselines(model: Model): Promise<ChangesetBaselines> {\n  if (model.lazyLoad) {\n    throw new Error(\"captureChangesetBaselines needs a model loaded with lazyLoad: false\");\n  }\n\n  const { changesets, errors } = await listStagedChangesets(model.rootPath);\n  const baselines: ChangesetBaselines = { snapshot: null, inStep: [], drifted: [], errors };\n  if (changesets.length === 0) {\n    return baselines;\n  }\n\n  const snapshot = await new BaseSnapshotManager().captureSnapshot(model);\n  baselines.snapshot = snapshot;\n  for (const { ref, baseSnapshot } of changesets) {\n    // A changeset without a base snapshot never reports drift, so it needs no re-baseline\n    if (!baseSnapshot) {\n      continue;\n    }\n    (baseSnapshot === snapshot ? baselines.inStep : baselines.drifted).push(ref);\n  }\n  return baselines;\n}\n\n/**\n * Point the changesets that were in step before the upgrade at the upgraded model. Call after\n * the upgraded model is saved.\n *\n * @param startPath - the path the model was loaded from before the upgrade\n */\nexport async function rebaselineChangesets(\n  startPath: string,\n  baselines: ChangesetBaselines\n): Promise<ChangesetRebaselineResult> {\n  const result: ChangesetRebaselineResult = {\n    rebaselined: [],\n    drifted: baselines.drifted,\n    errors: [...baselines.errors],\n  };\n  if (baselines.inStep.length === 0) {\n    return result;\n  }\n\n  // Reload rather than hash the model in memory: migrations may rewrite files on disk\n  // without updating it, and the commit hashes what it loads from disk\n  const upgraded = await Model.load(startPath, { lazyLoad: false });\n  const snapshot = await new BaseSnapshotManager().captureSnapshot(upgraded);\n  const storage = new StagedChangesetStorage(upgraded.rootPath);\n\n  for (const ref of baselines.inStep) {\n    try {\n      await new FileLock(storage.getChangesetPath(ref.id)).withLock(async () => {\n        const changeset = await storage.load(ref.id);\n        // Skip a changeset whose status or base changed while the upgrade ran\n        if (\n          !changeset ||\n          changeset.status !== \"staged\" ||\n          changeset.baseSnapshot !== baselines.snapshot\n        ) {\n          return;\n        }\n        changeset.baseSnapshot = snapshot;\n        changeset.updateModified();\n        await storage.save(changeset);\n        result.rebaselined.push(ref);\n      });\n    } catch (error) {\n      result.errors.push(\n        `Could not re-baseline changeset '${ref.name}': ${getErrorMessage(error)}; committing it needs --force`\n      );\n    }\n  }\n  return result;\n}\n\nasync function listStagedChangesets(rootPath: string): Promise<{\n  changesets: Array<{ ref: ChangesetRef; baseSnapshot: string | undefined }>;\n  errors: string[];\n}> {\n  const storage = new StagedChangesetStorage(rootPath);\n  const changesets: Array<{ ref: ChangesetRef; baseSnapshot: string | undefined }> = [];\n  const errors: string[] = [];\n\n  let ids: string[];\n  try {\n    ids = (await readdir(storage.getChangesetsDir(), { withFileTypes: true }))\n      // FileLock keeps \"<changeset>.lock\" directories beside the changesets\n      .filter((entry) => entry.isDirectory() && !entry.name.endsWith(\".lock\"))\n      .map((entry) => entry.name)\n      .sort();\n  } catch (error) {\n    if ((error as { code?: string }).code !== \"ENOENT\") {\n      errors.push(`Could not list changesets: ${getErrorMessage(error)}`);\n    }\n    return { changesets, errors };\n  }\n\n  for (const id of ids) {\n    try {\n      const changeset = await storage.load(id);\n      if (changeset?.status === \"staged\") {\n        changesets.push({\n          ref: { id, name: changeset.name || id },\n          baseSnapshot: changeset.baseSnapshot,\n        });\n      }\n    } catch (error) {\n      errors.push(`Could not read changeset '${id}': ${getErrorMessage(error)}`);\n    }\n  }\n  return { changesets, errors };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/core/model.js

@@ -12,6 +12,7 @@ import { startSpan, endSpan, startActiveSpan } from "../telemetry/index.js";
 import { findProjectRoot } from "../utils/project-paths.js";
 import { getCodebasePath } from "../utils/globals.js";
 import { getErrorMessage } from "../utils/errors.js";
+import { assertBaseModelWritable } from "./changeset-only-guard.js";
 import { getNodeType } from "../generated/node-types.js";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -64,6 +65,11 @@ class Model {
   _activeChangesetId = null;
   /** Layer names that exist only in staged changes (not yet committed to base model). */
   _stagedLayerNames = /* @__PURE__ */ new Set();
+  /**
+   * relationships.yaml as committed, captured at load time before the active changeset's staged
+   * relationship changes are merged into `relationships`. Null when no changeset was active.
+   */
+  _baseRelationships = null;
   constructor(rootPath, manifest, options = {}) {
     this.rootPath = rootPath, this.codebaseRoot = options.codebaseRoot ?? rootPath, this.manifest = manifest, this.graph = new GraphModel(), this.layers = /* @__PURE__ */ new Map(), this.relationships = new Relationships(), this.lazyLoad = options.lazyLoad ?? !1, this.loadedLayerFilter = options.layers, this.loadedLayers = /* @__PURE__ */ new Set();
   }
@@ -83,8 +89,11 @@ class Model {
     if (this.lazyLoad && !this.loadedLayers.has(name) && await this.loadLayer(name), this._activeChangesetId)
       try {
         return await this.getVirtualProjectionEngine().projectLayer(this, this._activeChangesetId, name);
-      } catch {
-        return this.layers.get(name);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err), isChangesetNotFound = errorMessage.includes("Changeset") && errorMessage.includes("not found"), isCorrupted = errorMessage.includes("corrupted");
+        if (isChangesetNotFound || isCorrupted)
+          return this.layers.get(name);
+        throw err;
       }
     return this.layers.get(name);
   }
@@ -112,6 +121,14 @@ class Model {
   getActiveChangesetId() {
     return this._activeChangesetId;
   }
+  /**
+   * The committed relationships, without the active changeset's staged additions and removals
+   * that load() merges into `relationships` for read commands. Equal to `relationships.getAll()`
+   * when no changeset was active at load time.
+   */
+  getBaseRelationships() {
+    return this._baseRelationships ? [...this._baseRelationships] : this.relationships.getAll();
+  }
   /**
    * Load a layer from disk (model/XX_layername/*.yaml files)
    */
@@ -223,10 +240,19 @@ class Model {
     const staged = Array.from(this._stagedLayerNames).filter((l) => !this.layers.has(l));
     return [...base, ...staged];
   }
+  /**
+   * Records that the active changeset now stages an element change in `layerName`, so
+   * getLayerNames() (and findElementLayer()) discover a layer the base model does not have without
+   * a reload. StagingAreaManager calls this when it stages into this model's active changeset.
+   */
+  noteStagedLayer(changesetId, layerName) {
+    this._activeChangesetId && this._activeChangesetId === changesetId && layerName && this._stagedLayerNames.add(layerName);
+  }
   /**
    * Save a layer to disk (model/XX_layername/*.yaml)
    */
   async saveLayer(name) {
+    assertBaseModelWritable();
     const layer = this.layers.get(name);
     if (!layer)
       throw new Error(`Layer ${name} not found`);
@@ -323,7 +349,7 @@ class Model {
    * Save the manifest to disk (documentation-robotics/model/manifest.yaml)
    */
   async saveManifest() {
-    this.manifest.updateModified();
+    assertBaseModelWritable(), this.manifest.updateModified();
     const yaml = await import("yaml"), manifestPath = `${this.rootPath}/documentation-robotics/model/manifest.yaml`, yamlData = {
       version: this.manifest.version,
       schema: "documentation-robotics-v1",
@@ -393,15 +419,28 @@ class Model {
   }
   /**
    * Save relationships to relationships.yaml
+   *
+   * @param options.preserveHeader - Keep the file's existing leading comment block
+   *   (refreshing its `# Last updated:` line) instead of writing the standard header.
    */
-  async saveRelationships() {
+  async saveRelationships(options = {}) {
+    assertBaseModelWritable();
     const fs2 = await import("fs/promises"), yaml = await import("yaml"), relationshipsPath = `${this.rootPath}/documentation-robotics/model/relationships.yaml`;
     await ensureDir(`${this.rootPath}/documentation-robotics/model`);
-    const data = this.relationships.toArray(), yamlContent = `# Intra-layer relationships
+    const data = this.relationships.toArray(), timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    let header = `# Intra-layer relationships
 # Format: source_id -> predicate -> target_id
-# Last updated: ${(/* @__PURE__ */ new Date()).toISOString()}
+# Last updated: ${timestamp}
 
-` + yaml.stringify(data);
+`;
+    if (options.preserveHeader)
+      try {
+        const { extractRelationshipsHeader } = await import("./relationship-prune.js"), existing = extractRelationshipsHeader(await fs2.readFile(relationshipsPath, "utf-8"));
+        existing && (header = existing.replace(/^(# Last updated:).*$/m, `$1 ${timestamp}`) + `
+`);
+      } catch {
+      }
+    const yamlContent = header + yaml.stringify(data);
     await fs2.writeFile(relationshipsPath, yamlContent, "utf-8"), this.relationships.markClean();
   }
   /**
@@ -444,11 +483,15 @@ class Model {
       const candidateManifestPath = path.join(currentPath, "documentation-robotics", "model", "manifest.yaml");
       try {
         return await fs.access(candidateManifestPath), candidateManifestPath;
-      } catch {
+      } catch (err) {
+        if (!(err?.code === "ENOENT"))
+          throw err;
       }
       try {
         return await fs.access(path.join(currentPath, ".git")), null;
-      } catch {
+      } catch (err) {
+        if (!(err?.code === "ENOENT"))
+          throw err;
       }
       const parentPath = path.dirname(currentPath);
       if (parentPath === currentPath)
@@ -604,29 +647,37 @@ Run "dr init" to create a model.`);
       try {
         const activeId = (await fs.readFile(activePath, "utf-8")).trim();
         if (activeId) {
-          model._activeChangesetId = activeId;
-          const changeset = await new StagedChangesetStorage(projectRoot).load(activeId);
-          if (changeset)
-            for (const change of changeset.changes) {
-              if ((change.type === "add" || change.type === "update" || change.type === "delete") && model._stagedLayerNames.add(change.layerName), change.type === "relationship-add" && change.after) {
-                const rel = change.after;
-                model.relationships.find(rel.source, rel.target, rel.predicate).length === 0 && model.relationships.add({
-                  source: rel.source,
-                  target: rel.target,
-                  predicate: rel.predicate,
-                  layer: rel.layer,
-                  ...rel.targetLayer ? { targetLayer: rel.targetLayer } : {},
-                  category: rel.category ?? "structural",
-                  ...rel.properties ? { properties: rel.properties } : {}
-                });
-              }
-              if (change.type === "relationship-delete" && change.before) {
-                const rel = change.before;
-                model.relationships.delete(rel.source, rel.target, rel.predicate);
+          model._activeChangesetId = activeId, model._baseRelationships = model.relationships.getAll();
+          const storage = new StagedChangesetStorage(projectRoot);
+          try {
+            const changeset = await storage.load(activeId);
+            if (changeset)
+              for (const change of changeset.changes) {
+                if ((change.type === "add" || change.type === "update" || change.type === "delete") && model._stagedLayerNames.add(change.layerName), change.type === "relationship-add" && change.after) {
+                  const rel = change.after;
+                  model.relationships.find(rel.source, rel.target, rel.predicate).length === 0 && model.relationships.add({
+                    source: rel.source,
+                    target: rel.target,
+                    predicate: rel.predicate,
+                    layer: rel.layer,
+                    ...rel.targetLayer ? { targetLayer: rel.targetLayer } : {},
+                    category: rel.category ?? "structural",
+                    ...rel.properties ? { properties: rel.properties } : {}
+                  });
+                }
+                if (change.type === "relationship-delete" && change.before) {
+                  const rel = change.before;
+                  model.relationships.delete(rel.source, rel.target, rel.predicate);
+                }
               }
-            }
+          } catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to load active changeset '${activeId}': ${errorMessage}`, { cause: err });
+          }
         }
-      } catch {
+      } catch (err) {
+        if (!(err?.code === "ENOENT"))
+          throw err;
         model._activeChangesetId = null;
       }
       let entityCount = 0;
@@ -753,6 +804,7 @@ Run "dr init" to create a model.`);
    * @throws Error if atomic write fails
    */
   async saveDirtyLayersAtomic() {
+    assertBaseModelWritable();
     const tempLayerWrites = [];
     try {
       for (const layer of this.layers.values())