ic-mops 2.13.0 → 2.13.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Next
 
+## 2.13.2
+- Fix race conditions when two `mops` processes run on the same project (e.g. an editor watcher and `caffeine check --fix`, or back-to-back invocations). `mops check-stable` used a shared `.mops/.check-stable/` scratch dir and `mops check`/`build`/`check-stable` used a shared `<parent>/.migrations-<canister>/` staging dir; concurrent runs would clobber each other and surface as misleading errors like `.mops/.check-stable/new.most: No such file or directory` or `EEXIST: file already exists, symlink ...`. Both directories are now per-invocation (created via `mkdtemp` and removed when the command finishes).
+- Deprecate `skipIfMissing` in `[canisters.<name>.check-stable]`. Behavior is unchanged for now, but `mops check`/`check-stable` print a warning when it is set. For initial deployments, commit a `.most` file at the configured `path` containing an empty actor (`// Version: 1.0.0\nactor { };`) instead — the stable check then runs against an empty baseline.
+- Drop the "you may need a migration" hint after a failed stable compatibility check in `mops check`/`check-stable`. The hint guessed at whether the user needed a new migration or a fix to an existing one, and `moc`'s underlying compatibility error already links to the migration docs.
+- The missing-chain-directory error from `mops check`/`build`/`check-stable` now points at adding a `.mo` file to the `chain` directory instead of running the experimental `mops migrate new <Name>` command.
+
+## 2.13.1
+- `mops lint` now honors `[canisters.<name>.migrations].check-limit`, skipping trimmed chain migrations so projects with large migration histories lint as fast as they type-check. Pass an explicit filter (`mops lint <name>`) to opt back in for a one-off lint of a trimmed file.
+
 ## 2.13.0
 - Fix `mops update` and `mops outdated` jumping across major versions (or pre-1.0 minor versions) — they are now caret-bound by default, matching `cargo update`. For example, `core = "2.0.0"` now updates within `2.x.y` instead of jumping to a future `3.0.0`. Use `--major` to opt into cross-major updates.
 

package/commands/check-stable.ts

@@ -1,5 +1,5 @@
-import { basename, join } from "node:path";
-import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import chalk from "chalk";
 import { execa } from "execa";
@@ -17,7 +17,10 @@ import {
 import { sourcesArgs } from "./sources.js";
 import { toolchain } from "./toolchain/index.js";
 
-const CHECK_STABLE_DIR = ".mops/.check-stable";
+// Per-invocation scratch dir lives under `.mops/`; `mkdtempSync` makes it unique so
+// concurrent `mops` processes don't clobber each other's `old.most`/`new.most`.
+const CHECK_STABLE_PARENT = ".mops";
+const CHECK_STABLE_PREFIX = ".check-stable-";
 
 export interface CheckStableOptions {
   verbose: boolean;
@@ -39,15 +42,25 @@ export function resolveStablePath(
     return null;
   }
   const stablePath = resolveConfigPath(stableConfig.path);
+  if (stableConfig.skipIfMissing) {
+    console.warn(
+      chalk.yellow(
+        `WARN: \`skipIfMissing\` in [canisters.${canisterName}.check-stable] is deprecated. ` +
+          `Instead, create ${stableConfig.path} with an empty actor:\n` +
+          "  // Version: 1.0.0\n" +
+          "  actor { };",
+      ),
+    );
+  }
   if (!existsSync(stablePath)) {
     if (stableConfig.skipIfMissing) {
       return null;
     }
     cliError(
       `Deployed file not found: ${stablePath} (canister '${canisterName}')\n` +
-        "Set skipIfMissing = true in [canisters." +
-        canisterName +
-        ".check-stable] to skip this check when the file is missing.",
+        `Create ${stableConfig.path} with an empty actor to enable the check:\n` +
+        "  // Version: 1.0.0\n" +
+        "  actor { };",
     );
   }
   return stablePath;
@@ -88,7 +101,6 @@ export async function checkStable(
         globalMocArgs,
         canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
         options,
-        hasMigrations: !!canister.migrations,
       });
     } finally {
       await migration.cleanup();
@@ -131,7 +143,6 @@ export async function checkStable(
         canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
         sources,
         options,
-        hasMigrations: !!canister.migrations,
       });
     } finally {
       await migration.cleanup();
@@ -159,7 +170,6 @@ export interface RunStableCheckParams {
   canisterArgs: string[];
   sources?: string[];
   options?: Partial<CheckStableOptions>;
-  hasMigrations?: boolean;
 }
 
 export async function runStableCheck(
@@ -182,15 +192,17 @@ export async function runStableCheck(
     cliError(`File not found: ${oldFile}`);
   }
 
-  await rm(CHECK_STABLE_DIR, { recursive: true, force: true });
-  mkdirSync(CHECK_STABLE_DIR, { recursive: true });
+  mkdirSync(CHECK_STABLE_PARENT, { recursive: true });
+  const scratchDir = mkdtempSync(
+    join(CHECK_STABLE_PARENT, CHECK_STABLE_PREFIX),
+  );
   try {
     const oldMostPath = isOldMostFile
       ? oldFile
       : await generateStableTypes(
           mocPath,
           oldFile,
-          join(CHECK_STABLE_DIR, "old.most"),
+          join(scratchDir, "old.most"),
           sources,
           globalMocArgs,
           canisterArgs,
@@ -200,7 +212,7 @@ export async function runStableCheck(
     const newMostPath = await generateStableTypes(
       mocPath,
       canisterMain,
-      join(CHECK_STABLE_DIR, "new.most"),
+      join(scratchDir, "new.most"),
       sources,
       globalMocArgs,
       canisterArgs,
@@ -228,13 +240,6 @@ export async function runStableCheck(
       if (result.stderr) {
         console.error(result.stderr);
       }
-      if (params.hasMigrations) {
-        console.error(
-          chalk.yellow(
-            "Hint: You may need a migration. Run `mops migrate new <Name>` to create one.",
-          ),
-        );
-      }
       cliError(
         `✗ Stable compatibility check failed for canister '${canisterName}'`,
       );
@@ -246,7 +251,7 @@ export async function runStableCheck(
       ),
     );
   } finally {
-    await rm(CHECK_STABLE_DIR, { recursive: true, force: true });
+    await rm(scratchDir, { recursive: true, force: true });
   }
 }
 
@@ -259,8 +264,7 @@ async function generateStableTypes(
   canisterArgs: string[],
   options: Partial<CheckStableOptions>,
 ): Promise<string> {
-  const base = basename(outputPath, ".most");
-  const wasmPath = join(CHECK_STABLE_DIR, base + ".wasm");
+  const wasmPath = outputPath.replace(/\.most$/, ".wasm");
   const args = [
     "--stable-types",
     "-o",

package/commands/check.ts

@@ -216,7 +216,6 @@ async function checkCanisters(
           canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
           sources,
           options: { verbose: options.verbose, extraArgs: options.extraArgs },
-          hasMigrations: !!canister.migrations,
         });
       }
     } finally {

package/commands/lint.ts

@@ -15,6 +15,7 @@ import { toolchain } from "./toolchain/index.js";
 import { MOTOKO_GLOB_CONFIG } from "../constants.js";
 import { existsSync } from "node:fs";
 import { Config } from "../types.js";
+import { getTrimmedMigrationFiles } from "../helpers/migrations.js";
 
 async function resolveDepRules(
   config: Config,
@@ -128,6 +129,17 @@ function buildCommonArgs(
   return args;
 }
 
+function dropTrimmedMigrations(
+  files: string[],
+  rootDir: string,
+  excluded: Set<string>,
+): string[] {
+  if (excluded.size === 0) {
+    return files;
+  }
+  return files.filter((f) => !excluded.has(path.resolve(rootDir, f)));
+}
+
 async function runLintoko(
   lintokoBinPath: string,
   rootDir: string,
@@ -169,6 +181,11 @@ export async function lint(
     ? await toolchain.bin("lintoko")
     : "lintoko";
 
+  const isExplicit = !!filter || !!(options.files && options.files.length > 0);
+  const trimmedMigrations = isExplicit
+    ? new Set<string>()
+    : getTrimmedMigrationFiles(config);
+
   let filesToLint: string[];
   if (options.files && options.files.length > 0) {
     filesToLint = options.files;
@@ -185,6 +202,20 @@ export async function lint(
           : "No .mo files found in the project",
       );
     }
+    const before = filesToLint.length;
+    filesToLint = dropTrimmedMigrations(
+      filesToLint,
+      rootDir,
+      trimmedMigrations,
+    );
+    if (options.verbose && before !== filesToLint.length) {
+      console.log(
+        chalk.blue("lint"),
+        chalk.gray(
+          `Trimmed ${before - filesToLint.length} migration file(s) (check-limit)`,
+        ),
+      );
+    }
   }
 
   const commonArgs = buildCommonArgs(options, config);
@@ -198,13 +229,9 @@ export async function lint(
   rules.forEach((rule) => baseArgs.push("--rules", rule));
   baseArgs.push(...filesToLint);
 
-  let failed = !(await runLintoko(
-    lintokoBinPath,
-    rootDir,
-    baseArgs,
-    options,
-    "base",
-  ));
+  let failed =
+    filesToLint.length > 0 &&
+    !(await runLintoko(lintokoBinPath, rootDir, baseArgs, options, "base"));
 
   // --- extra runs ---
   const extraEntries = config.lint?.extra;
@@ -243,6 +270,12 @@ export async function lint(
         );
       }
 
+      matchedFiles = dropTrimmedMigrations(
+        matchedFiles,
+        rootDir,
+        trimmedMigrations,
+      );
+
       if (matchedFiles.length === 0) {
         console.warn(
           chalk.yellow(

package/dist/commands/check-stable.d.ts

@@ -16,6 +16,5 @@ export interface RunStableCheckParams {
     canisterArgs: string[];
     sources?: string[];
     options?: Partial<CheckStableOptions>;
-    hasMigrations?: boolean;
 }
 export declare function runStableCheck(params: RunStableCheckParams): Promise<void>;

package/dist/commands/check-stable.js

@@ -1,5 +1,5 @@
-import { basename, join } from "node:path";
-import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import chalk from "chalk";
 import { execa } from "execa";
@@ -9,7 +9,10 @@ import { getGlobalMocArgs, readConfig, resolveConfigPath } from "../mops.js";
 import { filterCanisters, looksLikeFile, resolveCanisterConfigs, resolveSingleCanister, validateCanisterArgs, } from "../helpers/resolve-canisters.js";
 import { sourcesArgs } from "./sources.js";
 import { toolchain } from "./toolchain/index.js";
-const CHECK_STABLE_DIR = ".mops/.check-stable";
+// Per-invocation scratch dir lives under `.mops/`; `mkdtempSync` makes it unique so
+// concurrent `mops` processes don't clobber each other's `old.most`/`new.most`.
+const CHECK_STABLE_PARENT = ".mops";
+const CHECK_STABLE_PREFIX = ".check-stable-";
 export function resolveStablePath(canister, canisterName, options) {
     const stableConfig = canister["check-stable"];
     if (!stableConfig) {
@@ -19,14 +22,20 @@ export function resolveStablePath(canister, canisterName, options) {
         return null;
     }
     const stablePath = resolveConfigPath(stableConfig.path);
+    if (stableConfig.skipIfMissing) {
+        console.warn(chalk.yellow(`WARN: \`skipIfMissing\` in [canisters.${canisterName}.check-stable] is deprecated. ` +
+            `Instead, create ${stableConfig.path} with an empty actor:\n` +
+            "  // Version: 1.0.0\n" +
+            "  actor { };"));
+    }
     if (!existsSync(stablePath)) {
         if (stableConfig.skipIfMissing) {
             return null;
         }
         cliError(`Deployed file not found: ${stablePath} (canister '${canisterName}')\n` +
-            "Set skipIfMissing = true in [canisters." +
-            canisterName +
-            ".check-stable] to skip this check when the file is missing.");
+            `Create ${stableConfig.path} with an empty actor to enable the check:\n` +
+            "  // Version: 1.0.0\n" +
+            "  actor { };");
     }
     return stablePath;
 }
@@ -53,7 +62,6 @@ export async function checkStable(args, options = {}) {
                 globalMocArgs,
                 canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
                 options,
-                hasMigrations: !!canister.migrations,
             });
         }
         finally {
@@ -88,7 +96,6 @@ export async function checkStable(args, options = {}) {
                 canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
                 sources,
                 options,
-                hasMigrations: !!canister.migrations,
             });
         }
         finally {
@@ -111,13 +118,13 @@ export async function runStableCheck(params) {
     if (!existsSync(oldFile)) {
         cliError(`File not found: ${oldFile}`);
     }
-    await rm(CHECK_STABLE_DIR, { recursive: true, force: true });
-    mkdirSync(CHECK_STABLE_DIR, { recursive: true });
+    mkdirSync(CHECK_STABLE_PARENT, { recursive: true });
+    const scratchDir = mkdtempSync(join(CHECK_STABLE_PARENT, CHECK_STABLE_PREFIX));
     try {
         const oldMostPath = isOldMostFile
             ? oldFile
-            : await generateStableTypes(mocPath, oldFile, join(CHECK_STABLE_DIR, "old.most"), sources, globalMocArgs, canisterArgs, options);
-        const newMostPath = await generateStableTypes(mocPath, canisterMain, join(CHECK_STABLE_DIR, "new.most"), sources, globalMocArgs, canisterArgs, options);
+            : await generateStableTypes(mocPath, oldFile, join(scratchDir, "old.most"), sources, globalMocArgs, canisterArgs, options);
+        const newMostPath = await generateStableTypes(mocPath, canisterMain, join(scratchDir, "new.most"), sources, globalMocArgs, canisterArgs, options);
         if (options.verbose) {
             console.log(chalk.blue("check-stable"), chalk.gray(`Comparing ${oldMostPath} ↔ ${newMostPath}`));
         }
@@ -133,20 +140,16 @@ export async function runStableCheck(params) {
             if (result.stderr) {
                 console.error(result.stderr);
             }
-            if (params.hasMigrations) {
-                console.error(chalk.yellow("Hint: You may need a migration. Run `mops migrate new <Name>` to create one."));
-            }
             cliError(`✗ Stable compatibility check failed for canister '${canisterName}'`);
         }
         console.log(chalk.green(`✓ Stable compatibility check passed for canister '${canisterName}'`));
     }
     finally {
-        await rm(CHECK_STABLE_DIR, { recursive: true, force: true });
+        await rm(scratchDir, { recursive: true, force: true });
     }
 }
 async function generateStableTypes(mocPath, moFile, outputPath, sources, globalMocArgs, canisterArgs, options) {
-    const base = basename(outputPath, ".most");
-    const wasmPath = join(CHECK_STABLE_DIR, base + ".wasm");
+    const wasmPath = outputPath.replace(/\.most$/, ".wasm");
     const args = [
         "--stable-types",
         "-o",

package/dist/commands/check.js

@@ -137,7 +137,6 @@ async function checkCanisters(config, canisters, options) {
                     canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
                     sources,
                     options: { verbose: options.verbose, extraArgs: options.extraArgs },
-                    hasMigrations: !!canister.migrations,
                 });
             }
         }

package/dist/commands/lint.js

@@ -8,6 +8,7 @@ import { resolvePackages } from "../resolve-packages.js";
 import { toolchain } from "./toolchain/index.js";
 import { MOTOKO_GLOB_CONFIG } from "../constants.js";
 import { existsSync } from "node:fs";
+import { getTrimmedMigrationFiles } from "../helpers/migrations.js";
 async function resolveDepRules(config, rootDir) {
     const ext = config.lint?.extends;
     if (!ext) {
@@ -83,6 +84,12 @@ function buildCommonArgs(options, config) {
     }
     return args;
 }
+function dropTrimmedMigrations(files, rootDir, excluded) {
+    if (excluded.size === 0) {
+        return files;
+    }
+    return files.filter((f) => !excluded.has(path.resolve(rootDir, f)));
+}
 async function runLintoko(lintokoBinPath, rootDir, args, options, label) {
     try {
         if (options.verbose) {
@@ -107,6 +114,10 @@ export async function lint(filter, options) {
     let lintokoBinPath = config.toolchain?.lintoko
         ? await toolchain.bin("lintoko")
         : "lintoko";
+    const isExplicit = !!filter || !!(options.files && options.files.length > 0);
+    const trimmedMigrations = isExplicit
+        ? new Set()
+        : getTrimmedMigrationFiles(config);
     let filesToLint;
     if (options.files && options.files.length > 0) {
         filesToLint = options.files;
@@ -122,6 +133,11 @@ export async function lint(filter, options) {
                 ? `No files found for filter '${filter}'`
                 : "No .mo files found in the project");
         }
+        const before = filesToLint.length;
+        filesToLint = dropTrimmedMigrations(filesToLint, rootDir, trimmedMigrations);
+        if (options.verbose && before !== filesToLint.length) {
+            console.log(chalk.blue("lint"), chalk.gray(`Trimmed ${before - filesToLint.length} migration file(s) (check-limit)`));
+        }
     }
     const commonArgs = buildCommonArgs(options, config);
     // --- base run ---
@@ -131,7 +147,8 @@ export async function lint(filter, options) {
         : await collectLintRules(config, rootDir);
     rules.forEach((rule) => baseArgs.push("--rules", rule));
     baseArgs.push(...filesToLint);
-    let failed = !(await runLintoko(lintokoBinPath, rootDir, baseArgs, options, "base"));
+    let failed = filesToLint.length > 0 &&
+        !(await runLintoko(lintokoBinPath, rootDir, baseArgs, options, "base"));
     // --- extra runs ---
     const extraEntries = config.lint?.extra;
     if (extraEntries) {
@@ -156,6 +173,7 @@ export async function lint(filter, options) {
             if (baseFileSet) {
                 matchedFiles = matchedFiles.filter((f) => baseFileSet.has(path.resolve(rootDir, f)));
             }
+            matchedFiles = dropTrimmedMigrations(matchedFiles, rootDir, trimmedMigrations);
             if (matchedFiles.length === 0) {
                 console.warn(chalk.yellow(`[lint.extra] no files matched glob '${globPattern}', skipping`));
                 continue;

package/dist/helpers/migrations.d.ts

@@ -1,4 +1,4 @@
-import { MigrationsConfig } from "../types.js";
+import { Config, MigrationsConfig } from "../types.js";
 export interface MigrationArgsResult {
     migrationArgs: string[];
     cleanup: () => Promise<void>;
@@ -8,3 +8,10 @@ export declare function getNextMigrationFile(nextDir: string): string | null;
 export declare function validateNextMigrationOrder(chainDirOrFiles: string | string[], nextFile: string): void;
 export declare function validateMigrationsConfig(migrations: MigrationsConfig, canisterName: string): void;
 export declare function prepareMigrationArgs(migrations: MigrationsConfig | undefined, canisterName: string, mode: "check" | "build", verbose?: boolean): Promise<MigrationArgsResult>;
+/**
+ * Absolute paths of chain migration files that `mops lint` should skip,
+ * mirroring the `check-limit` trimming applied to `moc` during `mops check`.
+ * Validates the migrations config along the way, so misconfig surfaces here
+ * just as it does in `mops check` (consistent failure across commands).
+ */
+export declare function getTrimmedMigrationFiles(config: Config): Set<string>;

package/dist/helpers/migrations.js

@@ -1,9 +1,10 @@
-import { existsSync, mkdirSync, readdirSync, symlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, 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 { getRootDir, resolveConfigPath } from "../mops.js";
+import { resolveCanisterConfigs } from "./resolve-canisters.js";
 function stagedMigrationsDir(chainDir, canisterName) {
     return join(dirname(chainDir), `.migrations-${canisterName}`);
 }
@@ -60,14 +61,14 @@ export function validateMigrationsConfig(migrations, canisterName) {
         }
     }
 }
-export async function prepareMigrationArgs(migrations, canisterName, mode, verbose) {
-    const noOp = {
-        migrationArgs: [],
-        cleanup: async () => { },
-    };
-    if (!migrations) {
-        return noOp;
-    }
+/**
+ * Resolve the active migration chain for a canister: validate config, discover
+ * files, and apply `check-limit` / `build-limit`. Single source of truth for
+ * the trim semantics shared by `prepareMigrationArgs` (which stages `included`
+ * for moc) and `getTrimmedMigrationFiles` (which feeds `excludedChainFiles`
+ * to lint).
+ */
+function resolveMigrationChain(migrations, canisterName, mode) {
     validateMigrationsConfig(migrations, canisterName);
     const chainDir = resolveConfigPath(migrations.chain);
     const nextDir = migrations.next
@@ -76,50 +77,64 @@ export async function prepareMigrationArgs(migrations, canisterName, mode, verbo
     const nextFile = nextDir ? getNextMigrationFile(nextDir) : null;
     if (!existsSync(chainDir) && !nextFile) {
         cliError(`Migration chain directory not found: ${chainDir}\n` +
-            "Run `mops migrate new <Name>` to initialize the migration chain.");
+            "Create the directory and add a `.mo` migration file to initialize the chain.");
     }
     const chainFiles = getMigrationFiles(chainDir);
     if (nextFile) {
         validateNextMigrationOrder(chainFiles, nextFile);
     }
-    const allMigrations = chainFiles.map((f) => ({
+    // Treat chain + next as one virtual merged list; `next` is always last.
+    const all = chainFiles.map((f) => ({
         file: f,
         dir: chainDir,
     }));
     if (nextFile && nextDir) {
-        allMigrations.push({ file: nextFile, dir: nextDir });
+        all.push({ file: nextFile, dir: nextDir });
     }
     const limit = mode === "check" ? migrations["check-limit"] : migrations["build-limit"];
-    const isTrimming = limit !== undefined && limit < allMigrations.length;
-    const needsTempDir = nextFile !== null || isTrimming;
+    const isTrimming = limit !== undefined && limit < all.length;
+    const included = isTrimming ? all.slice(-limit) : all;
+    // Dropped entries are always a chain-only prefix (next sorts last).
+    const excludedChainFiles = all
+        .slice(0, all.length - included.length)
+        .map((e) => resolve(e.dir, e.file));
+    return { chainDir, nextDir, included, excludedChainFiles, isTrimming };
+}
+export async function prepareMigrationArgs(migrations, canisterName, mode, verbose) {
+    if (!migrations) {
+        return { migrationArgs: [], cleanup: async () => { } };
+    }
+    const { chainDir, nextDir, included, excludedChainFiles, isTrimming } = resolveMigrationChain(migrations, canisterName, mode);
+    const hasNext = included.some((e) => e.dir === nextDir);
+    const needsTempDir = hasNext || isTrimming;
     if (!needsTempDir) {
         return {
             migrationArgs: [`--enhanced-migration=${chainDir}`],
             cleanup: async () => { },
         };
     }
-    // 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)) {
+    // Shortcut: only the pending next migration is included → point moc at
+    // next-migration/ so diagnostics use the real path instead of the temp dir.
+    if (nextDir && included.length === 1 && included[0].dir === nextDir) {
         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 });
+    // Per-invocation staging dir; `mkdtempSync` makes it unique so concurrent `mops`
+    // processes don't clobber each other's symlinks. Cleaned up below in `cleanup()`.
+    const baseDir = stagedMigrationsDir(chainDir, canisterName);
+    mkdirSync(dirname(baseDir), { recursive: true });
+    const tempDir = mkdtempSync(`${baseDir}-`);
     writeFileSync(join(tempDir, ".gitignore"), "*\n");
-    const filesToInclude = isTrimming
-        ? allMigrations.slice(-limit)
-        : allMigrations;
-    for (const { file, dir } of filesToInclude) {
+    for (const { file, dir } of included) {
         symlinkSync(resolve(dir, file), join(tempDir, file));
     }
     if (verbose) {
-        console.log(chalk.blue("migrations"), chalk.gray(`Prepared ${filesToInclude.length} migration(s) for ${canisterName}` +
-            (isTrimming ? ` (trimmed from ${allMigrations.length})` : "")));
+        const totalCount = included.length + excludedChainFiles.length;
+        console.log(chalk.blue("migrations"), chalk.gray(`Prepared ${included.length} migration(s) for ${canisterName}` +
+            (isTrimming ? ` (trimmed from ${totalCount})` : "")));
     }
     const migrationArgs = [`--enhanced-migration=${tempDir}`];
     if (isTrimming) {
@@ -132,3 +147,22 @@ export async function prepareMigrationArgs(migrations, canisterName, mode, verbo
         },
     };
 }
+/**
+ * Absolute paths of chain migration files that `mops lint` should skip,
+ * mirroring the `check-limit` trimming applied to `moc` during `mops check`.
+ * Validates the migrations config along the way, so misconfig surfaces here
+ * just as it does in `mops check` (consistent failure across commands).
+ */
+export function getTrimmedMigrationFiles(config) {
+    const excluded = new Set();
+    for (const [name, canister] of Object.entries(resolveCanisterConfigs(config))) {
+        if (!canister.migrations) {
+            continue;
+        }
+        const { excludedChainFiles } = resolveMigrationChain(canister.migrations, name, "check");
+        for (const f of excludedChainFiles) {
+            excluded.add(f);
+        }
+    }
+    return excluded;
+}

package/dist/package.json

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

package/dist/tests/check-stable.test.js

@@ -77,4 +77,21 @@ describe("check-stable", () => {
         expect(result.exitCode).toBe(1);
         expect(result.stderr).toMatch(/File not found/);
     });
+    // Regression: two concurrent `mops check-stable` runs on the same project used to clobber
+    // each other's `.mops/.check-stable/new.most` and the staged migration symlinks, surfacing
+    // as a misleading `new.most: No such file or directory` or an `EEXIST: symlink` crash.
+    test("concurrent runs do not clobber each other's scratch state", async () => {
+        const cwd = path.join(import.meta.dirname, "check-stable/migrations-chain");
+        const results = await Promise.all(Array.from({ length: 10 }, () => cli(["check-stable"], { cwd })));
+        for (const result of results) {
+            expect({
+                exitCode: result.exitCode,
+                stderr: result.stderr,
+            }).toEqual({
+                exitCode: 0,
+                stderr: "",
+            });
+            expect(result.stdout).toMatch(/Stable compatibility check passed/);
+        }
+    }, 60_000);
 });

package/dist/tests/check.test.js

@@ -86,18 +86,19 @@ describe("check", () => {
         expect(result.exitCode).toBe(0);
         expect(result.stdout).toMatch(/Stable compatibility check passed/);
     });
-    test("deployed: silently skips when file missing and skipIfMissing", async () => {
+    test("deployed: skips when file missing and skipIfMissing, with deprecation warning", async () => {
         const cwd = path.join(import.meta.dirname, "check/deployed-missing-skip");
         const result = await cli(["check"], { cwd });
         expect(result.exitCode).toBe(0);
         expect(result.stdout).not.toMatch(/stable/i);
+        expect(result.stderr).toMatch(/skipIfMissing.*deprecated/);
     });
-    test("deployed: errors when file missing without deployedSkipIfFileMissing", async () => {
+    test("deployed: errors when file missing", async () => {
         const cwd = path.join(import.meta.dirname, "check/deployed-missing-error");
         const result = await cli(["check"], { cwd });
         expect(result.exitCode).toBe(1);
         expect(result.stderr).toMatch(/Deployed file not found/);
-        expect(result.stderr).toMatch(/skipIfMissing/);
+        expect(result.stderr).toMatch(/empty actor/);
     });
     test("--fix runs stable check after fixing", async () => {
         const cwd = path.join(import.meta.dirname, "check/deployed-compatible");

package/dist/tests/helpers.js

@@ -26,7 +26,11 @@ export const normalizePaths = (text) => {
         .replace(/\/[^\s"]+\/\.cache\/mops/g, "<CACHE>")
         .replace(/\/[^\s"]+\/Library\/Caches\/mops/g, "<CACHE>")
         .replace(/\/[^\s"[\]]+\/moc(?:-wrapper)?(?=\s|$)/g, "moc-wrapper")
-        .replace(/\/[^\s"[\]]+\.motoko\/bin\/moc/g, "moc-wrapper"));
+        .replace(/\/[^\s"[\]]+\.motoko\/bin\/moc/g, "moc-wrapper")
+        // Per-invocation scratch / staging dirs use mkdtemp; redact the random suffix
+        // (Node's exact suffix format isn't a stable contract) so snapshots stay stable.
+        .replace(/\.mops\/\.check-stable-\w+/g, ".mops/.check-stable")
+        .replace(/(\.migrations-[\w.-]+?)-\w+(?=[/\s"]|$)/g, "$1"));
 };
 export const cliSnapshot = async (args, options, exitCode) => {
     const result = await cli(args, options);

package/dist/tests/lint.test.js

@@ -1,4 +1,6 @@
-import { describe, expect, test } from "@jest/globals";
+import { describe, expect, test, afterEach } from "@jest/globals";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import path from "path";
 import { cli, cliSnapshot } from "./helpers";
 describe("lint", () => {
@@ -71,4 +73,64 @@ describe("lint", () => {
             await cliSnapshot(["lint"], { cwd }, 1);
         });
     });
+    describe("migration trimming via check-limit", () => {
+        const migrateFixturesDir = path.join(import.meta.dirname, "migrate");
+        const tempDirs = [];
+        afterEach(async () => {
+            for (const dir of tempDirs) {
+                await rm(dir, { recursive: true, force: true });
+            }
+            tempDirs.length = 0;
+        });
+        async function makeWithNextLintFixture(checkLimit) {
+            const dest = path.join(migrateFixturesDir, `_tmp_lint_with-next_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`);
+            await cp(path.join(migrateFixturesDir, "with-next"), dest, {
+                recursive: true,
+            });
+            tempDirs.push(dest);
+            // Empty lints/ → collectLintRules picks it up so lintoko runs cleanly
+            // (no rules → no violations → exit 0), preventing assertions from
+            // passing by coincidence on an unrelated lintoko failure.
+            await mkdir(path.join(dest, "lints"), { recursive: true });
+            let toml = readFileSync(path.join(dest, "mops.toml"), "utf-8").replace('moc = "1.5.0"', 'moc = "1.5.0"\nlintoko = "0.7.0"');
+            if (checkLimit !== undefined) {
+                toml = toml.replace('next = "next-migration"', `next = "next-migration"\ncheck-limit = ${checkLimit}`);
+            }
+            await writeFile(path.join(dest, "mops.toml"), toml);
+            return dest;
+        }
+        test("check-limit=1 trims old chain migrations from lint", async () => {
+            // with-next has 3 chain files + 1 next file. check-limit=1 keeps only
+            // the next file → 3 chain files trimmed from lint.
+            const cwd = await makeWithNextLintFixture(1);
+            const result = await cli(["lint", "--verbose"], { cwd });
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).toMatch(/Trimmed 3 migration file\(s\) \(check-limit\)/);
+            expect(result.stdout).not.toMatch(/20250101_000000_Init\.mo/);
+            expect(result.stdout).not.toMatch(/20250201_000000_AddName\.mo/);
+            expect(result.stdout).not.toMatch(/20250301_000000_AddEmail\.mo/);
+            expect(result.stdout).toMatch(/20250401_000000_RenameId\.mo/);
+        });
+        test("no check-limit → all migration files are linted", async () => {
+            const cwd = await makeWithNextLintFixture();
+            const result = await cli(["lint", "--verbose"], { cwd });
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).not.toMatch(/Trimmed \d+ migration file/);
+            expect(result.stdout).toMatch(/20250101_000000_Init\.mo/);
+            expect(result.stdout).toMatch(/20250401_000000_RenameId\.mo/);
+        });
+        test("explicit filter bypasses trimming so user can target a chain file", async () => {
+            const cwd = await makeWithNextLintFixture(1);
+            const result = await cli(["lint", "Init", "--verbose"], { cwd });
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).not.toMatch(/Trimmed \d+ migration file/);
+            expect(result.stdout).toMatch(/20250101_000000_Init\.mo/);
+        });
+        test("invalid check-limit fails `mops lint` (consistent with `mops check`)", async () => {
+            const cwd = await makeWithNextLintFixture(0);
+            const result = await cli(["lint"], { cwd });
+            expect(result.exitCode).toBe(1);
+            expect(result.stderr).toMatch(/check-limit must be a positive integer/);
+        });
+    });
 });

package/dist/tests/migrate.test.js

@@ -173,8 +173,8 @@ describe("migrate", () => {
             expect(most).toMatchSnapshot();
         });
     });
-    describe("stable check hint", () => {
-        test("stable check fails with hint when deployed.most is incompatible", async () => {
+    describe("stable check", () => {
+        test("stable check fails 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);

package/dist/types.d.ts

@@ -47,6 +47,7 @@ export type CanisterConfig = {
     initArg?: string;
     "check-stable"?: {
         path: string;
+        /** @deprecated Create the file with an empty actor instead. */
         skipIfMissing?: boolean;
     };
     migrations?: MigrationsConfig;

package/helpers/migrations.ts

@@ -1,6 +1,7 @@
 import {
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readdirSync,
   symlinkSync,
   writeFileSync,
@@ -10,7 +11,8 @@ import { rm } from "node:fs/promises";
 import chalk from "chalk";
 import { cliError } from "../error.js";
 import { getRootDir, resolveConfigPath } from "../mops.js";
-import { MigrationsConfig } from "../types.js";
+import { resolveCanisterConfigs } from "./resolve-canisters.js";
+import { Config, MigrationsConfig } from "../types.js";
 
 function stagedMigrationsDir(chainDir: string, canisterName: string): string {
   return join(dirname(chainDir), `.migrations-${canisterName}`);
@@ -95,21 +97,29 @@ export function validateMigrationsConfig(
   }
 }
 
-export async function prepareMigrationArgs(
-  migrations: MigrationsConfig | undefined,
+interface MigrationChain {
+  chainDir: string;
+  nextDir?: string;
+  /** Entries to pass to moc, in order, after `*-limit` trimming. */
+  included: { file: string; dir: string }[];
+  /** Absolute paths of chain files dropped by trimming (next is never dropped). */
+  excludedChainFiles: string[];
+  /** True when `*-limit` excluded any entries. */
+  isTrimming: boolean;
+}
+
+/**
+ * Resolve the active migration chain for a canister: validate config, discover
+ * files, and apply `check-limit` / `build-limit`. Single source of truth for
+ * the trim semantics shared by `prepareMigrationArgs` (which stages `included`
+ * for moc) and `getTrimmedMigrationFiles` (which feeds `excludedChainFiles`
+ * to lint).
+ */
+function resolveMigrationChain(
+  migrations: MigrationsConfig,
   canisterName: string,
   mode: "check" | "build",
-  verbose?: boolean,
-): Promise<MigrationArgsResult> {
-  const noOp: MigrationArgsResult = {
-    migrationArgs: [],
-    cleanup: async () => {},
-  };
-
-  if (!migrations) {
-    return noOp;
-  }
-
+): MigrationChain {
   validateMigrationsConfig(migrations, canisterName);
 
   const chainDir = resolveConfigPath(migrations.chain);
@@ -121,30 +131,51 @@ export async function prepareMigrationArgs(
   if (!existsSync(chainDir) && !nextFile) {
     cliError(
       `Migration chain directory not found: ${chainDir}\n` +
-        "Run `mops migrate new <Name>` to initialize the migration chain.",
+        "Create the directory and add a `.mo` migration file to initialize the chain.",
     );
   }
 
   const chainFiles = getMigrationFiles(chainDir);
-
   if (nextFile) {
     validateNextMigrationOrder(chainFiles, nextFile);
   }
 
-  // Treat chain + next as one virtual merged list
-  type MigrationEntry = { file: string; dir: string };
-  const allMigrations: MigrationEntry[] = chainFiles.map((f) => ({
+  // Treat chain + next as one virtual merged list; `next` is always last.
+  const all: { file: string; dir: string }[] = chainFiles.map((f) => ({
     file: f,
     dir: chainDir,
   }));
   if (nextFile && nextDir) {
-    allMigrations.push({ file: nextFile, dir: nextDir });
+    all.push({ file: nextFile, dir: nextDir });
   }
 
   const limit =
     mode === "check" ? migrations["check-limit"] : migrations["build-limit"];
-  const isTrimming = limit !== undefined && limit < allMigrations.length;
-  const needsTempDir = nextFile !== null || isTrimming;
+  const isTrimming = limit !== undefined && limit < all.length;
+  const included = isTrimming ? all.slice(-limit!) : all;
+  // Dropped entries are always a chain-only prefix (next sorts last).
+  const excludedChainFiles = all
+    .slice(0, all.length - included.length)
+    .map((e) => resolve(e.dir, e.file));
+
+  return { chainDir, nextDir, included, excludedChainFiles, isTrimming };
+}
+
+export async function prepareMigrationArgs(
+  migrations: MigrationsConfig | undefined,
+  canisterName: string,
+  mode: "check" | "build",
+  verbose?: boolean,
+): Promise<MigrationArgsResult> {
+  if (!migrations) {
+    return { migrationArgs: [], cleanup: async () => {} };
+  }
+
+  const { chainDir, nextDir, included, excludedChainFiles, isTrimming } =
+    resolveMigrationChain(migrations, canisterName, mode);
+
+  const hasNext = included.some((e) => e.dir === nextDir);
+  const needsTempDir = hasNext || isTrimming;
 
   if (!needsTempDir) {
     return {
@@ -153,9 +184,9 @@ 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)) {
+  // Shortcut: only the pending next migration is included → point moc at
+  // next-migration/ so diagnostics use the real path instead of the temp dir.
+  if (nextDir && included.length === 1 && included[0]!.dir === nextDir) {
     const migrationArgs = [`--enhanced-migration=${nextDir}`];
     if (isTrimming) {
       migrationArgs.push("-A=M0254");
@@ -163,25 +194,24 @@ export async function prepareMigrationArgs(
     return { migrationArgs, cleanup: async () => {} };
   }
 
-  const tempDir = stagedMigrationsDir(chainDir, canisterName);
-  await rm(tempDir, { recursive: true, force: true });
-  mkdirSync(tempDir, { recursive: true });
+  // Per-invocation staging dir; `mkdtempSync` makes it unique so concurrent `mops`
+  // processes don't clobber each other's symlinks. Cleaned up below in `cleanup()`.
+  const baseDir = stagedMigrationsDir(chainDir, canisterName);
+  mkdirSync(dirname(baseDir), { recursive: true });
+  const tempDir = mkdtempSync(`${baseDir}-`);
   writeFileSync(join(tempDir, ".gitignore"), "*\n");
 
-  const filesToInclude = isTrimming
-    ? allMigrations.slice(-limit)
-    : allMigrations;
-
-  for (const { file, dir } of filesToInclude) {
+  for (const { file, dir } of included) {
     symlinkSync(resolve(dir, file), join(tempDir, file));
   }
 
   if (verbose) {
+    const totalCount = included.length + excludedChainFiles.length;
     console.log(
       chalk.blue("migrations"),
       chalk.gray(
-        `Prepared ${filesToInclude.length} migration(s) for ${canisterName}` +
-          (isTrimming ? ` (trimmed from ${allMigrations.length})` : ""),
+        `Prepared ${included.length} migration(s) for ${canisterName}` +
+          (isTrimming ? ` (trimmed from ${totalCount})` : ""),
       ),
     );
   }
@@ -198,3 +228,29 @@ export async function prepareMigrationArgs(
     },
   };
 }
+
+/**
+ * Absolute paths of chain migration files that `mops lint` should skip,
+ * mirroring the `check-limit` trimming applied to `moc` during `mops check`.
+ * Validates the migrations config along the way, so misconfig surfaces here
+ * just as it does in `mops check` (consistent failure across commands).
+ */
+export function getTrimmedMigrationFiles(config: Config): Set<string> {
+  const excluded = new Set<string>();
+  for (const [name, canister] of Object.entries(
+    resolveCanisterConfigs(config),
+  )) {
+    if (!canister.migrations) {
+      continue;
+    }
+    const { excludedChainFiles } = resolveMigrationChain(
+      canister.migrations,
+      name,
+      "check",
+    );
+    for (const f of excludedChainFiles) {
+      excluded.add(f);
+    }
+  }
+  return excluded;
+}

package/package.json

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

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

@@ -143,12 +143,11 @@ exports[`migrate migrate new creates a migration file with timestamp and templat
 }
 `;
 
-exports[`migrate stable check hint stable check fails with hint when deployed.most is incompatible 1`] = `
+exports[`migrate stable check stable check fails 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/check-stable/migrations-chain/deployed.most

@@ -0,0 +1,14 @@
+// Version: 4.0.0
+{
+  "20250101_000000_Init" : {} -> {a : Nat; b : Text};
+  "20250201_000000_AddField" : (old : {a : Nat; b : Text}) -> {a : Nat; b : Text; c : Bool};
+  "20250301_000000_AddD" : (old : {a : Nat; b : Text; c : Bool}) -> {a : Nat; b : Text; c : Bool; d : Int};
+  "20250401_000000_AddE" : (old : {a : Nat; b : Text; c : Bool; d : Int}) -> {a : Nat; b : Text; c : Bool; d : Int; e : Text}
+}
+actor  {
+  stable a : Nat;
+  stable b : Text;
+  stable c : Bool;
+  stable d : Int;
+  stable e : Text
+};

package/tests/check-stable/migrations-chain/migrations/20250101_000000_Init.mo

@@ -0,0 +1,8 @@
+module {
+  public func migration(_ : {}) : { a : Nat; b : Text } {
+    {
+      a = 42;
+      b = "hello";
+    };
+  };
+};

package/tests/check-stable/migrations-chain/migrations/20250201_000000_AddField.mo

@@ -0,0 +1,9 @@
+module {
+  public func migration(old : { a : Nat; b : Text }) : {
+    a : Nat;
+    b : Text;
+    c : Bool;
+  } {
+    { old with c = true };
+  };
+};

package/tests/check-stable/migrations-chain/migrations/20250301_000000_AddD.mo

@@ -0,0 +1,10 @@
+module {
+  public func migration(old : { a : Nat; b : Text; c : Bool }) : {
+    a : Nat;
+    b : Text;
+    c : Bool;
+    d : Int;
+  } {
+    { old with d = 0 };
+  };
+};

package/tests/check-stable/migrations-chain/migrations/20250401_000000_AddE.mo

@@ -0,0 +1,11 @@
+module {
+  public func migration(old : { a : Nat; b : Text; c : Bool; d : Int }) : {
+    a : Nat;
+    b : Text;
+    c : Bool;
+    d : Int;
+    e : Text;
+  } {
+    { old with e = "" };
+  };
+};

package/tests/check-stable/migrations-chain/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"
+check-limit = 3
+
+[canisters.backend.check-stable]
+path = "deployed.most"

package/tests/check-stable/migrations-chain/src/main.mo

@@ -0,0 +1,13 @@
+import Prim "mo:prim";
+
+actor {
+  let a : Nat;
+  let b : Text;
+  let c : Bool;
+  let d : Int;
+  let e : Text;
+
+  public func check() : async () {
+    Prim.debugPrint(debug_show { a; b; c; d; e });
+  };
+};

package/tests/check-stable.test.ts

@@ -86,4 +86,24 @@ describe("check-stable", () => {
     expect(result.exitCode).toBe(1);
     expect(result.stderr).toMatch(/File not found/);
   });
+
+  // Regression: two concurrent `mops check-stable` runs on the same project used to clobber
+  // each other's `.mops/.check-stable/new.most` and the staged migration symlinks, surfacing
+  // as a misleading `new.most: No such file or directory` or an `EEXIST: symlink` crash.
+  test("concurrent runs do not clobber each other's scratch state", async () => {
+    const cwd = path.join(import.meta.dirname, "check-stable/migrations-chain");
+    const results = await Promise.all(
+      Array.from({ length: 10 }, () => cli(["check-stable"], { cwd })),
+    );
+    for (const result of results) {
+      expect({
+        exitCode: result.exitCode,
+        stderr: result.stderr,
+      }).toEqual({
+        exitCode: 0,
+        stderr: "",
+      });
+      expect(result.stdout).toMatch(/Stable compatibility check passed/);
+    }
+  }, 60_000);
 });

package/tests/check.test.ts

@@ -113,19 +113,20 @@ describe("check", () => {
     expect(result.stdout).toMatch(/Stable compatibility check passed/);
   });
 
-  test("deployed: silently skips when file missing and skipIfMissing", async () => {
+  test("deployed: skips when file missing and skipIfMissing, with deprecation warning", async () => {
     const cwd = path.join(import.meta.dirname, "check/deployed-missing-skip");
     const result = await cli(["check"], { cwd });
     expect(result.exitCode).toBe(0);
     expect(result.stdout).not.toMatch(/stable/i);
+    expect(result.stderr).toMatch(/skipIfMissing.*deprecated/);
   });
 
-  test("deployed: errors when file missing without deployedSkipIfFileMissing", async () => {
+  test("deployed: errors when file missing", async () => {
     const cwd = path.join(import.meta.dirname, "check/deployed-missing-error");
     const result = await cli(["check"], { cwd });
     expect(result.exitCode).toBe(1);
     expect(result.stderr).toMatch(/Deployed file not found/);
-    expect(result.stderr).toMatch(/skipIfMissing/);
+    expect(result.stderr).toMatch(/empty actor/);
   });
 
   test("--fix runs stable check after fixing", async () => {

package/tests/helpers.ts

@@ -37,7 +37,11 @@ export const normalizePaths = (text: string): string => {
       .replace(/\/[^\s"]+\/\.cache\/mops/g, "<CACHE>")
       .replace(/\/[^\s"]+\/Library\/Caches\/mops/g, "<CACHE>")
       .replace(/\/[^\s"[\]]+\/moc(?:-wrapper)?(?=\s|$)/g, "moc-wrapper")
-      .replace(/\/[^\s"[\]]+\.motoko\/bin\/moc/g, "moc-wrapper"),
+      .replace(/\/[^\s"[\]]+\.motoko\/bin\/moc/g, "moc-wrapper")
+      // Per-invocation scratch / staging dirs use mkdtemp; redact the random suffix
+      // (Node's exact suffix format isn't a stable contract) so snapshots stay stable.
+      .replace(/\.mops\/\.check-stable-\w+/g, ".mops/.check-stable")
+      .replace(/(\.migrations-[\w.-]+?)-\w+(?=[/\s"]|$)/g, "$1"),
   );
 };
 

package/tests/lint.test.ts

@@ -1,4 +1,6 @@
-import { describe, expect, test } from "@jest/globals";
+import { describe, expect, test, afterEach } from "@jest/globals";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import path from "path";
 import { cli, cliSnapshot } from "./helpers";
 
@@ -86,4 +88,86 @@ describe("lint", () => {
       await cliSnapshot(["lint"], { cwd }, 1);
     });
   });
+
+  describe("migration trimming via check-limit", () => {
+    const migrateFixturesDir = path.join(import.meta.dirname, "migrate");
+    const tempDirs: string[] = [];
+
+    afterEach(async () => {
+      for (const dir of tempDirs) {
+        await rm(dir, { recursive: true, force: true });
+      }
+      tempDirs.length = 0;
+    });
+
+    async function makeWithNextLintFixture(
+      checkLimit?: number,
+    ): Promise<string> {
+      const dest = path.join(
+        migrateFixturesDir,
+        `_tmp_lint_with-next_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      );
+      await cp(path.join(migrateFixturesDir, "with-next"), dest, {
+        recursive: true,
+      });
+      tempDirs.push(dest);
+
+      // Empty lints/ → collectLintRules picks it up so lintoko runs cleanly
+      // (no rules → no violations → exit 0), preventing assertions from
+      // passing by coincidence on an unrelated lintoko failure.
+      await mkdir(path.join(dest, "lints"), { recursive: true });
+
+      let toml = readFileSync(path.join(dest, "mops.toml"), "utf-8").replace(
+        'moc = "1.5.0"',
+        'moc = "1.5.0"\nlintoko = "0.7.0"',
+      );
+      if (checkLimit !== undefined) {
+        toml = toml.replace(
+          'next = "next-migration"',
+          `next = "next-migration"\ncheck-limit = ${checkLimit}`,
+        );
+      }
+      await writeFile(path.join(dest, "mops.toml"), toml);
+      return dest;
+    }
+
+    test("check-limit=1 trims old chain migrations from lint", async () => {
+      // with-next has 3 chain files + 1 next file. check-limit=1 keeps only
+      // the next file → 3 chain files trimmed from lint.
+      const cwd = await makeWithNextLintFixture(1);
+      const result = await cli(["lint", "--verbose"], { cwd });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toMatch(
+        /Trimmed 3 migration file\(s\) \(check-limit\)/,
+      );
+      expect(result.stdout).not.toMatch(/20250101_000000_Init\.mo/);
+      expect(result.stdout).not.toMatch(/20250201_000000_AddName\.mo/);
+      expect(result.stdout).not.toMatch(/20250301_000000_AddEmail\.mo/);
+      expect(result.stdout).toMatch(/20250401_000000_RenameId\.mo/);
+    });
+
+    test("no check-limit → all migration files are linted", async () => {
+      const cwd = await makeWithNextLintFixture();
+      const result = await cli(["lint", "--verbose"], { cwd });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).not.toMatch(/Trimmed \d+ migration file/);
+      expect(result.stdout).toMatch(/20250101_000000_Init\.mo/);
+      expect(result.stdout).toMatch(/20250401_000000_RenameId\.mo/);
+    });
+
+    test("explicit filter bypasses trimming so user can target a chain file", async () => {
+      const cwd = await makeWithNextLintFixture(1);
+      const result = await cli(["lint", "Init", "--verbose"], { cwd });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).not.toMatch(/Trimmed \d+ migration file/);
+      expect(result.stdout).toMatch(/20250101_000000_Init\.mo/);
+    });
+
+    test("invalid check-limit fails `mops lint` (consistent with `mops check`)", async () => {
+      const cwd = await makeWithNextLintFixture(0);
+      const result = await cli(["lint"], { cwd });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toMatch(/check-limit must be a positive integer/);
+    });
+  });
 });

package/tests/migrate.test.ts

@@ -241,8 +241,8 @@ describe("migrate", () => {
     });
   });
 
-  describe("stable check hint", () => {
-    test("stable check fails with hint when deployed.most is incompatible", async () => {
+  describe("stable check", () => {
+    test("stable check fails when deployed.most is incompatible", async () => {
       const cwd = await makeTempFixture("basic");
       await writeFile(
         path.join(cwd, "deployed.most"),

package/types.ts

@@ -49,6 +49,7 @@ export type CanisterConfig = {
   initArg?: string;
   "check-stable"?: {
     path: string;
+    /** @deprecated Create the file with an empty actor instead. */
     skipIfMissing?: boolean;
   };
   migrations?: MigrationsConfig;