ic-mops 2.10.0 → 2.11.0

package/tests/migrate/basic/migrations/20250201_000000_AddName.mo

@@ -0,0 +1,5 @@
+module {
+  public func migration(old : { a : Nat }) : { a : Nat; name : Text } {
+    { old with name = "" };
+  };
+};

package/tests/migrate/basic/migrations/20250301_000000_AddEmail.mo

@@ -0,0 +1,9 @@
+module {
+  public func migration(old : { a : Nat; name : Text }) : {
+    a : Nat;
+    name : Text;
+    email : Text;
+  } {
+    { old with email = "" };
+  };
+};

package/tests/migrate/basic/mops.toml

@@ -0,0 +1,15 @@
+[toolchain]
+moc = "1.5.0"
+
+[moc]
+args = ["--default-persistent-actors"]
+
+[canisters.backend]
+main = "src/main.mo"
+
+[canisters.backend.migrations]
+chain = "migrations"
+next = "next-migration"
+
+[canisters.backend.check-stable]
+path = "deployed.most"

package/tests/migrate/basic/src/main.mo

@@ -0,0 +1,11 @@
+import Prim "mo:prim";
+
+actor {
+  let a : Nat;
+  let name : Text;
+  let email : Text;
+
+  public func check() : async () {
+    Prim.debugPrint(debug_show { a; name; email });
+  };
+};

package/tests/migrate/with-next/deployed.most

@@ -0,0 +1,12 @@
+// Version: 4.0.0
+{
+  "20250101_000000_Init" : {} -> {a : Nat};
+  "20250201_000000_AddName" : (old : {a : Nat}) -> {a : Nat; name : Text};
+  "20250301_000000_AddEmail" :
+    (old : {a : Nat; name : Text}) -> {a : Nat; email : Text; name : Text}
+}
+actor  {
+  stable a : Nat;
+  stable email : Text;
+  stable name : Text
+};

package/tests/migrate/with-next/migrations/20250101_000000_Init.mo

@@ -0,0 +1,5 @@
+module {
+  public func migration(_ : {}) : { a : Nat } {
+    { a = 0 };
+  };
+};

package/tests/migrate/with-next/migrations/20250201_000000_AddName.mo

@@ -0,0 +1,5 @@
+module {
+  public func migration(old : { a : Nat }) : { a : Nat; name : Text } {
+    { old with name = "" };
+  };
+};

package/tests/migrate/with-next/migrations/20250301_000000_AddEmail.mo

@@ -0,0 +1,9 @@
+module {
+  public func migration(old : { a : Nat; name : Text }) : {
+    a : Nat;
+    name : Text;
+    email : Text;
+  } {
+    { old with email = "" };
+  };
+};

package/tests/migrate/with-next/mops.toml

@@ -0,0 +1,15 @@
+[toolchain]
+moc = "1.5.0"
+
+[moc]
+args = ["--default-persistent-actors"]
+
+[canisters.backend]
+main = "src/main.mo"
+
+[canisters.backend.migrations]
+chain = "migrations"
+next = "next-migration"
+
+[canisters.backend.check-stable]
+path = "deployed.most"

package/tests/migrate/with-next/next-migration/20250401_000000_RenameId.mo

@@ -0,0 +1,9 @@
+module {
+  public func migration(old : { a : Nat; name : Text; email : Text }) : {
+    id : Nat;
+    name : Text;
+    email : Text;
+  } {
+    { id = old.a; name = old.name; email = old.email };
+  };
+};

package/tests/migrate/with-next/src/main.mo

@@ -0,0 +1,11 @@
+import Prim "mo:prim";
+
+actor {
+  let id : Nat;
+  let name : Text;
+  let email : Text;
+
+  public func check() : async () {
+    Prim.debugPrint(debug_show { id; name; email });
+  };
+};

package/tests/migrate.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, test, afterEach } from "@jest/globals";
+import { readdirSync, readFileSync } from "node:fs";
+import { cp, rm, writeFile } from "node:fs/promises";
+import path from "path";
+import { cli, cliSnapshot, normalizePaths } from "./helpers";
+
+const normalizeTimestamp = (text: string) =>
+  text.replace(/\d{8}_\d{6}/g, "<TIMESTAMP>");
+
+const fixturesDir = path.join(import.meta.dirname, "migrate");
+
+describe("migrate", () => {
+  const tempDirs: string[] = [];
+
+  async function makeTempFixture(fixture: string): Promise<string> {
+    const src = path.join(fixturesDir, fixture);
+    const dest = path.join(fixturesDir, `_tmp_${fixture}_${Date.now()}`);
+    await cp(src, dest, { recursive: true });
+    tempDirs.push(dest);
+    return dest;
+  }
+
+  async function patchMigrations(cwd: string, extra: string): Promise<void> {
+    const tomlPath = path.join(cwd, "mops.toml");
+    const toml = readFileSync(tomlPath, "utf-8");
+    await writeFile(
+      tomlPath,
+      toml.replace(
+        'next = "next-migration"',
+        `next = "next-migration"\n${extra}`,
+      ),
+    );
+  }
+
+  afterEach(async () => {
+    for (const dir of tempDirs) {
+      await rm(dir, { recursive: true, force: true });
+    }
+    tempDirs.length = 0;
+  });
+
+  describe("migrate new", () => {
+    test("creates a migration file with timestamp and template", async () => {
+      const cwd = await makeTempFixture("basic");
+      const result = await cli(["migrate", "new", "AddPhone"], { cwd });
+      expect(result.exitCode).toBe(0);
+
+      const nextDir = path.join(cwd, "next-migration");
+      const files = readdirSync(nextDir).filter((f) => f.endsWith(".mo"));
+      expect(files).toHaveLength(1);
+      expect(files[0]).toMatch(/^\d{8}_\d{6}_AddPhone\.mo$/);
+
+      const content = readFileSync(path.join(nextDir, files[0]!), "utf-8");
+
+      expect({
+        exitCode: result.exitCode,
+        stdout: normalizeTimestamp(normalizePaths(result.stdout)),
+        stderr: normalizePaths(result.stderr),
+        template: content,
+      }).toMatchSnapshot();
+    });
+
+    test("errors when next already has a file", async () => {
+      const cwd = await makeTempFixture("basic");
+      await cli(["migrate", "new", "First"], { cwd });
+      const result = await cli(["migrate", "new", "Second"], { cwd });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toMatch(/next migration already exists/i);
+    });
+
+    test("errors on invalid migration name", async () => {
+      const cwd = await makeTempFixture("basic");
+      for (const name of ["../evil", "has space", "123start", "foo/bar"]) {
+        const result = await cli(["migrate", "new", name], { cwd });
+        expect(result.exitCode).toBe(1);
+        expect(result.stderr).toMatch(/invalid migration name/i);
+      }
+    });
+
+    test("errors when [migrations] not configured", async () => {
+      const cwd = await makeTempFixture("basic");
+      const tomlPath = path.join(cwd, "mops.toml");
+      const toml = readFileSync(tomlPath, "utf-8");
+      await writeFile(
+        tomlPath,
+        toml.replace(/\[canisters\.backend\.migrations\][\s\S]*$/, ""),
+      );
+      const result = await cli(["migrate", "new", "Test"], { cwd });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toMatch(/\[migrations\]/i);
+    });
+  });
+
+  describe("migrate freeze", () => {
+    test("moves the file from next to chain", async () => {
+      const cwd = await makeTempFixture("with-next");
+      const result = await cli(["migrate", "freeze"], { cwd });
+      expect(result.exitCode).toBe(0);
+
+      const nextFiles = readdirSync(path.join(cwd, "next-migration")).filter(
+        (f) => f.endsWith(".mo"),
+      );
+      expect(nextFiles).toHaveLength(0);
+
+      const chainFiles = readdirSync(path.join(cwd, "migrations")).filter((f) =>
+        f.endsWith(".mo"),
+      );
+      expect(chainFiles).toContain("20250401_000000_RenameId.mo");
+
+      expect({
+        exitCode: result.exitCode,
+        stdout: normalizePaths(result.stdout),
+        stderr: normalizePaths(result.stderr),
+      }).toMatchSnapshot();
+    });
+
+    test("errors when next is empty", async () => {
+      const cwd = await makeTempFixture("basic");
+      const result = await cli(["migrate", "freeze"], { cwd });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toMatch(/no next migration/i);
+    });
+
+    test("errors when next-migration does not sort last", async () => {
+      const cwd = await makeTempFixture("basic");
+      await writeFile(
+        path.join(cwd, "next-migration", "00000000_000000_Early.mo"),
+        "module {\n  public func migration(_ : {}) : {} {\n    {}\n  }\n}\n",
+      );
+      const result = await cli(["migrate", "freeze"], { cwd });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toMatch(/must sort after/i);
+    });
+  });
+
+  describe("check", () => {
+    test("check fails without next migration, passes with it", async () => {
+      const cwd = await makeTempFixture("with-next");
+      const nextFile = readdirSync(path.join(cwd, "next-migration")).find((f) =>
+        f.endsWith(".mo"),
+      )!;
+      const nextPath = path.join(cwd, "next-migration", nextFile);
+      const nextContent = readFileSync(nextPath, "utf-8");
+      await rm(nextPath);
+
+      await cliSnapshot(["check"], { cwd }, 1);
+
+      await writeFile(nextPath, nextContent);
+      await cliSnapshot(["check"], { cwd }, 0);
+    });
+
+    test("check with trimming shows reduced chain", async () => {
+      const cwd = await makeTempFixture("basic");
+      await patchMigrations(cwd, "check-limit = 2");
+      await cliSnapshot(["check", "--verbose"], { cwd }, 0);
+    });
+  });
+
+  describe("build", () => {
+    test("build produces .most with full migration chain", async () => {
+      const cwd = await makeTempFixture("basic");
+      const result = await cli(["build"], { cwd });
+      expect(result.exitCode).toBe(0);
+
+      const most = readFileSync(
+        path.join(cwd, ".mops", ".build", "backend.most"),
+        "utf-8",
+      );
+      expect(most).toMatchSnapshot();
+    });
+
+    test("build with build-limit produces trimmed .most", async () => {
+      const cwd = await makeTempFixture("basic");
+      await patchMigrations(cwd, "build-limit = 2");
+      const result = await cli(["build"], { cwd });
+      expect(result.exitCode).toBe(0);
+
+      const most = readFileSync(
+        path.join(cwd, ".mops", ".build", "backend.most"),
+        "utf-8",
+      );
+      expect(most).toMatchSnapshot();
+    });
+
+    test("build-limit counts next migration as part of the chain", async () => {
+      const cwd = await makeTempFixture("with-next");
+      await patchMigrations(cwd, "build-limit = 2");
+      const result = await cli(["build"], { cwd });
+      expect(result.exitCode).toBe(0);
+
+      const most = readFileSync(
+        path.join(cwd, ".mops", ".build", "backend.most"),
+        "utf-8",
+      );
+      expect(most).toMatchSnapshot();
+    });
+  });
+
+  describe("stable check hint", () => {
+    test("stable check fails with hint when deployed.most is incompatible", async () => {
+      const cwd = await makeTempFixture("basic");
+      await writeFile(
+        path.join(cwd, "deployed.most"),
+        "// Version: 1.0.0\nactor {\n  stable var a : Nat;\n  stable var name : Int\n};\n",
+      );
+      await cliSnapshot(["check"], { cwd }, 1);
+    });
+  });
+
+  describe("conflict detection", () => {
+    test("errors when both [migrations] and --enhanced-migration in args", async () => {
+      const cwd = await makeTempFixture("basic");
+      const tomlPath = path.join(cwd, "mops.toml");
+      const toml = readFileSync(tomlPath, "utf-8");
+      await writeFile(
+        tomlPath,
+        toml.replace(
+          "[canisters.backend.migrations]",
+          'args = ["--enhanced-migration=migrations"]\n\n[canisters.backend.migrations]',
+        ),
+      );
+      const result = await cli(["check"], { cwd });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toMatch(/--enhanced-migration/);
+      expect(result.stderr).toMatch(/managed automatically/i);
+    });
+  });
+});

package/types.ts

@@ -35,6 +35,13 @@ export type Config = {
   };
 };
 
+export type MigrationsConfig = {
+  chain: string;
+  next?: string;
+  "check-limit"?: number;
+  "build-limit"?: number;
+};
+
 export type CanisterConfig = {
   main?: string;
   args?: string[];
@@ -44,6 +51,7 @@ export type CanisterConfig = {
     path: string;
     skipIfMissing?: boolean;
   };
+  migrations?: MigrationsConfig;
 };
 
 export type Dependencies = Record<string, Dependency>;