ic-mops 2.15.1 → 2.15.2

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Next
 
+## 2.15.2
+
+- `mops check-stable` (and the stable check inside `mops check`) reports when `[canisters.<name>.migrations].check-limit` is set but more migrations are pending than the limit allows. If the compatibility check failed, the check-limit diagnostic replaces the misleading `moc` error; if it passed anyway, a warning is shown. Compares the deployed `.most` baseline against the local chain; use `--no-check-limit` to suppress.
+
 ## 2.15.1
 
 - `mops check --fix` no longer aborts when a fixable file is read-only (e.g. a frozen migration chain file deliberately `chmod`'d to remove write access). The autofixer now skips such files with a warning and continues fixing the rest, instead of crashing the whole run on `EACCES`/`EPERM`.

package/cli.ts

@@ -102,14 +102,26 @@ function parseExtraArgs(variadicArgs?: string[]): {
 // Shared `--help` section describing the enhanced migration `check-limit`
 // trimming and its override flag, so the limit behaviour is discoverable
 // from `--help`. `withFix` appends the `--fix` hint for commands that support it.
-function enhancedMigrationHelp(withFix: boolean): string {
-  const example = withFix ? " (e.g. to --fix older migrations)" : "";
-  return (
+// `withPendingWarning` adds the stable-check pending-migration warning (check / check-stable only).
+function enhancedMigrationHelp(
+  options: {
+    withFix?: boolean;
+    withPendingWarning?: boolean;
+  } = {},
+): string {
+  const example = options.withFix ? " (e.g. to --fix older migrations)" : "";
+  let text =
     "\nEnhanced migration ([canisters.<name>.migrations]):\n" +
     "  The canister is checked against its migration chain. [migrations].check-limit\n" +
     "  trims it to the last N migrations (older ones are skipped). Pass --no-check-limit\n" +
-    `  to use the full chain${example}.`
-  );
+    `  to use the full chain${example}.`;
+  if (options.withPendingWarning) {
+    text +=
+      "\n  When check-limit is set, the stable check reports if more migrations are pending\n" +
+      "  (relative to the deployed .most baseline) than the limit allows — as an error if\n" +
+      "  compat failed, otherwise a warning.";
+  }
+  return text;
 }
 
 program.name("mops");
@@ -372,14 +384,17 @@ program
   .addOption(
     new Option(
       "--no-check-limit",
-      "Check the full migration chain, ignoring [migrations].check-limit",
+      "Use the full migration chain, ignoring [migrations].check-limit; also suppresses the pending-migration warning",
     ),
   )
   .addHelpText(
     "after",
     "\nArguments after -- are forwarded directly to moc, e.g.:\n  $ mops check -- -Werror",
   )
-  .addHelpText("after", enhancedMigrationHelp(true))
+  .addHelpText(
+    "after",
+    enhancedMigrationHelp({ withFix: true, withPendingWarning: true }),
+  )
   .allowUnknownOption(true)
   .action(async (args, options) => {
     checkConfigFile(true);
@@ -419,14 +434,14 @@ program
   .addOption(
     new Option(
       "--no-check-limit",
-      "Check the full migration chain, ignoring [migrations].check-limit",
+      "Use the full migration chain, ignoring [migrations].check-limit; also suppresses the pending-migration warning",
     ),
   )
   .addHelpText(
     "after",
     "\nArguments after -- are forwarded directly to moc, e.g.:\n  $ mops check-stable -- -Werror",
   )
-  .addHelpText("after", enhancedMigrationHelp(false))
+  .addHelpText("after", enhancedMigrationHelp({ withPendingWarning: true }))
   .allowUnknownOption(true)
   .action(async (args, options) => {
     checkConfigFile(true);
@@ -979,7 +994,7 @@ program
     "after",
     "\nArguments after -- are forwarded directly to lintoko, e.g.:\n  $ mops lint -- --severity warning",
   )
-  .addHelpText("after", enhancedMigrationHelp(true))
+  .addHelpText("after", enhancedMigrationHelp({ withFix: true }))
   .allowUnknownOption(true)
   .action(async (filter, options) => {
     checkConfigFile(true);

package/commands/check-stable.ts

@@ -4,9 +4,13 @@ import { rm } from "node:fs/promises";
 import chalk from "chalk";
 import { execa } from "execa";
 import { cliError } from "../error.js";
-import { prepareMigrationArgs } from "../helpers/migrations.js";
+import {
+  getCheckLimitPendingIssue,
+  prepareMigrationArgs,
+  reportCheckLimitPendingIssue,
+} from "../helpers/migrations.js";
 import { getGlobalMocArgs, readConfig, resolveConfigPath } from "../mops.js";
-import { CanisterConfig } from "../types.js";
+import { CanisterConfig, MigrationsConfig } from "../types.js";
 import {
   filterCanisters,
   looksLikeFile,
@@ -103,6 +107,7 @@ export async function checkStable(
         mocPath,
         globalMocArgs,
         canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
+        migrations: canister.migrations,
         options,
       });
     } finally {
@@ -146,6 +151,7 @@ export async function checkStable(
         globalMocArgs,
         canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
         sources,
+        migrations: canister.migrations,
         options,
       });
     } finally {
@@ -173,6 +179,7 @@ export interface RunStableCheckParams {
   globalMocArgs: string[];
   canisterArgs: string[];
   sources?: string[];
+  migrations?: MigrationsConfig;
   options?: Partial<CheckStableOptions>;
 }
 
@@ -240,7 +247,17 @@ export async function runStableCheck(
       reject: false,
     });
 
-    if (result.exitCode !== 0) {
+    const issue = getCheckLimitPendingIssue(
+      params.migrations,
+      canisterName,
+      oldMostPath,
+      options.checkLimit === false,
+      isOldMostFile,
+    );
+
+    if (issue) {
+      reportCheckLimitPendingIssue(issue, result.exitCode !== 0);
+    } else if (result.exitCode !== 0) {
       if (result.stderr) {
         console.error(result.stderr);
       }

package/commands/check.ts

@@ -230,7 +230,12 @@ async function checkCanisters(
           globalMocArgs,
           canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
           sources,
-          options: { verbose: options.verbose, extraArgs: options.extraArgs },
+          migrations: canister.migrations,
+          options: {
+            verbose: options.verbose,
+            extraArgs: options.extraArgs,
+            checkLimit: options.checkLimit,
+          },
         });
       }
     } finally {

package/dist/cli.js

@@ -65,12 +65,20 @@ function parseExtraArgs(variadicArgs) {
 // Shared `--help` section describing the enhanced migration `check-limit`
 // trimming and its override flag, so the limit behaviour is discoverable
 // from `--help`. `withFix` appends the `--fix` hint for commands that support it.
-function enhancedMigrationHelp(withFix) {
-    const example = withFix ? " (e.g. to --fix older migrations)" : "";
-    return ("\nEnhanced migration ([canisters.<name>.migrations]):\n" +
+// `withPendingWarning` adds the stable-check pending-migration warning (check / check-stable only).
+function enhancedMigrationHelp(options = {}) {
+    const example = options.withFix ? " (e.g. to --fix older migrations)" : "";
+    let text = "\nEnhanced migration ([canisters.<name>.migrations]):\n" +
         "  The canister is checked against its migration chain. [migrations].check-limit\n" +
         "  trims it to the last N migrations (older ones are skipped). Pass --no-check-limit\n" +
-        `  to use the full chain${example}.`);
+        `  to use the full chain${example}.`;
+    if (options.withPendingWarning) {
+        text +=
+            "\n  When check-limit is set, the stable check reports if more migrations are pending\n" +
+                "  (relative to the deployed .most baseline) than the limit allows — as an error if\n" +
+                "  compat failed, otherwise a warning.";
+    }
+    return text;
 }
 program.name("mops");
 // --version
@@ -286,9 +294,9 @@ program
     .description("Check Motoko canisters or files for syntax errors and type issues. Arguments can be canister names or file paths. If no arguments are given, checks all canisters from mops.toml. Also runs stable compatibility checks for canisters with [check-stable] configured, and runs linting if lintoko is configured in [toolchain]")
     .option("--verbose", "Verbose console output")
     .addOption(new Option("--fix", "Apply autofixes to all files, including transitively imported ones"))
-    .addOption(new Option("--no-check-limit", "Check the full migration chain, ignoring [migrations].check-limit"))
+    .addOption(new Option("--no-check-limit", "Use the full migration chain, ignoring [migrations].check-limit; also suppresses the pending-migration warning"))
     .addHelpText("after", "\nArguments after -- are forwarded directly to moc, e.g.:\n  $ mops check -- -Werror")
-    .addHelpText("after", enhancedMigrationHelp(true))
+    .addHelpText("after", enhancedMigrationHelp({ withFix: true, withPendingWarning: true }))
     .allowUnknownOption(true)
     .action(async (args, options) => {
     checkConfigFile(true);
@@ -321,9 +329,9 @@ program
     .command("check-stable [args...]")
     .description("Check stable variable compatibility. With no arguments, checks all canisters with [check-stable] configured. Arguments can be canister names or an old file path followed by an optional canister name")
     .option("--verbose", "Verbose console output")
-    .addOption(new Option("--no-check-limit", "Check the full migration chain, ignoring [migrations].check-limit"))
+    .addOption(new Option("--no-check-limit", "Use the full migration chain, ignoring [migrations].check-limit; also suppresses the pending-migration warning"))
     .addHelpText("after", "\nArguments after -- are forwarded directly to moc, e.g.:\n  $ mops check-stable -- -Werror")
-    .addHelpText("after", enhancedMigrationHelp(false))
+    .addHelpText("after", enhancedMigrationHelp({ withPendingWarning: true }))
     .allowUnknownOption(true)
     .action(async (args, options) => {
     checkConfigFile(true);
@@ -693,7 +701,7 @@ program
     .addOption(new Option("-r, --rules <directory...>", "Directories containing rules (can be used multiple times)"))
     .addOption(new Option("--no-check-limit", "Lint the full migration chain, ignoring [migrations].check-limit"))
     .addHelpText("after", "\nArguments after -- are forwarded directly to lintoko, e.g.:\n  $ mops lint -- --severity warning")
-    .addHelpText("after", enhancedMigrationHelp(true))
+    .addHelpText("after", enhancedMigrationHelp({ withFix: true }))
     .allowUnknownOption(true)
     .action(async (filter, options) => {
     checkConfigFile(true);

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

@@ -1,4 +1,4 @@
-import { CanisterConfig } from "../types.js";
+import { CanisterConfig, MigrationsConfig } from "../types.js";
 export interface CheckStableOptions {
     verbose: boolean;
     extraArgs: string[];
@@ -17,6 +17,7 @@ export interface RunStableCheckParams {
     globalMocArgs: string[];
     canisterArgs: string[];
     sources?: string[];
+    migrations?: MigrationsConfig;
     options?: Partial<CheckStableOptions>;
 }
 export declare function runStableCheck(params: RunStableCheckParams): Promise<void>;

package/dist/commands/check-stable.js

@@ -4,7 +4,7 @@ import { rm } from "node:fs/promises";
 import chalk from "chalk";
 import { execa } from "execa";
 import { cliError } from "../error.js";
-import { prepareMigrationArgs } from "../helpers/migrations.js";
+import { getCheckLimitPendingIssue, prepareMigrationArgs, reportCheckLimitPendingIssue, } from "../helpers/migrations.js";
 import { getGlobalMocArgs, readConfig, resolveConfigPath } from "../mops.js";
 import { filterCanisters, looksLikeFile, resolveCanisterConfigs, resolveSingleCanister, validateCanisterArgs, } from "../helpers/resolve-canisters.js";
 import { sourcesArgs } from "./sources.js";
@@ -61,6 +61,7 @@ export async function checkStable(args, options = {}) {
                 mocPath,
                 globalMocArgs,
                 canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
+                migrations: canister.migrations,
                 options,
             });
         }
@@ -95,6 +96,7 @@ export async function checkStable(args, options = {}) {
                 globalMocArgs,
                 canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
                 sources,
+                migrations: canister.migrations,
                 options,
             });
         }
@@ -136,7 +138,11 @@ export async function runStableCheck(params) {
             stdio: "pipe",
             reject: false,
         });
-        if (result.exitCode !== 0) {
+        const issue = getCheckLimitPendingIssue(params.migrations, canisterName, oldMostPath, options.checkLimit === false, isOldMostFile);
+        if (issue) {
+            reportCheckLimitPendingIssue(issue, result.exitCode !== 0);
+        }
+        else if (result.exitCode !== 0) {
             if (result.stderr) {
                 console.error(result.stderr);
             }

package/dist/commands/check.js

@@ -144,7 +144,12 @@ async function checkCanisters(config, canisters, options) {
                     globalMocArgs,
                     canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
                     sources,
-                    options: { verbose: options.verbose, extraArgs: options.extraArgs },
+                    migrations: canister.migrations,
+                    options: {
+                        verbose: options.verbose,
+                        extraArgs: options.extraArgs,
+                        checkLimit: options.checkLimit,
+                    },
                 });
             }
         }

package/dist/helpers/migrations.d.ts

@@ -8,6 +8,22 @@ 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, ignoreLimit?: boolean): Promise<MigrationArgsResult>;
+/**
+ * Local chain (+ next) files not yet recorded in the deployed `.most` baseline.
+ */
+export declare function getPendingMigrationFiles(migrations: MigrationsConfig, canisterName: string, appliedNames: string[]): string[];
+/**
+ * Pending migrations exceed `check-limit` relative to the deployed `.most` baseline.
+ */
+export interface CheckLimitPendingIssue {
+    canisterName: string;
+    pending: string[];
+    checkLimit: number;
+    latestApplied: string | null;
+}
+export declare function getCheckLimitPendingIssue(migrations: MigrationsConfig | undefined, canisterName: string, oldMostPath: string, ignoreCheckLimit: boolean, baselineIsMostFile: boolean): CheckLimitPendingIssue | null;
+/** Warn on accidental compat pass; fail with this diagnostic when compat already failed. */
+export declare function reportCheckLimitPendingIssue(issue: CheckLimitPendingIssue, compatFailed: boolean): void;
 /**
  * Absolute paths of chain migration files that `mops lint` should skip,
  * mirroring the `check-limit` trimming applied to `moc` during `mops check`.

package/dist/helpers/migrations.js

@@ -1,10 +1,11 @@
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, symlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, 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";
+import { latestAppliedMigrationName, migrationBasename, parseMostAppliedMigrationNames, } from "./parse-most.js";
 function stagedMigrationsDir(chainDir, canisterName) {
     return join(dirname(chainDir), `.migrations-${canisterName}`);
 }
@@ -151,6 +152,75 @@ export async function prepareMigrationArgs(migrations, canisterName, mode, verbo
         },
     };
 }
+/**
+ * Local chain (+ next) files not yet recorded in the deployed `.most` baseline.
+ */
+export function getPendingMigrationFiles(migrations, canisterName, appliedNames) {
+    validateMigrationsConfig(migrations, canisterName);
+    const chainDir = resolveConfigPath(migrations.chain);
+    const nextDir = migrations.next
+        ? resolveConfigPath(migrations.next)
+        : undefined;
+    const nextFile = nextDir ? getNextMigrationFile(nextDir) : null;
+    const all = getMigrationFiles(chainDir);
+    if (nextFile) {
+        all.push(nextFile);
+    }
+    const highWaterMark = appliedNames.length > 0 ? latestAppliedMigrationName(appliedNames) : "";
+    return all.filter((file) => migrationBasename(file) > highWaterMark);
+}
+export function getCheckLimitPendingIssue(migrations, canisterName, oldMostPath, ignoreCheckLimit, baselineIsMostFile) {
+    if (!migrations || ignoreCheckLimit || !baselineIsMostFile) {
+        return null;
+    }
+    const checkLimit = migrations["check-limit"];
+    if (checkLimit === undefined) {
+        return null;
+    }
+    let appliedNames;
+    try {
+        appliedNames = parseMostAppliedMigrationNames(readFileSync(oldMostPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (appliedNames === null) {
+        return null;
+    }
+    const pending = getPendingMigrationFiles(migrations, canisterName, appliedNames);
+    if (pending.length <= checkLimit) {
+        return null;
+    }
+    return {
+        canisterName,
+        pending,
+        checkLimit,
+        latestApplied: appliedNames.length > 0 ? latestAppliedMigrationName(appliedNames) : null,
+    };
+}
+function formatCheckLimitPendingLines(issue) {
+    const { canisterName, pending, checkLimit } = issue;
+    return [
+        `Canister '${canisterName}' has ${pending.length} pending migration(s) but check-limit=${checkLimit}. ` +
+            `Fold all changes into the latest pending migration: ${pending[pending.length - 1]}`,
+        `  Pending: ${pending.join(", ")}`,
+        ...(issue.latestApplied
+            ? [`  Latest already applied migration: ${issue.latestApplied}`]
+            : []),
+    ];
+}
+/** Warn on accidental compat pass; fail with this diagnostic when compat already failed. */
+export function reportCheckLimitPendingIssue(issue, compatFailed) {
+    const lines = formatCheckLimitPendingLines(issue);
+    if (compatFailed) {
+        cliError(`✗ Stable compatibility check failed for canister '${issue.canisterName}': too many pending migrations for check-limit=${issue.checkLimit}\n` +
+            lines.join("\n"));
+    }
+    console.warn(chalk.yellow(`WARN: ${lines[0]}`));
+    for (const line of lines.slice(1)) {
+        console.warn(chalk.yellow(line));
+    }
+}
 /**
  * Absolute paths of chain migration files that `mops lint` should skip,
  * mirroring the `check-limit` trimming applied to `moc` during `mops check`.

package/dist/helpers/parse-most.d.ts

@@ -0,0 +1,5 @@
+/** Enhanced-migration names recorded in a Version 4.0.0 `.most` chain block. */
+export declare function parseMostAppliedMigrationNames(content: string): string[] | null;
+export declare function migrationBasename(file: string): string;
+/** Lexicographic max of applied migration names (matches chain file sort order). */
+export declare function latestAppliedMigrationName(appliedNames: string[]): string;

package/dist/helpers/parse-most.js

@@ -0,0 +1,28 @@
+/** Enhanced-migration names recorded in a Version 4.0.0 `.most` chain block. */
+export function parseMostAppliedMigrationNames(content) {
+    const version = content.match(/^\/\/ Version: ([^\n]+)/m)?.[1]?.trim();
+    if (!version) {
+        return null;
+    }
+    if (version !== "4.0.0") {
+        return [];
+    }
+    // Safe: actor types in type aliases are always indented (col ≥ 2); the main actor is at col 0.
+    const actorIdx = content.search(/\nactor\b/);
+    if (actorIdx < 0) {
+        return null;
+    }
+    const chainBlock = content.slice(0, actorIdx);
+    const names = [];
+    for (const match of chainBlock.matchAll(/[{;]\s*"([^"]+)"\s*:/gs)) {
+        names.push(match[1]);
+    }
+    return names;
+}
+export function migrationBasename(file) {
+    return file.endsWith(".mo") ? file.slice(0, -3) : file;
+}
+/** Lexicographic max of applied migration names (matches chain file sort order). */
+export function latestAppliedMigrationName(appliedNames) {
+    return appliedNames.reduce((max, name) => (name > max ? name : max), "");
+}

package/dist/package.json

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

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

@@ -94,4 +94,19 @@ describe("check-stable", () => {
             expect(result.stdout).toMatch(/Stable compatibility check passed/);
         }
     }, 60_000);
+    test("fails with check-limit diagnostic when pending migrations exceed check-limit", async () => {
+        const cwd = path.join(import.meta.dirname, "check-stable/check-limit-warning");
+        await cliSnapshot(["check-stable"], { cwd }, 1);
+    });
+    test("does not warn when deployed baseline matches the chain", async () => {
+        const cwd = path.join(import.meta.dirname, "check-stable/migrations-chain");
+        const result = await cli(["check-stable"], { cwd });
+        expect(result.exitCode).toBe(0);
+        expect(result.stderr).not.toMatch(/pending migration\(s\) but check-limit/);
+    });
+    test("--no-check-limit suppresses pending migration warning", async () => {
+        const cwd = path.join(import.meta.dirname, "check-stable/check-limit-warning");
+        const result = await cli(["check-stable", "--no-check-limit"], { cwd });
+        expect(result.stderr).not.toMatch(/pending migration\(s\) but check-limit/);
+    });
 });

package/dist/tests/check.test.js

@@ -158,4 +158,9 @@ describe("check", () => {
         expect(result.stdout).not.toMatch(/\.migrations-/);
         expect(result.stdout).not.toMatch(/-A=M0254/);
     });
+    test("--no-check-limit suppresses pending migration warning in check", async () => {
+        const cwd = path.join(import.meta.dirname, "check-stable/check-limit-warning");
+        const result = await cli(["check", "--no-check-limit"], { cwd });
+        expect(result.stderr).not.toMatch(/pending migration\(s\) but check-limit/);
+    });
 });

package/dist/tests/lint.test.js

@@ -68,7 +68,7 @@ describe("lint", () => {
             const cwd = path.join(import.meta.dirname, "lint-extra-with-cli-rules");
             await cliSnapshot(["lint", "--rules", "empty-rules", "--verbose"], { cwd }, 1);
         });
-        test("example rules: no-types, types-only, migration-only", async () => {
+        test("example rules: no-types, types-only, migration-only, migration-self-contained", async () => {
             const cwd = path.join(import.meta.dirname, "lint-extra-example-rules");
             await cliSnapshot(["lint"], { cwd }, 1);
         });

package/dist/tests/migrations-most.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/migrations-most.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "@jest/globals";
+import { latestAppliedMigrationName, parseMostAppliedMigrationNames, } from "../helpers/parse-most";
+describe("parseMostAppliedMigrationNames", () => {
+    test("parses Version 4.0.0 enhanced-migration chain", () => {
+        const content = `// 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};
+}
+actor  {
+  stable a : Nat;
+  stable b : Text;
+  stable c : Bool
+};
+`;
+        expect(parseMostAppliedMigrationNames(content)).toEqual([
+            "20250101_000000_Init",
+            "20250201_000000_AddField",
+        ]);
+    });
+    test("returns empty array for Version 1.0.0 (no EM chain)", () => {
+        expect(parseMostAppliedMigrationNames("// Version: 1.0.0\nactor { };\n")).toEqual([]);
+    });
+    test("returns empty array for Version 3.0.0 (legacy migration)", () => {
+        const content = `// Version: 3.0.0
+actor ({
+}, {
+  stable var field1 : Nat;
+  stable var field2 : Text
+});
+`;
+        expect(parseMostAppliedMigrationNames(content)).toEqual([]);
+    });
+    test("returns null when version header is missing", () => {
+        expect(parseMostAppliedMigrationNames("actor { };\n")).toBeNull();
+    });
+    test("returns null when Version 4.0.0 has no actor block", () => {
+        expect(parseMostAppliedMigrationNames('// Version: 4.0.0\n{ "Init" : {} -> {} }')).toBeNull();
+    });
+    test("latestAppliedMigrationName picks lexicographic max", () => {
+        expect(latestAppliedMigrationName([
+            "20250101_000000_Init",
+            "20250301_000000_AddD",
+            "20250201_000000_AddField",
+        ])).toBe("20250301_000000_AddD");
+    });
+});

package/helpers/migrations.ts

@@ -2,6 +2,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readFileSync,
   readdirSync,
   symlinkSync,
   writeFileSync,
@@ -13,6 +14,11 @@ import { cliError } from "../error.js";
 import { getRootDir, resolveConfigPath } from "../mops.js";
 import { resolveCanisterConfigs } from "./resolve-canisters.js";
 import { Config, MigrationsConfig } from "../types.js";
+import {
+  latestAppliedMigrationName,
+  migrationBasename,
+  parseMostAppliedMigrationNames,
+} from "./parse-most.js";
 
 function stagedMigrationsDir(chainDir: string, canisterName: string): string {
   return join(dirname(chainDir), `.migrations-${canisterName}`);
@@ -234,6 +240,117 @@ export async function prepareMigrationArgs(
   };
 }
 
+/**
+ * Local chain (+ next) files not yet recorded in the deployed `.most` baseline.
+ */
+export function getPendingMigrationFiles(
+  migrations: MigrationsConfig,
+  canisterName: string,
+  appliedNames: string[],
+): string[] {
+  validateMigrationsConfig(migrations, canisterName);
+
+  const chainDir = resolveConfigPath(migrations.chain);
+  const nextDir = migrations.next
+    ? resolveConfigPath(migrations.next)
+    : undefined;
+  const nextFile = nextDir ? getNextMigrationFile(nextDir) : null;
+
+  const all = getMigrationFiles(chainDir);
+  if (nextFile) {
+    all.push(nextFile);
+  }
+
+  const highWaterMark =
+    appliedNames.length > 0 ? latestAppliedMigrationName(appliedNames) : "";
+  return all.filter((file) => migrationBasename(file) > highWaterMark);
+}
+
+/**
+ * Pending migrations exceed `check-limit` relative to the deployed `.most` baseline.
+ */
+export interface CheckLimitPendingIssue {
+  canisterName: string;
+  pending: string[];
+  checkLimit: number;
+  latestApplied: string | null;
+}
+
+export function getCheckLimitPendingIssue(
+  migrations: MigrationsConfig | undefined,
+  canisterName: string,
+  oldMostPath: string,
+  ignoreCheckLimit: boolean,
+  baselineIsMostFile: boolean,
+): CheckLimitPendingIssue | null {
+  if (!migrations || ignoreCheckLimit || !baselineIsMostFile) {
+    return null;
+  }
+  const checkLimit = migrations["check-limit"];
+  if (checkLimit === undefined) {
+    return null;
+  }
+
+  let appliedNames: string[] | null;
+  try {
+    appliedNames = parseMostAppliedMigrationNames(
+      readFileSync(oldMostPath, "utf8"),
+    );
+  } catch {
+    return null;
+  }
+  if (appliedNames === null) {
+    return null;
+  }
+
+  const pending = getPendingMigrationFiles(
+    migrations,
+    canisterName,
+    appliedNames,
+  );
+  if (pending.length <= checkLimit) {
+    return null;
+  }
+
+  return {
+    canisterName,
+    pending,
+    checkLimit,
+    latestApplied:
+      appliedNames.length > 0 ? latestAppliedMigrationName(appliedNames) : null,
+  };
+}
+
+function formatCheckLimitPendingLines(issue: CheckLimitPendingIssue): string[] {
+  const { canisterName, pending, checkLimit } = issue;
+  return [
+    `Canister '${canisterName}' has ${pending.length} pending migration(s) but check-limit=${checkLimit}. ` +
+      `Fold all changes into the latest pending migration: ${pending[pending.length - 1]}`,
+    `  Pending: ${pending.join(", ")}`,
+    ...(issue.latestApplied
+      ? [`  Latest already applied migration: ${issue.latestApplied}`]
+      : []),
+  ];
+}
+
+/** Warn on accidental compat pass; fail with this diagnostic when compat already failed. */
+export function reportCheckLimitPendingIssue(
+  issue: CheckLimitPendingIssue,
+  compatFailed: boolean,
+): void {
+  const lines = formatCheckLimitPendingLines(issue);
+  if (compatFailed) {
+    cliError(
+      `✗ Stable compatibility check failed for canister '${issue.canisterName}': too many pending migrations for check-limit=${issue.checkLimit}\n` +
+        lines.join("\n"),
+    );
+  }
+  console.warn(chalk.yellow(`WARN: ${lines[0]}`));
+  for (const line of lines.slice(1)) {
+    console.warn(chalk.yellow(line));
+  }
+}
+
 /**
  * Absolute paths of chain migration files that `mops lint` should skip,
  * mirroring the `check-limit` trimming applied to `moc` during `mops check`.

package/helpers/parse-most.ts

@@ -0,0 +1,32 @@
+/** Enhanced-migration names recorded in a Version 4.0.0 `.most` chain block. */
+export function parseMostAppliedMigrationNames(
+  content: string,
+): string[] | null {
+  const version = content.match(/^\/\/ Version: ([^\n]+)/m)?.[1]?.trim();
+  if (!version) {
+    return null;
+  }
+  if (version !== "4.0.0") {
+    return [];
+  }
+  // Safe: actor types in type aliases are always indented (col ≥ 2); the main actor is at col 0.
+  const actorIdx = content.search(/\nactor\b/);
+  if (actorIdx < 0) {
+    return null;
+  }
+  const chainBlock = content.slice(0, actorIdx);
+  const names: string[] = [];
+  for (const match of chainBlock.matchAll(/[{;]\s*"([^"]+)"\s*:/gs)) {
+    names.push(match[1]!);
+  }
+  return names;
+}
+
+export function migrationBasename(file: string): string {
+  return file.endsWith(".mo") ? file.slice(0, -3) : file;
+}
+
+/** Lexicographic max of applied migration names (matches chain file sort order). */
+export function latestAppliedMigrationName(appliedNames: string[]): string {
+  return appliedNames.reduce((max, name) => (name > max ? name : max), "");
+}

package/package.json

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

package/tests/__snapshots__/check-stable.test.ts.snap

@@ -8,6 +8,17 @@ exports[`check-stable compatible upgrade from .mo file 1`] = `
 }
 `;
 
+exports[`check-stable fails with check-limit diagnostic when pending migrations exceed check-limit 1`] = `
+{
+  "exitCode": 1,
+  "stderr": "✗ Stable compatibility check failed for canister 'backend': too many pending migrations for check-limit=1
+Canister 'backend' has 2 pending migration(s) but check-limit=1. Fold all changes into the latest pending migration: 20250301_000000_AddD.mo
+  Pending: 20250201_000000_AddField.mo, 20250301_000000_AddD.mo
+  Latest already applied migration: 20250101_000000_Init",
+  "stdout": "",
+}
+`;
+
 exports[`check-stable incompatible upgrade from .mo file 1`] = `
 {
   "exitCode": 1,

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

@@ -77,7 +77,7 @@ exports[`lint [lint.extra] edge cases: pass, empty value, no-match, missing dir
 }
 `;
 
-exports[`lint [lint.extra] example rules: no-types, types-only, migration-only 1`] = `
+exports[`lint [lint.extra] example rules: no-types, types-only, migration-only, migration-self-contained 1`] = `
 {
   "exitCode": 1,
   "stderr": "  × [ERROR]: no-types
@@ -114,6 +114,34 @@ Error: Found 1 errors
    ╰────
 
 Error: Found 1 errors
+  × [ERROR]: migration-self-contained
+   ╭─[<TEST_DIR>/lint-extra-example-rules/migrations/20250101_000000_Init.mo:3:14]
+ 2 │ import Backend "canister:backend";
+ 3 │ import Types "Types";
+   ·              ───┬───
+   ·                 ╰── Migration files must not import local modules (relative paths). Got: "Types"
+ 4 │ import TypesDot "./Types";
+   ╰────
+
+  × [ERROR]: migration-self-contained
+   ╭─[<TEST_DIR>/lint-extra-example-rules/migrations/20250101_000000_Init.mo:4:17]
+ 3 │ import Types "Types";
+ 4 │ import TypesDot "./Types";
+   ·                 ────┬────
+   ·                     ╰── Migration files must not import local modules (relative paths). Got: "./Types"
+ 5 │ import TypesParent "../src/Types";
+   ╰────
+
+  × [ERROR]: migration-self-contained
+   ╭─[<TEST_DIR>/lint-extra-example-rules/migrations/20250101_000000_Init.mo:5:20]
+ 4 │ import TypesDot "./Types";
+ 5 │ import TypesParent "../src/Types";
+   ·                    ───────┬──────
+   ·                           ╰── Migration files must not import local modules (relative paths). Got: "../src/Types"
+ 6 │ 
+   ╰────
+
+Error: Found 3 errors
 Lint failed",
   "stdout": "",
 }

package/tests/check-stable/check-limit-warning/deployed.most

@@ -0,0 +1,8 @@
+// Version: 4.0.0
+{
+  "20250101_000000_Init" : {} -> {a : Nat; b : Text};
+}
+actor  {
+  stable a : Nat;
+  stable b : Text
+};

package/tests/check-stable/check-limit-warning/migrations/20250101_000000_Init.mo

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

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

package/tests/check-stable/check-limit-warning/src/main.mo

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

package/tests/check-stable.test.ts

@@ -106,4 +106,28 @@ describe("check-stable", () => {
       expect(result.stdout).toMatch(/Stable compatibility check passed/);
     }
   }, 60_000);
+
+  test("fails with check-limit diagnostic when pending migrations exceed check-limit", async () => {
+    const cwd = path.join(
+      import.meta.dirname,
+      "check-stable/check-limit-warning",
+    );
+    await cliSnapshot(["check-stable"], { cwd }, 1);
+  });
+
+  test("does not warn when deployed baseline matches the chain", async () => {
+    const cwd = path.join(import.meta.dirname, "check-stable/migrations-chain");
+    const result = await cli(["check-stable"], { cwd });
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).not.toMatch(/pending migration\(s\) but check-limit/);
+  });
+
+  test("--no-check-limit suppresses pending migration warning", async () => {
+    const cwd = path.join(
+      import.meta.dirname,
+      "check-stable/check-limit-warning",
+    );
+    const result = await cli(["check-stable", "--no-check-limit"], { cwd });
+    expect(result.stderr).not.toMatch(/pending migration\(s\) but check-limit/);
+  });
 });

package/tests/check.test.ts

@@ -195,4 +195,13 @@ describe("check", () => {
     expect(result.stdout).not.toMatch(/\.migrations-/);
     expect(result.stdout).not.toMatch(/-A=M0254/);
   });
+
+  test("--no-check-limit suppresses pending migration warning in check", async () => {
+    const cwd = path.join(
+      import.meta.dirname,
+      "check-stable/check-limit-warning",
+    );
+    const result = await cli(["check", "--no-check-limit"], { cwd });
+    expect(result.stderr).not.toMatch(/pending migration\(s\) but check-limit/);
+  });
 });

package/tests/lint-extra-example-rules/lint/migration-self-contained/migration-self-contained.toml

@@ -0,0 +1,7 @@
+name = "migration-self-contained"
+description = "Migration files must not import local modules (relative paths). Got: @path"
+includes = ["**/migrations/**"]
+query = '''
+(import (text_literal) @path @error
+  (#match? @path "^\"[^:]*\"$"))
+'''

package/tests/lint-extra-example-rules/migrations/20250101_000000_Init.mo

@@ -0,0 +1,11 @@
+import Map "mo:map/Map";
+import Backend "canister:backend";
+import Types "Types";
+import TypesDot "./Types";
+import TypesParent "../src/Types";
+
+module {
+  public func migration(_ : {}) : { count : Nat } {
+    { count = 0 };
+  };
+};

package/tests/lint-extra-example-rules/mops.toml

@@ -5,3 +5,4 @@ lintoko = "0.7.0"
 "src/Main.mo" = ["lint/no-types"]
 "src/Types.mo" = ["lint/types-only"]
 "src/Migration.mo" = ["lint/migration-only"]
+"migrations/**" = ["lint/migration-self-contained"]

package/tests/lint.test.ts

@@ -83,7 +83,7 @@ describe("lint", () => {
       );
     });
 
-    test("example rules: no-types, types-only, migration-only", async () => {
+    test("example rules: no-types, types-only, migration-only, migration-self-contained", async () => {
       const cwd = path.join(import.meta.dirname, "lint-extra-example-rules");
       await cliSnapshot(["lint"], { cwd }, 1);
     });

package/tests/migrations-most.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "@jest/globals";
+import {
+  latestAppliedMigrationName,
+  parseMostAppliedMigrationNames,
+} from "../helpers/parse-most";
+
+describe("parseMostAppliedMigrationNames", () => {
+  test("parses Version 4.0.0 enhanced-migration chain", () => {
+    const content = `// 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};
+}
+actor  {
+  stable a : Nat;
+  stable b : Text;
+  stable c : Bool
+};
+`;
+    expect(parseMostAppliedMigrationNames(content)).toEqual([
+      "20250101_000000_Init",
+      "20250201_000000_AddField",
+    ]);
+  });
+
+  test("returns empty array for Version 1.0.0 (no EM chain)", () => {
+    expect(
+      parseMostAppliedMigrationNames("// Version: 1.0.0\nactor { };\n"),
+    ).toEqual([]);
+  });
+
+  test("returns empty array for Version 3.0.0 (legacy migration)", () => {
+    const content = `// Version: 3.0.0
+actor ({
+}, {
+  stable var field1 : Nat;
+  stable var field2 : Text
+});
+`;
+    expect(parseMostAppliedMigrationNames(content)).toEqual([]);
+  });
+
+  test("returns null when version header is missing", () => {
+    expect(parseMostAppliedMigrationNames("actor { };\n")).toBeNull();
+  });
+
+  test("returns null when Version 4.0.0 has no actor block", () => {
+    expect(
+      parseMostAppliedMigrationNames(
+        '// Version: 4.0.0\n{ "Init" : {} -> {} }',
+      ),
+    ).toBeNull();
+  });
+
+  test("latestAppliedMigrationName picks lexicographic max", () => {
+    expect(
+      latestAppliedMigrationName([
+        "20250101_000000_Init",
+        "20250301_000000_AddD",
+        "20250201_000000_AddField",
+      ]),
+    ).toBe("20250301_000000_AddD");
+  });
+});