ic-mops 2.15.0 → 2.15.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## 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`.
+
+- Load the PocketIC client lazily, only when a command actually starts a replica. Commands like `mops check`, `mops build`, and `mops install` no longer pay to load it (and its `@icp-sdk/core` dependency) at startup. This also unblocks running the CLI via `tsx` in local dev, where `pic-js-mops` (shipped as ESM without `"type": "module"`) fails to resolve as a static import.
+
+- `mops bench --verbose` is now actually verbose. It prints the benchmark pipeline up front — compiler version, replica + version, GC, profile, and whether the wasm is optimized (`dfx` post-optimizes with `optimize: "cycles"` via ic-wasm on deploy; `pocket-ic` runs the raw `moc` output) — logs the full `moc` build command, and streams the compiler and `dfx` output instead of capturing and discarding it. Notably this surfaces dfx's `WARNING: Failed to optimize the Wasm module`, which dfx prints (and then silently deploys the unoptimized module) when `optimize: "cycles"` fails — e.g. on multi-value modules that the bundled ic-wasm can't process. Previously all of this was hidden even with `--verbose`.
+
 ## 2.15.0
 
 - Fix `mops check --fix` corrupting source on lines containing multi-byte UTF-8 characters (e.g. `Char.toNat32('京')` dropping its trailing `)`). The autofixer was feeding moc's UTF-8 byte columns into LSP's UTF-16 position API, mis-applying every edit past the first non-ASCII byte on the line. When moc emits `byte_start`/`byte_end` (1.10.0 and newer) the fixer now applies edits byte-accurately; older moc still falls back to the line+column path (unchanged behavior, still ASCII-only).

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);
@@ -543,7 +558,12 @@ program
     ),
   )
   // .addOption(new Option('--force-gc', 'Force GC'))
-  .addOption(new Option("--verbose", "Show more information"))
+  .addOption(
+    new Option(
+      "--verbose",
+      "Print the benchmark pipeline (compiler, replica, GC, optimization) and stream compiler/replica output, including dfx optimization warnings",
+    ),
+  )
   .action(async (filter, options) => {
     checkConfigFile(true);
     await installAll({
@@ -974,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/bench-replica.ts

@@ -74,7 +74,8 @@ export class BenchReplica {
     if (this.type === "dfx" || this.type === "dfx-pocket-ic") {
       await execaCommand(
         `dfx deploy ${name} --mode reinstall --yes --identity anonymous`,
-        { cwd, stdio: this.verbose ? "pipe" : ["pipe", "ignore", "pipe"] },
+        // `inherit` so dfx output is streamed under --verbose (incl. its `Failed to optimize` warning)
+        { cwd, stdio: this.verbose ? "inherit" : ["pipe", "ignore", "pipe"] },
       );
       let canisterId = execSync(`dfx canister id ${name}`, { cwd })
         .toString()

package/commands/bench.ts

@@ -101,7 +101,28 @@ export async function bench(
 
   warnIfDfxReplica(replicaType, optionsArg.replica === "dfx");
 
-  options.verbose && console.log(options);
+  if (options.verbose) {
+    // `dfx` post-optimizes the wasm on deploy (`optimize: "cycles"`, via ic-wasm);
+    // `pocket-ic` runs the raw moc output. This changes instruction counts, so surface it.
+    let optimize =
+      replicaType === "dfx" || replicaType === "dfx-pocket-ic"
+        ? 'dfx `optimize: "cycles"` (ic-wasm) on deploy'
+        : "none (raw moc output)";
+    console.log(chalk.gray("Benchmark pipeline:"));
+    console.log(chalk.gray(`  compiler:  moc ${options.compilerVersion}`));
+    console.log(
+      chalk.gray(
+        `  replica:   ${replicaType}${options.replicaVersion ? ` ${options.replicaVersion}` : ""}`,
+      ),
+    );
+    console.log(
+      chalk.gray(
+        `  gc:        ${options.gc}${options.forceGc ? " (forced)" : ""}`,
+      ),
+    );
+    console.log(chalk.gray(`  profile:   ${options.profile}`));
+    console.log(chalk.gray(`  optimize:  ${optimize}`));
+  }
 
   let replica = new BenchReplica(replicaType, options.verbose);
 
@@ -303,14 +324,16 @@ async function deployBenchFile(
   // build canister
   let mocPath = getMocPath();
   let mocArgs = getMocArgs(options);
-  options.verbose && console.time(`build ${canisterName}`);
-  await execaCommand(
-    `${mocPath} -c --idl canister.mo ${globalMocArgs.join(" ")} ${mocArgs} ${(await sources({ cwd: tempDir })).join(" ")}`,
-    {
-      cwd: tempDir,
-      stdio: options.verbose ? "pipe" : ["pipe", "ignore", "pipe"],
-    },
-  );
+  let buildCmd = `${mocPath} -c --idl canister.mo ${globalMocArgs.join(" ")} ${mocArgs} ${(await sources({ cwd: tempDir })).join(" ")}`;
+  if (options.verbose) {
+    console.log(chalk.gray(`[${canisterName}] ${buildCmd}`));
+    console.time(`build ${canisterName}`);
+  }
+  await execaCommand(buildCmd, {
+    cwd: tempDir,
+    // `inherit` so the compiler output (warnings/errors) is streamed under --verbose
+    stdio: options.verbose ? "inherit" : ["pipe", "ignore", "pipe"],
+  });
   options.verbose && console.timeEnd(`build ${canisterName}`);
 
   // deploy canister

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);
@@ -393,7 +401,7 @@ program
     .addOption(new Option("--save", "Save benchmark results to .bench/<filename>.json"))
     .addOption(new Option("--compare", "Run benchmark and compare results with .bench/<filename>.json"))
     // .addOption(new Option('--force-gc', 'Force GC'))
-    .addOption(new Option("--verbose", "Show more information"))
+    .addOption(new Option("--verbose", "Print the benchmark pipeline (compiler, replica, GC, optimization) and stream compiler/replica output, including dfx optimization warnings"))
     .action(async (filter, options) => {
     checkConfigFile(true);
     await installAll({
@@ -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/bench-replica.js

@@ -55,7 +55,9 @@ export class BenchReplica {
     }
     async deploy(name, wasm, cwd = process.cwd()) {
         if (this.type === "dfx" || this.type === "dfx-pocket-ic") {
-            await execaCommand(`dfx deploy ${name} --mode reinstall --yes --identity anonymous`, { cwd, stdio: this.verbose ? "pipe" : ["pipe", "ignore", "pipe"] });
+            await execaCommand(`dfx deploy ${name} --mode reinstall --yes --identity anonymous`, 
+            // `inherit` so dfx output is streamed under --verbose (incl. its `Failed to optimize` warning)
+            { cwd, stdio: this.verbose ? "inherit" : ["pipe", "ignore", "pipe"] });
             let canisterId = execSync(`dfx canister id ${name}`, { cwd })
                 .toString()
                 .trim();

package/dist/commands/bench.js

@@ -61,7 +61,19 @@ export async function bench(filter = "", optionsArg = {}) {
         options.replicaVersion = config.toolchain?.["pocket-ic"] || "";
     }
     warnIfDfxReplica(replicaType, optionsArg.replica === "dfx");
-    options.verbose && console.log(options);
+    if (options.verbose) {
+        // `dfx` post-optimizes the wasm on deploy (`optimize: "cycles"`, via ic-wasm);
+        // `pocket-ic` runs the raw moc output. This changes instruction counts, so surface it.
+        let optimize = replicaType === "dfx" || replicaType === "dfx-pocket-ic"
+            ? 'dfx `optimize: "cycles"` (ic-wasm) on deploy'
+            : "none (raw moc output)";
+        console.log(chalk.gray("Benchmark pipeline:"));
+        console.log(chalk.gray(`  compiler:  moc ${options.compilerVersion}`));
+        console.log(chalk.gray(`  replica:   ${replicaType}${options.replicaVersion ? ` ${options.replicaVersion}` : ""}`));
+        console.log(chalk.gray(`  gc:        ${options.gc}${options.forceGc ? " (forced)" : ""}`));
+        console.log(chalk.gray(`  profile:   ${options.profile}`));
+        console.log(chalk.gray(`  optimize:  ${optimize}`));
+    }
     let replica = new BenchReplica(replicaType, options.verbose);
     let rootDir = getRootDir();
     let globStr = "**/bench?(mark)/**/*.bench.mo";
@@ -207,10 +219,15 @@ async function deployBenchFile(file, options, replica, globalMocArgs) {
     // build canister
     let mocPath = getMocPath();
     let mocArgs = getMocArgs(options);
-    options.verbose && console.time(`build ${canisterName}`);
-    await execaCommand(`${mocPath} -c --idl canister.mo ${globalMocArgs.join(" ")} ${mocArgs} ${(await sources({ cwd: tempDir })).join(" ")}`, {
+    let buildCmd = `${mocPath} -c --idl canister.mo ${globalMocArgs.join(" ")} ${mocArgs} ${(await sources({ cwd: tempDir })).join(" ")}`;
+    if (options.verbose) {
+        console.log(chalk.gray(`[${canisterName}] ${buildCmd}`));
+        console.time(`build ${canisterName}`);
+    }
+    await execaCommand(buildCmd, {
         cwd: tempDir,
-        stdio: options.verbose ? "pipe" : ["pipe", "ignore", "pipe"],
+        // `inherit` so the compiler output (warnings/errors) is streamed under --verbose
+        stdio: options.verbose ? "inherit" : ["pipe", "ignore", "pipe"],
     });
     options.verbose && console.timeEnd(`build ${canisterName}`);
     // deploy canister

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/autofix-motoko.js

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
+import chalk from "chalk";
 import { execa } from "execa";
 import { TextDocument } from "vscode-languageserver-textdocument";
 export function parseDiagnostics(stdout) {
@@ -110,6 +111,9 @@ function applyDiagnosticFixes(content, fixes) {
 const MAX_FIX_ITERATIONS = 10;
 export async function autofixMotoko(mocPath, files, mocArgs) {
     const fixedFilesCodes = new Map();
+    // Frozen migration files are often chmod'd read-only; warn once and skip
+    // them rather than aborting the whole run on EACCES/EPERM.
+    const readOnlySkipped = new Set();
     for (let iteration = 0; iteration < MAX_FIX_ITERATIONS; iteration++) {
         const fixesByFile = new Map();
         for (const file of files) {
@@ -126,12 +130,25 @@ export async function autofixMotoko(mocPath, files, mocArgs) {
         }
         let progress = false;
         for (const [file, fixes] of fixesByFile) {
+            if (readOnlySkipped.has(file)) {
+                continue;
+            }
             const original = await readFile(file, "utf-8");
             const { text: result, appliedCodes } = applyDiagnosticFixes(original, fixes);
             if (result === original) {
                 continue;
             }
-            await writeFile(file, result, "utf-8");
+            try {
+                await writeFile(file, result, "utf-8");
+            }
+            catch (err) {
+                if (err?.code === "EACCES" || err?.code === "EPERM") {
+                    readOnlySkipped.add(file);
+                    console.warn(chalk.yellow(`Skipped read-only file ${relative(process.cwd(), file)} (${appliedCodes.length} fix(es) not applied)`));
+                    continue;
+                }
+                throw err;
+            }
             progress = true;
             const existing = fixedFilesCodes.get(file) ?? [];
             existing.push(...appliedCodes);

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/helpers/pocket-ic-client.d.ts

@@ -1,5 +1,5 @@
-import { PocketIc, PocketIcServer } from "pic-ic";
-import { PocketIc as PocketIcModern, PocketIcServer as PocketIcServerModern, type StartServerOptions } from "pic-js-mops";
+import type { PocketIc, PocketIcServer } from "pic-ic";
+import type { PocketIc as PocketIcModern, PocketIcServer as PocketIcServerModern, StartServerOptions } from "pic-js-mops";
 export type AnyPocketIcServer = PocketIcServer | PocketIcServerModern;
 export type AnyPocketIc = PocketIc | PocketIcModern;
 export type AnySetupCanister = PocketIc["setupCanister"] & PocketIcModern["setupCanister"];