fix(migrate): skip staging when window is exactly the pending next migration (#503)

## Problem

When `[canisters.<name>.migrations]` triggers staging (a pending `next`
migration, or `check-limit`/`build-limit` trimming the chain), mops
creates a temp `.migrations-<canister>/` directory of symlinks and
points moc at it. Errors look like:

```
.migrations-backend/20250401_000000_RenameId.mo:4.12-4.19: type error [M0050] ...
```

The staged dir is `rm -rf`-ed in a `finally` before the process exits,
so by the time the user reads the error the path no longer resolves —
editor jump-to-error fails, and CI logs contain a path that looks like
an internal artifact.

## Why staging exists

`moc --enhanced-migration` takes a single directory. When the active
window straddles `chain/` and `next-migration/`, or when trimming hides
files inside `chain/`, mops needs a synthesized directory holding
exactly the files moc should see.

## Fix

When moc only needs the pending `next` migration — empty chain, or
`check-limit = 1` with a pending next — there's nothing to merge. Point
moc at `next-migration/` directly:

Before:
```
.migrations-backend/20250401_000000_RenameId.mo:4.12-4.19: type error [M0050] ...
```

After:
```
next-migration/20250401_000000_RenameId.mo:4.12-4.19: type error [M0050] ...
```

This covers the common dev-loop case (writing a new migration with
`check-limit = 1`) and the first-migration case (no frozen chain yet).
Every other trimming / merge case still stages — diagnostics there
continue to print the `.migrations-backend/...` path.

## Test plan

- [x] `check-limit=1 with pending next reports real next-migration path
on error` — pins the trimmed-to-1 branch
- [x] `empty chain with pending next reports real next-migration path on
error` — pins the empty-chain branch
- [x] `error inside a chain migration reports its file location` — pins
the staged-path behavior for the cases that still stage
- [x] `npm test -- --testPathPatterns=migrate.test.ts` — 19/19 pass
- [x] `npm run check` — clean
- [x] Pre-existing `build.test.ts` failures verified unrelated (stash +
retest on `main`)

Author: Kamirus

.agents/skills/mops-cli/SKILL.md

@@ -146,6 +146,8 @@ When `[canisters.<name>.migrations]` is configured, `mops check`, `mops build`,
 
 `chain` and `next` must live in the same parent directory. Migration files can import from sibling folders via relative paths (e.g. shared types in `src/backend/types/`); mops stages the active chain into `<parent-of-chain>/.migrations-<canister>/`, preserving depth so relative imports resolve identically. The staged dir self-stamps a `.gitignore`; `mops init` also adds `.migrations-*/` to the project `.gitignore`.
 
+`moc` diagnostics may print paths under `.migrations-<canister>/` — a staging dir that mops removes when the command finishes. The real file has the same name under `chain/` or `next/`.
+
 Typical workflow: make a breaking change → `mops check` fails with a hint → `mops migrate new Name` → edit migration → `mops check` passes → `mops build` → deploy → `mops migrate freeze`.
 
 ### `mops remove <package>`

cli/CHANGELOG.md

@@ -1,6 +1,7 @@
 # Mops CLI Changelog
 
 ## Next
+- `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`

cli/helpers/migrations.ts

@@ -153,6 +153,16 @@ export async function prepareMigrationArgs(
     };
   }
 
+  // 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 });

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

@@ -85,6 +85,42 @@ check-stable Comparing deployed.most ↔ .mops/.check-stable/new.most
 }
 `;
 
+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,

cli/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", () => {

docs/docs/09-mops.toml.md

@@ -167,6 +167,8 @@ When `[migrations]` is configured, do not add `--enhanced-migration` to `[canist
 
 :::note
 When a `next` migration exists or chain trimming is active, mops stages the active chain into `<parent-of-chain>/.migrations-<canister>/` for compilation. This keeps the staged files at the same depth as the originals so relative imports (e.g. a shared `types/` folder next to `chain` and `next`) resolve identically. The staged dir self-stamps a `.gitignore`, and `mops init` adds `.migrations-*/` to the project `.gitignore`.
+
+`moc` diagnostics may point to a staged path under `.migrations-<canister>/`, which mops removes when the command finishes.
 :::
 
 Shorthand — when only the entrypoint is needed:

docs/docs/cli/4-dev/08-mops-migrate.md

@@ -61,6 +61,8 @@ build-limit = 100
 
 `chain` and `next` must live in the same parent directory. Migration files can import from sibling folders (e.g. a shared `types/` folder) using relative paths — mops stages the active chain into `<parent-of-chain>/.migrations-<canister>/` for compilation, preserving the depth of the originals so relative imports resolve identically. The staged dir self-stamps a `.gitignore`, and `mops init` adds `.migrations-*/` to the project `.gitignore`.
 
+`moc` diagnostics may point to a staged path under `.migrations-<canister>/`, which mops removes when the command finishes.
+
 See [`mops.toml` reference](/mops.toml#canistersnamemigrations) for all fields.
 
 ## Typical workflow