@prisma-next/cli 0.12.0-dev.9 → 0.13.0-dev.1

package/src/control-api/types.ts

@@ -2,7 +2,12 @@ import type {
   ContractSourceDiagnostics,
   ContractSourceProvider,
 } from '@prisma-next/config/config-types';
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type {
+  Contract,
+  ContractMarkerRecord,
+  LedgerEntryRecord,
+} from '@prisma-next/contract/types';
+import type { AuthoringPslBlockDescriptorNamespace } from '@prisma-next/framework-components/authoring';
 import type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
@@ -67,7 +72,7 @@ export type ControlActionName =
   | 'dbInit'
   | 'dbUpdate'
   | 'dbVerify'
-  | 'migrationApply'
+  | 'migrate'
   | 'verify'
   | 'schemaVerify'
   | 'sign'
@@ -391,6 +396,7 @@ export interface DbInitSuccess {
    */
   readonly perSpace?: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly summary: string;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
 }
 
 /**
@@ -406,6 +412,7 @@ export interface DbInitFailure {
   readonly summary: string;
   readonly why: string | undefined;
   readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
   readonly meta: Record<string, unknown> | undefined;
   readonly marker?: {
     readonly storageHash?: string;
@@ -461,6 +468,7 @@ export interface DbUpdateSuccess {
    */
   readonly perSpace?: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly summary: string;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
 }
 
 /**
@@ -476,6 +484,7 @@ export interface DbUpdateFailure {
   readonly summary: string;
   readonly why: string | undefined;
   readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
   readonly meta: Record<string, unknown> | undefined;
 }
 
@@ -532,17 +541,17 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
 // ============================================================================
 
 /**
- * Options for the aggregate-walking `migrationApply` operation.
+ * Options for the aggregate-walking `migrate` operation.
  *
  * The control-api operation is responsible for: loading the
  * contract-space aggregate, reading per-space marker rows from the
  * live database, plotting per-space paths via `graphWalkStrategy`
  * (replay-only — no synth, no introspection), and dispatching
- * through the shared `applyMigration` primitive. The CLI command
+ * through the shared `runMigration` primitive. The CLI command
  * just resolves the descriptor surface (config, refs, contract
  * envelope, app-space migration packages) and hands the inputs in.
  */
-export interface MigrationApplyOptions {
+export interface MigrateOptions {
   /** Already-validated app contract (the canonical "where we are heading" hash). */
   readonly contract: unknown;
   /** Migrations root directory (`migrations/` under the project). */
@@ -567,7 +576,7 @@ export interface MigrationApplyOptions {
    */
   readonly refName?: string;
   /**
-   * Database connection. If provided, migrationApply will connect before executing.
+   * Database connection. If provided, migrate will connect before executing.
    * If omitted, the client must already be connected.
    */
   readonly connection?: unknown;
@@ -611,7 +620,7 @@ export interface MigrationApplyStep {
  * Per-space aggregate detail (markers, ops grouped by space) lives
  * on `perSpace[]`; this list is the per-edge view.
  */
-export interface MigrationApplyAppliedEntry {
+export interface MigrateRanEntry {
   readonly spaceId: string;
   readonly dirName: string;
   readonly migrationHash: string;
@@ -621,13 +630,13 @@ export interface MigrationApplyAppliedEntry {
 }
 
 /**
- * Successful migrationApply result. Carries both the top-level fields
- * (`markerHash` is the **app member's** post-apply marker) and the
+ * Successful migrate result. Carries both the top-level fields
+ * (`markerHash` is the **app member's** post-migrate marker) and the
  * per-space breakdown (`perSpace` — markers / operations in canonical
  * schedule order).
  */
 /**
- * Path-decision summary for the **app member** post-apply. Surfaced
+ * Path-decision summary for the **app member** post-migrate. Surfaced
  * at the top level (and consumed by the cli-journeys suite, which
  * inspects `requiredInvariants`/`satisfiedInvariants`/
  * `selectedPath` to validate invariant routing).
@@ -635,7 +644,7 @@ export interface MigrationApplyAppliedEntry {
  * Per-space path decisions for extension members are not surfaced —
  * extensions own their own ref/invariant control.
  */
-export interface MigrationApplyPathDecision {
+export interface MigratePathDecision {
   readonly fromHash: string;
   readonly toHash: string;
   readonly alternativeCount: number;
@@ -652,10 +661,10 @@ export interface MigrationApplyPathDecision {
   }[];
 }
 
-export interface MigrationApplySuccess {
+export interface MigrateSuccess {
   readonly migrationsApplied: number;
   readonly markerHash: string;
-  readonly applied: readonly MigrationApplyAppliedEntry[];
+  readonly applied: readonly MigrateRanEntry[];
   readonly summary: string;
   /**
    * Per-space breakdown in canonical schedule order (extensions
@@ -666,31 +675,31 @@ export interface MigrationApplySuccess {
   /**
    * Path-decision data for the app member. Present whenever the
    * graph-walk strategy ran for the app (i.e. always for the
-   * aggregate-walking apply path). Absent only for the no-op
+   * aggregate-walking migrate path). Absent only for the no-op
    * "Already up to date" early return when the app has no plan.
    */
-  readonly pathDecision?: MigrationApplyPathDecision;
+  readonly pathDecision?: MigratePathDecision;
 }
 
 /**
- * Failure codes for migrationApply operation.
+ * Failure codes for migrate operation.
  */
-export type MigrationApplyFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
+export type MigrateFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
 
 /**
- * Failure details for migrationApply operation.
+ * Failure details for migrate operation.
  */
-export interface MigrationApplyFailure {
-  readonly code: MigrationApplyFailureCode;
+export interface MigrateFailure {
+  readonly code: MigrateFailureCode;
   readonly summary: string;
   readonly why: string | undefined;
   readonly meta: Record<string, unknown> | undefined;
 }
 
 /**
- * Result type for migrationApply operation.
+ * Result type for migrate operation.
  */
-export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyFailure>;
+export type MigrateResult = Result<MigrateSuccess, MigrateFailure>;
 
 // ============================================================================
 // Standalone Contract Emit Types
@@ -877,17 +886,26 @@ export interface ControlClient {
   readAllMarkers(): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
 
   /**
-   * Applies pre-planned on-disk migrations to the database.
+   * Reads the per-migration ledger journal for `space` in apply order.
+   * Returns an empty array when the ledger store does not yet exist or
+   * has no rows for that space.
+   */
+  readLedger(space?: string): Promise<readonly LedgerEntryRecord[]>;
+
+  /**
+   * Advances the database along the migration graph to the target contract.
    * Each migration runs in its own transaction with full execution checks.
-   * Resume-safe: re-running after failure picks up from the last applied migration.
+   * Resume-safe: re-running after failure picks up from the last run migration.
    *
-   * @param options.originHash - Explicit source hash for the apply path
-   * @param options.destinationHash - Explicit destination hash for the apply path
-   * @param options.pendingMigrations - Ordered migrations to execute
-   * @returns Result pattern: Ok with applied details, NotOk with failure details
+   * @param options.contract - The target contract to migrate to
+   * @param options.migrationsDir - Root migrations directory (`migrations/` under the project)
+   * @param options.refHash - Optional app-space ref override hash
+   * @param options.refInvariants - Required invariants on the user-supplied ref
+   * @param options.refName - Resolved name of the user-supplied app-space ref
+   * @returns Result pattern: Ok with migration details, NotOk with failure details
    * @throws If not connected, target doesn't support migrations, or infrastructure failure
    */
-  migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult>;
+  migrate(options: MigrateOptions): Promise<MigrateResult>;
 
   /**
    * Introspects the database schema.
@@ -915,6 +933,15 @@ export interface ControlClient {
    */
   inferPslContract(schemaIR: unknown): PslDocumentAst | undefined;
 
+  /**
+   * Returns the assembled PSL block descriptors from the control stack — the full
+   * set of extension-contributed top-level block descriptors. The CLI's
+   * `contract infer` command threads these through to `printPsl` so
+   * extension-contributed blocks in the inferred AST round-trip back to PSL
+   * source. Forces `init()` so the stack is built before access.
+   */
+  getPslBlockDescriptors(): AuthoringPslBlockDescriptorNamespace;
+
   /**
    * Renders a textual preview of a migration plan's operations for the CLI's
    * "DDL preview" output. Delegates to the family instance's

package/src/utils/cli-errors.ts

@@ -28,7 +28,8 @@ import {
 import { errorRuntime } from '@prisma-next/errors/execution';
 import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';
-import type { MigrationApplyFailure } from '../control-api/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { MigrateFailure } from '../control-api/types';
 
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
@@ -108,6 +109,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
@@ -250,7 +268,7 @@ export function errorMarkerMismatch(
   });
 }
 
-export function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {
+export function errorPathUnreachable(failure: MigrateFailure): CliStructuredError {
   const meta = failure.meta ?? {};
   const fromHashMeta = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;
   // `buildPathNotFoundFailure` uses this sentinel in meta when the live marker is null.
@@ -325,10 +343,60 @@ export function mapMigrationToolsError(error: MigrationToolsError): CliStructure
   });
 }
 
+/**
+ * Shared "needs a live database" precondition for read verbs that consult the
+ * marker/ledger (`migration log`, `migration status`). A command needs both a
+ * connection string and a control-plane driver; either missing yields the same
+ * `PN-CLI-4005` envelope with `meta.missingFlags` (canonical long-form flags
+ * per CLI Style Guide §Errors) so callers can react programmatically. Returns
+ * `null` when both are present.
+ */
+export function requireLiveDatabase(args: {
+  readonly dbConnection: unknown;
+  readonly hasDriver: boolean;
+  readonly why: string;
+  readonly commandName?: string;
+  readonly retryCommand?: string;
+}): CliStructuredError | null {
+  if (args.dbConnection && args.hasDriver) {
+    return null;
+  }
+  const missingFlags = args.dbConnection ? [] : ['--db'];
+  return errorDatabaseConnectionRequired({
+    why: args.why,
+    missingFlags,
+    ...ifDefined('commandName', args.commandName),
+    ...ifDefined('retryCommand', args.retryCommand),
+  });
+}
+
 /**
  * Maps a `RefResolutionError` from the contract/migration reference
  * resolver into a CLI structured error envelope.
  */
+/**
+ * A migration ref (dirName or hash-prefix) resolves in more than one contract
+ * space. The user must qualify with `--space <id>` to disambiguate.
+ */
+export function errorAmbiguousMigrationRef(
+  ref: string,
+  spaceIds: readonly string[],
+): CliStructuredError {
+  const spaceList = spaceIds.join(', ');
+  return errorRuntime(
+    `Ambiguous migration reference: "${ref}" resolves in multiple spaces — qualify with --space <id>`,
+    {
+      why: `"${ref}" matches migrations in spaces: ${spaceList}.`,
+      fix: `Qualify with --space <id> to select one space. Available matching spaces: ${spaceList}.`,
+      meta: {
+        code: 'MIGRATION.AMBIGUOUS_MIGRATION_REF',
+        ref,
+        spaceIds: [...spaceIds],
+      },
+    },
+  );
+}
+
 export function mapRefResolutionError(error: RefResolutionError): CliStructuredError {
   switch (error.kind) {
     case 'not-found':

package/src/utils/formatters/errors.ts

@@ -1,8 +1,11 @@
+import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
+import { blindCast } from '@prisma-next/utils/casts';
 import { red } from 'colorette';
 
 import type { CliErrorConflict, CliErrorEnvelope } from '../cli-errors';
 import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
+import { formatPlannerWarningsBlock } from './migrations';
 
 /**
  * Formats error output for human-readable display.
@@ -67,6 +70,14 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
   if (error.docsUrl && isVerbose(flags, 1)) {
     lines.push(formatDimText(error.docsUrl));
   }
+  const plannerWarnings = error.meta?.['plannerWarnings'];
+  if (Array.isArray(plannerWarnings) && plannerWarnings.length > 0) {
+    const typedWarnings = blindCast<
+      readonly MigrationPlannerConflict[],
+      'mapDbUpdateFailure (db-update.ts) writes meta.plannerWarnings as MigrationPlannerConflict[]; meta is typed Record<string, unknown> so the channel erases the element type'
+    >(plannerWarnings);
+    lines.push(...formatPlannerWarningsBlock(typedWarnings, useColor));
+  }
   if (isVerbose(flags, 2) && error.meta) {
     lines.push(`${formatDimText(`  Meta: ${JSON.stringify(error.meta, null, 2)}`)}`);
   }

package/src/utils/formatters/migration-graph-command-render.ts

@@ -0,0 +1,239 @@
+/**
+ * Command graph renderer: composes the gutter (from the grid) with per-row labels.
+ *
+ * Pipeline: buildMigrationGraphRows → buildGrid → renderMigrationGraphCommand
+ *
+ * Each grid row is classified by its cells: a node row gets a contract label;
+ * a migration arrow row gets a migration label; connector rows get no label.
+ * Label format and styling live in `./migration-graph-labels`.
+ */
+
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import { ifDefined } from '@prisma-next/utils/defined';
+import stringWidth from 'string-width';
+import type { GlyphMode } from '../glyph-mode';
+import {
+  formatMigrationLabel,
+  formatNodeLabel,
+  type MigrationEdgeAnnotation,
+  type MigrationGraphLabelOptions,
+} from './migration-graph-labels';
+import type { Cell, CellLine, Grid } from './migration-graph-model';
+import { renderGridRow } from './migration-graph-occlusion-render';
+import type { ClassifiedEdge, MigrationGraphRowModel } from './migration-graph-rows';
+import type { MigrationListStyler } from './migration-list-render';
+
+const LABEL_GAP = 2;
+const MIN_HASH_DATA_COLUMN = 25;
+
+export interface RenderMigrationGraphCommandInput {
+  readonly grid: Grid;
+  readonly rowModel: MigrationGraphRowModel;
+  readonly colorize: boolean;
+  readonly glyphMode: GlyphMode;
+  readonly refsByHash?: ReadonlyMap<string, readonly string[]>;
+  readonly edgeAnnotationsByHash?: ReadonlyMap<string, MigrationEdgeAnnotation>;
+  readonly dbHash?: string;
+  readonly contractHash?: string;
+  readonly isAppSpace?: boolean;
+  readonly activeRefName?: string;
+  readonly styler?: MigrationListStyler;
+  /** Cross-space override for the gutter→label column (max gutter width). */
+  readonly globalLabelColumn?: number;
+  /** Cross-space override for the migration-name column width. */
+  readonly globalMaxDirNameWidth?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Row classification — derive each grid row's identity from its own cells.
+// ---------------------------------------------------------------------------
+
+type RowIdentity =
+  | { readonly kind: 'node'; readonly contractHash: string }
+  | { readonly kind: 'migration'; readonly edge: ClassifiedEdge; readonly lane: number }
+  | { readonly kind: 'none' };
+
+/**
+ * Classify a grid row by its own cells:
+ *   - a cell carrying a NodeRef → node row (contract label);
+ *   - a cell whose top line is an arrow ({up}/{down}/self-loop) → migration row;
+ *   - otherwise → no label.
+ *
+ * A migration's arrow appears in exactly one grid row (the forward `↑` row, the
+ * adjacent-rollback `↓` row, or the self-loop `⟲` row), so each migration gets
+ * exactly one label, on the row that draws its arrow.
+ *
+ * Two distinct migrations with identical content (same from/to/ops) hash to the
+ * SAME migration hash, so the arrow line is matched on BOTH its hash and its
+ * `dirName` (which the LineRef carries per-row) — otherwise both rows would
+ * resolve to one edge and the other migration's name would be lost.
+ */
+function classifyRow(
+  row: readonly Cell[],
+  edgesByHash: ReadonlyMap<string, readonly ClassifiedEdge[]>,
+): RowIdentity {
+  for (const cell of row) {
+    if (cell.node !== undefined) {
+      return { kind: 'node', contractHash: cell.node.contractHash };
+    }
+  }
+  for (const cell of row) {
+    const arrow = arrowLine(cell);
+    if (arrow === undefined) continue;
+    const candidates = edgesByHash.get(arrow.line.migrationHash) ?? [];
+    const edge = candidates.find((e) => e.dirName === arrow.line.dirName) ?? candidates[0];
+    if (edge !== undefined) return { kind: 'migration', edge, lane: arrow.line.lane };
+  }
+  return { kind: 'none' };
+}
+
+/**
+ * Return the cell's arrow line if it carries one — a self-loop, or a line whose
+ * directions are exactly `{up}` or `{down}` (the migration-direction arrows).
+ * Connector/corner/vertical lines are not arrows and yield `undefined`.
+ */
+function arrowLine(cell: Cell): CellLine | undefined {
+  for (const line of cell.lines) {
+    if (line.selfLoop === true) return line;
+    if (line.landingArrow === true) continue;
+    const dirs = line.directions;
+    if (dirs.size !== 1) continue;
+    if (dirs.has('up') || dirs.has('down')) return line;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Node path-highlight resolution (focus mode).
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve each contract's path-highlight role from the edges incident on it.
+ * On-path wins: a contract touched by any on-path edge is on-path. Empty unless
+ * focus-mode annotations are present.
+ */
+function resolveNodeHighlights(
+  rowModel: MigrationGraphRowModel,
+  edgeAnnotationsByHash: ReadonlyMap<string, MigrationEdgeAnnotation> | undefined,
+): Map<string, 'on-path' | 'off-path'> {
+  const result = new Map<string, 'on-path' | 'off-path'>();
+  if (edgeAnnotationsByHash === undefined) return result;
+  for (const edge of rowModel.edges) {
+    const highlight = edgeAnnotationsByHash.get(edge.migrationHash)?.pathHighlight;
+    if (highlight === undefined) continue;
+    for (const hash of [edge.from, edge.to]) {
+      if (hash === EMPTY_CONTRACT_HASH) continue;
+      if (result.get(hash) !== 'on-path') result.set(hash, highlight);
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Width helpers
+// ---------------------------------------------------------------------------
+
+function maxDirNameLength(edges: readonly ClassifiedEdge[]): number {
+  let max = 0;
+  for (const edge of edges) max = Math.max(max, edge.dirName.length);
+  return max;
+}
+
+/**
+ * The label column for a render: the widest gutter (visible width) across every
+ * row, plus the label gap. Labels begin here so they line up regardless of how
+ * deep the lane structure runs on any one row. A cross-space override widens it
+ * so sibling space sections share one column.
+ */
+export function computeLabelColumn(grid: Grid, glyphMode: GlyphMode): number {
+  let maxGutter = 0;
+  for (const row of grid) {
+    const gutter = renderGridRow(row, { colorize: false, glyphMode });
+    maxGutter = Math.max(maxGutter, stringWidth(gutter));
+  }
+  return maxGutter + LABEL_GAP;
+}
+
+export function computeMaxDirNameWidth(rowModel: MigrationGraphRowModel): number {
+  return maxDirNameLength(rowModel.edges);
+}
+
+function padVisible(text: string, targetWidth: number): string {
+  const padding = Math.max(0, targetWidth - stringWidth(text));
+  return text + ' '.repeat(padding);
+}
+
+const ANSI_ESCAPE = '\x1b';
+
+function trimTrailingWhitespace(line: string): string {
+  const trailingSpaceBeforeReset = new RegExp(`[\\t ]+((?:${ANSI_ESCAPE}\\[[0-9;]*m)+)$`);
+  return line.replace(trailingSpaceBeforeReset, '$1').replace(/\s+$/, '');
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+export function renderMigrationGraphCommand(input: RenderMigrationGraphCommandInput): string {
+  const { grid, rowModel } = input;
+  const glyphMode = input.glyphMode;
+
+  // Edges grouped by hash — a list, not a single entry, because two distinct
+  // migrations with identical content collide on one hash. classifyRow then
+  // disambiguates by the row's own dirName.
+  const edgesByHash = new Map<string, ClassifiedEdge[]>();
+  for (const edge of rowModel.edges) {
+    const bucket = edgesByHash.get(edge.migrationHash);
+    if (bucket) bucket.push(edge);
+    else edgesByHash.set(edge.migrationHash, [edge]);
+  }
+
+  const labelOpts: MigrationGraphLabelOptions = {
+    colorize: input.colorize,
+    glyphMode,
+    ...ifDefined('refsByHash', input.refsByHash),
+    ...ifDefined('edgeAnnotationsByHash', input.edgeAnnotationsByHash),
+    ...ifDefined('dbHash', input.dbHash),
+    ...ifDefined('contractHash', input.contractHash),
+    ...ifDefined('isAppSpace', input.isAppSpace),
+    ...ifDefined('activeRefName', input.activeRefName),
+    ...ifDefined('styler', input.styler),
+  };
+
+  const nodeHighlights = resolveNodeHighlights(rowModel, input.edgeAnnotationsByHash);
+
+  const labelColumn = input.globalLabelColumn ?? computeLabelColumn(grid, glyphMode);
+  const maxDirNameLen = input.globalMaxDirNameWidth ?? maxDirNameLength(rowModel.edges);
+  // The migration-name column is at least wide enough to push the `from → to`
+  // hash column to MIN_HASH_DATA_COLUMN, matching the historical layout.
+  const dirNameWidth = Math.max(maxDirNameLen + LABEL_GAP, MIN_HASH_DATA_COLUMN - labelColumn);
+
+  const lines: string[] = [];
+  for (const row of grid) {
+    const gutter = renderGridRow(row, { colorize: input.colorize, glyphMode });
+    const identity = classifyRow(row, edgesByHash);
+
+    if (identity.kind === 'none') {
+      // Connector / pass-through / back-arc rows carry no label. A wholly empty
+      // grid row (the blank line between disjoint components) renders as a blank.
+      lines.push(trimTrailingWhitespace(gutter));
+      continue;
+    }
+
+    const gutterPad = padVisible(gutter, labelColumn);
+    if (identity.kind === 'node') {
+      const label = formatNodeLabel(
+        identity.contractHash,
+        labelOpts,
+        nodeHighlights.get(identity.contractHash),
+      );
+      lines.push(trimTrailingWhitespace(label.length === 0 ? gutter : `${gutterPad}${label}`));
+      continue;
+    }
+
+    const label = formatMigrationLabel(identity.edge, dirNameWidth, labelOpts, identity.lane);
+    lines.push(trimTrailingWhitespace(`${gutterPad}${label}`));
+  }
+
+  return lines.join('\n');
+}