@prisma-next/cli 0.12.0-dev.6 → 0.12.0-dev.7

package/dist/cli.mjs

@@ -9,7 +9,7 @@ import { createDbUpdateCommand } from "./commands/db-update.mjs";
 import { t as createDbVerifyCommand } from "./db-verify-v_vUKXTU.mjs";
 import { createMigrateCommand } from "./commands/migrate.mjs";
 import { t as createMigrationCheckCommand } from "./migration-check-BiBJoYYW.mjs";
-import { t as createMigrationGraphCommand } from "./migration-graph-D7DVUElV.mjs";
+import { t as createMigrationGraphCommand } from "./migration-graph-BzxEsMZg.mjs";
 import { createMigrationListCommand } from "./commands/migration-list.mjs";
 import { createMigrationLogCommand } from "./commands/migration-log.mjs";
 import { createMigrationNewCommand } from "./commands/migration-new.mjs";
@@ -24,7 +24,7 @@ import { fileURLToPath } from "node:url";
 import { readUserConfig, resolveGating, runTelemetry } from "@prisma-next/cli-telemetry";
 import { distance } from "closest-match";
 //#region package.json
-var version = "0.12.0-dev.6";
+var version = "0.12.0-dev.7";
 //#endregion
 //#region src/utils/telemetry.ts
 /**

package/dist/commands/migration-graph.d.mts

@@ -12,7 +12,25 @@ interface MigrationGraphOptions extends CommonCommandOptions {
   readonly dot?: boolean;
   readonly tree?: boolean;
   readonly ascii?: boolean;
+  readonly legend?: boolean;
 }
+/**
+ * `--legend` describes the `--tree` visual language, so passing it auto-enables
+ * the tree path (it has nothing to say about the legacy dagre default).
+ */
+declare function migrationGraphUsesTree(options: {
+  readonly tree?: boolean;
+  readonly legend?: boolean;
+}): boolean;
+/**
+ * The legend is decoration printed alongside the command header on stderr, so
+ * it is suppressed for the machine-readable / silent paths (`--json`, `--dot`,
+ * `--quiet`) exactly as the header is.
+ */
+declare function migrationGraphShowsLegend(options: {
+  readonly legend?: boolean;
+  readonly dot?: boolean;
+}, flags: GlobalFlags): boolean;
 interface MigrationGraphResult {
   readonly ok: true;
   readonly graph: MigrationGraph;
@@ -23,5 +41,5 @@ interface MigrationGraphResult {
 declare function executeMigrationGraphCommand(options: MigrationGraphOptions, flags: GlobalFlags, ui: TerminalUI): Promise<Result<MigrationGraphResult, CliStructuredError>>;
 declare function createMigrationGraphCommand(): Command;
 //#endregion
-export { MigrationGraphResult, createMigrationGraphCommand, executeMigrationGraphCommand };
+export { MigrationGraphResult, createMigrationGraphCommand, executeMigrationGraphCommand, migrationGraphShowsLegend, migrationGraphUsesTree };
 //# sourceMappingURL=migration-graph.d.mts.map

package/dist/commands/migration-graph.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-graph.d.mts","names":[],"sources":["../../src/commands/migration-graph.ts"],"mappings":";;;;;;;;;UA0BU,qBAAA,SAA8B,oBAAoB;EAAA,SACjD,MAAA;EAAA,SACA,GAAA;EAAA,SACA,IAAA;EAAA,SACA,KAAA;AAAA;AAAA,UAGM,oBAAA;EAAA,SACN,EAAA;EAAA,SACA,KAAA,EAAO,cAAA;EAAA,SACP,YAAA;EAAA,SACA,IAAA,WAAe,SAAS;EAAA,SACxB,OAAA;AAAA;AAAA,iBAGW,4BAAA,CACpB,OAAA,EAAS,qBAAA,EACT,KAAA,EAAO,WAAA,EACP,EAAA,EAAI,UAAA,GACH,OAAA,CAAQ,MAAA,CAAO,oBAAA,EAAsB,kBAAA;AAAA,iBA0CxB,2BAAA,CAAA,GAA+B,OAAO"}
+{"version":3,"file":"migration-graph.d.mts","names":[],"sources":["../../src/commands/migration-graph.ts"],"mappings":";;;;;;;;;UA6BU,qBAAA,SAA8B,oBAAoB;EAAA,SACjD,MAAA;EAAA,SACA,GAAA;EAAA,SACA,IAAA;EAAA,SACA,KAAA;EAAA,SACA,MAAA;AAAA;;;;;iBAOK,sBAAA,CAAuB,OAAA;EAAA,SAC5B,IAAA;EAAA,SACA,MAAA;AAAA;;;;;;iBAUK,yBAAA,CACd,OAAA;EAAA,SAAoB,MAAA;EAAA,SAA2B,GAAA;AAAA,GAC/C,KAAA,EAAO,WAAW;AAAA,UAOH,oBAAA;EAAA,SACN,EAAA;EAAA,SACA,KAAA,EAAO,cAAA;EAAA,SACP,YAAA;EAAA,SACA,IAAA,WAAe,SAAS;EAAA,SACxB,OAAA;AAAA;AAAA,iBAGW,4BAAA,CACpB,OAAA,EAAS,qBAAA,EACT,KAAA,EAAO,WAAA,EACP,EAAA,EAAI,UAAA,GACH,OAAA,CAAQ,MAAA,CAAO,oBAAA,EAAsB,kBAAA;AAAA,iBAoDxB,2BAAA,CAAA,GAA+B,OAAO"}

package/dist/commands/migration-graph.mjs

@@ -1,2 +1,2 @@
-import { n as executeMigrationGraphCommand, t as createMigrationGraphCommand } from "../migration-graph-D7DVUElV.mjs";
-export { createMigrationGraphCommand, executeMigrationGraphCommand };
+import { i as migrationGraphUsesTree, n as executeMigrationGraphCommand, r as migrationGraphShowsLegend, t as createMigrationGraphCommand } from "../migration-graph-BzxEsMZg.mjs";
+export { createMigrationGraphCommand, executeMigrationGraphCommand, migrationGraphShowsLegend, migrationGraphUsesTree };

package/dist/{migration-graph-D7DVUElV.mjs → migration-graph-BzxEsMZg.mjs}

@@ -5,7 +5,7 @@ import { i as migrationGraphToRenderInput, n as graphRenderer } from "./graph-re
 import { a as migrationListEmptySource, n as createAnsiMigrationListStyler, o as migrationListForwardArrow, s as classifyMigrationGraphTopology, t as CONTRACT_MARKER_NAME } from "./migration-list-styler-BRwF4-gy.mjs";
 import { Command } from "commander";
 import { ok } from "@prisma-next/utils/result";
-import { bold } from "colorette";
+import { bold, createColors } from "colorette";
 import stringWidth from "string-width";
 import { EMPTY_CONTRACT_HASH } from "@prisma-next/migration-tools/constants";
 //#region src/utils/formatters/migration-graph-layout.ts
@@ -835,6 +835,30 @@ function buildMigrationGraphRows(graph, options = {}) {
 	};
 }
 //#endregion
+//#region src/utils/formatters/migration-graph-lane-colors.ts
+const { magenta: magenta$1, cyan: cyan$1, green: green$1, yellow: yellow$1, blueBright, red: red$1 } = createColors({ useColor: true });
+const LANE_COLOR_CYCLE = [
+	magenta$1,
+	cyan$1,
+	green$1,
+	yellow$1,
+	blueBright,
+	red$1
+];
+/**
+* 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
+* the renderer dims it rather than tinting it; the rotating palette is reserved
+* for columns ≥ 1 (where a second lane exists to distinguish). Callers must dim
+* column 0 themselves; this returns identity for it as a guard. A lane freed and
+* reused by a later branch keeps its column's hue — coloring is by position, not
+* branch identity, exactly like `git log --graph`.
+*/
+function laneColorForColumn(column) {
+	if (column <= 0) return (text) => text;
+	return LANE_COLOR_CYCLE[(column - 1) % LANE_COLOR_CYCLE.length] ?? ((text) => text);
+}
+//#endregion
 //#region src/utils/formatters/migration-graph-tree-render.ts
 const LABEL_GAP = 2;
 /**
@@ -902,74 +926,226 @@ function arrowForEdgeKind(kind, palette) {
 	return palette.edgeArrow[kind];
 }
 /**
+* The leftmost lane (column 0) renders with the neutral dim lane style rather
+* than a palette hue — in the common single-lane case it has nothing to be told
+* apart from. Used as the "no owning arc" sentinel during colour resolution.
+*/
+const NEUTRAL_LANE = 0;
+/**
+* Forced bold for branch-coloured names. A branched name pairs its lane hue
+* (also forced, via {@link laneColorForColumn}) with bold; both must emit even
+* when colorette's ambient TTY detection is off, so the colorized branch name
+* is deterministically bold + hue rather than hue-only.
+*/
+const { bold: forcedBold } = createColors({ useColor: true });
+/**
+* Resolve per-cell colour columns for a row. Scanning right-to-left lets each
+* arc bridge inherit the corner column that closes it (the arc's back-lane), so
+* the whole arc — vertical run (already its own column), horizontal bridges,
+* corners, crossings, and the `◂`/`─` connector — reads as a single continuous
+* hue. A crossing can only be one colour, so rather than leave it dim (wrong for
+* both crossing lines) it takes the arc owning the horizontal run at this row
+* (the nearest corner to its right); the crossed vertical lane is simply
+* occluded at that one cell and reappears on the next row.
+*/
+function resolveRowLaneColors(cells) {
+	const lane = new Array(cells.length);
+	const connector = new Array(cells.length);
+	let arcCorner = NEUTRAL_LANE;
+	for (let column = cells.length - 1; column >= 0; column--) {
+		const cell = cells[column];
+		connector[column] = arcCorner;
+		switch (cell?.kind) {
+			case "arc-branch-corner":
+			case "arc-land-corner":
+				arcCorner = column;
+				lane[column] = column;
+				break;
+			case "arc-branch-tee":
+				lane[column] = column;
+				break;
+			case "arc-crossing":
+			case "arc-land-bridge":
+				lane[column] = arcCorner;
+				break;
+			case "horizontal-pass":
+				lane[column] = arcCorner === NEUTRAL_LANE ? column : arcCorner;
+				break;
+			case "node":
+				lane[column] = column;
+				arcCorner = NEUTRAL_LANE;
+				break;
+			default:
+				lane[column] = column;
+				arcCorner = NEUTRAL_LANE;
+		}
+	}
+	return {
+		lane,
+		connector
+	};
+}
+/**
+* Resolve per-cell connector colours. Scanning right-to-left, a corner or an
+* intermediate tee anchors its own lane (its junction glyph takes that column),
+* but a tee's **trailing dash leads into the branch on its right** (the next
+* branch point), so `┬─` reads as "this lane, then on toward the next" rather
+* than tinting the dash with the left lane. The leading tee at `startLane` (the
+* fork/merge origin) and pure horizontal segments inherit the nearest branch
+* point to their right whole-cell, so the run into a branch — or collapsing
+* into a merge corner — stays continuous. Pass-through verticals outside the
+* run keep their own column (column 0 stays neutral).
+*/
+function resolveConnectorLaneColors(cells, startLane) {
+	const glyph = new Array(cells.length);
+	const dash = new Array(cells.length);
+	let owner = NEUTRAL_LANE;
+	for (let column = cells.length - 1; column >= 0; column--) switch (cells[column]?.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 : owner;
+				glyph[column] = served;
+				dash[column] = served;
+			} else {
+				dash[column] = owner === NEUTRAL_LANE ? column : owner;
+				glyph[column] = column;
+				owner = column;
+			}
+			break;
+		case "horizontal-pass": {
+			const served = owner === NEUTRAL_LANE ? column : owner;
+			glyph[column] = served;
+			dash[column] = served;
+			break;
+		}
+		default:
+			glyph[column] = column;
+			dash[column] = column;
+	}
+	return {
+		glyph,
+		dash
+	};
+}
+/**
+* Style a structural glyph by its resolved colour column. Column 0 and the
+* neutral sentinel render dim (`style.lane`); columns ≥ 1 take a palette hue.
+*/
+function laneStylerForColumn(colorColumn, colorize, style) {
+	if (!colorize || colorColumn <= NEUTRAL_LANE) return (text) => style.lane(text);
+	return laneColorForColumn(colorColumn);
+}
+/**
+* Tint a branch-owned token (direction arrow, migration name) by its edge's
+* lane so the whole branch row reads in one colour. Column 0 has nothing to be
+* told apart from in the common linear chain, so it keeps the token's existing
+* default styling (`fallback`) rather than a palette hue; only lanes ≥ 1 take a
+* colour. With colour off, the fallback (also colourless) is used unchanged.
+*/
+function branchStylerOrDefault(column, colorize, fallback) {
+	if (!colorize || column <= NEUTRAL_LANE) return fallback;
+	return laneColorForColumn(column);
+}
+/**
+* Render a connector tee (`├─` / `┬─` / `┴─`) with its junction glyph and its
+* trailing dash coloured independently: the junction anchors its own lane while
+* the dash leads into the branch on its right.
+*/
+function renderConnectorTee(pair, glyphColumn, dashColumn, colorize, style) {
+	const glyph = laneStylerForColumn(glyphColumn, colorize, style);
+	if (glyphColumn === dashColumn) return glyph(pair);
+	return glyph(pair.slice(0, 1)) + laneStylerForColumn(dashColumn, colorize, style)(pair.slice(1));
+}
+/**
 * A node-marker glyph pair (`○◂`, `○─`, `*<`, `*-`) is the contract node
-* marker (`○` / `*`) followed by an arc connector (`◂` / `─` / `<` / `-`).
-* The marker is the signal and stays bright (`style.kind`); the connector is
-* gutter and stays dim (`style.lane`) — consistent with the plain node marker,
-* which is never dimmed.
+* marker (`○` / `*`) followed by an arc connector (`◂` / `─` / `<` / `-`). The
+* marker takes its own lane's hue (so each node visibly belongs to its branch);
+* the connector follows the arc it belongs to (its owning back-lane hue).
+* Direction arrows are handled elsewhere — they take their edge's lane hue too.
 */
-function renderNodeMarkerPair(pair, style) {
-	return style.kind(pair.slice(0, 1)) + style.lane(pair.slice(1));
+function renderNodeMarkerPair(pair, nodeColumn, arcColumn, colorize, style) {
+	const marker = laneStylerForColumn(nodeColumn, colorize, style);
+	const connector = laneStylerForColumn(arcColumn, colorize, style);
+	return marker(pair.slice(0, 1)) + connector(pair.slice(1));
 }
-function renderCellPair(cell, style, palette) {
+function renderCellPair(cell, column, colors, colorize, style, palette) {
+	const lane = laneStylerForColumn(colors.lane[column] ?? column, colorize, style);
 	switch (cell.kind) {
-		case "node":
-			if (cell.arcLand === true) return renderNodeMarkerPair(palette.arcLand, style);
-			if (cell.arcTee === true) return renderNodeMarkerPair(palette.arcTee, style);
-			return style.kind(palette.node);
-		case "vertical-pass": return style.lane(palette.verticalPass);
-		case "edge-lane": return cell.ownsLabel ? style.lane(palette.verticalPass.trimEnd()) + style.kind(arrowForEdgeKind(cell.edgeKind, palette)) : style.lane(palette.verticalPass);
-		case "branch-tee": return style.lane(palette.branchTee);
-		case "merge-tee": return style.lane(palette.mergeTee);
-		case "branch-corner": return style.lane(palette.branchCorner);
-		case "merge-corner": return style.lane(palette.mergeCorner);
-		case "arc-branch-corner": return style.lane(palette.arcBranchCorner);
-		case "arc-branch-tee": return style.lane(palette.arcBranchTee);
-		case "arc-land-corner": return style.lane(palette.arcLandCorner);
-		case "arc-crossing": return style.lane(palette.arcCrossing);
-		case "arc-land-bridge": return style.lane(palette.arcLandBridge);
-		case "horizontal-pass": return style.lane(palette.horizontalPass);
+		case "node": {
+			const arcColumn = colors.connector[column] ?? NEUTRAL_LANE;
+			if (cell.arcLand === true) return renderNodeMarkerPair(palette.arcLand, column, arcColumn, colorize, style);
+			if (cell.arcTee === true) return renderNodeMarkerPair(palette.arcTee, column, arcColumn, colorize, style);
+			return lane(palette.node);
+		}
+		case "vertical-pass": return lane(palette.verticalPass);
+		case "edge-lane": return cell.ownsLabel ? lane(palette.verticalPass.trimEnd()) + branchStylerOrDefault(column, colorize, style.kind)(arrowForEdgeKind(cell.edgeKind, palette)) : lane(palette.verticalPass);
+		case "branch-tee": return lane(palette.branchTee);
+		case "merge-tee": return lane(palette.mergeTee);
+		case "branch-corner": return lane(palette.branchCorner);
+		case "merge-corner": return lane(palette.mergeCorner);
+		case "arc-branch-corner": return lane(palette.arcBranchCorner);
+		case "arc-branch-tee": return lane(palette.arcBranchTee);
+		case "arc-land-corner": return lane(palette.arcLandCorner);
+		case "arc-crossing": return lane(palette.arcCrossing);
+		case "arc-land-bridge": return lane(palette.arcLandBridge);
+		case "horizontal-pass": return lane(palette.horizontalPass);
 		case "empty": return "  ";
 	}
 }
-function renderConnectorRow(row, gridWidth, style, palette) {
+function renderConnectorRow(row, gridWidth, colorize, style, palette) {
 	const isMerge = row.kind === "merge-connector";
 	if (row.cells.length > 0) {
+		const colors = resolveConnectorLaneColors(row.cells, row.startLane ?? 0);
 		let seenTee = false;
 		let out = "";
-		for (const cell of row.cells) switch (cell.kind) {
-			case "branch-tee":
-				out += style.lane(seenTee ? palette.connectorBranchTeeCo : palette.connectorBranchTee);
-				seenTee = true;
-				break;
-			case "merge-tee":
-				out += style.lane(seenTee ? palette.connectorMergeTeeCo : palette.connectorBranchTee);
-				seenTee = true;
-				break;
-			case "branch-corner":
-				out += style.lane(palette.branchCorner);
-				break;
-			case "merge-corner":
-				out += style.lane(palette.mergeCorner);
-				break;
-			case "vertical-pass":
-				out += style.lane(palette.verticalPass);
-				break;
-			case "horizontal-pass":
-				out += style.lane(palette.horizontalPass);
-				break;
-			default: out += "  ";
+		for (let column = 0; column < row.cells.length; column++) {
+			const cell = row.cells[column];
+			if (cell === void 0) continue;
+			const glyphColumn = colors.glyph[column] ?? column;
+			const dashColumn = colors.dash[column] ?? glyphColumn;
+			const lane = laneStylerForColumn(glyphColumn, colorize, style);
+			switch (cell.kind) {
+				case "branch-tee":
+					out += renderConnectorTee(seenTee ? palette.connectorBranchTeeCo : palette.connectorBranchTee, glyphColumn, dashColumn, colorize, style);
+					seenTee = true;
+					break;
+				case "merge-tee":
+					out += renderConnectorTee(seenTee ? palette.connectorMergeTeeCo : palette.connectorBranchTee, glyphColumn, dashColumn, colorize, style);
+					seenTee = true;
+					break;
+				case "branch-corner":
+					out += lane(palette.branchCorner);
+					break;
+				case "merge-corner":
+					out += lane(palette.mergeCorner);
+					break;
+				case "vertical-pass":
+					out += lane(palette.verticalPass);
+					break;
+				case "horizontal-pass":
+					out += lane(palette.horizontalPass);
+					break;
+				default: out += "  ";
+			}
 		}
 		for (let column = row.cells.length; column < gridWidth; column++) out += "  ";
 		return out;
 	}
 	const start = row.startLane ?? 0;
 	const end = row.endLane ?? start;
+	const runLane = laneStylerForColumn(end, colorize, style);
 	let out = "";
 	for (let column = 0; column < gridWidth; column++) if (column < start || column > end) out += "  ";
-	else if (column === start) out += style.lane(palette.connectorBranchTee);
-	else if (column === end) out += style.lane(isMerge ? palette.mergeCorner : palette.branchCorner);
-	else out += style.lane(isMerge ? palette.connectorMergeTeeCo : palette.connectorBranchTeeCo);
+	else if (column === start) out += runLane(palette.connectorBranchTee);
+	else if (column === end) out += runLane(isMerge ? palette.mergeCorner : palette.branchCorner);
+	else out += runLane(isMerge ? palette.connectorMergeTeeCo : palette.connectorBranchTeeCo);
 	return out;
 }
 function abbreviateHash(hash, hashLength, emptySource) {
@@ -1008,6 +1184,11 @@ function padVisible(text, targetWidth) {
 	const padding = Math.max(0, targetWidth - stringWidth(text));
 	return text + " ".repeat(padding);
 }
+const ANSI_ESCAPE = "\x1B";
+function trimTrailingWhitespace(line) {
+	const trailingSpaceBeforeReset = new RegExp(`[\\t ]+((?:${ANSI_ESCAPE}\\[[0-9;]*m)+)$`);
+	return line.replace(trailingSpaceBeforeReset, "$1").replace(/\s+$/, "");
+}
 function gridWidthForModel(rows) {
 	return rows.reduce((max, row) => row.kind === "node" || row.kind === "edge" ? Math.max(max, row.cells.length) : max, 1);
 }
@@ -1047,10 +1228,11 @@ function renderMigrationGraphTree(model, opts) {
 			continue;
 		}
 		if (row.kind === "branch-connector" || row.kind === "merge-connector") {
-			lines.push(renderConnectorRow(row, gridWidth, style, palette).replace(/\s+$/, ""));
+			lines.push(trimTrailingWhitespace(renderConnectorRow(row, gridWidth, opts.colorize, style, palette)));
 			continue;
 		}
-		let gutter = row.cells.map((cell) => renderCellPair(cell, style, palette)).join("");
+		const cellColors = resolveRowLaneColors(row.cells);
+		let gutter = row.cells.map((cell, column) => renderCellPair(cell, column, cellColors, opts.colorize, style, palette)).join("");
 		const prevRow = model.rows[rowIndex - 1];
 		let laneSpan = row.cells.length;
 		if (row.kind === "node") {
@@ -1059,8 +1241,8 @@ function renderMigrationGraphTree(model, opts) {
 			else laneSpan = row.cells.length;
 		}
 		const labelColumn = row.kind === "edge" ? edgeLabelColumn(row, wideLabelColumn) : wideLabelColumn !== void 0 && (nodeHasArcDecoration(row) || row.contractHash !== void 0) ? wideLabelColumn : laneSpan * 2 + LABEL_GAP;
-		if (row.kind === "edge" && row.edge?.from === EMPTY_CONTRACT_HASH && (row.laneIndex ?? 0) === 0) gutter = row.cells.slice(0, 1).map((cell) => renderCellPair(cell, style, palette)).join("");
-		else if (row.kind === "node" && laneSpan < row.cells.length && !nodeHasArcDecoration(row)) gutter = row.cells.slice(0, laneSpan).map((cell) => renderCellPair(cell, style, palette)).join("");
+		if (row.kind === "edge" && row.edge?.from === EMPTY_CONTRACT_HASH && (row.laneIndex ?? 0) === 0) gutter = row.cells.slice(0, 1).map((cell, column) => renderCellPair(cell, column, cellColors, opts.colorize, style, palette)).join("");
+		else if (row.kind === "node" && laneSpan < row.cells.length && !nodeHasArcDecoration(row)) gutter = row.cells.slice(0, laneSpan).map((cell, column) => renderCellPair(cell, column, cellColors, opts.colorize, style, palette)).join("");
 		else if (gutter.length < laneSpan * 2) gutter = gutter.padEnd(laneSpan * 2, " ");
 		const dirNameWidth = rowDirNameWidth(labelColumn, maxDirNameLen, dirNameGap);
 		const dataColumn = labelColumn + dirNameWidth;
@@ -1068,35 +1250,76 @@ function renderMigrationGraphTree(model, opts) {
 		if (row.kind === "node") {
 			const contractHash = row.contractHash ?? EMPTY_CONTRACT_HASH;
 			if (contractHash === EMPTY_CONTRACT_HASH) {
-				const trailingLanes = row.cells.slice(1).map((cell) => renderCellPair(cell, style, palette)).join("");
+				const trailingLanes = row.cells.slice(1).map((cell, offset) => renderCellPair(cell, offset + 1, cellColors, opts.colorize, style, palette)).join("");
 				const emptyGutter = palette.emptySource.padEnd(2, " ") + trailingLanes;
 				const overlayNames = overlayNamesForContract(contractHash, opts);
 				if (overlayNames.length === 0) {
-					lines.push(emptyGutter.replace(/\s+$/, ""));
+					lines.push(trimTrailingWhitespace(emptyGutter));
 					continue;
 				}
 				const overlay = style.refs(overlayNames);
-				lines.push(`${padVisible(emptyGutter, dataColumn)}${overlay}`.replace(/\s+$/, ""));
+				lines.push(trimTrailingWhitespace(`${padVisible(emptyGutter, dataColumn)}${overlay}`));
 				continue;
 			}
 			const hashText = style.sourceHash(abbreviateHash(contractHash, hashLength, palette.emptySource));
 			const overlayNames = overlayNamesForContract(contractHash, opts);
 			const overlayPad = overlayNames.length > 0 ? " ".repeat(Math.max(0, dataColumn - labelColumn - stringWidth(hashText))) : "";
 			const overlay = overlayNames.length > 0 ? style.refs(overlayNames) : "";
-			lines.push(`${gutterPad}${hashText}${overlayPad}${overlay}`.replace(/\s+$/, ""));
+			lines.push(trimTrailingWhitespace(`${gutterPad}${hashText}${overlayPad}${overlay}`));
 			continue;
 		}
 		const edge = row.edge;
 		if (edge === void 0) continue;
 		const dirNamePadding = " ".repeat(Math.max(0, dirNameWidth - edge.dirName.length));
-		const dirName = `${style.dirName(edge.dirName)}${dirNamePadding}`;
+		const laneIndex = row.laneIndex ?? 0;
+		const dirName = `${(opts.colorize && laneIndex > NEUTRAL_LANE ? (text) => forcedBold(laneColorForColumn(laneIndex)(text)) : style.dirName)(edge.dirName)}${dirNamePadding}`;
 		const hashColumn = formatEdgeHashColumn(edge, style, hashLength, palette);
-		lines.push(`${gutterPad}${dirName}${hashColumn}`.replace(/\s+$/, ""));
+		lines.push(trimTrailingWhitespace(`${gutterPad}${dirName}${hashColumn}`));
 	}
 	return lines.join("\n");
 }
+/**
+* A compact key for the `--tree` visual language: the contract marker, the
+* in-lane direction arrows, the empty baseline, the `(refs)` overlay (including
+* the reserved `db` live-database and `contract` working-schema markers), and a
+* worked sample of the data-column `from → to` migration hash arrow.
+*
+* Honors the same glyph palette (unicode vs ASCII) and `colorize` gate as the
+* tree renderer, so the key matches whatever the graph itself drew and stays
+* pipe-safe (zero ANSI when color is off). The caller adds the trailing blank
+* line that separates this stderr key from the graph on stdout.
+*/
+function renderMigrationGraphLegend(opts) {
+	const palette = paletteFor(opts.glyphMode ?? "unicode");
+	const style = createAnsiMigrationListStyler({ useColor: opts.colorize });
+	const node = palette.node.trimEnd();
+	const sampleArrow = `${style.sourceHash("aaaaaa")} ${style.glyph(palette.forwardArrow)} ${style.destHash("bbbbbb")}`;
+	return [
+		"Legend:",
+		`  ${style.kind(node)} contract   ${style.kind(palette.edgeArrow.forward)} forward   ${style.kind(palette.edgeArrow.rollback)} rollback`,
+		`  ${style.kind(palette.edgeArrow.self)} migration without schema change`,
+		`  ${style.glyph(palette.emptySource)} empty database (baseline)`,
+		`  ${style.refs(["refs"])} ${DB_MARKER_NAME} / ${CONTRACT_MARKER_NAME} markers`,
+		`  ${sampleArrow}   migration from contract aaaaaa to bbbbbb`
+	].join("\n");
+}
 //#endregion
 //#region src/commands/migration-graph.ts
+/**
+* `--legend` describes the `--tree` visual language, so passing it auto-enables
+* the tree path (it has nothing to say about the legacy dagre default).
+*/
+function migrationGraphUsesTree(options) {
+	return options.tree === true || options.legend === true;
+}
+/**
+* The legend is decoration printed alongside the command header on stderr, so
+* it is suppressed for the machine-readable / silent paths (`--json`, `--dot`,
+* `--quiet`) exactly as the header is.
+*/
+function migrationGraphShowsLegend(options, flags) {
+	return options.legend === true && options.dot !== true && flags.json !== true && flags.quiet !== true;
+}
 async function executeMigrationGraphCommand(options, flags, ui) {
 	const config = await loadConfig(options.config);
 	const { configPath, appMigrationsRelative, migrationsDir } = resolveMigrationPaths(options.config, config);
@@ -1114,6 +1337,13 @@ async function executeMigrationGraphCommand(options, flags, ui) {
 			flags
 		});
 		ui.stderr(header);
+		if (migrationGraphShowsLegend(options, flags)) {
+			ui.stderr(renderMigrationGraphLegend({
+				colorize: flags.color !== false,
+				glyphMode: ui.resolveGlyphMode(options.ascii === true)
+			}));
+			ui.stderr("");
+		}
 	}
 	const loaded = await buildReadAggregate(config, { migrationsDir });
 	if (!loaded.ok) return loaded;
@@ -1139,7 +1369,8 @@ function createMigrationGraphCommand() {
 		"prisma-next migration graph --json",
 		"prisma-next migration graph --dot",
 		"prisma-next migration graph --tree",
-		"prisma-next migration graph --tree --ascii"
+		"prisma-next migration graph --tree --ascii",
+		"prisma-next migration graph --legend"
 	]);
 	setCommandSeeAlso(command, [
 		{
@@ -1159,7 +1390,7 @@ function createMigrationGraphCommand() {
 			oneLiner: "Display migration package contents"
 		}
 	]);
-	addGlobalOptions(command).option("--config <path>", "Path to prisma-next.config.ts").option("--dot", "Output in Graphviz DOT format").option("--tree", "Experimental condensed annotated tree renderer").option("--ascii", "Use ASCII glyphs for --tree (pipe-friendly)").action(async (options) => {
+	addGlobalOptions(command).option("--config <path>", "Path to prisma-next.config.ts").option("--dot", "Output in Graphviz DOT format").option("--tree", "Experimental condensed annotated tree renderer").option("--ascii", "Use ASCII glyphs for --tree (pipe-friendly)").option("--legend", "Print a key for the --tree glyphs and lane colors (implies --tree)").action(async (options) => {
 		const flags = parseGlobalFlagsOrExit(options);
 		const ui = createTerminalUI(flags);
 		const exitCode = handleResult(await executeMigrationGraphCommand(options, flags, ui), flags, ui, (graphResult) => {
@@ -1186,7 +1417,7 @@ function createMigrationGraphCommand() {
 					edges,
 					summary: graphResult.summary
 				}, null, 2));
-			} else if (!flags.quiet) if (options.tree) {
+			} else if (!flags.quiet) if (migrationGraphUsesTree(options)) {
 				const refsByHash = /* @__PURE__ */ new Map();
 				for (const ref of graphResult.refs) {
 					const existing = refsByHash.get(ref.hash);
@@ -1227,6 +1458,6 @@ function createMigrationGraphCommand() {
 	return command;
 }
 //#endregion
-export { executeMigrationGraphCommand as n, createMigrationGraphCommand as t };
+export { migrationGraphUsesTree as i, executeMigrationGraphCommand as n, migrationGraphShowsLegend as r, createMigrationGraphCommand as t };
 
-//# sourceMappingURL=migration-graph-D7DVUElV.mjs.map
+//# sourceMappingURL=migration-graph-BzxEsMZg.mjs.map