@prisma-next/cli 0.11.0-dev.3 → 0.11.0-dev.31

package/src/commands/migration-list.ts

@@ -1,23 +1,30 @@
-import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
-import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import { enumerateMigrationSpaces } from '@prisma-next/migration-tools/enumerate-migration-spaces';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
-import { findPath } from '@prisma-next/migration-tools/migration-graph';
+import type {
+  MigrationListResult,
+  MigrationSpaceListEntry,
+} from '@prisma-next/migration-tools/migration-list-types';
+import { APP_SPACE_ID, isValidSpaceId } from '@prisma-next/migration-tools/spaces';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
 import {
   type CliStructuredError,
+  errorInvalidSpaceId,
+  errorSpaceNotFound,
   errorUnexpected,
   mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   setCommandSeeAlso,
 } from '../utils/command-helpers';
+import { renderMigrationListWithStyle } from '../utils/formatters/migration-list-render';
+import { createAnsiMigrationListStyler } from '../utils/formatters/migration-list-styler';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
@@ -26,30 +33,131 @@ import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationListOptions extends CommonCommandOptions {
   readonly config?: string;
+  readonly space?: string;
 }
 
-export interface MigrationListEntry {
-  readonly dirName: string;
-  readonly from: string;
-  readonly to: string;
-  readonly migrationHash: string;
-  readonly operationCount: number;
-  readonly createdAt: string;
+/**
+ * Inputs for {@link runMigrationList} — the pure-ish data-and-policy core
+ * of `migration list` that tests exercise directly.
+ *
+ * The core depends only on the filesystem rooted at `migrationsDir`. It
+ * does NOT call `loadConfig`, parse CLI flags, render a styled header,
+ * or write to any stream. Output rendering is the caller's concern (the
+ * CLI shell renders via {@link renderMigrationList}; JSON callers
+ * serialize the {@link MigrationListResult} directly).
+ */
+export interface RunMigrationListInputs {
+  /** Absolute path to the project's `migrations/` directory. */
+  readonly migrationsDir: string;
+  /**
+   * Optional contract-space id to narrow the result to a single space.
+   * Same validation rules as {@link isValidSpaceId}. When absent, every
+   * on-disk space contributes.
+   */
+  readonly spaceFilter?: string;
 }
 
-export interface MigrationListResult {
-  readonly ok: true;
-  readonly migrations: readonly MigrationListEntry[];
-  readonly summary: string;
+/**
+ * Compute the trailing one-line summary appended below the migration
+ * rows. Wording follows the existing CLI's pluralization style ("N
+ * migration(s) on disk" for the common single-space path; multi-space
+ * adds "across K contract space(s)" so consumers can see the spread).
+ *
+ * The renderer suppresses the summary line when `totalMigrations === 0`
+ * — the empty-state line carries enough information on its own — so
+ * this function always returns a string even for the empty-state.
+ */
+function computeSummary(spaces: readonly MigrationSpaceListEntry[]): string {
+  const totalMigrations = spaces.reduce((count, space) => count + space.migrations.length, 0);
+  if (spaces.length <= 1) {
+    return `${totalMigrations} migration(s) on disk`;
+  }
+  return `${totalMigrations} migration(s) across ${spaces.length} contract space(s)`;
 }
 
+/**
+ * The unit-testable core of `migration list`. Given an absolute
+ * `migrationsDir` and an optional `spaceFilter`, enumerates every
+ * on-disk migration (via {@link enumerateMigrationSpaces}), narrows to
+ * the requested space if any, and assembles a {@link MigrationListResult}
+ * ready for the renderer or JSON serializer.
+ *
+ * The enumerator is the single source of truth for "what is a contract
+ * space": existence, the `--space` candidate-suggestion list, and
+ * scoping are all derived from one {@link enumerateMigrationSpaces}
+ * traversal. This means the reserved-name exclusion the enumerator
+ * applies (e.g. the per-space `refs/` subdirectory) is honoured here for
+ * free — a `--space refs` request resolves to `SPACE_NOT_FOUND`, not a
+ * synthesized empty-state.
+ *
+ * Distinct empty-state paths:
+ *
+ * - `migrations/` missing or contains no valid space directories →
+ *   synthesizes `[{ spaceId: APP_SPACE_ID, migrations: [] }]` so the
+ *   renderer's empty-state path can name a directory (spec § Empty-state +
+ *   the `migrations/` missing edge case).
+ * - `--space <id>` on an existing-but-empty space dir → the enumerator
+ *   surfaces `{ spaceId, migrations: [] }`; `<id>` is in the set, so it
+ *   scopes to that entry and renders the empty-state the same way.
+ * - `--space <id>` on a non-existent (or reserved) space → structured
+ *   `MIGRATION.SPACE_NOT_FOUND` error (NOT empty-state).
+ *
+ * Errors caught here:
+ *
+ * - {@link MigrationToolsError} from the enumerator → mapped through
+ *   {@link mapMigrationToolsError} so callers see the catalogue code.
+ * - Anything else (filesystem etc.) → wrapped via {@link errorUnexpected}.
+ */
+export async function runMigrationList(
+  inputs: RunMigrationListInputs,
+): Promise<Result<MigrationListResult, CliStructuredError>> {
+  const { migrationsDir, spaceFilter } = inputs;
+
+  if (spaceFilter !== undefined && !isValidSpaceId(spaceFilter)) {
+    return notOk(errorInvalidSpaceId(spaceFilter));
+  }
+
+  let spaces: readonly MigrationSpaceListEntry[];
+  try {
+    spaces = await enumerateMigrationSpaces({ projectMigrationsDir: migrationsDir });
+  } catch (error) {
+    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to enumerate migrations: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+
+  if (spaceFilter !== undefined && !spaces.some((s) => s.spaceId === spaceFilter)) {
+    return notOk(errorSpaceNotFound(spaceFilter, spaces.map((s) => s.spaceId).sort()));
+  }
+
+  const scopedSpaces =
+    spaceFilter !== undefined ? spaces.filter((s) => s.spaceId === spaceFilter) : spaces;
+
+  const resultSpaces: readonly MigrationSpaceListEntry[] =
+    scopedSpaces.length === 0 ? [{ spaceId: APP_SPACE_ID, migrations: [] }] : scopedSpaces;
+
+  return ok({
+    ok: true,
+    spaces: resultSpaces,
+    summary: computeSummary(resultSpaces),
+  });
+}
+
+/**
+ * CLI shell: loads config, resolves paths, prints the styled header on
+ * stderr (interactive mode only), and delegates to {@link runMigrationList}.
+ * Kept intentionally thin so the unit-testable surface lives in the core.
+ */
 async function executeMigrationListCommand(
   options: MigrationListOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationListResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+  const { configPath, migrationsDir, migrationsRelative } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -57,58 +165,20 @@ async function executeMigrationListCommand(
   if (!flags.json && !flags.quiet) {
     const header = formatStyledHeader({
       command: 'migration list',
-      description: 'List on-disk migrations in topological order',
+      description: 'List on-disk migrations, latest first, per contract space',
       details: [
         { label: 'config', value: configPath },
-        { label: 'migrations', value: appMigrationsRelative },
+        { label: 'migrations', value: migrationsRelative },
+        ...(options.space !== undefined ? [{ label: 'space', value: options.space }] : []),
       ],
       flags,
     });
     ui.stderr(header);
   }
 
-  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
-  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
-  try {
-    ({ bundles, graph } = await loadMigrationPackages(appMigrationsDir));
-  } catch (error) {
-    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
-    return notOk(
-      errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
-  }
-
-  if (bundles.length === 0) {
-    return ok({ ok: true, migrations: [], summary: 'No migrations found' });
-  }
-
-  const leaves = [...graph.nodes].filter(
-    (n) => !graph.forwardChain.has(n) || graph.forwardChain.get(n)!.length === 0,
-  );
-  const targetHash =
-    leaves.length === 1 ? leaves[0]! : ([...graph.nodes].values().next().value as string);
-  const chain = findPath(graph, EMPTY_CONTRACT_HASH, targetHash) ?? [];
-
-  const pkgByDirName = new Map(bundles.map((p) => [p.dirName, p]));
-  const entries: MigrationListEntry[] = chain.map((edge) => {
-    const pkg = pkgByDirName.get(edge.dirName);
-    const ops = (pkg?.ops ?? []) as readonly MigrationPlanOperation[];
-    return {
-      dirName: edge.dirName,
-      from: edge.from,
-      to: edge.to,
-      migrationHash: edge.migrationHash,
-      operationCount: ops.length,
-      createdAt: edge.createdAt,
-    };
-  });
-
-  return ok({
-    ok: true,
-    migrations: entries,
-    summary: `${entries.length} migration(s) on disk`,
+  return runMigrationList({
+    migrationsDir,
+    ...ifDefined('spaceFilter', options.space),
   });
 }
 
@@ -116,11 +186,19 @@ export function createMigrationListCommand(): Command {
   const command = new Command('list');
   setCommandDescriptions(
     command,
-    'List on-disk migrations in topological order',
-    'Enumerates all migration packages under migrations/<space>/ in\n' +
-      'topological order. Offline — does not consult the database.',
+    'List on-disk migrations, latest first, per contract space',
+    'Enumerates every on-disk migration under migrations/<space>/ for every\n' +
+      'contract space found on disk, latest first. Offline — does not consult\n' +
+      'the database. Each row shows source → destination contract hashes\n' +
+      '(7-char git-style), the self-edge marker (⟲), any provided invariants\n' +
+      '({...}), and refs landing on the destination ((production, db)). Pass\n' +
+      '--space <id> to narrow to a single contract space.',
   );
-  setCommandExamples(command, ['prisma-next migration list']);
+  setCommandExamples(command, [
+    'prisma-next migration list',
+    'prisma-next migration list --space app',
+    'prisma-next migration list --json',
+  ]);
   setCommandSeeAlso(command, [
     { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
     { verb: 'migration log', oneLiner: 'Show executed migration history' },
@@ -129,6 +207,7 @@ export function createMigrationListCommand(): Command {
   ]);
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
+    .option('--space <id>', 'Narrow output to a single contract space')
     .action(async (options: MigrationListOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);
@@ -137,16 +216,8 @@ export function createMigrationListCommand(): Command {
         if (flags.json) {
           ui.output(JSON.stringify(listResult, null, 2));
         } else if (!flags.quiet) {
-          if (listResult.migrations.length === 0) {
-            ui.log('No migrations found');
-          } else {
-            for (const entry of listResult.migrations) {
-              ui.log(
-                `${entry.dirName}  ${entry.migrationHash.slice(0, 16)}…  ${entry.operationCount} op(s)`,
-              );
-            }
-            ui.log(`\n${listResult.summary}`);
-          }
+          const styler = createAnsiMigrationListStyler({ useColor: ui.useColor });
+          ui.output(renderMigrationListWithStyle(listResult, styler));
         }
       });
       process.exit(exitCode);