@prisma-next/cli 0.11.0-dev.5 → 0.11.0-dev.50

package/src/commands/migration-list.ts

@@ -1,23 +1,37 @@
-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 {
+  type GlyphMode,
+  renderMigrationListGraphResult,
+} from '../utils/formatters/migration-list-graph-render';
+import {
+  buildMigrationListTopologyBySpace,
+  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 +40,141 @@ import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationListOptions extends CommonCommandOptions {
   readonly config?: string;
+  readonly space?: string;
+  readonly graph?: boolean;
+  readonly ascii?: boolean;
+}
+
+export interface MigrationListHumanRenderOptions {
+  readonly graph: boolean;
+  readonly glyphMode: GlyphMode;
+  readonly useColor: boolean;
+}
+
+export function renderMigrationListHumanOutput(
+  result: MigrationListResult,
+  options: MigrationListHumanRenderOptions,
+): string {
+  const styler = createAnsiMigrationListStyler({ useColor: options.useColor });
+  const topologyBySpaceId = buildMigrationListTopologyBySpace(result);
+  if (options.graph) {
+    return renderMigrationListGraphResult(result, styler, options.glyphMode, topologyBySpaceId);
+  }
+  return renderMigrationListWithStyle(result, styler, options.glyphMode, topologyBySpaceId);
 }
 
-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;
+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 +182,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 +203,23 @@ 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 leads with a kind glyph (* forward, ↩ rollback,\n' +
+      '⟲ self), then dirName, then source → destination contract hashes\n' +
+      '(7-char git-style). Self-edges show a single hash. Invariants render as\n' +
+      '{...}; refs on the destination as (production, db). Pass --space <id>\n' +
+      'to narrow to one contract space. --graph draws the forward spine with\n' +
+      'lane gutters; --ascii forces ASCII glyphs (orthogonal to --no-color).',
   );
-  setCommandExamples(command, ['prisma-next migration list']);
+  setCommandExamples(command, [
+    'prisma-next migration list',
+    'prisma-next migration list --graph',
+    'prisma-next migration list --space app',
+    'prisma-next migration list --graph --ascii',
+    '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 +228,9 @@ 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')
+    .option('--graph', 'Draw migration relationships as an annotated tree')
+    .option('--ascii', 'Use ASCII glyphs for --graph (pipe-friendly)')
     .action(async (options: MigrationListOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);
@@ -137,16 +239,13 @@ 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}`);
-          }
+          ui.output(
+            renderMigrationListHumanOutput(listResult, {
+              graph: options.graph === true,
+              glyphMode: ui.resolveGlyphMode(options.ascii === true),
+              useColor: ui.useColor,
+            }),
+          );
         }
       });
       process.exit(exitCode);

package/src/commands/migration-new.ts

@@ -12,19 +12,15 @@ import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { APP_SPACE_ID, createControlStack } from '@prisma-next/framework-components/control';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
 import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
 import {
   copyFilesWithRename,
   formatMigrationDirName,
-  readMigrationsDir,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
-import {
-  findLatestMigration,
-  reconstructGraph,
-} from '@prisma-next/migration-tools/migration-graph';
+import { findLatestMigration } from '@prisma-next/migration-tools/migration-graph';
 import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -36,7 +32,6 @@ import {
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
-  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -46,6 +41,7 @@ import {
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
+import { refusePackageCorruptionOnAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -71,7 +67,10 @@ async function executeMigrationNewCommand(
   options: MigrationNewOptions,
 ): Promise<Result<MigrationNewResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(options.config, config);
+  const { migrationsDir, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
 
   // Construct the family instance up-front so the on-disk contract read
   // below crosses the serializer seam (`familyInstance.deserializeContract`)
@@ -98,7 +97,8 @@ async function executeMigrationNewCommand(
 
   let toContract: Contract;
   try {
-    toContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
+    const parsedContract: unknown = JSON.parse(contractJsonContent);
+    toContract = familyInstance.deserializeContract(parsedContract);
   } catch (error) {
     return notOk(
       errorRuntime('Contract JSON is invalid', {
@@ -118,45 +118,47 @@ async function executeMigrationNewCommand(
     );
   }
 
-  let fromHash: string | null = null;
-  let fromContractSourceDir: string | null = null;
+  const aggregate = await loadContractSpaceAggregate({
+    migrationsDir,
+    deserializeContract: (json) => familyInstance.deserializeContract(json),
+    appContract: toContract,
+  });
+  const packageCorruptionFailure = refusePackageCorruptionOnAggregate(aggregate);
+  if (packageCorruptionFailure) {
+    return notOk(packageCorruptionFailure);
+  }
 
-  try {
-    const packages = await readMigrationsDir(appMigrationsDir);
+  const packages = aggregate.app.packages;
+  const graph = aggregate.app.graph();
 
-    if (packages.length > 0) {
-      const graph = reconstructGraph(packages);
+  let fromHash: string | null = null;
+  let fromContractSourceDir: string | null = null;
 
-      if (options.from) {
-        const match = packages.find((p) => p.metadata.to.startsWith(options.from!));
-        if (!match) {
-          return notOk(
-            errorRuntime('Starting contract not found', {
-              why: `No migration with to hash matching "${options.from}" exists in ${appMigrationsRelative}`,
-              fix: 'Check that the --from hash matches a known migration target hash.',
-            }),
-          );
-        }
-        fromHash = match.metadata.to;
-        fromContractSourceDir = match.dirPath;
-      } else {
-        const latestMigration = findLatestMigration(graph);
-        if (latestMigration) {
-          fromHash = latestMigration.to;
-          const leafPkg = packages.find(
-            (p) => p.metadata.migrationHash === latestMigration.migrationHash,
-          );
-          if (leafPkg) {
-            fromContractSourceDir = leafPkg.dirPath;
-          }
+  if (packages.length > 0) {
+    if (options.from) {
+      const match = packages.find((p) => p.metadata.to.startsWith(options.from!));
+      if (!match) {
+        return notOk(
+          errorRuntime('Starting contract not found', {
+            why: `No migration with to hash matching "${options.from}" exists in ${appMigrationsRelative}`,
+            fix: 'Check that the --from hash matches a known migration target hash.',
+          }),
+        );
+      }
+      fromHash = match.metadata.to;
+      fromContractSourceDir = match.dirPath;
+    } else {
+      const latestMigration = findLatestMigration(graph);
+      if (latestMigration) {
+        fromHash = latestMigration.to;
+        const leafPkg = packages.find(
+          (p) => p.metadata.migrationHash === latestMigration.migrationHash,
+        );
+        if (leafPkg) {
+          fromContractSourceDir = leafPkg.dirPath;
         }
       }
     }
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      return notOk(mapMigrationToolsError(error));
-    }
-    throw error;
   }
 
   if (fromHash === toStorageHash && !options.from) {
@@ -180,12 +182,6 @@ async function executeMigrationNewCommand(
   const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: fromHash,
     to: toStorageHash,
-    hints: {
-      used: [],
-      applied: [],
-      plannerVersion: '1.0.0',
-    },
-    labels: [],
     providedInvariants: [],
     createdAt: timestamp.toISOString(),
   };