ic-mops 2.10.0 → 2.12.0

package/tests/__snapshots__/migrate.test.ts.snap

@@ -0,0 +1,119 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`migrate build build produces .most with full migration chain 1`] = `
+"// 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
+};
+"
+`;
+
+exports[`migrate build build with build-limit produces trimmed .most 1`] = `
+"// Version: 4.0.0
+{
+  "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
+};
+"
+`;
+
+exports[`migrate build build-limit counts next migration as part of the chain 1`] = `
+"// Version: 4.0.0
+type V2__933402648 = {a : Nat; name : Text};
+type V3__40989327 = {a : Nat; email : Text; name : Text};
+type V4__364034734 = {email : Text; id : Nat; name : Text};
+{
+  "20250301_000000_AddEmail" : (old : V2__933402648) -> V3__40989327;
+  "20250401_000000_RenameId" : (old : V3__40989327) -> V4__364034734
+}
+actor  {
+  stable email : Text;
+  stable id : Nat;
+  stable name : Text
+};
+"
+`;
+
+exports[`migrate check check fails without next migration, passes with it 1`] = `
+{
+  "exitCode": 1,
+  "stderr": "src/main.mo:3.1-11.2: Compatibility error [M0169], the stable variable \`a\` of version \`20250301_000000_AddEmail\` cannot be implicitly discarded. The variable can only be dropped by an explicit migration function, please see https://internetcomputer.org/docs/motoko/fundamentals/actors/compatibility#explicit-migration-using-a-migration-function
+migrations/20250101_000000_Init.mo:0.1: warning [M0254], initial actor requires field \`id\` of type
+  Nat
+✗ Check failed for canister backend (exit code: 1)",
+  "stdout": "",
+}
+`;
+
+exports[`migrate check check fails without next migration, passes with it 2`] = `
+{
+  "exitCode": 0,
+  "stderr": "",
+  "stdout": "✓ backend
+✓ Stable compatibility check passed for canister 'backend'",
+}
+`;
+
+exports[`migrate check check with trimming shows reduced chain 1`] = `
+{
+  "exitCode": 0,
+  "stderr": "",
+  "stdout": "check Using --all-libs for richer diagnostics
+migrations Prepared 2 migration(s) for backend (trimmed from 3)
+check Checking canister backend:
+<CACHE>moc-wrapper ["src/main.mo","--check","--all-libs","--default-persistent-actors","--enhanced-migration=.migrations-backend","-A=M0254"]
+✓ backend
+check-stable Generating stable types for src/main.mo
+<CACHE>moc-wrapper ["--stable-types","-o",".mops/.check-stable/new.wasm","src/main.mo","--default-persistent-actors","--enhanced-migration=.migrations-backend","-A=M0254"]
+check-stable Comparing deployed.most ↔ .mops/.check-stable/new.most
+<CACHE>moc-wrapper ["--stable-compatible","deployed.most",".mops/.check-stable/new.most"]
+✓ Stable compatibility check passed for canister 'backend'",
+}
+`;
+
+exports[`migrate migrate freeze moves the file from next to chain 1`] = `
+{
+  "exitCode": 0,
+  "stderr": "",
+  "stdout": "✓ Frozen migration: 20250401_000000_RenameId.mo → migrations/",
+}
+`;
+
+exports[`migrate migrate new creates a migration file with timestamp and template 1`] = `
+{
+  "exitCode": 0,
+  "stderr": "",
+  "stdout": "✓ Created migration: next-migration/<TIMESTAMP>_AddPhone.mo",
+  "template": "module {
+  public func migration(old : {}) : {} {
+    {}
+  }
+}
+",
+}
+`;
+
+exports[`migrate stable check hint stable check fails with hint when deployed.most is incompatible 1`] = `
+{
+  "exitCode": 1,
+  "stderr": "(unknown location): Compatibility error [M0169], the stable variable \`a\` of the previous version cannot be implicitly discarded. The variable can only be dropped by an explicit migration function, please see https://internetcomputer.org/docs/motoko/fundamentals/actors/compatibility#explicit-migration-using-a-migration-function
+(unknown location): Compatibility error [M0169], the stable variable \`name\` of the previous version cannot be implicitly discarded. The variable can only be dropped by an explicit migration function, please see https://internetcomputer.org/docs/motoko/fundamentals/actors/compatibility#explicit-migration-using-a-migration-function
+Hint: You may need a migration. Run \`mops migrate new <Name>\` to create one.
+✗ Stable compatibility check failed for canister 'backend'",
+  "stdout": "✓ backend",
+}
+`;

package/tests/migrate/basic/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/basic/migrations/20250101_000000_Init.mo

@@ -0,0 +1,5 @@
+module {
+  public func migration(_ : {}) : { a : Nat } {
+    { a = 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,7 @@
+import State "../types/State";
+
+module {
+  public func migration(_ : State.V0) : State.V1 {
+    { a = 0 };
+  };
+};

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

@@ -0,0 +1,7 @@
+import State "../types/State";
+
+module {
+  public func migration(old : State.V1) : State.V2 {
+    { old with name = "" };
+  };
+};

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

@@ -0,0 +1,7 @@
+import State "../types/State";
+
+module {
+  public func migration(old : State.V2) : State.V3 {
+    { 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,7 @@
+import State "../types/State";
+
+module {
+  public func migration(old : State.V3) : State.V4 {
+    { 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/with-next/types/State.mo

@@ -0,0 +1,7 @@
+module {
+  public type V0 = {};
+  public type V1 = { a : Nat };
+  public type V2 = { a : Nat; name : Text };
+  public type V3 = { a : Nat; name : Text; email : Text };
+  public type V4 = { id : Nat; name : Text; email : Text };
+};

package/tests/migrate.test.ts

@@ -0,0 +1,255 @@
+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("sibling validation", () => {
+    async function patchNextDir(cwd: string, nextValue: 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 = "${nextValue}"`),
+      );
+    }
+
+    test("errors from `mops check` when chain and next have different parents", async () => {
+      const cwd = await makeTempFixture("with-next");
+      await patchNextDir(cwd, "other/next-migration");
+      const result = await cli(["check"], { cwd });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toMatch(/same parent directory/i);
+    });
+
+    test("errors from `mops migrate new` too — validation runs in every entry point", async () => {
+      const cwd = await makeTempFixture("basic");
+      await patchNextDir(cwd, "other/next-migration");
+      const result = await cli(["migrate", "new", "Test"], { cwd });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toMatch(/same parent directory/i);
+    });
+  });
+
+  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>;