Add an explicit way to validate migration files

Migration classes are now only loaded when they are executed, so a file
that cannot be loaded is no longer reported by status checks until the
migration runs.

Adds Manager::validateMigrations(), which loads every migration class and
returns the error messages indexed by version, and exposes it as
`bin/cake migrations status --validate`. The command exits with 1 and
prints the offending versions when a migration cannot be loaded, so CI can
validate every migration while status checks and the middleware stay fast.
The option can be combined with --all to cover the app and every loaded
plugin.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: nicosp

docs/en/getting-started/running-and-managing-migrations.md

@@ -90,6 +90,27 @@ in CI.
 e.g. `{"app": [...], "PluginName": [...]}`. `--all` cannot be combined with
 `--plugin` or `--cleanup`.
 
+### Validating Migration Files
+
+Migration classes are only loaded when the migration they contain is executed.
+A migration file that cannot be loaded, for example one still extending the
+removed `Migrations\AbstractMigration` class, will therefore not fail `status`
+or the `PendingMigrationsMiddleware`. The `--validate` option loads every
+migration class and reports the ones that cannot be loaded:
+
+```bash
+bin/cake migrations status --validate
+```
+
+When any migration cannot be loaded, the offending versions are printed to
+stderr and the command exits with `1`, which makes it a useful CI check.
+Otherwise the regular status output follows. The option can be combined with
+`--all` to validate the app and every loaded plugin in one call.
+
+The same check is available programmatically through
+`Manager::validateMigrations()`, which returns the error messages indexed by
+migration version.
+
 ### Cleaning Up Missing Migrations
 
 Sometimes migration files may be deleted from the filesystem but still exist in

src/Command/StatusCommand.php

@@ -20,6 +20,7 @@
 use Cake\Core\Plugin;
 use Migrations\Config\ConfigInterface;
 use Migrations\Db\Adapter\UnifiedMigrationsTableStorage;
+use Migrations\Migration\Manager;
 use Migrations\Migration\ManagerFactory;
 
 /**
@@ -78,6 +79,8 @@ protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOption
             'Add <info>-v</info> to also print the per-section migration tables.',
             '<info>migrations status --cleanup</info>',
             'Remove *MISSING* migrations from the migration tracking table',
+            '<info>migrations status --validate</info>',
+            'Load every migration class and fail if any of them cannot be loaded.',
         ])->addOption('plugin', [
             'short' => 'p',
             'help' => 'The plugin to run migrations for',
@@ -104,6 +107,11 @@ protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOption
             'help' => 'Remove MISSING migrations from the migration tracking table',
             'boolean' => true,
             'default' => false,
+        ])->addOption('validate', [
+            'help' => 'Load every migration class and fail if any of them cannot be loaded. '
+                . 'Migration classes are otherwise only loaded when they are executed.',
+            'boolean' => true,
+            'default' => false,
         ]);
 
         return $parser;
@@ -146,6 +154,20 @@ public function execute(Arguments $args, ConsoleIo $io): ?int
         ]);
         $manager = $factory->createManager($io);
 
+        if ($args->getOption('validate')) {
+            /** @var string|null $plugin */
+            $plugin = $args->getOption('plugin');
+            if (!$this->validateMigrations($manager, $io, $plugin ?? 'app')) {
+                return Command::CODE_ERROR;
+            }
+            if ($format !== 'json') {
+                $io->out(sprintf(
+                    '<success>All %d migrations can be loaded.</success>',
+                    count($manager->getMigrationVersions()),
+                ));
+            }
+        }
+
         if ($clean) {
             $removed = $manager->cleanupMissingMigrations();
             if ($removed === 0) {
@@ -200,6 +222,8 @@ protected function executeAll(Arguments $args, ConsoleIo $io, ?string $format):
         }
 
         $verbose = (bool)$args->getOption('verbose');
+        $validate = (bool)$args->getOption('validate');
+        $validationFailed = false;
         $jsonResults = [];
         $summary = [];
         $exitCode = Command::CODE_SUCCESS;
@@ -212,6 +236,11 @@ protected function executeAll(Arguments $args, ConsoleIo $io, ?string $format):
                 'dry-run' => $args->getOption('dry-run'),
             ]);
             $manager = $factory->createManager($io);
+
+            if ($validate && !$this->validateMigrations($manager, $io, $label)) {
+                $validationFailed = true;
+            }
+
             $migrations = $manager->printStatus($format);
 
             $sectionExit = $this->statusExitCode($migrations);
@@ -241,6 +270,10 @@ protected function executeAll(Arguments $args, ConsoleIo $io, ?string $format):
             $this->display($migrations, $io, $manager->getSchemaTableName());
         }
 
+        if ($validationFailed) {
+            return Command::CODE_ERROR;
+        }
+
         if ($format === 'json') {
             $flags = 0;
             if ($verbose) {
@@ -256,6 +289,33 @@ protected function executeAll(Arguments $args, ConsoleIo $io, ?string $format):
         return $exitCode;
     }
 
+    /**
+     * Load every migration class and print the ones that could not be loaded.
+     *
+     * @param \Migrations\Migration\Manager $manager The manager to load migrations with.
+     * @param \Cake\Console\ConsoleIo $io The console io.
+     * @param string $label The section the migrations belong to.
+     * @return bool True when every migration class could be loaded.
+     */
+    protected function validateMigrations(Manager $manager, ConsoleIo $io, string $label): bool
+    {
+        $errors = $manager->validateMigrations();
+        if (!$errors) {
+            return true;
+        }
+
+        $io->err(sprintf(
+            '<error>%s: %d migration(s) could not be loaded:</error>',
+            $label === 'app' ? 'APP' : $label,
+            count($errors),
+        ));
+        foreach ($errors as $version => $message) {
+            $io->err(sprintf('  - %d: %s', $version, $message));
+        }
+
+        return false;
+    }
+
     /**
      * Count actionable items (down + missing) in a section's migrations array.
      *

src/Migration/Manager.php

@@ -19,6 +19,7 @@
 use Migrations\Util\Util;
 use Psr\Container\ContainerInterface;
 use RuntimeException;
+use Throwable;
 
 class Manager
 {
@@ -981,6 +982,30 @@ public function getMigration(int $version): MigrationInterface
         return $this->loadedMigrations[$version];
     }
 
+    /**
+     * Loads every migration class and collects the errors that prevent them from being loaded.
+     *
+     * Migration classes are loaded when the migration they contain is executed, so a broken
+     * migration file is only reported when that migration runs. This loads all of them upfront
+     * so that the migration files can be validated explicitly, for example in CI.
+     *
+     * @throws \InvalidArgumentException When two migrations share a version or a name
+     * @return array<int, string> Error messages indexed by migration version.
+     */
+    public function validateMigrations(): array
+    {
+        $errors = [];
+        foreach ($this->getMigrationVersions() as $version) {
+            try {
+                $this->getMigration($version);
+            } catch (Throwable $e) {
+                $errors[$version] = $e->getMessage();
+            }
+        }
+
+        return $errors;
+    }
+
     /**
      * Gets the name of a database migration without loading its class.
      *

tests/TestCase/Command/CompletionTest.php

@@ -134,7 +134,8 @@ public function testMigrationsOptionsStatus(): void
         $this->exec('completion options migrations.migrations status');
         $this->assertCount(1, $this->_out->messages());
         $output = $this->_out->messages()[0];
-        $expected = '--all --cleanup --connection -c --format -f --help -h --plugin -p --quiet -q --source -s --verbose -v';
+        $expected = '--all --cleanup --connection -c --format -f --help -h --plugin -p --quiet -q --source -s';
+        $expected .= ' --validate --verbose -v';
         $outputExplode = explode(' ', trim($output));
         sort($outputExplode);
         $expectedExplode = explode(' ', $expected);

tests/TestCase/Command/StatusCommandTest.php

@@ -182,4 +182,36 @@ public function testAllRejectsCleanupOption(): void
         $this->assertExitError();
         $this->assertErrorContains('cannot be combined with --cleanup');
     }
+
+    public function testValidateHelp(): void
+    {
+        $this->exec('migrations status --help');
+        $this->assertExitSuccess();
+        $this->assertOutputContains('--validate');
+        $this->assertOutputContains('Load every migration class');
+    }
+
+    public function testValidateWithValidMigrations(): void
+    {
+        $this->exec('migrations status -c test --validate');
+        $this->assertExitSuccess();
+        $this->assertOutputContains('migrations can be loaded');
+        // The status table is still printed.
+        $this->assertOutputContains('Migration ID');
+    }
+
+    public function testValidateWithMigrationThatCannotBeLoaded(): void
+    {
+        $this->exec('migrations status -c test -s LegacyAbstractMigration --validate');
+        $this->assertExitError();
+        $this->assertErrorContains('could not be loaded');
+        $this->assertErrorContains('20260327000000');
+        $this->assertOutputNotContains('Migration ID');
+    }
+
+    public function testAllValidatesEverySection(): void
+    {
+        $this->exec('migrations status -c test --all --validate');
+        $this->assertExitCode(StatusCommand::CODE_STATUS_DOWN);
+    }
 }

tests/TestCase/Migration/ManagerTest.php

@@ -718,6 +718,23 @@ public function testMigrateDoesNotLoadExecutedMigrations(): void
         $manager->migrate();
     }
 
+    public function testValidateMigrationsReportsMigrationsThatCannotBeLoaded(): void
+    {
+        $config = new Config(['paths' => ['migrations' => ROOT . '/config/LegacyAbstractMigration']]);
+        $manager = new Manager($config, $this->io);
+
+        $errors = $manager->validateMigrations();
+
+        $this->assertCount(1, $errors);
+        $this->assertArrayHasKey(20260327000000, $errors);
+        $this->assertStringContainsString('uses the legacy', $errors[20260327000000]);
+    }
+
+    public function testValidateMigrationsWithValidMigrations(): void
+    {
+        $this->assertSame([], $this->manager->validateMigrations());
+    }
+
     public function testGettingAValidEnvironment(): void
     {
         $this->assertInstanceOf(