@prisma-next/migration-tools 0.5.0-dev.62 → 0.5.0-dev.63

package/src/exports/spaces.ts

@@ -0,0 +1,36 @@
+export {
+  concatenateSpaceApplyInputs,
+  type SpaceApplyInput,
+} from '../concatenate-space-apply-inputs';
+export {
+  type DetectSpaceContractDriftInputs,
+  detectSpaceContractDrift,
+  type SpaceContractDriftResult,
+} from '../detect-space-contract-drift';
+export {
+  emitPinnedSpaceArtefacts,
+  type PinnedSpaceArtefactInputs,
+  type PinnedSpaceHeadRef,
+} from '../emit-pinned-space-artefacts';
+export {
+  planAllSpaces,
+  type SpacePlanInput,
+  type SpacePlanOutput,
+} from '../plan-all-spaces';
+export { readPinnedContractHash } from '../read-pinned-contract-hash';
+export {
+  APP_SPACE_ID,
+  assertValidSpaceId,
+  isValidSpaceId,
+  spaceMigrationDirectory,
+  type ValidSpaceId,
+} from '../space-layout';
+export {
+  listPinnedSpaceDirectories,
+  type SpaceMarkerRecord,
+  type SpacePinnedHashRecord,
+  type SpaceVerifierViolation,
+  type VerifyContractSpacesInputs,
+  type VerifyContractSpacesResult,
+  verifyContractSpaces,
+} from '../verify-contract-spaces';

package/src/hash.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { canonicalizeJson } from './canonicalize-json';
 import type { MigrationMetadata } from './metadata';
-import type { MigrationOps, MigrationPackage } from './package';
+import type { MigrationOps, OnDiskMigrationPackage } from './package';
 
 export interface VerifyResult {
   readonly ok: boolean;
@@ -71,7 +71,7 @@ export function computeMigrationHash(
  * not — typically a sign of FS corruption, partial writes, or a post-emit
  * hand edit.
  */
-export function verifyMigrationHash(pkg: MigrationPackage): VerifyResult {
+export function verifyMigrationHash(pkg: OnDiskMigrationPackage): VerifyResult {
   const computed = computeMigrationHash(pkg.metadata, pkg.ops);
 
   if (pkg.metadata.migrationHash === computed) {

package/src/io.ts

@@ -1,6 +1,11 @@
-import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import type {
+  MigrationMetadata,
+  MigrationPackage,
+} from '@prisma-next/framework-components/control';
 import { type } from 'arktype';
-import { basename, dirname, join } from 'pathe';
+import { basename, dirname, join, resolve } from 'pathe';
+import { canonicalizeJson } from './canonicalize-json';
 import {
   errorDirectoryExists,
   errorInvalidDestName,
@@ -13,11 +18,10 @@ import {
 } from './errors';
 import { verifyMigrationHash } from './hash';
 import { deriveProvidedInvariants } from './invariants';
-import type { MigrationMetadata } from './metadata';
 import { MigrationOpsSchema } from './op-schema';
-import type { MigrationOps, MigrationPackage } from './package';
+import type { MigrationOps, OnDiskMigrationPackage } from './package';
 
-const MANIFEST_FILE = 'migration.json';
+export const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
 const MAX_SLUG_LENGTH = 64;
 
@@ -74,6 +78,52 @@ export async function writeMigrationPackage(
   await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });
 }
 
+/**
+ * Materialise an in-memory {@link MigrationPackage} to a per-space
+ * directory on disk.
+ *
+ * Writes three files under `<targetDir>/<pkg.dirName>/`:
+ *
+ * - `migration.json` — the manifest (pretty-printed, matches
+ *   {@link writeMigrationPackage}'s output for byte-for-byte parity with
+ *   app-space migrations).
+ * - `ops.json` — the operation list (pretty-printed).
+ * - `contract.json` — the canonical-JSON serialisation of
+ *   `metadata.toContract`. This is the per-package post-state contract
+ *   snapshot; the canonicalisation pass guarantees byte-determinism so
+ *   re-emitting the same package across machines / runs produces an
+ *   identical file.
+ *
+ * Distinct verb from the lower-level {@link writeMigrationPackage}
+ * (which takes constituent `(metadata, ops)`): callers reading
+ * `materialise…` know they are persisting a struct-typed package
+ * including its contract-snapshot side car.
+ *
+ * Overwrite-idempotent: the per-package directory is cleared before
+ * each emit, so re-running against the same `targetDir` produces
+ * byte-identical contents and never leaves stale files behind. The
+ * spec's "re-emitting the same package across runs / machines produces
+ * byte-identical files" guarantee (§ 3) covers both same-dir and
+ * fresh-dir re-emits. The lower-level {@link writeMigrationPackage}
+ * stays strict because the CLI authoring path (`migration plan` /
+ * `migration new`) deliberately refuses to clobber an existing
+ * authored migration; this helper is the re-emit path that is
+ * supposed to converge on a single canonical on-disk shape.
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Emission helper (T1.7).
+ */
+export async function materialiseMigrationPackage(
+  targetDir: string,
+  pkg: MigrationPackage,
+): Promise<void> {
+  const dir = join(targetDir, pkg.dirName);
+  await rm(dir, { recursive: true, force: true });
+  await writeMigrationPackage(dir, pkg.metadata, pkg.ops);
+  await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(pkg.metadata.toContract)}\n`, {
+    flag: 'wx',
+  });
+}
+
 /**
  * Copy a list of files into `destDir`, optionally renaming each one.
  *
@@ -109,16 +159,17 @@ export async function writeMigrationOps(dir: string, ops: MigrationOps): Promise
   await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\n`);
 }
 
-export async function readMigrationPackage(dir: string): Promise<MigrationPackage> {
-  const manifestPath = join(dir, MANIFEST_FILE);
-  const opsPath = join(dir, OPS_FILE);
+export async function readMigrationPackage(dir: string): Promise<OnDiskMigrationPackage> {
+  const absoluteDir = resolve(dir);
+  const manifestPath = join(absoluteDir, MANIFEST_FILE);
+  const opsPath = join(absoluteDir, OPS_FILE);
 
   let manifestRaw: string;
   try {
     manifestRaw = await readFile(manifestPath, 'utf-8');
   } catch (error) {
     if (hasErrnoCode(error, 'ENOENT')) {
-      throw errorMissingFile(MANIFEST_FILE, dir);
+      throw errorMissingFile(MANIFEST_FILE, absoluteDir);
     }
     throw error;
   }
@@ -128,7 +179,7 @@ export async function readMigrationPackage(dir: string): Promise<MigrationPackag
     opsRaw = await readFile(opsPath, 'utf-8');
   } catch (error) {
     if (hasErrnoCode(error, 'ENOENT')) {
-      throw errorMissingFile(OPS_FILE, dir);
+      throw errorMissingFile(OPS_FILE, absoluteDir);
     }
     throw error;
   }
@@ -161,16 +212,20 @@ export async function readMigrationPackage(dir: string): Promise<MigrationPackag
     );
   }
 
-  const pkg: MigrationPackage = {
-    dirName: basename(dir),
-    dirPath: dir,
+  const pkg: OnDiskMigrationPackage = {
+    dirName: basename(absoluteDir),
+    dirPath: absoluteDir,
     metadata,
     ops,
   };
 
   const verification = verifyMigrationHash(pkg);
   if (!verification.ok) {
-    throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);
+    throw errorMigrationHashMismatch(
+      absoluteDir,
+      verification.storedHash,
+      verification.computedHash,
+    );
   }
 
   return pkg;
@@ -203,7 +258,7 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
 
 export async function readMigrationsDir(
   migrationsRoot: string,
-): Promise<readonly MigrationPackage[]> {
+): Promise<readonly OnDiskMigrationPackage[]> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
@@ -214,7 +269,7 @@ export async function readMigrationsDir(
     throw error;
   }
 
-  const packages: MigrationPackage[] = [];
+  const packages: OnDiskMigrationPackage[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);

package/src/metadata.ts

@@ -1,41 +1 @@
-import type { Contract } from '@prisma-next/contract/types';
-
-export interface MigrationHints {
-  readonly used: readonly string[];
-  readonly applied: readonly string[];
-  readonly plannerVersion: string;
-}
-
-/**
- * In-memory migration metadata envelope. Every migration is content-addressed:
- * the `migrationHash` is a hash over the metadata envelope plus the operations
- * list, computed at write time. There is no draft state — a migration
- * directory either exists with fully attested metadata or it does not.
- *
- * When the planner cannot lower an operation because of an unfilled
- * `placeholder(...)` slot, the migration is still written with `migrationHash`
- * hashed over `ops: []`. Re-running self-emit after the user fills the
- * placeholder produces a *different* `migrationHash` (committed to the real
- * ops); this is intentional.
- *
- * The on-disk JSON shape in `migration.json` matches this type field-for-field
- * — `JSON.stringify(metadata, null, 2)` is the canonical writer output.
- */
-export interface MigrationMetadata {
-  readonly migrationHash: string;
-  readonly from: string | null;
-  readonly to: string;
-  readonly fromContract: Contract | null;
-  readonly toContract: Contract;
-  readonly hints: MigrationHints;
-  readonly labels: readonly string[];
-  /**
-   * Sorted, deduplicated list of `invariantId`s declared by the
-   * migration's data-transform ops. Always present; an empty array
-   * means the migration has no routing-visible data transforms.
-   */
-  readonly providedInvariants: readonly string[];
-  readonly authorship?: { readonly author?: string; readonly email?: string };
-  readonly signature?: { readonly keyId: string; readonly value: string } | null;
-  readonly createdAt: string;
-}
+export type { MigrationHints, MigrationMetadata } from '@prisma-next/framework-components/control';

package/src/migration-graph.ts

@@ -9,7 +9,7 @@ import {
 } from './errors';
 import type { MigrationEdge, MigrationGraph } from './graph';
 import { bfs } from './graph-ops';
-import type { MigrationPackage } from './package';
+import type { OnDiskMigrationPackage } from './package';
 
 /** Forward-edge neighbours: edge `e` from `n` visits `e.to` next. */
 function forwardNeighbours(graph: MigrationGraph, node: string) {
@@ -36,7 +36,7 @@ function appendEdge(map: Map<string, MigrationEdge[]>, key: string, entry: Migra
   else map.set(key, [entry]);
 }
 
-export function reconstructGraph(packages: readonly MigrationPackage[]): MigrationGraph {
+export function reconstructGraph(packages: readonly OnDiskMigrationPackage[]): MigrationGraph {
   const nodes = new Set<string>();
   const forwardChain = new Map<string, MigrationEdge[]>();
   const reverseChain = new Map<string, MigrationEdge[]>();

package/src/package.ts

@@ -1,18 +1,21 @@
-import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
-import type { MigrationMetadata } from './metadata';
+import type {
+  MigrationPackage,
+  MigrationPlanOperation,
+} from '@prisma-next/framework-components/control';
 
 export type MigrationOps = readonly MigrationPlanOperation[];
 
 /**
- * An on-disk migration directory (a "package") with its parsed metadata and
- * operations. Returned from `readMigrationPackage` / `readMigrationsDir` only
- * after the loader has verified the package's integrity (hash recomputation
- * against the stored `migrationHash`); holding a `MigrationPackage` value
- * therefore implies the package is internally consistent.
+ * Augmented form of the canonical {@link MigrationPackage} returned by
+ * the on-disk readers (`readMigrationPackage`, `readMigrationsDir`).
+ * Adds `dirPath` — the absolute path the package was loaded from — so
+ * downstream diagnostics can point operators at a concrete directory.
+ *
+ * Holding an `OnDiskMigrationPackage` value implies the loader verified
+ * the package's integrity (hash recomputation against the stored
+ * `migrationHash`); the canonical structural shape carries no such
+ * guarantee on its own.
  */
-export interface MigrationPackage {
-  readonly dirName: string;
+export interface OnDiskMigrationPackage extends MigrationPackage {
   readonly dirPath: string;
-  readonly metadata: MigrationMetadata;
-  readonly ops: MigrationOps;
 }

package/src/plan-all-spaces.ts

@@ -0,0 +1,80 @@
+import { errorDuplicateSpaceId } from './errors';
+
+/**
+ * Per-space input for {@link planAllSpaces}. One entry per loaded
+ * contract space (the application's `'app'` plus each extension that
+ * exposes a `contractSpace`).
+ *
+ * - `priorContract` is `null` for a space that has never been emitted
+ *   (no `migrations/<space-id>/contract.json` on disk yet); otherwise it
+ *   is the canonical contract value pinned for that space.
+ * - `newContract` is the canonical contract value the planner is about
+ *   to emit for that space — for app-space, the just-emitted root
+ *   `contract.json`; for an extension space, the descriptor's
+ *   `contractSpace.contractJson`.
+ *
+ * @see specs/framework-mechanism.spec.md § 3.
+ */
+export interface SpacePlanInput<TContract> {
+  readonly spaceId: string;
+  readonly priorContract: TContract | null;
+  readonly newContract: TContract;
+}
+
+export interface SpacePlanOutput<TPackage> {
+  readonly spaceId: string;
+  readonly migrationPackages: readonly TPackage[];
+}
+
+/**
+ * Iterate the per-space planner across a set of loaded contract spaces
+ * and return a deterministic shape regardless of declaration order.
+ *
+ * Behaviour:
+ *
+ * - The output is sorted alphabetically by `spaceId` (AM3). Two callers
+ *   passing the same set of inputs in different orders observe
+ *   byte-identical outputs.
+ * - The per-space planner (`planSpace`) is called exactly once per
+ *   input, in alphabetical-by-spaceId order. Its return value is
+ *   attached to the corresponding output entry verbatim.
+ * - Duplicate `spaceId`s in the input array throw
+ *   `MIGRATION.DUPLICATE_SPACE_ID` before any `planSpace` call runs,
+ *   keeping the planner pure when the input is malformed.
+ *
+ * The signature is generic over `TContract` and `TPackage` because the
+ * shape is framework-neutral (SQL family today, Mongo family
+ * eventually). Callers wire in whatever contract value and migration
+ * package shape their family already speaks.
+ *
+ * Synchronous: the underlying per-space planner (target's
+ * `MigrationPlanner.plan(...)`) is synchronous; callers that need to
+ * resolve async I/O (e.g. reading pinned `contract.json` from disk)
+ * resolve it before calling `planAllSpaces` and pass the materialised
+ * inputs through.
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Per-space planner (T1.3).
+ */
+export function planAllSpaces<TContract, TPackage>(
+  inputs: readonly SpacePlanInput<TContract>[],
+  planSpace: (input: SpacePlanInput<TContract>) => readonly TPackage[],
+): readonly SpacePlanOutput<TPackage>[] {
+  const seen = new Set<string>();
+  for (const input of inputs) {
+    if (seen.has(input.spaceId)) {
+      throw errorDuplicateSpaceId(input.spaceId);
+    }
+    seen.add(input.spaceId);
+  }
+
+  const sorted = [...inputs].sort((a, b) => {
+    if (a.spaceId < b.spaceId) return -1;
+    if (a.spaceId > b.spaceId) return 1;
+    return 0;
+  });
+
+  return sorted.map((input) => ({
+    spaceId: input.spaceId,
+    migrationPackages: planSpace(input),
+  }));
+}

package/src/read-pinned-contract-hash.ts

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'pathe';
+import { errorInvalidJson, errorInvalidRefFile, errorPinnedArtefactsAppSpace } from './errors';
+import { APP_SPACE_ID, assertValidSpaceId } from './space-layout';
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return error instanceof Error && (error as { code?: string }).code === code;
+}
+
+/**
+ * Read the pinned head hash for an extension space.
+ *
+ * Returns the `hash` field of `<projectMigrationsDir>/<spaceId>/refs/head.json`
+ * — i.e. the canonical contract hash the framework wrote on the last
+ * `migrate` for this space. Returns `null` when the file does not exist
+ * (or the migrations directory is missing entirely), which is the
+ * "first emit" signal {@link import('./detect-space-contract-drift').detectSpaceContractDrift}
+ * uses to distinguish a brand-new extension from drift.
+ *
+ * Pure I/O (read + parse). The "comparison hash" is stored on disk by
+ * {@link import('./emit-pinned-space-artefacts').emitPinnedSpaceArtefacts}
+ * via the descriptor's `headRef.hash`, so reading it back here matches
+ * the descriptor's hashing pipeline by construction — neither side
+ * recomputes anything.
+ *
+ * Validation:
+ *
+ * - Rejects the app space — pinned head refs are an extension-space
+ *   concept; the app space's contract-of-record lives at the project
+ *   root, not under `migrations/`.
+ * - Validates the space id against the same `[a-z][a-z0-9_-]{0,63}`
+ *   pattern as the rest of the per-space helpers.
+ * - Surfaces `MIGRATION.INVALID_JSON` / `MIGRATION.INVALID_REF_FILE`
+ *   on a corrupt `refs/head.json` so callers can distinguish "no
+ *   pinned file" (returns `null`) from "pinned file but unreadable"
+ *   (throws).
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Drift detection (T1.9).
+ */
+export async function readPinnedContractHash(
+  projectMigrationsDir: string,
+  spaceId: string,
+): Promise<string | null> {
+  if (spaceId === APP_SPACE_ID) {
+    throw errorPinnedArtefactsAppSpace();
+  }
+  assertValidSpaceId(spaceId);
+
+  const filePath = join(projectMigrationsDir, spaceId, 'refs', 'head.json');
+
+  let raw: string;
+  try {
+    raw = await readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) {
+      return null;
+    }
+    throw error;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw errorInvalidJson(filePath, e instanceof Error ? e.message : String(e));
+  }
+
+  if (
+    typeof parsed !== 'object' ||
+    parsed === null ||
+    typeof (parsed as { hash?: unknown }).hash !== 'string'
+  ) {
+    throw errorInvalidRefFile(filePath, 'expected an object with a string `hash` field');
+  }
+
+  return (parsed as { hash: string }).hash;
+}

package/src/space-layout.ts

@@ -0,0 +1,55 @@
+import { APP_SPACE_ID } from '@prisma-next/framework-components/control';
+import { join } from 'pathe';
+import { errorInvalidSpaceId } from './errors';
+
+export { APP_SPACE_ID };
+
+/**
+ * Branded string carrying a compile-time guarantee that the value has
+ * been validated by {@link assertValidSpaceId}. Downstream filesystem
+ * helpers (e.g. {@link spaceMigrationDirectory}) accept this type to
+ * make "validated" tracking visible at the type level rather than
+ * relying purely on a runtime check.
+ */
+export type ValidSpaceId = string & { readonly __brand: 'ValidSpaceId' };
+
+/**
+ * Pattern a contract-space identifier must match. The constraint is
+ * filesystem-friendly: lowercase letters / digits / hyphen / underscore,
+ * starts with a letter, max 64 characters.
+ *
+ * @see specs/framework-mechanism.spec.md § 3.
+ */
+const SPACE_ID_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+
+export function isValidSpaceId(spaceId: string): spaceId is ValidSpaceId {
+  return SPACE_ID_PATTERN.test(spaceId);
+}
+
+export function assertValidSpaceId(spaceId: string): asserts spaceId is ValidSpaceId {
+  if (!isValidSpaceId(spaceId)) {
+    throw errorInvalidSpaceId(spaceId);
+  }
+}
+
+/**
+ * Resolve the migrations subdirectory for a given contract space.
+ *
+ * - **App space** (`spaceId === APP_SPACE_ID`) keeps today's layout: the
+ *   project's `migrations/` directory is the migrations directory, no
+ *   subdirectory.
+ * - **Extension space** lands under `<projectMigrationsDir>/<spaceId>/`.
+ *   The space id is validated against {@link SPACE_ID_PATTERN} because
+ *   it becomes a filesystem directory name verbatim.
+ *
+ * `projectMigrationsDir` is the project's top-level `migrations/`
+ * directory; the helper does not assume anything about its absolute /
+ * relative shape and is symmetric with `pathe.join`.
+ */
+export function spaceMigrationDirectory(projectMigrationsDir: string, spaceId: string): string {
+  if (spaceId === APP_SPACE_ID) {
+    return projectMigrationsDir;
+  }
+  assertValidSpaceId(spaceId);
+  return join(projectMigrationsDir, spaceId);
+}