ic-mops 2.11.0 → 2.12.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Next
 
+## 2.12.1
+- `mops check`/`build`/`check-stable` skip migration staging when only the pending `next` migration is needed, so `moc` diagnostics reference the real `next-migration/<file>` path.
+
+## 2.12.0
+- Migration staging directory moved from `.mops/.migrations/<canister>/` to `<parent-of-chain>/.migrations-<canister>/`, so migration files can import shared modules from sibling folders (e.g. a `types/` folder next to `migrations/`) — relative imports now resolve to the same target whether moc reads the original chain dir or the staged one. The staged dir self-stamps a `.gitignore` so it doesn't pollute `git status`; `mops init` now also adds `.migrations-*/` to the project `.gitignore`
+- `[canisters.<name>.migrations]` now requires `chain` and `next` to share the same parent directory (any layout where the parents differed is rejected with a clear error). The default layout `chain = "migrations"` + `next = "next-migration"` already satisfies this. For per-canister setups, use sibling subdirectories, e.g. `chain = "src/backend/migrations"` + `next = "src/backend/next-migration"`
+
 ## 2.11.0
 - Add `mops migrate new <Name>` and `mops migrate freeze` commands for managing enhanced migration chains
 - Add `[canisters.<name>.migrations]` config section with `chain`, `next`, `check-limit`, and `build-limit` fields

package/commands/init.ts

@@ -282,16 +282,29 @@ async function applyInit({
     await template("github-workflow:mops-test");
   }
 
-  // add .mops to .gitignore
+  // add mops-managed paths to .gitignore
   {
     let gitignore = path.join(process.cwd(), ".gitignore");
     let gitignoreData = existsSync(gitignore)
       ? readFileSync(gitignore).toString()
       : "";
-    let lf = gitignoreData.endsWith("\n") ? "\n" : "";
+    const additions: string[] = [];
     if (!gitignoreData.includes(".mops")) {
-      writeFileSync(gitignore, `${gitignoreData}\n.mops${lf}`.trimStart());
-      console.log(chalk.green("Added"), ".mops to .gitignore");
+      additions.push(".mops");
+    }
+    if (!gitignoreData.includes(".migrations-")) {
+      additions.push(".migrations-*/");
+    }
+    if (additions.length > 0) {
+      let lf = gitignoreData.endsWith("\n") ? "\n" : "";
+      writeFileSync(
+        gitignore,
+        `${gitignoreData}\n${additions.join("\n")}${lf}`.trimStart(),
+      );
+      console.log(
+        chalk.green("Added"),
+        `${additions.join(", ")} to .gitignore`,
+      );
     }
   }
 

package/dist/commands/init.js

@@ -226,16 +226,23 @@ async function applyInit({ type, config, setupWorkflow, addTest, copyrightOwner,
     if (setupWorkflow) {
         await template("github-workflow:mops-test");
     }
-    // add .mops to .gitignore
+    // add mops-managed paths to .gitignore
     {
         let gitignore = path.join(process.cwd(), ".gitignore");
         let gitignoreData = existsSync(gitignore)
             ? readFileSync(gitignore).toString()
             : "";
-        let lf = gitignoreData.endsWith("\n") ? "\n" : "";
+        const additions = [];
         if (!gitignoreData.includes(".mops")) {
-            writeFileSync(gitignore, `${gitignoreData}\n.mops${lf}`.trimStart());
-            console.log(chalk.green("Added"), ".mops to .gitignore");
+            additions.push(".mops");
+        }
+        if (!gitignoreData.includes(".migrations-")) {
+            additions.push(".migrations-*/");
+        }
+        if (additions.length > 0) {
+            let lf = gitignoreData.endsWith("\n") ? "\n" : "";
+            writeFileSync(gitignore, `${gitignoreData}\n${additions.join("\n")}${lf}`.trimStart());
+            console.log(chalk.green("Added"), `${additions.join(", ")} to .gitignore`);
         }
     }
     // install deps

package/dist/helpers/migrations.js

@@ -1,10 +1,12 @@
-import { existsSync, mkdirSync, readdirSync, symlinkSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, symlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { rm } from "node:fs/promises";
 import chalk from "chalk";
 import { cliError } from "../error.js";
-import { resolveConfigPath } from "../mops.js";
-const MIGRATIONS_TEMP_DIR = ".mops/.migrations";
+import { getRootDir, resolveConfigPath } from "../mops.js";
+function stagedMigrationsDir(chainDir, canisterName) {
+    return join(dirname(chainDir), `.migrations-${canisterName}`);
+}
 export function getMigrationFiles(dir) {
     if (!existsSync(dir)) {
         return [];
@@ -44,6 +46,19 @@ export function validateMigrationsConfig(migrations, canisterName) {
             cliError(`[canisters.${canisterName}.migrations] ${field} must be a positive integer`);
         }
     }
+    if (migrations.next) {
+        const parentOf = (p) => dirname(resolve(getRootDir(), p));
+        const chainParent = parentOf(migrations.chain);
+        const nextParent = parentOf(migrations.next);
+        if (chainParent !== nextParent) {
+            cliError(`[canisters.${canisterName}.migrations] "chain" and "next" must live in the same parent directory.\n` +
+                `  chain = "${migrations.chain}" (parent: ${chainParent})\n` +
+                `  next  = "${migrations.next}" (parent: ${nextParent})\n` +
+                "Place them in the same parent directory, e.g.:\n" +
+                '  chain = "migrations"\n' +
+                '  next  = "next-migration"');
+        }
+    }
 }
 export async function prepareMigrationArgs(migrations, canisterName, mode, verbose) {
     const noOp = {
@@ -83,9 +98,19 @@ export async function prepareMigrationArgs(migrations, canisterName, mode, verbo
             cleanup: async () => { },
         };
     }
-    const tempDir = join(MIGRATIONS_TEMP_DIR, canisterName);
+    // Shortcut: when only the pending next migration is needed (empty chain or
+    // trimmed to 1), point moc at next-migration/ so diagnostics use the real path.
+    if (nextFile && nextDir && (chainFiles.length === 0 || limit === 1)) {
+        const migrationArgs = [`--enhanced-migration=${nextDir}`];
+        if (isTrimming) {
+            migrationArgs.push("-A=M0254");
+        }
+        return { migrationArgs, cleanup: async () => { } };
+    }
+    const tempDir = stagedMigrationsDir(chainDir, canisterName);
     await rm(tempDir, { recursive: true, force: true });
     mkdirSync(tempDir, { recursive: true });
+    writeFileSync(join(tempDir, ".gitignore"), "*\n");
     const filesToInclude = isTrimming
         ? allMigrations.slice(-limit)
         : allMigrations;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ic-mops",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "type": "module",
   "bin": {
     "mops": "bin/mops.js",

package/dist/tests/migrate.test.js

@@ -112,6 +112,41 @@ describe("migrate", () => {
             await patchMigrations(cwd, "check-limit = 2");
             await cliSnapshot(["check", "--verbose"], { cwd }, 0);
         });
+        test("error inside a chain migration reports its file location", async () => {
+            const cwd = await makeTempFixture("with-next");
+            await writeFile(path.join(cwd, "migrations", "20250301_000000_AddEmail.mo"), 'import State "../types/State";\n' +
+                "module {\n" +
+                "  public func migration(old : State.V2) : State.V3 {\n" +
+                "    { old with email = 42 };\n" +
+                "  };\n" +
+                "};\n");
+            await cliSnapshot(["check"], { cwd }, 1);
+        });
+        async function corruptNextMigration(cwd) {
+            const nextDir = path.join(cwd, "next-migration");
+            const nextFile = readdirSync(nextDir).find((f) => f.endsWith(".mo"));
+            await writeFile(path.join(nextDir, nextFile), 'import State "../types/State";\n' +
+                "module {\n" +
+                "  public func migration(old : State.V3) : State.V4 {\n" +
+                '    { id = "wrong"; name = old.name; email = old.email };\n' +
+                "  };\n" +
+                "};\n");
+        }
+        test("check-limit=1 with pending next reports real next-migration path on error", async () => {
+            const cwd = await makeTempFixture("with-next");
+            await patchMigrations(cwd, "check-limit = 1");
+            await corruptNextMigration(cwd);
+            await cliSnapshot(["check"], { cwd }, 1);
+        });
+        test("empty chain with pending next reports real next-migration path on error", async () => {
+            const cwd = await makeTempFixture("with-next");
+            const chainDir = path.join(cwd, "migrations");
+            for (const f of readdirSync(chainDir).filter((f) => f.endsWith(".mo"))) {
+                await rm(path.join(chainDir, f));
+            }
+            await corruptNextMigration(cwd);
+            await cliSnapshot(["check"], { cwd }, 1);
+        });
     });
     describe("build", () => {
         test("build produces .most with full migration chain", async () => {
@@ -145,6 +180,27 @@ describe("migrate", () => {
             await cliSnapshot(["check"], { cwd }, 1);
         });
     });
+    describe("sibling validation", () => {
+        async function patchNextDir(cwd, nextValue) {
+            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");

package/helpers/migrations.ts

@@ -1,12 +1,20 @@
-import { existsSync, mkdirSync, readdirSync, symlinkSync } from "node:fs";
-import { join, resolve } from "node:path";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { rm } from "node:fs/promises";
 import chalk from "chalk";
 import { cliError } from "../error.js";
-import { resolveConfigPath } from "../mops.js";
+import { getRootDir, resolveConfigPath } from "../mops.js";
 import { MigrationsConfig } from "../types.js";
 
-const MIGRATIONS_TEMP_DIR = ".mops/.migrations";
+function stagedMigrationsDir(chainDir: string, canisterName: string): string {
+  return join(dirname(chainDir), `.migrations-${canisterName}`);
+}
 
 export interface MigrationArgsResult {
   migrationArgs: string[];
@@ -70,6 +78,21 @@ export function validateMigrationsConfig(
       );
     }
   }
+  if (migrations.next) {
+    const parentOf = (p: string) => dirname(resolve(getRootDir(), p));
+    const chainParent = parentOf(migrations.chain);
+    const nextParent = parentOf(migrations.next);
+    if (chainParent !== nextParent) {
+      cliError(
+        `[canisters.${canisterName}.migrations] "chain" and "next" must live in the same parent directory.\n` +
+          `  chain = "${migrations.chain}" (parent: ${chainParent})\n` +
+          `  next  = "${migrations.next}" (parent: ${nextParent})\n` +
+          "Place them in the same parent directory, e.g.:\n" +
+          '  chain = "migrations"\n' +
+          '  next  = "next-migration"',
+      );
+    }
+  }
 }
 
 export async function prepareMigrationArgs(
@@ -130,9 +153,20 @@ export async function prepareMigrationArgs(
     };
   }
 
-  const tempDir = join(MIGRATIONS_TEMP_DIR, canisterName);
+  // Shortcut: when only the pending next migration is needed (empty chain or
+  // trimmed to 1), point moc at next-migration/ so diagnostics use the real path.
+  if (nextFile && nextDir && (chainFiles.length === 0 || limit === 1)) {
+    const migrationArgs = [`--enhanced-migration=${nextDir}`];
+    if (isTrimming) {
+      migrationArgs.push("-A=M0254");
+    }
+    return { migrationArgs, cleanup: async () => {} };
+  }
+
+  const tempDir = stagedMigrationsDir(chainDir, canisterName);
   await rm(tempDir, { recursive: true, force: true });
   mkdirSync(tempDir, { recursive: true });
+  writeFileSync(join(tempDir, ".gitignore"), "*\n");
 
   const filesToInclude = isTrimming
     ? allMigrations.slice(-limit)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ic-mops",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "type": "module",
   "bin": {
     "mops": "dist/bin/mops.js",

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

@@ -33,12 +33,12 @@ actor  {
 
 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 : {a : Nat; name : Text}) -> {a : Nat; email : Text; name : Text};
-  "20250401_000000_RenameId" :
-    (old : {a : Nat; email : Text; name : Text}) ->
-      {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;
@@ -75,16 +75,52 @@ exports[`migrate check check with trimming shows reduced chain 1`] = `
   "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=.mops/.migrations/backend","-A=M0254"]
+<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=.mops/.migrations/backend","-A=M0254"]
+<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 check check-limit=1 with pending next reports real next-migration path on error 1`] = `
+{
+  "exitCode": 1,
+  "stderr": "next-migration/20250401_000000_RenameId.mo:4.12-4.19: type error [M0050], literal of type
+  Text
+does not have expected type
+  Nat
+✗ Check failed for canister backend (exit code: 1)",
+  "stdout": "",
+}
+`;
+
+exports[`migrate check empty chain with pending next reports real next-migration path on error 1`] = `
+{
+  "exitCode": 1,
+  "stderr": "next-migration/20250401_000000_RenameId.mo:4.12-4.19: type error [M0050], literal of type
+  Text
+does not have expected type
+  Nat
+✗ Check failed for canister backend (exit code: 1)",
+  "stdout": "",
+}
+`;
+
+exports[`migrate check error inside a chain migration reports its file location 1`] = `
+{
+  "exitCode": 1,
+  "stderr": ".migrations-backend/20250301_000000_AddEmail.mo:4.24-4.26: type error [M0050], literal of type
+  Nat
+does not have expected type
+  Text
+✗ Check failed for canister backend (exit code: 1)",
+  "stdout": "",
+}
+`;
+
 exports[`migrate migrate freeze moves the file from next to chain 1`] = `
 {
   "exitCode": 0,

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

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

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

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

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

@@ -1,9 +1,7 @@
+import State "../types/State";
+
 module {
-  public func migration(old : { a : Nat; name : Text }) : {
-    a : Nat;
-    name : Text;
-    email : Text;
-  } {
+  public func migration(old : State.V2) : State.V3 {
     { old with email = "" };
   };
 };

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

@@ -1,9 +1,7 @@
+import State "../types/State";
+
 module {
-  public func migration(old : { a : Nat; name : Text; email : Text }) : {
-    id : Nat;
-    name : Text;
-    email : Text;
-  } {
+  public func migration(old : State.V3) : State.V4 {
     { id = old.a; name = old.name; email = old.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

@@ -154,6 +154,51 @@ describe("migrate", () => {
       await patchMigrations(cwd, "check-limit = 2");
       await cliSnapshot(["check", "--verbose"], { cwd }, 0);
     });
+
+    test("error inside a chain migration reports its file location", async () => {
+      const cwd = await makeTempFixture("with-next");
+      await writeFile(
+        path.join(cwd, "migrations", "20250301_000000_AddEmail.mo"),
+        'import State "../types/State";\n' +
+          "module {\n" +
+          "  public func migration(old : State.V2) : State.V3 {\n" +
+          "    { old with email = 42 };\n" +
+          "  };\n" +
+          "};\n",
+      );
+      await cliSnapshot(["check"], { cwd }, 1);
+    });
+
+    async function corruptNextMigration(cwd: string): Promise<void> {
+      const nextDir = path.join(cwd, "next-migration");
+      const nextFile = readdirSync(nextDir).find((f) => f.endsWith(".mo"))!;
+      await writeFile(
+        path.join(nextDir, nextFile),
+        'import State "../types/State";\n' +
+          "module {\n" +
+          "  public func migration(old : State.V3) : State.V4 {\n" +
+          '    { id = "wrong"; name = old.name; email = old.email };\n' +
+          "  };\n" +
+          "};\n",
+      );
+    }
+
+    test("check-limit=1 with pending next reports real next-migration path on error", async () => {
+      const cwd = await makeTempFixture("with-next");
+      await patchMigrations(cwd, "check-limit = 1");
+      await corruptNextMigration(cwd);
+      await cliSnapshot(["check"], { cwd }, 1);
+    });
+
+    test("empty chain with pending next reports real next-migration path on error", async () => {
+      const cwd = await makeTempFixture("with-next");
+      const chainDir = path.join(cwd, "migrations");
+      for (const f of readdirSync(chainDir).filter((f) => f.endsWith(".mo"))) {
+        await rm(path.join(chainDir, f));
+      }
+      await corruptNextMigration(cwd);
+      await cliSnapshot(["check"], { cwd }, 1);
+    });
   });
 
   describe("build", () => {
@@ -207,6 +252,33 @@ describe("migrate", () => {
     });
   });
 
+  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");