@prisma-next/cli 0.11.0 → 0.12.0

package/src/utils/formatters/migration-list-graph-topology.ts

@@ -0,0 +1,368 @@
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
+import type { MigrationListEntry } from './migration-list-types';
+
+export type MigrationEdgeKind = 'forward' | 'rollback' | 'self';
+
+export interface MigrationListGraphTopology {
+  readonly kindByMigrationHash: ReadonlyMap<string, MigrationEdgeKind>;
+  readonly forwardInDegree: ReadonlyMap<string, number>;
+  readonly forwardOutDegree: ReadonlyMap<string, number>;
+}
+
+// ---------------------------------------------------------------------------
+// Shared classifier — operates on a normalized edge shape common to both
+// MigrationListEntry (Tier-2) and MigrationEdge / MigrationGraph (Tier-3).
+// ---------------------------------------------------------------------------
+
+interface NormalizedEdge {
+  readonly hash: string;
+  readonly from: string;
+  readonly to: string;
+  readonly dirName: string;
+}
+
+function compareDirNameDesc(a: NormalizedEdge, b: NormalizedEdge): number {
+  return b.dirName.localeCompare(a.dirName);
+}
+
+function bumpDegree(map: Map<string, number>, key: string): void {
+  map.set(key, (map.get(key) ?? 0) + 1);
+}
+
+function forwardRootsForDepth(
+  nodes: ReadonlySet<string>,
+  candidates: readonly NormalizedEdge[],
+): readonly string[] {
+  const inDegree = new Map<string, number>();
+  for (const node of nodes) {
+    inDegree.set(node, 0);
+  }
+  for (const edge of candidates) {
+    bumpDegree(inDegree, edge.to);
+  }
+
+  const roots: string[] = [];
+  for (const node of nodes) {
+    if ((inDegree.get(node) ?? 0) === 0) {
+      roots.push(node);
+    }
+  }
+  roots.sort((a, b) => {
+    if (a === EMPTY_CONTRACT_HASH) return -1;
+    if (b === EMPTY_CONTRACT_HASH) return 1;
+    return a.localeCompare(b);
+  });
+  if (roots.length > 0) return roots;
+
+  return [...nodes].sort((a, b) => {
+    if (a === EMPTY_CONTRACT_HASH) return -1;
+    if (b === EMPTY_CONTRACT_HASH) return 1;
+    return a.localeCompare(b);
+  });
+}
+
+function longestPathDepths(
+  nodes: ReadonlySet<string>,
+  candidates: readonly NormalizedEdge[],
+): Map<string, number> {
+  const depth = new Map<string, number>();
+  for (const root of forwardRootsForDepth(nodes, candidates)) {
+    depth.set(root, 0);
+  }
+
+  const maxPasses = nodes.size;
+  for (let pass = 0; pass < maxPasses; pass++) {
+    let changed = false;
+    for (const edge of candidates) {
+      const base = depth.get(edge.from);
+      if (base === undefined) continue;
+      const next = base + 1;
+      if (next > (depth.get(edge.to) ?? -1)) {
+        depth.set(edge.to, next);
+        changed = true;
+      }
+    }
+    if (!changed) break;
+  }
+
+  for (const node of nodes) {
+    if (!depth.has(node)) {
+      depth.set(node, 0);
+    }
+  }
+
+  return depth;
+}
+
+function canReachForward(
+  start: string,
+  goal: string,
+  candidates: readonly NormalizedEdge[],
+): boolean {
+  if (start === goal) return true;
+
+  const outgoing = new Map<string, string[]>();
+  for (const edge of candidates) {
+    const bucket = outgoing.get(edge.from);
+    if (bucket) bucket.push(edge.to);
+    else outgoing.set(edge.from, [edge.to]);
+  }
+
+  const visited = new Set<string>([start]);
+  const queue = [start];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    if (node === undefined) continue;
+    for (const next of outgoing.get(node) ?? []) {
+      if (next === goal) return true;
+      if (!visited.has(next)) {
+        visited.add(next);
+        queue.push(next);
+      }
+    }
+  }
+
+  return false;
+}
+
+function isMarginalForwardEdge(
+  nodes: ReadonlySet<string>,
+  candidates: readonly NormalizedEdge[],
+  edge: NormalizedEdge,
+): boolean {
+  const without = candidates.filter((candidate) => candidate !== edge);
+  const depthWithout = longestPathDepths(nodes, without);
+  const depthWith = longestPathDepths(nodes, candidates);
+  const fromDepth = depthWithout.get(edge.from) ?? 0;
+  const toWith = depthWith.get(edge.to) ?? 0;
+  return toWith > fromDepth;
+}
+
+// The first branch is the load-bearing one: a forward edge `from → to` is a
+// disguised node-skipping rollback when, after removing it, `to` can still
+// reach `from` and `from` sits strictly deeper than `to + 1` (a longer path
+// already connects them). This branch fires on every cycle-closing edge, and
+// the caller peels exactly one edge (dirName-max) per iteration before
+// recomputing — so cycles are broken deterministically regardless of edge
+// order. `isMarginalForwardEdge` is only a fallback for the residual case and
+// is reached only while the candidate set is still cyclic.
+function shouldPeelForwardEdge(
+  nodes: ReadonlySet<string>,
+  candidates: readonly NormalizedEdge[],
+  edge: NormalizedEdge,
+): boolean {
+  const without = candidates.filter((candidate) => candidate !== edge);
+  const depthWithout = longestPathDepths(nodes, without);
+  const fromDepth = depthWithout.get(edge.from) ?? 0;
+  const toWithout = depthWithout.get(edge.to) ?? 0;
+
+  if (canReachForward(edge.to, edge.from, without) && fromDepth > toWithout + 1) {
+    return true;
+  }
+
+  return !isMarginalForwardEdge(nodes, candidates, edge);
+}
+
+function peelNonMarginalForwardEdges(
+  nodes: ReadonlySet<string>,
+  kindByMigrationHash: Map<string, MigrationEdgeKind>,
+  nonSelf: readonly NormalizedEdge[],
+): void {
+  let candidates = nonSelf.filter((edge) => kindByMigrationHash.get(edge.hash) === 'forward');
+
+  while (candidates.length > 0) {
+    const rollbackCandidates = candidates.filter((edge) =>
+      shouldPeelForwardEdge(nodes, candidates, edge),
+    );
+    if (rollbackCandidates.length === 0) break;
+
+    rollbackCandidates.sort(compareDirNameDesc);
+    const rollback = rollbackCandidates[0];
+    if (rollback === undefined) break;
+
+    kindByMigrationHash.set(rollback.hash, 'rollback');
+    candidates = candidates.filter((edge) => edge !== rollback);
+  }
+}
+
+/**
+ * DFS with dirName-descending traversal. A GRAY target is a rollback only when it
+ * is the immediate DFS parent of the source — cross-links to other GRAY nodes
+ * stay forward. A follow-up peel pass drops node-skipping rollbacks (target can
+ * reach the source on the forward subgraph and sits more than one rank below).
+ */
+function classifyNormalizedEdges(edges: readonly NormalizedEdge[]): MigrationListGraphTopology {
+  const nodes = new Set<string>();
+  const kindByMigrationHash = new Map<string, MigrationEdgeKind>();
+  const outgoingByFrom = new Map<string, NormalizedEdge[]>();
+  const nonSelf: NormalizedEdge[] = [];
+
+  for (const edge of edges) {
+    nodes.add(edge.from);
+    nodes.add(edge.to);
+
+    if (edge.from === edge.to) {
+      kindByMigrationHash.set(edge.hash, 'self');
+      continue;
+    }
+
+    nonSelf.push(edge);
+    const bucket = outgoingByFrom.get(edge.from);
+    if (bucket) bucket.push(edge);
+    else outgoingByFrom.set(edge.from, [edge]);
+  }
+
+  for (const bucket of outgoingByFrom.values()) {
+    bucket.sort(compareDirNameDesc);
+  }
+
+  const nonSelfInDegree = new Map<string, number>();
+  for (const node of nodes) {
+    nonSelfInDegree.set(node, 0);
+  }
+  for (const bucket of outgoingByFrom.values()) {
+    for (const edge of bucket) {
+      bumpDegree(nonSelfInDegree, edge.to);
+    }
+  }
+
+  const dfsRoots: string[] = [];
+  for (const node of nodes) {
+    if ((nonSelfInDegree.get(node) ?? 0) === 0) {
+      dfsRoots.push(node);
+    }
+  }
+  dfsRoots.sort((a, b) => {
+    if (a === EMPTY_CONTRACT_HASH) return -1;
+    if (b === EMPTY_CONTRACT_HASH) return 1;
+    return a.localeCompare(b);
+  });
+  if (dfsRoots.length === 0) {
+    dfsRoots.push(...[...nodes].sort((a, b) => a.localeCompare(b)));
+  }
+
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map<string, number>();
+  const dfsParent = new Map<string, string | undefined>();
+  for (const node of nodes) {
+    color.set(node, WHITE);
+  }
+
+  interface Frame {
+    node: string;
+    outgoing: readonly NormalizedEdge[];
+    index: number;
+  }
+  const stack: Frame[] = [];
+
+  function isImmediateDfsParent(ancestor: string, node: string): boolean {
+    return dfsParent.get(node) === ancestor;
+  }
+
+  function pushFrame(node: string, parent: string | undefined): void {
+    color.set(node, GRAY);
+    dfsParent.set(node, parent);
+    stack.push({ node, outgoing: outgoingByFrom.get(node) ?? [], index: 0 });
+  }
+
+  function runDfsFrom(root: string): void {
+    if (color.get(root) !== WHITE) return;
+    pushFrame(root, undefined);
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (frame === undefined) break;
+      if (frame.index >= frame.outgoing.length) {
+        color.set(frame.node, BLACK);
+        stack.pop();
+        continue;
+      }
+
+      const edge = frame.outgoing[frame.index];
+      frame.index += 1;
+      if (edge === undefined) continue;
+
+      const v = edge.to;
+      const vColor = color.get(v);
+      if (vColor === GRAY && isImmediateDfsParent(v, frame.node)) {
+        kindByMigrationHash.set(edge.hash, 'rollback');
+      } else {
+        kindByMigrationHash.set(edge.hash, 'forward');
+        if (vColor === WHITE) {
+          pushFrame(v, frame.node);
+        }
+      }
+    }
+  }
+
+  for (const root of dfsRoots) {
+    runDfsFrom(root);
+  }
+  const remainingWhite = [...nodes].filter((node) => color.get(node) === WHITE);
+  remainingWhite.sort((a, b) => a.localeCompare(b));
+  for (const root of remainingWhite) {
+    runDfsFrom(root);
+  }
+
+  peelNonMarginalForwardEdges(nodes, kindByMigrationHash, nonSelf);
+
+  const forwardInDegree = new Map<string, number>();
+  const forwardOutDegree = new Map<string, number>();
+
+  for (const edge of edges) {
+    if (kindByMigrationHash.get(edge.hash) !== 'forward') continue;
+    bumpDegree(forwardOutDegree, edge.from);
+    bumpDegree(forwardInDegree, edge.to);
+  }
+
+  return {
+    kindByMigrationHash,
+    forwardInDegree,
+    forwardOutDegree,
+  };
+}
+
+function canonicalFrom(from: string | null): string {
+  return from ?? EMPTY_CONTRACT_HASH;
+}
+
+/**
+ * Classify forward/rollback/self for a Tier-2 `MigrationListEntry[]` edge set.
+ * Returns the kind of each migration plus the forward in/out degree of each
+ * contract node. This is the established Tier-2 surface; its behaviour is
+ * unchanged — only its implementation now delegates to the shared classifier.
+ */
+export function classifyMigrationListGraphTopology(
+  entries: readonly MigrationListEntry[],
+): MigrationListGraphTopology {
+  const normalized: NormalizedEdge[] = entries.map((entry) => ({
+    hash: entry.migrationHash,
+    from: canonicalFrom(entry.from),
+    to: entry.to,
+    dirName: entry.dirName,
+  }));
+  return classifyNormalizedEdges(normalized);
+}
+
+/**
+ * Classify forward/rollback/self for a `MigrationGraph` edge set (Tier-3).
+ * Delegates to the same shared classifier as `classifyMigrationListGraphTopology`
+ * so both tiers agree on forward/rollback/self without duplicating logic.
+ */
+export function classifyMigrationGraphTopology(graph: MigrationGraph): MigrationListGraphTopology {
+  const normalized: NormalizedEdge[] = [];
+  for (const edges of graph.forwardChain.values()) {
+    for (const edge of edges) {
+      normalized.push({
+        hash: edge.migrationHash,
+        from: edge.from,
+        to: edge.to,
+        dirName: edge.dirName,
+      });
+    }
+  }
+  return classifyNormalizedEdges(normalized);
+}

package/src/utils/formatters/migration-list-render.ts

@@ -0,0 +1,191 @@
+import type { GlyphMode } from '../glyph-mode';
+import {
+  computeMigrationDirNameWidth,
+  formatMigrationDataColumn,
+  migrationListEmptySource,
+  migrationListForwardArrow,
+  migrationListKindGlyph,
+} from './migration-list-data-column';
+import {
+  classifyMigrationListGraphTopology,
+  type MigrationEdgeKind,
+  type MigrationListGraphTopology,
+} from './migration-list-graph-topology';
+import type { MigrationListEntry, MigrationListResult } from './migration-list-types';
+
+export type { GlyphMode } from '../glyph-mode';
+export type { MigrationEdgeKind } from './migration-list-graph-topology';
+export type {
+  MigrationListEntry,
+  MigrationListResult,
+  MigrationSpaceListEntry,
+} from './migration-list-types';
+
+/**
+ * Semantic styler for `migration list` output tokens. Token-typed so
+ * the renderer composes presentation-neutral fragments and the styler
+ * decides how each token kind is decorated (ANSI codes, plain text,
+ * etc.). The renderer pads with raw spaces *outside* styled tokens so
+ * visible column widths stay stable regardless of what the styler
+ * emits — adding ANSI escape sequences never disturbs alignment.
+ *
+ * `invariants` and `refs` receive the underlying string arrays rather
+ * than a pre-joined string so per-element styling (e.g. distinguishing
+ * the live-DB `db` marker from user-named refs) is possible without
+ * having to re-parse a joined block.
+ */
+export interface MigrationListStyler {
+  kind(text: string): string;
+  dirName(text: string): string;
+  sourceHash(text: string): string;
+  destHash(text: string): string;
+  glyph(text: string): string;
+  lane(text: string): string;
+  invariants(ids: readonly string[]): string;
+  refs(names: readonly string[]): string;
+  spaceHeading(text: string): string;
+  summary(text: string): string;
+  emptyState(text: string): string;
+}
+
+export const IDENTITY_MIGRATION_LIST_STYLER: MigrationListStyler = {
+  kind: (text) => text,
+  dirName: (text) => text,
+  sourceHash: (text) => text,
+  destHash: (text) => text,
+  glyph: (text) => text,
+  lane: (text) => text,
+  invariants: (ids) => `{${ids.join(', ')}}`,
+  refs: (names) => `(${names.join(', ')})`,
+  spaceHeading: (text) => text,
+  summary: (text) => text,
+  emptyState: (text) => text,
+};
+
+function resolveEdgeKind(
+  migrationHash: string,
+  kindByMigrationHash: ReadonlyMap<string, MigrationEdgeKind>,
+): MigrationEdgeKind {
+  return kindByMigrationHash.get(migrationHash) ?? 'forward';
+}
+
+function formatMigrationRow(
+  migration: MigrationListEntry,
+  dirNameWidth: number,
+  edgeKind: MigrationEdgeKind,
+  glyphMode: GlyphMode,
+  style: MigrationListStyler,
+): string {
+  const kindColumn = `${style.kind(migrationListKindGlyph(glyphMode, edgeKind))} `;
+  const data = formatMigrationDataColumn(migration, {
+    dirNameWidth,
+    edgeKind,
+    style,
+    forwardArrow: migrationListForwardArrow(glyphMode),
+    emptySource: migrationListEmptySource(glyphMode),
+  });
+  return `${kindColumn}${data}`;
+}
+
+function formatEmptyStateLine(spaceId: string, style: MigrationListStyler): string {
+  return style.emptyState(`There are no migrations in migrations/${spaceId}/ yet`);
+}
+
+function renderSpaceBlock(
+  spaceId: string,
+  migrations: readonly MigrationListEntry[],
+  multiSpace: boolean,
+  glyphMode: GlyphMode,
+  kindByMigrationHash: ReadonlyMap<string, MigrationEdgeKind>,
+  style: MigrationListStyler,
+): readonly string[] {
+  if (migrations.length === 0) {
+    const emptyLine = formatEmptyStateLine(spaceId, style);
+    if (!multiSpace) {
+      return [emptyLine];
+    }
+    return [style.spaceHeading(`${spaceId}:`), `  ${emptyLine}`];
+  }
+
+  const dirNameWidth = computeMigrationDirNameWidth(migrations);
+  const rows = migrations.map((entry) =>
+    formatMigrationRow(
+      entry,
+      dirNameWidth,
+      resolveEdgeKind(entry.migrationHash, kindByMigrationHash),
+      glyphMode,
+      style,
+    ),
+  );
+  if (!multiSpace) {
+    return rows;
+  }
+  return [style.spaceHeading(`${spaceId}:`), ...rows.map((row) => `  ${row}`)];
+}
+
+export function buildMigrationListTopologyBySpace(
+  result: MigrationListResult,
+): ReadonlyMap<string, MigrationListGraphTopology> {
+  const topologyBySpaceId = new Map<string, MigrationListGraphTopology>();
+  for (const space of result.spaces) {
+    topologyBySpaceId.set(space.spaceId, classifyMigrationListGraphTopology(space.migrations));
+  }
+  return topologyBySpaceId;
+}
+
+/**
+ * Compose the styled `migration list` output. The renderer is
+ * presentation-neutral — every token passes through `style` before
+ * landing in the output, so the same composition serves the pure-text
+ * path ({@link renderMigrationList} via
+ * {@link IDENTITY_MIGRATION_LIST_STYLER}) and the ANSI-styled CLI path
+ * (via the ANSI styler the CLI shell wires up).
+ */
+export function renderMigrationListWithStyle(
+  result: MigrationListResult,
+  style: MigrationListStyler,
+  glyphMode: GlyphMode = 'unicode',
+  topologyBySpaceId: ReadonlyMap<
+    string,
+    MigrationListGraphTopology
+  > = buildMigrationListTopologyBySpace(result),
+): string {
+  const multiSpace = result.spaces.length > 1;
+  const lines: string[] = [];
+
+  for (let index = 0; index < result.spaces.length; index++) {
+    const space = result.spaces[index]!;
+    if (index > 0) {
+      lines.push('');
+    }
+    const topology = topologyBySpaceId.get(space.spaceId);
+    const kindByMigrationHash =
+      topology?.kindByMigrationHash ??
+      classifyMigrationListGraphTopology(space.migrations).kindByMigrationHash;
+    lines.push(
+      ...renderSpaceBlock(
+        space.spaceId,
+        space.migrations,
+        multiSpace,
+        glyphMode,
+        kindByMigrationHash,
+        style,
+      ),
+    );
+  }
+
+  const totalMigrations = result.spaces.reduce(
+    (count, space) => count + space.migrations.length,
+    0,
+  );
+  if (totalMigrations > 0) {
+    lines.push('');
+    lines.push(style.summary(result.summary));
+  }
+
+  return lines.join('\n');
+}
+
+export function renderMigrationList(result: MigrationListResult): string {
+  return renderMigrationListWithStyle(result, IDENTITY_MIGRATION_LIST_STYLER);
+}

package/src/utils/formatters/migration-list-styler.ts

@@ -0,0 +1,63 @@
+import { bold, cyan, cyanBright, dim, green, yellow } from 'colorette';
+import { IDENTITY_MIGRATION_LIST_STYLER, type MigrationListStyler } from './migration-list-render';
+
+/**
+ * The current contract overlay marker. Unlike user refs, this names the user's
+ * declared desired state — the implicit base/target for `plan` / `migrate` —
+ * not a stored label. It is emphasized (bold) so it stands out from plain refs
+ * (including the live-database `db` marker, which is just another ref).
+ */
+export const CONTRACT_MARKER_NAME = 'contract';
+
+function styleRefName(name: string): string {
+  return name === CONTRACT_MARKER_NAME ? bold(green(name)) : green(name);
+}
+
+/**
+ * Build a {@link MigrationListStyler} that decorates `migration list`
+ * tokens with ANSI SGR codes. When `useColor` is `false` (non-TTY,
+ * `--no-color`, `NO_COLOR=1`, piped output) the function returns the
+ * shared identity styler so callers get plain text with zero ANSI
+ * bytes — pipe-friendly by construction.
+ *
+ * Palette:
+ *
+ * - `dirName`: bold
+ * - `sourceHash`: dim cyan
+ * - `destHash`: bright cyan
+ * - `kind` (`*` / `↩` / `⟲`): bright — the signal; lanes and arrows dim
+ * - `glyph` (`→` / `⟲` / `∅`): dim
+ * - `lane` (graph gutter lines `│` and fan/join connectors `├─┐` / `├─┘`): dim
+ * - `invariants` (`{...}`): yellow
+ * - `refs` (`(...)`): green; the `contract` desired-state marker inside is
+ *   green-bold (the active ref is bolded separately by the tree styler)
+ * - `spaceHeading` (`<spaceId>:`): bold
+ * - `summary`: dim
+ * - `emptyState`: dim
+ */
+export function createAnsiMigrationListStyler(opts: {
+  readonly useColor: boolean;
+}): MigrationListStyler {
+  if (!opts.useColor) {
+    return IDENTITY_MIGRATION_LIST_STYLER;
+  }
+  return {
+    // Kind glyphs stay bright in both flat and graph views; lanes carry the dim gutter.
+    kind: (text) => text,
+    dirName: (text) => bold(text),
+    sourceHash: (text) => dim(cyan(text)),
+    destHash: (text) => cyanBright(text),
+    glyph: (text) => dim(text),
+    lane: (text) => dim(text),
+    invariants: (ids) => yellow(`{${ids.join(', ')}}`),
+    refs: (names) => {
+      const open = green('(');
+      const close = green(')');
+      const separator = green(', ');
+      return open + names.map(styleRefName).join(separator) + close;
+    },
+    spaceHeading: (text) => bold(text),
+    summary: (text) => dim(text),
+    emptyState: (text) => dim(text),
+  };
+}

package/src/utils/formatters/migration-list-types.ts

@@ -0,0 +1,21 @@
+export interface MigrationListEntry {
+  readonly dirName: string;
+  readonly from: string | null;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly operationCount: number;
+  readonly createdAt: string;
+  readonly refs: readonly string[];
+  readonly providedInvariants: readonly string[];
+}
+
+export interface MigrationSpaceListEntry {
+  readonly spaceId: string;
+  readonly migrations: readonly MigrationListEntry[];
+}
+
+export interface MigrationListResult {
+  readonly ok: true;
+  readonly spaces: readonly MigrationSpaceListEntry[];
+  readonly summary: string;
+}