@prisma-next/migration-tools 0.11.0-dev.4 → 0.11.0-dev.40

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.11.0-dev.4",
+  "version": "0.11.0-dev.40",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "On-disk migration persistence, hash verification, and chain reconstruction for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.11.0-dev.4",
-    "@prisma-next/framework-components": "0.11.0-dev.4",
-    "@prisma-next/utils": "0.11.0-dev.4",
+    "@prisma-next/contract": "0.11.0-dev.40",
+    "@prisma-next/framework-components": "0.11.0-dev.40",
+    "@prisma-next/utils": "0.11.0-dev.40",
     "arktype": "^2.2.0",
     "pathe": "^2.0.3",
     "prettier": "^3.8.3"
   },
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.11.0-dev.4",
-    "@prisma-next/tsdown": "0.11.0-dev.4",
+    "@prisma-next/tsconfig": "0.11.0-dev.40",
+    "@prisma-next/tsdown": "0.11.0-dev.40",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.6"
@@ -60,6 +60,14 @@
       "types": "./dist/exports/migration-graph.d.mts",
       "import": "./dist/exports/migration-graph.mjs"
     },
+    "./migration-list-types": {
+      "types": "./dist/exports/migration-list-types.d.mts",
+      "import": "./dist/exports/migration-list-types.mjs"
+    },
+    "./enumerate-migration-spaces": {
+      "types": "./dist/exports/enumerate-migration-spaces.d.mts",
+      "import": "./dist/exports/enumerate-migration-spaces.mjs"
+    },
     "./refs": {
       "types": "./dist/exports/refs.d.mts",
       "import": "./dist/exports/refs.mjs"

package/src/emit-contract-space-artefacts.ts

@@ -2,7 +2,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { canonicalizeJson } from '@prisma-next/framework-components/utils';
 import { join } from 'pathe';
 import type { ContractSpaceHeadRef } from './read-contract-space-head-ref';
-import { assertValidSpaceId } from './space-layout';
+import { assertValidSpaceId, spaceRefsDirectory } from './space-layout';
 
 /**
  * Inputs for {@link emitContractSpaceArtefacts}.
@@ -56,7 +56,8 @@ export async function emitContractSpaceArtefacts(
   assertValidSpaceId(spaceId);
 
   const dir = join(projectMigrationsDir, spaceId);
-  await mkdir(join(dir, 'refs'), { recursive: true });
+  const refsDir = spaceRefsDirectory(dir);
+  await mkdir(refsDir, { recursive: true });
 
   await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(inputs.contract)}\n`);
   await writeFile(join(dir, 'contract.d.ts'), inputs.contractDts);
@@ -66,5 +67,5 @@ export async function emitContractSpaceArtefacts(
     hash: inputs.headRef.hash,
     invariants: sortedInvariants,
   });
-  await writeFile(join(dir, 'refs', 'head.json'), `${headJson}\n`);
+  await writeFile(join(refsDir, 'head.json'), `${headJson}\n`);
 }

package/src/enumerate-migration-spaces.ts

@@ -0,0 +1,127 @@
+import { readMigrationsDir } from './io';
+import type { MigrationListEntry, MigrationSpaceListEntry } from './migration-list-types';
+import { readRefs } from './refs';
+import {
+  APP_SPACE_ID,
+  isValidSpaceId,
+  RESERVED_SPACE_SUBDIR_NAMES,
+  spaceMigrationDirectory,
+  spaceRefsDirectory,
+} from './space-layout';
+import { listContractSpaceDirectories } from './verify-contract-spaces';
+
+/**
+ * Index `migrations/<space>/refs/*.json` by the contract hash each ref
+ * points at, so callers can attach `(ref names)` decorations to every
+ * row whose destination contract hash matches.
+ *
+ * Each bucket is sorted lex-asc to keep rendered output deterministic
+ * (adjacent rows pointing at the same hash render their ref decorations
+ * in the same order).
+ *
+ * Refs whose hash matches no migration on disk are still indexed; the
+ * caller decides whether to surface them. Migration rows only carry
+ * `(refs)` decorations when a matching destination contract hash exists
+ * on disk — orphan refs are not rendered on any row.
+ *
+ * Returns an empty map when the refs directory does not exist
+ * ({@link readRefs} treats `ENOENT` as "no refs").
+ */
+export async function resolveRefsByContractHash(
+  refsDir: string,
+): Promise<ReadonlyMap<string, readonly string[]>> {
+  const refs = await readRefs(refsDir);
+  const byHash = new Map<string, string[]>();
+  for (const [name, entry] of Object.entries(refs)) {
+    const bucket = byHash.get(entry.hash);
+    if (bucket) bucket.push(name);
+    else byHash.set(entry.hash, [name]);
+  }
+  for (const bucket of byHash.values()) {
+    bucket.sort();
+  }
+  return byHash;
+}
+
+/**
+ * Compare two contract-space IDs for the inter-space ordering rule:
+ * {@link APP_SPACE_ID} first if present, then lex-asc on the rest.
+ */
+function compareSpaceIds(a: string, b: string): number {
+  if (a === APP_SPACE_ID) return b === APP_SPACE_ID ? 0 : -1;
+  if (b === APP_SPACE_ID) return 1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * Sort `dirName` descending so the rendered output reads latest-first,
+ * matching the `git log` latest-first convention.
+ */
+function compareDirNamesDescending(a: MigrationListEntry, b: MigrationListEntry): number {
+  if (a.dirName < b.dirName) return 1;
+  if (a.dirName > b.dirName) return -1;
+  return 0;
+}
+
+/**
+ * Enumerate every contract space's on-disk migrations under
+ * `<projectMigrationsDir>/`. For each valid space directory:
+ *
+ * - Loads on-disk packages via {@link readMigrationsDir}.
+ * - Attaches ref decorations: each migration's `refs[]` lists every ref
+ *   name from `migrations/<spaceId>/refs/*.json` whose hash equals the
+ *   migration's destination contract hash.
+ * - Sorts migrations within the space by `dirName` descending
+ *   (reverse-filename, latest first).
+ *
+ * Contract spaces are returned with {@link APP_SPACE_ID} first when
+ * present, then the remaining ids lex-asc. A contract-space directory
+ * that contains no migrations becomes `{ spaceId, migrations: [] }` so
+ * the renderer's empty-state path can surface it.
+ *
+ * Directory entries that are not valid {@link isValidSpaceId} names are
+ * skipped (a stray non-space directory under `migrations/` does not
+ * spawn a phantom space entry). Entries whose name appears in
+ * {@link RESERVED_SPACE_SUBDIR_NAMES} are also skipped — the per-space
+ * `refs/` subdirectory name shape would otherwise satisfy
+ * {@link isValidSpaceId} and surface as a phantom contract space.
+ *
+ * Returns `[]` when `<projectMigrationsDir>` does not exist — a fresh
+ * project that has not authored any migration yet.
+ */
+export async function enumerateMigrationSpaces(args: {
+  readonly projectMigrationsDir: string;
+}): Promise<readonly MigrationSpaceListEntry[]> {
+  const { projectMigrationsDir } = args;
+  const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
+  const spaceIds = candidateDirs
+    .filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name))
+    .filter(isValidSpaceId)
+    .sort(compareSpaceIds);
+
+  const spaces: MigrationSpaceListEntry[] = [];
+  for (const spaceId of spaceIds) {
+    const spaceDir = spaceMigrationDirectory(projectMigrationsDir, spaceId);
+    const packages = await readMigrationsDir(spaceDir);
+    const refsByHash = await resolveRefsByContractHash(spaceRefsDirectory(spaceDir));
+
+    const migrations: MigrationListEntry[] = packages
+      .map((pkg) => ({
+        dirName: pkg.dirName,
+        from: pkg.metadata.from,
+        to: pkg.metadata.to,
+        migrationHash: pkg.metadata.migrationHash,
+        operationCount: pkg.ops.length,
+        createdAt: pkg.metadata.createdAt,
+        refs: refsByHash.get(pkg.metadata.to) ?? [],
+        providedInvariants: pkg.metadata.providedInvariants,
+      }))
+      .sort(compareDirNamesDescending);
+
+    spaces.push({ spaceId, migrations });
+  }
+
+  return spaces;
+}

package/src/errors.ts

@@ -1,5 +1,6 @@
 import { ifDefined } from '@prisma-next/utils/defined';
 import { basename, dirname, relative } from 'pathe';
+import type { MigrationGraph } from './graph';
 
 /**
  * Build the canonical "re-emit this package" remediation hint.
@@ -319,8 +320,8 @@ export function errorProvidedInvariantsMismatch(
 /**
  * Wire-shape edge surfaced through the JSON envelope's
  * `meta.structuralPath` of `MIGRATION.NO_INVARIANT_PATH`. Slim by design —
- * authoring metadata (`createdAt`, `labels`) lives on `MigrationEdge` but
- * is intentionally dropped here so the envelope stays stable across
+ * authoring metadata (`createdAt`) lives on `MigrationEdge` but is
+ * intentionally dropped here so the envelope stays stable across
  * graph-internal refactors.
  *
  * Stability: any field added here is part of the public CLI JSON contract.
@@ -399,3 +400,17 @@ export function errorMigrationHashMismatch(
     details: { dir, storedHash, computedHash },
   });
 }
+
+export function errorHashNotInGraph(hash: string, graph: MigrationGraph): MigrationToolsError {
+  const reachableHashes = [...graph.nodes].sort();
+  const reachableList = reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none)';
+  return new MigrationToolsError(
+    'MIGRATION.HASH_NOT_IN_GRAPH',
+    `Hash "${hash}" is not a node in the migration graph`,
+    {
+      why: `The migration graph contains nodes ${reachableList}; "${hash}" isn't one of them.`,
+      fix: `Pass a hash that's the from-or-to of an on-disk migration bundle, use --from with a graph-node hash, or run "prisma-next migration plan" to introduce it.`,
+      details: { hash, reachableHashes },
+    },
+  );
+}

package/src/exports/enumerate-migration-spaces.ts

@@ -0,0 +1,4 @@
+export {
+  enumerateMigrationSpaces,
+  resolveRefsByContractHash,
+} from '../enumerate-migration-spaces';

package/src/exports/metadata.ts

@@ -1 +1 @@
-export type { MigrationHints, MigrationMetadata } from '../metadata';
+export type { MigrationMetadata } from '../metadata';

package/src/exports/migration-graph.ts

@@ -1,3 +1,4 @@
+export { assertHashIsGraphNode, isGraphNode } from '../graph-membership';
 export type { PathDecision } from '../migration-graph';
 export {
   detectCycles,

package/src/exports/migration-list-types.ts

@@ -0,0 +1,5 @@
+export type {
+  MigrationListEntry,
+  MigrationListResult,
+  MigrationSpaceListEntry,
+} from '../migration-list-types';

package/src/exports/refs.ts

@@ -8,3 +8,11 @@ export {
   validateRefValue,
   writeRef,
 } from '../refs';
+export type { ContractIR } from '../refs/snapshot';
+export {
+  deleteRefPaired,
+  deleteRefSnapshot,
+  readRefSnapshot,
+  writeRefPaired,
+  writeRefSnapshot,
+} from '../refs/snapshot';

package/src/exports/spaces.ts

@@ -31,7 +31,10 @@ export {
   APP_SPACE_ID,
   assertValidSpaceId,
   isValidSpaceId,
+  RESERVED_SPACE_SUBDIR_NAMES,
+  SPACE_REFS_DIRNAME,
   spaceMigrationDirectory,
+  spaceRefsDirectory,
   type ValidSpaceId,
 } from '../space-layout';
 export {

package/src/graph-membership.ts

@@ -0,0 +1,17 @@
+import { EMPTY_CONTRACT_HASH } from './constants';
+import { errorHashNotInGraph } from './errors';
+import type { MigrationGraph } from './graph';
+
+export function isGraphNode(hash: string, graph: MigrationGraph): boolean {
+  if (hash === EMPTY_CONTRACT_HASH) {
+    return true;
+  }
+  return graph.nodes.has(hash);
+}
+
+export function assertHashIsGraphNode(hash: string, graph: MigrationGraph): asserts hash is string {
+  if (isGraphNode(hash, graph)) {
+    return;
+  }
+  throw errorHashNotInGraph(hash, graph);
+}

package/src/graph.ts

@@ -8,7 +8,6 @@ export interface MigrationEdge {
   readonly migrationHash: string;
   readonly dirName: string;
   readonly createdAt: string;
-  readonly labels: readonly string[];
   /**
    * Sorted, deduplicated list of `invariantId`s this edge provides.
    * An empty array means the migration declares no routing-visible

package/src/hash.ts

@@ -15,13 +15,12 @@ function sha256Hex(input: string): string {
 }
 
 /**
- * Content-addressed migration hash over (metadata envelope sans hints,
- * ops). See ADR 199 — Storage-only migration identity for the
- * rationale: the storage-hash bookends (`from`, `to`) inside the
- * envelope anchor the contract identity by hash, and planner hints are
- * advisory and must not affect identity. The full contract IRs are not
- * part of the manifest — they live in sibling `*-contract.json` files
- * authored alongside the migration, never inlined here.
+ * Content-addressed migration hash over (metadata envelope, ops). See
+ * ADR 199 — Storage-only migration identity for the rationale: the
+ * storage-hash bookends (`from`, `to`) inside the envelope anchor the
+ * contract identity by hash. The full contract IRs are not part of the
+ * manifest — they live in sibling `*-contract.json` files authored
+ * alongside the migration, never inlined here.
  *
  * The integrity check is purely structural, not semantic. The function
  * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`
@@ -46,7 +45,7 @@ export function computeMigrationHash(
   metadata: Omit<MigrationMetadata, 'migrationHash'> & { readonly migrationHash?: string },
   ops: MigrationOps,
 ): string {
-  const { migrationHash: _migrationHash, hints: _hints, ...strippedMeta } = metadata;
+  const { migrationHash: _migrationHash, ...strippedMeta } = metadata;
 
   const canonicalMetadata = canonicalizeJson(strippedMeta);
   const canonicalOps = canonicalizeJson(ops);

package/src/io.ts

@@ -28,19 +28,11 @@ function hasErrnoCode(error: unknown, code: string): boolean {
   return error instanceof Error && (error as { code?: string }).code === code;
 }
 
-const MigrationHintsSchema = type({
-  used: 'string[]',
-  applied: 'string[]',
-  plannerVersion: 'string',
-});
-
 const MigrationMetadataSchema = type({
   '+': 'reject',
   from: 'string > 0 | null',
   to: 'string',
   migrationHash: 'string',
-  hints: MigrationHintsSchema,
-  labels: 'string[]',
   providedInvariants: 'string[]',
   createdAt: 'string',
 });

package/src/metadata.ts

@@ -1 +1 @@
-export type { MigrationHints, MigrationMetadata } from '@prisma-next/framework-components/control';
+export type { MigrationMetadata } from '@prisma-next/framework-components/control';

package/src/migration-base.ts

@@ -9,14 +9,13 @@ import { type } from 'arktype';
 import { errorInvalidOperationEntry } from './errors';
 import { computeMigrationHash } from './hash';
 import { deriveProvidedInvariants } from './invariants';
-import type { MigrationHints, MigrationMetadata } from './metadata';
+import type { MigrationMetadata } from './metadata';
 import { MigrationOpSchema } from './op-schema';
 import type { MigrationOps } from './package';
 
 export interface MigrationMeta {
   readonly from: string | null;
   readonly to: string;
-  readonly labels?: readonly string[];
 }
 
 // `from` rejects empty strings to mirror `MigrationMetadataSchema` in
@@ -27,7 +26,6 @@ export interface MigrationMeta {
 const MigrationMetaSchema = type({
   from: 'string > 0 | null',
   to: 'string',
-  'labels?': type('string').array(),
 });
 
 /**
@@ -127,12 +125,11 @@ export interface MigrationArtifacts {
  * operations list, and the previously-scaffolded metadata (if any).
  *
  * When a `migration.json` already exists for this package (the common
- * case: it was scaffolded by `migration plan`), preserve the contract
- * bookends, hints, labels, and `createdAt` set there — those fields are
- * owned by the CLI scaffolder, not the authored class. Only the
- * `describe()`-derived fields (`from`, `to`) and the operations
- * change as the author iterates. When no metadata exists yet (a bare
- * `migration.ts` run from scratch), synthesize a minimal but
+ * case: it was scaffolded by `migration plan`), preserve `createdAt`
+ * set there — that field is owned by the CLI scaffolder, not the authored
+ * class. Only the `describe()`-derived fields (`from`, `to`) and the
+ * operations change as the author iterates. When no metadata exists yet
+ * (a bare `migration.ts` run from scratch), synthesize a minimal but
  * schema-conformant record so the resulting package can still be read,
  * verified, and applied.
  *
@@ -147,39 +144,22 @@ function buildAttestedMetadata(
   const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: meta.from,
     to: meta.to,
-    labels: meta.labels ?? existing?.labels ?? [],
     providedInvariants: deriveProvidedInvariants(ops),
     createdAt: existing?.createdAt ?? new Date().toISOString(),
-    hints: normalizeHints(existing?.hints),
   };
 
   const migrationHash = computeMigrationHash(baseMetadata, ops);
   return { ...baseMetadata, migrationHash };
 }
 
-/**
- * Project `existing.hints` down to the known `MigrationHints` shape, dropping
- * any legacy keys that may linger in metadata scaffolded by older CLI
- * versions (e.g. `planningStrategy`). Picking fields explicitly instead of
- * spreading keeps refreshed `migration.json` files schema-clean regardless
- * of what was on disk before.
- */
-function normalizeHints(existing: MigrationHints | undefined): MigrationHints {
-  return {
-    used: existing?.used ?? [],
-    applied: existing?.applied ?? [],
-    plannerVersion: existing?.plannerVersion ?? '2.0.0',
-  };
-}
-
 /**
  * Pure conversion from a `Migration` instance (plus the previously
  * scaffolded metadata, when one exists on disk) to the in-memory
  * artifacts that downstream tooling persists. Owns metadata validation,
- * metadata synthesis/preservation, hint normalization, and the
- * content-addressed `migrationHash` computation, but performs no file I/O
- * — callers handle reads (to source `existing`) and writes (to persist
- * `opsJson` / `metadataJson`).
+ * metadata synthesis/preservation, and the content-addressed
+ * `migrationHash` computation, but performs no file I/O — callers handle
+ * reads (to source `existing`) and writes (to persist `opsJson` /
+ * `metadataJson`).
  */
 export function buildMigrationArtifacts(
   instance: Migration,

package/src/migration-graph.ts

@@ -66,7 +66,6 @@ export function reconstructGraph(packages: readonly OnDiskMigrationPackage[]): M
       migrationHash: pkg.metadata.migrationHash,
       dirName: pkg.dirName,
       createdAt: pkg.metadata.createdAt,
-      labels: pkg.metadata.labels,
       invariants: pkg.metadata.providedInvariants,
     };
 
@@ -85,23 +84,10 @@ export function reconstructGraph(packages: readonly OnDiskMigrationPackage[]): M
 // ---------------------------------------------------------------------------
 // Deterministic tie-breaking for BFS neighbour order.
 // Used by path-finders only; not a general-purpose utility.
-// Ordering: label priority → createdAt → to → migrationHash.
+// Ordering: createdAt → to → migrationHash.
 // ---------------------------------------------------------------------------
 
-const LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };
-
-function labelPriority(labels: readonly string[]): number {
-  let best = 3;
-  for (const l of labels) {
-    const p = LABEL_PRIORITY[l];
-    if (p !== undefined && p < best) best = p;
-  }
-  return best;
-}
-
 function compareTieBreak(a: MigrationEdge, b: MigrationEdge): number {
-  const lp = labelPriority(a.labels) - labelPriority(b.labels);
-  if (lp !== 0) return lp;
   const ca = a.createdAt.localeCompare(b.createdAt);
   if (ca !== 0) return ca;
   const tc = a.to.localeCompare(b.to);
@@ -119,7 +105,7 @@ function sortedNeighbors(edges: readonly MigrationEdge[]): readonly MigrationEdg
  * exists. Returns an empty array when `fromHash === toHash` (no-op).
  *
  * Neighbor ordering is deterministic via the tie-break sort key:
- * label priority → createdAt → to → migrationHash.
+ * createdAt → to → migrationHash.
  */
 export function findPath(
   graph: MigrationGraph,
@@ -165,8 +151,8 @@ export function findPath(
  * control chars at authoring time).
  *
  * Neighbour ordering when `required ≠ ∅`: edges covering ≥1 still-needed
- * invariant come first, with `labelPriority → createdAt → to → migrationHash`
- * as the secondary key. The heuristic steers BFS toward the satisfying path;
+ * invariant come first, with `createdAt → to → migrationHash` as the
+ * secondary key. The heuristic steers BFS toward the satisfying path;
  * correctness (shortest, deterministic) does not depend on it.
  */
 export function findPathWithInvariants(

package/src/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;
+}

package/src/read-contract-space-head-ref.ts

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import type { ContractSpaceHeadRef } from '@prisma-next/framework-components/control';
 import { join } from 'pathe';
 import { errorInvalidJson, errorInvalidRefFile } from './errors';
-import { assertValidSpaceId } from './space-layout';
+import { assertValidSpaceId, spaceMigrationDirectory, spaceRefsDirectory } from './space-layout';
 
 export type { ContractSpaceHeadRef };
 
@@ -29,7 +29,10 @@ export async function readContractSpaceHeadRef(
 ): Promise<ContractSpaceHeadRef | null> {
   assertValidSpaceId(spaceId);
 
-  const filePath = join(projectMigrationsDir, spaceId, 'refs', 'head.json');
+  const filePath = join(
+    spaceRefsDirectory(spaceMigrationDirectory(projectMigrationsDir, spaceId)),
+    'head.json',
+  );
 
   let raw: string;
   try {