@prisma-next/cli 0.12.0-dev.28 → 0.12.0-dev.29

package/src/commands/migration-status.ts

@@ -3,18 +3,13 @@ import type {
   ContractMarkerRecordLike,
   ContractSpaceMember,
 } from '@prisma-next/migration-tools/aggregate';
-import { requireHeadRef } from '@prisma-next/migration-tools/aggregate';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import {
   errorNoInvariantPath,
   errorUnknownInvariant,
   MigrationToolsError,
 } from '@prisma-next/migration-tools/errors';
-import {
-  findPath,
-  findPathWithDecision,
-  findReachableLeaves,
-} from '@prisma-next/migration-tools/migration-graph';
+import { findPath, findPathWithDecision } from '@prisma-next/migration-tools/migration-graph';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry, Refs } from '@prisma-next/migration-tools/refs';
 import { readRefs } from '@prisma-next/migration-tools/refs';
@@ -47,16 +42,19 @@ import {
   loadContractRawSafely,
   refusePackageCorruptionOnAggregate,
 } from '../utils/contract-space-aggregate-loader';
-import { buildMigrationGraphLayout } from '../utils/formatters/migration-graph-layout';
-import { buildMigrationGraphRows } from '../utils/formatters/migration-graph-rows';
 import {
-  type MigrationEdgeAnnotation,
-  renderMigrationGraphTree,
-} from '../utils/formatters/migration-graph-tree-render';
+  computeGlobalMaxDirNameWidth,
+  computeGlobalMaxEdgeTreePrefixWidth,
+  indentMigrationGraphTreeBlock,
+  renderMigrationGraphSpaceTree,
+} from '../utils/formatters/migration-graph-space-render';
+import type { MigrationEdgeAnnotation } from '../utils/formatters/migration-graph-tree-render';
+import { renderMigrationGraphLegend } from '../utils/formatters/migration-graph-tree-render';
 import type { MigrationListEntry } from '../utils/formatters/migration-list-types';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { shouldShowLegend, validateLegendOptions } from '../utils/legend';
 import type { StatusDiagnostic } from '../utils/migration-types';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
@@ -77,6 +75,7 @@ interface MigrationStatusOptions extends CommonCommandOptions {
   readonly to?: string;
   readonly from?: string;
   readonly space?: string;
+  readonly legend?: boolean;
 }
 
 export interface MigrationStatusMigrationEntry extends MigrationListEntry {
@@ -112,26 +111,8 @@ function shortDisplayHash(hash: string): string {
   return stripped.slice(0, 12);
 }
 
-function resolveTargetHashForSpace(
-  member: ContractSpaceMember,
-  contractHash: string,
-  activeRefHash: string | undefined,
-): string | undefined {
-  const graph = member.graph();
-  if (activeRefHash !== undefined && graph.nodes.has(activeRefHash)) {
-    return activeRefHash;
-  }
-  if (graph.nodes.has(contractHash)) {
-    return contractHash;
-  }
-  if (graph.nodes.size === 0) {
-    return requireHeadRef(member).hash;
-  }
-  const leaves = findReachableLeaves(graph, EMPTY_CONTRACT_HASH);
-  if (leaves.length === 1) {
-    return leaves[0];
-  }
-  return undefined;
+function resolveTarget(contractHash: string, activeRefHash: string | undefined): string {
+  return activeRefHash ?? contractHash;
 }
 
 function buildStatusMigrations(
@@ -146,28 +127,35 @@ function buildStatusMigrations(
 
 function renderSpaceTree(args: {
   readonly member: ContractSpaceMember;
-  readonly contractHash: string;
+  readonly liveContractHash: string;
+  readonly migrations: readonly MigrationListEntry[];
   readonly markerHash: string | undefined;
   readonly showDbMarker: boolean;
-  readonly targetHash: string;
-  readonly edgeAnnotations: ReadonlyMap<string, MigrationEdgeAnnotation>;
+  readonly statusOverlay: ReadonlyMap<string, MigrationEdgeAnnotation>;
   readonly colorize: boolean;
   readonly glyphMode: 'unicode' | 'ascii';
+  readonly globalMaxEdgeTreePrefixWidth?: number;
+  readonly globalMaxDirNameWidth?: number;
 }): string {
   const graph = args.member.graph();
   if (graph.nodes.size === 0) {
     return '';
   }
-  const refsByHash = listRefsByContractHash(args.member);
-  const rowModel = buildMigrationGraphRows(graph, { contractHash: args.contractHash });
-  const layout = buildMigrationGraphLayout(rowModel);
-  return renderMigrationGraphTree(layout, {
-    refsByHash,
-    ...(args.showDbMarker && args.markerHash !== undefined ? { dbHash: args.markerHash } : {}),
-    contractHash: args.contractHash,
-    edgeAnnotationsByHash: args.edgeAnnotations,
+  return renderMigrationGraphSpaceTree({
+    graph,
+    migrations: args.migrations,
+    liveContractHash: args.liveContractHash,
+    refsByHash: listRefsByContractHash(args.member),
+    statusOverlayByHash: args.statusOverlay,
     colorize: args.colorize,
     glyphMode: args.glyphMode,
+    ...(args.showDbMarker && args.markerHash !== undefined ? { dbHash: args.markerHash } : {}),
+    ...(args.globalMaxEdgeTreePrefixWidth !== undefined
+      ? { globalMaxEdgeTreePrefixWidth: args.globalMaxEdgeTreePrefixWidth }
+      : {}),
+    ...(args.globalMaxDirNameWidth !== undefined
+      ? { globalMaxDirNameWidth: args.globalMaxDirNameWidth }
+      : {}),
   });
 }
 
@@ -175,6 +163,27 @@ function countPending(migrations: readonly MigrationStatusMigrationEntry[]): num
   return migrations.filter((m) => m.status === 'pending').length;
 }
 
+export function buildNoPathSummary(args: {
+  readonly markerHash: string | undefined;
+  readonly targetHash: string;
+  readonly explicitTarget: boolean;
+  readonly refName: string | undefined;
+}): string {
+  const markerPart =
+    args.markerHash !== undefined
+      ? `the database state (${shortDisplayHash(args.markerHash)})`
+      : 'the database state';
+  const targetShort = shortDisplayHash(args.targetHash);
+  if (!args.explicitTarget) {
+    return `No migration path from ${markerPart} to the application's contract (${targetShort}). Run \`prisma-next migration plan --name <name>\` to author one.`;
+  }
+  const targetLabel =
+    args.refName !== undefined
+      ? `the target (${targetShort} via \`${args.refName}\`)`
+      : `the target (${targetShort})`;
+  return `No migration path from ${markerPart} to ${targetLabel}. Run \`prisma-next migration plan --name <name>\` to author one, or pass \`--to <contract>\` to pick a reachable target.`;
+}
+
 export function buildStatusHeadline(args: {
   readonly pendingCount: number;
   readonly targetHash: string;
@@ -185,7 +194,7 @@ export function buildStatusHeadline(args: {
     return `Database marker ${shortDisplayHash(args.markerHash)} is not in the on-disk migration graph`;
   }
   if (args.pendingCount === 0) {
-    return 'up to date';
+    return 'Up to date';
   }
   return `${args.pendingCount} pending — run \`prisma-next migrate --to ${shortDisplayHash(args.targetHash)}\``;
 }
@@ -361,6 +370,15 @@ async function executeMigrationStatusCommand(
       flags,
     });
     ui.stderr(header);
+    if (shouldShowLegend(options, flags)) {
+      ui.stderr(
+        renderMigrationGraphLegend({
+          colorize: flags.color !== false,
+          glyphMode: ui.resolveGlyphMode(false),
+        }),
+      );
+      ui.stderr('');
+    }
   }
 
   const listSpaces = await migrationSpaceListEntriesFromAggregate(aggregate, migrationsDir);
@@ -440,7 +458,21 @@ async function executeMigrationStatusCommand(
   let markerCannotReachTarget = false;
   let headlineTargetHash = activeRefHash ?? contractHash;
   let totalPending = 0;
-  let hasAmbiguousTarget = false;
+
+  const globalLayoutInputs = showSpaceHeadings
+    ? scopedSpaces
+        .filter((spaceEntry) => spaceEntry.migrations.length > 0)
+        .map((spaceEntry) => ({
+          graph: aggregate.space(spaceEntry.spaceId)!.graph(),
+          liveContractHash: contractHash,
+        }))
+    : [];
+  const globalMaxEdgeTreePrefixWidth =
+    globalLayoutInputs.length > 0
+      ? computeGlobalMaxEdgeTreePrefixWidth(globalLayoutInputs)
+      : undefined;
+  const globalMaxDirNameWidth =
+    globalLayoutInputs.length > 0 ? computeGlobalMaxDirNameWidth(globalLayoutInputs) : undefined;
 
   for (const spaceEntry of scopedSpaces) {
     const member = aggregate.space(spaceEntry.spaceId);
@@ -449,20 +481,7 @@ async function executeMigrationStatusCommand(
     }
     const graph = member.graph();
     const spaceContractHash = member.contract().storage.storageHash;
-    const targetHash = resolveTargetHashForSpace(member, spaceContractHash, activeRefHash);
-    if (targetHash === undefined) {
-      hasAmbiguousTarget = true;
-      diagnostics.push({
-        code: 'MIGRATION.DIVERGED',
-        severity: 'warn',
-        message: 'There are multiple valid migration paths — you must select a target',
-        hints: [
-          "Use '--to <contract>' to select a target",
-          "Or 'prisma-next ref set <name> <hash>' to create one",
-        ],
-      });
-      continue;
-    }
+    const targetHash = resolveTarget(spaceContractHash, activeRefHash);
     if (spaceEntry.spaceId === aggregate.app.spaceId) {
       headlineTargetHash = targetHash;
     }
@@ -477,9 +496,8 @@ async function executeMigrationStatusCommand(
     if (
       connected &&
       !usingFromOverride &&
-      markerHash !== undefined &&
       markerInGraph &&
-      markerHash !== targetHash &&
+      originHash !== targetHash &&
       findPath(graph, originHash, targetHash) === null
     ) {
       markerCannotReachTarget = true;
@@ -511,13 +529,15 @@ async function executeMigrationStatusCommand(
     });
     const tree = renderSpaceTree({
       member,
-      contractHash: spaceContractHash,
+      liveContractHash: contractHash,
+      migrations: spaceEntry.migrations,
       markerHash,
       showDbMarker,
-      targetHash,
-      edgeAnnotations: annotations,
+      statusOverlay: annotations,
       colorize,
       glyphMode,
+      ...(globalMaxEdgeTreePrefixWidth !== undefined ? { globalMaxEdgeTreePrefixWidth } : {}),
+      ...(globalMaxDirNameWidth !== undefined ? { globalMaxDirNameWidth } : {}),
     });
     const migrations = buildStatusMigrations(spaceEntry.migrations, annotations);
     const pending = countPending(migrations);
@@ -529,9 +549,11 @@ async function executeMigrationStatusCommand(
       targetHash,
       migrations,
     });
+    const displayTree =
+      showSpaceHeadings && tree.length > 0 ? indentMigrationGraphTreeBlock(tree, '  ') : tree;
     treeSections.push({
       spaceId: spaceEntry.spaceId,
-      tree,
+      tree: displayTree,
       showHeading: showSpaceHeadings,
     });
   }
@@ -567,16 +589,19 @@ async function executeMigrationStatusCommand(
   }
 
   const appMarkerHash = markersBySpace.get(aggregate.app.spaceId)?.storageHash;
-  const summary = hasAmbiguousTarget
-    ? 'Multiple valid migration paths — select a target with --to'
-    : markerCannotReachTarget
-      ? 'Database marker cannot reach the selected target'
-      : buildStatusHeadline({
-          pendingCount: totalPending,
-          targetHash: headlineTargetHash,
-          markerDiverged,
-          markerHash: appMarkerHash,
-        });
+  const summary = markerCannotReachTarget
+    ? buildNoPathSummary({
+        markerHash: appMarkerHash,
+        targetHash: headlineTargetHash,
+        explicitTarget: options.to !== undefined,
+        refName: activeRefName,
+      })
+    : buildStatusHeadline({
+        pendingCount: totalPending,
+        targetHash: headlineTargetHash,
+        markerDiverged,
+        markerHash: appMarkerHash,
+      });
 
   if (scopedSpaces.every((s) => s.migrations.length === 0)) {
     return ok({
@@ -613,6 +638,7 @@ export function createMigrationStatusCommand(): Command {
     'prisma-next migration status --db $DATABASE_URL',
     'prisma-next migration status --to production --db $DATABASE_URL',
     'prisma-next migration status --from sha256:abc --to production',
+    'prisma-next migration status --legend --from sha256:abc --to production',
   ]);
   setCommandSeeAlso(command, [
     { verb: 'migration log', oneLiner: 'Show executed migration history' },
@@ -632,10 +658,16 @@ export function createMigrationStatusCommand(): Command {
       '--from <contract>',
       'Origin contract reference; same grammar as --to. Supplying --from switches to offline path computation.',
     )
+    .option('--legend', 'Print a key for the tree glyphs and lane colors')
     .action(async (options: MigrationStatusOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);
 
+      const legendValidation = validateLegendOptions(options, flags);
+      if (!legendValidation.ok) {
+        process.exit(handleResult(legendValidation, flags, ui));
+      }
+
       const result = await executeMigrationStatusCommand(options, flags, ui);
 
       const exitCode = handleResult(result, flags, ui, (statusResult) => {

package/src/control-api/operations/db-apply.ts

@@ -33,7 +33,12 @@ import type {
   OnControlProgress,
   PerSpaceExecutionEntry,
 } from '../types';
-import { applyMigration, buildPerSpaceBreakdown, collectOrdered } from './apply';
+import {
+  applyMigration,
+  buildPerSpaceBreakdown,
+  collectOrdered,
+  type OrderedResolution,
+} from './apply';
 import { stripOperations } from './migration-helpers';
 
 /**
@@ -255,9 +260,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
 }
 
 function aggregatePlannerWarnings(
-  orderedResolutions: ReadonlyArray<{
-    readonly entry: { readonly warnings?: readonly MigrationPlannerConflict[] };
-  }>,
+  orderedResolutions: readonly OrderedResolution[],
 ): readonly MigrationPlannerConflict[] | undefined {
   const warnings = orderedResolutions.flatMap((r) => r.entry.warnings ?? []);
   return warnings.length > 0 ? warnings : undefined;

package/src/utils/cli-errors.ts

@@ -108,6 +108,23 @@ export function errorRefSetEmptySentinel(hash: string): CliStructuredError {
   });
 }
 
+/**
+ * `--legend` was combined with a machine-readable or silent output flag.
+ * The legend is human-only decoration on stderr.
+ */
+export function errorLegendHumanOnly(
+  conflictingFlag: '--json' | '--dot' | '--quiet',
+): CliStructuredError {
+  return errorRuntime('`--legend` is only available for human-readable output', {
+    why: `\`--legend\` prints a glyph key to stderr and cannot be combined with ${conflictingFlag}.`,
+    fix: `Omit ${conflictingFlag} to print the legend alongside the tree, or omit --legend when using ${conflictingFlag}.`,
+    meta: {
+      code: 'MIGRATION.LEGEND_HUMAN_ONLY',
+      conflictingFlag,
+    },
+  });
+}
+
 /**
  * `--space <id>` was given a value that doesn't satisfy the contract-space
  * naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before

package/src/utils/formatters/migration-graph-lane-colors.ts

@@ -1,4 +1,5 @@
 import { createColors } from 'colorette';
+import type { StructuralCell } from './migration-graph-layout';
 
 export type LaneColorizer = (text: string) => string;
 
@@ -13,6 +14,12 @@ export const LANE_COLOR_CYCLE: readonly LaneColorizer[] = [
   red,
 ];
 
+/**
+ * The leftmost lane (column 0) renders neutral — no palette hue. Columns ≥ 1
+ * rotate through {@link LANE_COLOR_CYCLE}.
+ */
+export const NEUTRAL_LANE_COLUMN = 0;
+
 /**
  * The hue for a gutter column. The leftmost lane (column 0) is **neutral** — it
  * has nothing to be told apart from in the common single-lane linear case, so
@@ -23,9 +30,165 @@ export const LANE_COLOR_CYCLE: readonly LaneColorizer[] = [
  * branch identity, exactly like `git log --graph`.
  */
 export function laneColorForColumn(column: number): LaneColorizer {
-  if (column <= 0) {
+  if (column <= NEUTRAL_LANE_COLUMN) {
     return (text) => text;
   }
   const colorizer = LANE_COLOR_CYCLE[(column - 1) % LANE_COLOR_CYCLE.length];
   return colorizer ?? ((text) => text);
 }
+
+/**
+ * Style a structural glyph by its resolved colour column. Column 0 and the
+ * neutral sentinel render dim (`dimLane`); columns ≥ 1 take a palette hue.
+ */
+export function stylerForLaneColumn(
+  colorColumn: number,
+  colorize: boolean,
+  dimLane: (text: string) => string,
+): LaneColorizer {
+  if (!colorize || colorColumn <= NEUTRAL_LANE_COLUMN) {
+    return dimLane;
+  }
+  return laneColorForColumn(colorColumn);
+}
+
+/**
+ * The colour-source column for each cell of a row, resolved together because a
+ * routed back-arc spans columns and must read as **one hue** rather than a
+ * per-column "rainbow".
+ */
+export interface RowArcLaneColors {
+  /** Colour column for a cell's structural glyph (lane / spine / arc body). */
+  readonly lane: readonly number[];
+  /** Colour column for a node arc-pair's connector half (`◂` / `─`). */
+  readonly connector: readonly number[];
+  /**
+   * Colour column for the trailing `─` of a landing tee (`┴─`). The junction
+   * (`lane`) keeps its own column; the dash leads into the next converging arc.
+   */
+  readonly dash: readonly number[];
+}
+
+/**
+ * Resolve per-cell colour columns for a node/arc row. Scanning right-to-left
+ * lets each arc segment inherit the hue of the arc it leads into.
+ */
+export function resolveRowArcLaneColors(cells: readonly StructuralCell[]): RowArcLaneColors {
+  const lane = new Array<number>(cells.length);
+  const connector = new Array<number>(cells.length);
+  const dash = new Array<number>(cells.length);
+  let arcCorner = NEUTRAL_LANE_COLUMN;
+  let landingAnchor = NEUTRAL_LANE_COLUMN;
+  for (let column = cells.length - 1; column >= 0; column--) {
+    const cell = cells[column];
+    connector[column] = landingAnchor !== NEUTRAL_LANE_COLUMN ? landingAnchor : arcCorner;
+    switch (cell?.kind) {
+      case 'arc-branch-corner':
+        arcCorner = column;
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-land-corner':
+        arcCorner = column;
+        landingAnchor = column;
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-branch-tee':
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-land-tee':
+        lane[column] = column;
+        dash[column] = landingAnchor === NEUTRAL_LANE_COLUMN ? column : landingAnchor;
+        landingAnchor = column;
+        break;
+      case 'arc-crossing':
+      case 'arc-land-bridge': {
+        const served = landingAnchor !== NEUTRAL_LANE_COLUMN ? landingAnchor : arcCorner;
+        lane[column] = served;
+        dash[column] = served;
+        break;
+      }
+      case 'horizontal-pass':
+        lane[column] = arcCorner === NEUTRAL_LANE_COLUMN ? column : arcCorner;
+        dash[column] = lane[column] ?? column;
+        break;
+      case 'node':
+        lane[column] = column;
+        dash[column] = column;
+        arcCorner = NEUTRAL_LANE_COLUMN;
+        landingAnchor = NEUTRAL_LANE_COLUMN;
+        break;
+      default:
+        lane[column] = column;
+        dash[column] = column;
+        arcCorner = NEUTRAL_LANE_COLUMN;
+        landingAnchor = NEUTRAL_LANE_COLUMN;
+    }
+  }
+  return { lane, connector, dash };
+}
+
+/**
+ * Per-cell colour for a forward branch/merge connector row, split into the
+ * cell's junction `glyph` and its trailing `dash`.
+ */
+export interface ConnectorLaneColors {
+  /** Colour column for a cell's junction glyph (`├` / `┬` / `┴` / `╮` / `╯`). */
+  readonly glyph: readonly number[];
+  /** Colour column for a tee's trailing `─` — the branch it leads into. */
+  readonly dash: readonly number[];
+}
+
+/**
+ * Resolve per-cell connector colours. Scanning right-to-left, a corner or an
+ * intermediate tee anchors its own lane, but a tee's trailing dash leads into
+ * the branch on its right.
+ */
+export function resolveConnectorLaneColors(
+  cells: readonly StructuralCell[],
+  startLane: number,
+): ConnectorLaneColors {
+  const glyph = new Array<number>(cells.length);
+  const dash = new Array<number>(cells.length);
+  let owner = NEUTRAL_LANE_COLUMN;
+  for (let column = cells.length - 1; column >= 0; column--) {
+    const cell = cells[column];
+    switch (cell?.kind) {
+      case 'branch-corner':
+      case 'merge-corner':
+        owner = column;
+        glyph[column] = column;
+        dash[column] = column;
+        break;
+      case 'branch-tee':
+      case 'merge-tee':
+        if (column === startLane) {
+          const served = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+          glyph[column] = column;
+          dash[column] = served;
+        } else {
+          dash[column] = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+          glyph[column] = column;
+          owner = column;
+        }
+        break;
+      case 'arc-crossing':
+        glyph[column] = column;
+        dash[column] = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+        owner = column;
+        break;
+      case 'horizontal-pass': {
+        const served = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+        glyph[column] = served;
+        dash[column] = served;
+        break;
+      }
+      default:
+        glyph[column] = column;
+        dash[column] = column;
+    }
+  }
+  return { glyph, dash };
+}