@crewhaus/migration-engine 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/migration-engine",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "IR version migrations: register up/down chains; migrate(spec, fromVersion, toVersion) walks the chain",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/migration-engine"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/migration-engine#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Section 28 — `migration-engine` tests:
+ *  - T1 round-trip per registered migration
+ *  - T4 fixture corpus replay
+ */
+import { describe, expect, test } from "bun:test";
+import { MigrationEngine, MigrationError, NOOP_0_TO_1, createDefaultEngine } from "./index";
+
+describe("migration-engine — T1 single-step migrations", () => {
+  test("0 → 1 NOOP migrates and stamps version", () => {
+    const e = createDefaultEngine();
+    const out = e.migrate({ name: "x", target: "cli" }, 1);
+    expect(out.version).toBe(1);
+  });
+
+  test("up + down round-trip", () => {
+    const e = createDefaultEngine();
+    const original = { name: "x", target: "cli", version: 0 };
+    const up = e.migrate(original, 1);
+    expect(up.version).toBe(1);
+    const back = e.migrate(up, 0);
+    expect(back.version).toBe(0);
+  });
+
+  test("from === to is a no-op", () => {
+    const e = createDefaultEngine();
+    const spec = { version: 0 };
+    expect(e.migrate(spec, 0)).toBe(spec);
+  });
+
+  test("missing version step throws", () => {
+    const e = new MigrationEngine();
+    expect(() => e.migrate({ version: 0 }, 1)).toThrow(MigrationError);
+  });
+
+  test("registering same key twice throws", () => {
+    const e = new MigrationEngine();
+    e.register(NOOP_0_TO_1);
+    expect(() => e.register(NOOP_0_TO_1)).toThrow(MigrationError);
+  });
+
+  test("registering same-version migration throws", () => {
+    const e = new MigrationEngine();
+    expect(() =>
+      e.register({
+        from: 0,
+        to: 0,
+        up: (s) => s,
+        down: (s) => s,
+      }),
+    ).toThrow(MigrationError);
+  });
+
+  test("registering >1-step migration throws", () => {
+    const e = new MigrationEngine();
+    expect(() =>
+      e.register({
+        from: 0,
+        to: 2,
+        up: (s) => s,
+        down: (s) => s,
+      }),
+    ).toThrow(MigrationError);
+  });
+});
+
+describe("migration-engine — T4 multi-step chain replay", () => {
+  test("0 → 2 walks 0→1 then 1→2", () => {
+    const e = new MigrationEngine();
+    e.register({
+      from: 0,
+      to: 1,
+      up: (s) => ({ ...s, version: 1, addedAt1: true }),
+      down: (s) => ({ ...s, version: 0 }),
+    });
+    e.register({
+      from: 1,
+      to: 2,
+      up: (s) => ({ ...s, version: 2, addedAt2: true }),
+      down: (s) => ({ ...s, version: 1 }),
+    });
+    const out = e.migrate({ version: 0 }, 2);
+    expect(out.version).toBe(2);
+    expect((out as { addedAt1?: boolean }).addedAt1).toBe(true);
+    expect((out as { addedAt2?: boolean }).addedAt2).toBe(true);
+  });
+
+  test("2 → 0 walks 1→2.down then 0→1.down", () => {
+    const e = new MigrationEngine();
+    e.register({
+      from: 0,
+      to: 1,
+      up: (s) => ({ ...s, version: 1 }),
+      down: (s) => ({ ...s, version: 0, removedAt0: true }),
+    });
+    e.register({
+      from: 1,
+      to: 2,
+      up: (s) => ({ ...s, version: 2 }),
+      down: (s) => ({ ...s, version: 1, removedAt1: true }),
+    });
+    const out = e.migrate({ version: 2 }, 0);
+    expect(out.version).toBe(0);
+    expect((out as { removedAt0?: boolean }).removedAt0).toBe(true);
+    expect((out as { removedAt1?: boolean }).removedAt1).toBe(true);
+  });
+
+  test("list returns sorted migration keys", () => {
+    const e = createDefaultEngine();
+    e.register({
+      from: 1,
+      to: 2,
+      up: (s) => s,
+      down: (s) => s,
+    });
+    expect(e.list()).toEqual(["0→1", "1→2"]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,118 @@
+/**
+ * Section 28 — `migration-engine`. Versioned spec migrations registered as
+ * `{ from, to, up, down }` so rollbacks work both directions. The engine
+ * walks the registered chain to bridge any pair of source/target versions
+ * (forward when `from < to`, reverse when `from > to`).
+ *
+ * Spec versions are integer ints (today every spec is `version: 0`). The
+ * first migration registered is the no-op skeleton 0 → 1.
+ *
+ * Specs are passed in as parsed YAML (raw object); migration steps are
+ * pure transforms `(spec) → spec` returning the next-version shape. The
+ * engine is unaware of YAML serialisation — callers use yaml-js or the
+ * spec parser to round-trip.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+
+export type SpecObject = Record<string, unknown> & {
+  readonly version?: number;
+};
+
+export type Migration = {
+  readonly from: number;
+  readonly to: number;
+  up(spec: SpecObject): SpecObject;
+  down(spec: SpecObject): SpecObject;
+};
+
+export class MigrationError extends CrewhausError {
+  override readonly name = "MigrationError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export class MigrationEngine {
+  private readonly migrations = new Map<string, Migration>();
+
+  register(m: Migration): void {
+    if (m.from === m.to) {
+      throw new MigrationError(
+        `migration ${m.from} → ${m.to} is a no-op (from === to); refusing to register`,
+      );
+    }
+    if (Math.abs(m.to - m.from) !== 1) {
+      throw new MigrationError(`migrations must be single-version steps; got ${m.from} → ${m.to}`);
+    }
+    const key = `${m.from}→${m.to}`;
+    if (this.migrations.has(key)) {
+      throw new MigrationError(`duplicate migration ${key}`);
+    }
+    this.migrations.set(key, m);
+  }
+
+  /**
+   * Walk the registered chain to migrate `spec` from its current version
+   * to `toVersion`. Throws MigrationError when a step is missing.
+   */
+  migrate(spec: SpecObject, toVersion: number): SpecObject {
+    const fromVersion = (spec.version ?? 0) | 0;
+    if (fromVersion === toVersion) return spec;
+
+    let current = spec;
+    if (fromVersion < toVersion) {
+      // Walk up
+      for (let v = fromVersion; v < toVersion; v++) {
+        const key = `${v}→${v + 1}`;
+        const step = this.migrations.get(key);
+        if (!step) {
+          throw new MigrationError(`no migration registered for ${key}`);
+        }
+        current = step.up(current);
+      }
+    } else {
+      // Walk down
+      for (let v = fromVersion; v > toVersion; v--) {
+        const key = `${v - 1}→${v}`;
+        const step = this.migrations.get(key);
+        if (!step) {
+          throw new MigrationError(`no migration registered for ${key} (needed for downgrade)`);
+        }
+        current = step.down(current);
+      }
+    }
+    return current;
+  }
+
+  /** Diagnostic: list registered migration keys. */
+  list(): ReadonlyArray<string> {
+    return [...this.migrations.keys()].sort();
+  }
+
+  /** Reset the registry (tests). */
+  clear(): void {
+    this.migrations.clear();
+  }
+}
+
+/**
+ * Skeleton migration 0 → 1 that today is a no-op. Future schema changes
+ * land here and bump the IR version on the up() side.
+ */
+export const NOOP_0_TO_1: Migration = Object.freeze({
+  from: 0,
+  to: 1,
+  up(spec) {
+    return { ...spec, version: 1 };
+  },
+  down(spec) {
+    return { ...spec, version: 0 };
+  },
+});
+
+/** A pre-built engine with the v0 → v1 skeleton registered. */
+export function createDefaultEngine(): MigrationEngine {
+  const e = new MigrationEngine();
+  e.register(NOOP_0_TO_1);
+  return e;
+}