fix(core): Report when migration patterns match no files

`runMigrations()` returns an empty array both when every migration has
already been applied and when the configured `migrations` glob patterns
matched no files at all. The CLI derives its report from that array
alone, so the second case is presented as "No pending migrations found"
— a database that is out of sync with the entity schema looks identical
to an up-to-date one.

The patterns are resolved relative to the current working directory, so
this happens when the command is run from an unexpected directory, or
when the patterns point at compiled output that has not been built.

Detect the case via the migration classes TypeORM actually loaded and
hand the diagnostic to the caller through a new optional
`RunMigrationsOptions.onNoMigrationsFound` callback. A callback is used
rather than logging directly because `log()` is a no-op while running
from the CLI, where a spinner is active for the duration of the call.
Both CLI entry points surface the message in place of the misleading
default.

The exit code is deliberately unchanged: a freshly scaffolded project
configures a `migrations` glob before any migration file exists, so
failing here would break the default project template.

Fixes #5001

Author: alex-hahn

packages/cli/src/commands/migrate/migration-operations-reporting.spec.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const runMigrationsMock = vi.fn();
+
+vi.mock('@clack/prompts', () => ({
+    log: { info: vi.fn(), error: vi.fn(), success: vi.fn() },
+}));
+vi.mock('../../shared/project-validation', () => ({
+    validateVendureProjectDirectory: vi.fn(),
+}));
+vi.mock('../../shared/shared-prompts', () => ({
+    analyzeProject: vi.fn().mockResolvedValue({ project: {}, tsConfigPath: 'tsconfig.json' }),
+}));
+vi.mock('../../shared/vendure-config-ref', () => ({
+    VendureConfigRef: class {
+        getPathRelativeToProjectRoot() {
+            return 'src/vendure-config.ts';
+        }
+    },
+}));
+vi.mock('../../shared/load-vendure-config-file', () => ({
+    loadVendureConfigFile: vi.fn().mockResolvedValue({}),
+}));
+vi.mock('@vendure/core', () => ({
+    runMigrations: (...args: any[]) => runMigrationsMock(...args),
+    generateMigration: vi.fn(),
+    revertLastMigration: vi.fn(),
+}));
+
+// eslint-disable-next-line import/first
+import { runMigrationsOperation } from './migration-operations';
+
+describe('runMigrationsOperation() reporting', () => {
+    beforeEach(() => {
+        runMigrationsMock.mockReset();
+    });
+
+    it('reports the reason when no migration files were found', async () => {
+        // #5001 — a non-matching `migrations` glob is reported as success, which makes an
+        // out-of-sync database look like an up-to-date one.
+        runMigrationsMock.mockImplementation((config: unknown, options: any) => {
+            options?.onNoMigrationsFound?.('No migration files matched the configured patterns.');
+            return Promise.resolve([]);
+        });
+
+        const result = await runMigrationsOperation();
+
+        expect(result.success).toBe(true);
+        expect(result.message).toBe('No migration files matched the configured patterns.');
+        expect(result.message).not.toBe('No pending migrations found');
+    });
+
+    it('still reports "No pending migrations found" when migration files exist', async () => {
+        runMigrationsMock.mockResolvedValue([]);
+
+        const result = await runMigrationsOperation();
+
+        expect(result.success).toBe(true);
+        expect(result.message).toBe('No pending migrations found');
+    });
+
+    it('reports the number of migrations that ran', async () => {
+        runMigrationsMock.mockResolvedValue(['1700000000000-first', '1700000000001-second']);
+
+        const result = await runMigrationsOperation();
+
+        expect(result.success).toBe(true);
+        expect(result.message).toBe('Successfully ran 2 migrations');
+        expect(result.migrationsRan).toHaveLength(2);
+    });
+});

packages/cli/src/commands/migrate/migration-operations.ts

@@ -78,11 +78,14 @@ export async function runMigrationsOperation(configFile?: string): Promise<Migra
         const config = await loadVendureConfigFile(vendureConfig);
 
         log.info('Running migrations...');
-        const migrationsRan = await runMigrations(config);
+        let noMigrationsFoundMessage: string | undefined;
+        const migrationsRan = await runMigrations(config, {
+            onNoMigrationsFound: message => (noMigrationsFoundMessage = message),
+        });
 
         const report = migrationsRan.length
             ? `Successfully ran ${migrationsRan.length} migrations`
-            : 'No pending migrations found';
+            : (noMigrationsFoundMessage ?? 'No pending migrations found');
 
         return {
             success: true,

packages/cli/src/commands/migrate/run-migration/run-migration.ts

@@ -23,10 +23,13 @@ async function runRunMigration(configFile?: string): Promise<CliCommandReturnVal
 
     const runSpinner = spinner();
     runSpinner.start('Running migrations...');
-    const migrationsRan = await runMigrations(config);
+    let noMigrationsFoundMessage: string | undefined;
+    const migrationsRan = await runMigrations(config, {
+        onNoMigrationsFound: message => (noMigrationsFoundMessage = message),
+    });
     const report = migrationsRan.length
         ? `Successfully ran ${migrationsRan.length} migrations`
-        : 'No pending migrations found';
+        : (noMigrationsFoundMessage ?? 'No pending migrations found');
     runSpinner.stop(report);
     return {
         project,

packages/core/src/index.ts

@@ -18,7 +18,7 @@ export * from './event-bus/index';
 export * from './health-check/index';
 export * from './i18n/index';
 export * from './job-queue/index';
-export { generateMigration, revertLastMigration, runMigrations } from './migrate';
+export { RunMigrationsOptions, generateMigration, revertLastMigration, runMigrations } from './migrate';
 export * from './migration-utils/index';
 export * from './plugin/index';
 export * from './process-context/index';

packages/core/src/migrate.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { getNoMigrationsFoundMessage } from './migrate';
+
+describe('getNoMigrationsFoundMessage()', () => {
+    class SomeMigration {}
+
+    it('returns undefined when migration files were loaded', () => {
+        expect(getNoMigrationsFoundMessage(3, ['src/migrations/*.ts'], '/project')).toBeUndefined();
+    });
+
+    it('returns undefined when no migrations are configured', () => {
+        expect(getNoMigrationsFoundMessage(0, undefined, '/project')).toBeUndefined();
+        expect(getNoMigrationsFoundMessage(0, [], '/project')).toBeUndefined();
+    });
+
+    it('returns undefined when migrations are configured as classes', () => {
+        // Classes are passed directly rather than resolved from disk, so a zero count
+        // cannot be attributed to non-matching glob patterns.
+        expect(getNoMigrationsFoundMessage(0, [SomeMigration], '/project')).toBeUndefined();
+    });
+
+    it('reports the patterns and the cwd they resolve against', () => {
+        const message = getNoMigrationsFoundMessage(0, ['dist/migrations/*.js'], '/project');
+
+        expect(message).toContain('No migration files matched');
+        expect(message).toContain('/project');
+        expect(message).toContain('dist/migrations/*.js');
+    });
+
+    it('reports every configured pattern', () => {
+        const message = getNoMigrationsFoundMessage(
+            0,
+            ['dist/migrations/*.js', 'plugins/*/migrations/*.js'],
+            '/project',
+        );
+
+        expect(message).toContain('dist/migrations/*.js');
+        expect(message).toContain('plugins/*/migrations/*.js');
+    });
+
+    it('supports the object form of the migrations option', () => {
+        const message = getNoMigrationsFoundMessage(0, { first: 'dist/migrations/*.js' } as any, '/project');
+
+        expect(message).toContain('dist/migrations/*.js');
+    });
+
+    it('ignores class entries when reporting patterns', () => {
+        const message = getNoMigrationsFoundMessage(0, [SomeMigration, 'dist/migrations/*.js'], '/project');
+
+        expect(message).toContain('dist/migrations/*.js');
+        expect(message).not.toContain('SomeMigration');
+    });
+});

packages/core/src/migrate.ts

@@ -30,18 +30,40 @@ export interface MigrationOptions {
     outputDir?: string;
 }
 
+/**
+ * @description
+ * Options for {@link runMigrations}.
+ *
+ * @docsCategory migration
+ * @since 3.7.2
+ */
+export interface RunMigrationsOptions {
+    /**
+     * @description
+     * Invoked when the configured `migrations` patterns matched no files at all, which is
+     * otherwise indistinguishable from "no pending migrations" since both result in an empty
+     * return value. The message describes the patterns and the directory they were resolved
+     * against.
+     */
+    onNoMigrationsFound?: (message: string) => void;
+}
+
 /**
  * @description
  * Runs any pending database migrations. See [TypeORM migration docs](https://typeorm.io/#/migrations)
  * for more information about the underlying migration mechanism.
  *
  * @docsCategory migration
  */
-export async function runMigrations(userConfig: Partial<VendureConfig>): Promise<string[]> {
+export async function runMigrations(
+    userConfig: Partial<VendureConfig>,
+    options?: RunMigrationsOptions,
+): Promise<string[]> {
     const config = await preBootstrapConfig(userConfig);
     const connection = await createConnection(createConnectionOptions(config));
     const migrationsRan: string[] = [];
     try {
+        warnIfNoMigrationsFound(connection, options?.onNoMigrationsFound);
         const migrations = await disableForeignKeysForSqLite(connection, () =>
             connection.runMigrations({ transaction: 'each' }),
         );
@@ -79,6 +101,50 @@ async function checkMigrationStatus(connection: Connection) {
     }
 }
 
+/**
+ * TypeORM resolves the `migrations` option to zero classes when the configured glob patterns
+ * match no files. By the time `runMigrations()` returns, that case is indistinguishable from
+ * "every migration has already been applied" — both yield an empty array — so the command
+ * reports success while leaving the database untouched.
+ *
+ * The patterns are resolved relative to the current working directory, so this typically
+ * happens when the command is run from a different directory than expected, or when the
+ * patterns point at compiled output (e.g. `dist/migrations/*.js`) which has not been built.
+ * Neither is detectable from the return value, so report it here.
+ */
+export function getNoMigrationsFoundMessage(
+    loadedMigrationCount: number,
+    configuredMigrations: DataSourceOptions['migrations'],
+    cwd: string = process.cwd(),
+): string | undefined {
+    if (loadedMigrationCount) {
+        return;
+    }
+    const patterns = (
+        Array.isArray(configuredMigrations) ? configuredMigrations : Object.values(configuredMigrations ?? {})
+    ).filter((migration): migration is string => typeof migration === 'string');
+    if (!patterns.length) {
+        return;
+    }
+    return [
+        'No migration files matched the configured `migrations` patterns, so no migrations can be run.',
+        `Patterns are resolved relative to the current directory (${cwd}):`,
+        ...patterns.map(pattern => ' - ' + pattern),
+    ].join('\n');
+}
+
+function warnIfNoMigrationsFound(connection: Connection, onNoMigrationsFound?: (message: string) => void) {
+    const message = getNoMigrationsFoundMessage(connection.migrations.length, connection.options.migrations);
+    if (!message) {
+        return;
+    }
+    // `log()` is a no-op while running from the CLI, because a spinner is active for the
+    // duration of this call and writing to stdout would corrupt it. Hand the message to the
+    // caller instead, so the CLI can report it once the spinner has stopped.
+    onNoMigrationsFound?.(message);
+    log(pc.yellow(message));
+}
+
 /**
  * @description
  * Reverts the last applied database migration. See [TypeORM migration docs](https://typeorm.io/#/migrations)