@prisma-next/cli 0.6.0-dev.3 → 0.6.0-dev.4

package/src/utils/contract-space-extension-migrations-pass.ts

@@ -1,120 +0,0 @@
-import { materialiseExtensionMigrationPackageIfMissing } from '@prisma-next/migration-tools/io';
-import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
-import type { MigrationOps } from '@prisma-next/migration-tools/package';
-import {
-  planAllSpaces,
-  type SpacePlanOutput,
-  spaceMigrationDirectory,
-} from '@prisma-next/migration-tools/spaces';
-
-/**
- * In-memory authored migration package shipped by an extension descriptor.
- * Mirrors `MigrationPackage` from `@prisma-next/migration-tools/io`
- * (the on-disk shape minus `dirPath`); redeclared structurally here so
- * the CLI helper does not couple to the SQL family's `ExtensionMigrationPackage`
- * type — any family that ships pre-built migration packages can pass them
- * through unchanged.
- */
-export interface DescriptorMigrationPackage {
-  readonly dirName: string;
-  readonly metadata: MigrationMetadata;
-  readonly ops: MigrationOps;
-}
-
-/**
- * Minimal descriptor view consumed by the migration-materialisation pass.
- * Mirrors {@link import('./contract-space-migrate-pass').MigrateExtensionInput}
- * but adds the `migrations` field — the canonical set of pre-built
- * migration packages the extension ships.
- */
-export interface ExtensionMigrationsExtensionInput {
-  readonly id: string;
-  readonly contractSpace?: {
-    readonly contractJson: unknown;
-    readonly migrations: readonly DescriptorMigrationPackage[];
-    readonly headRef: { readonly hash: string; readonly invariants: readonly string[] };
-  };
-}
-
-export interface ContractSpaceExtensionMigrationsPassInputs {
-  readonly migrationsDir: string;
-  readonly extensionPacks: ReadonlyArray<ExtensionMigrationsExtensionInput>;
-}
-
-export interface ContractSpaceExtensionMigrationsPassResult {
-  readonly emitted: readonly { readonly spaceId: string; readonly dirName: string }[];
-  readonly skipped: readonly { readonly spaceId: string; readonly dirName: string }[];
-}
-
-/**
- * Materialise an extension's pre-built migration packages onto disk
- * under `migrations/<spaceId>/<dirName>/` for every package that does
- * not yet exist there.
- *
- * Helper-location pattern — the per-space "planner" for extension
- * spaces is a no-op that just returns the descriptor's `migrations`
- * verbatim; the value `planAllSpaces` brings to this consumer site is
- * **deterministic ordering** (alphabetical by spaceId) and
- * **duplicate-spaceId detection**. The actual write is performed via
- * `materialiseMigrationPackage` per package.
- *
- * Idempotent: an existing `migrations/<spaceId>/<dirName>/` is left
- * untouched and reported in `result.skipped` — the helper never
- * overwrites authored migration content, ensuring re-running
- * `migrate` does not corrupt or churn extension migration packages.
- *
- * Per-space artefacts (`contract.json`, `contract.d.ts`,
- * `refs/head.json`) are emitted by
- * {@link import('./contract-space-migrate-pass').runContractSpaceMigratePass}
- * separately — they cover the head-pointer side of the ledger. This
- * helper covers the migration-graph side.
- */
-export async function runContractSpaceExtensionMigrationsPass(
-  inputs: ContractSpaceExtensionMigrationsPassInputs,
-): Promise<ContractSpaceExtensionMigrationsPassResult> {
-  const planInputs = inputs.extensionPacks
-    .filter(
-      (
-        pack,
-      ): pack is ExtensionMigrationsExtensionInput & {
-        contractSpace: NonNullable<ExtensionMigrationsExtensionInput['contractSpace']>;
-      } => pack.contractSpace !== undefined,
-    )
-    .map((pack) => ({
-      spaceId: pack.id,
-      priorContract: null,
-      newContract: pack.contractSpace.contractJson,
-      __migrations: pack.contractSpace.migrations,
-    }));
-
-  // Threading the descriptor's pre-built migrations into the
-  // `planAllSpaces` callback by piggybacking on the input shape.
-  // The framework helper is generic over the per-space planner output;
-  // here the "planner" is a no-op that returns the descriptor's
-  // `migrations` array. The benefit of routing through `planAllSpaces`
-  // is duplicate-spaceId detection + alphabetical ordering — failures
-  // there throw `MIGRATION.DUPLICATE_SPACE_ID` before any write.
-  const planned: readonly SpacePlanOutput<DescriptorMigrationPackage>[] = planAllSpaces(
-    planInputs,
-    (input) =>
-      (input as typeof input & { readonly __migrations: readonly DescriptorMigrationPackage[] })
-        .__migrations,
-  );
-
-  const emitted: { spaceId: string; dirName: string }[] = [];
-  const skipped: { spaceId: string; dirName: string }[] = [];
-
-  for (const space of planned) {
-    const spaceDir = spaceMigrationDirectory(inputs.migrationsDir, space.spaceId);
-    for (const pkg of space.migrationPackages) {
-      const { written } = await materialiseExtensionMigrationPackageIfMissing(spaceDir, pkg);
-      if (written) {
-        emitted.push({ spaceId: space.spaceId, dirName: pkg.dirName });
-      } else {
-        skipped.push({ spaceId: space.spaceId, dirName: pkg.dirName });
-      }
-    }
-  }
-
-  return { emitted, skipped };
-}

package/src/utils/contract-space-migrate-pass.ts

@@ -1,156 +0,0 @@
-import {
-  detectSpaceContractDrift,
-  emitContractSpaceArtefacts,
-  readContractSpaceHeadRef,
-  type SpaceContractDriftResult,
-} from '@prisma-next/migration-tools/spaces';
-
-/**
- * Minimal descriptor view consumed by the migrate-time per-space pass.
- *
- * The CLI receives descriptors typed against the SQL family (or any other
- * family in the future); this helper only needs the structural shape of
- * `contractSpace`, so it accepts an `unknown`-typed `contractJson` and
- * a structurally-typed `headRef`. SQL-family callers pass the same
- * `Contract<SqlStorage>` value through unchanged — `emitContractSpaceArtefacts`
- * already serialises through `canonicalizeJson` and is framework-neutral.
- *
- * @see specs/framework-mechanism.spec.md § 3 — Per-space helper location.
- */
-export interface MigrateExtensionInput {
-  readonly id: string;
-  readonly contractSpace?: {
-    readonly contractJson: unknown;
-    readonly headRef: { readonly hash: string; readonly invariants: readonly string[] };
-  };
-}
-
-/**
- * Inputs needed to compose the migrate-time per-space pass at the CLI
- * surface — typically called once after the app-space migration package
- * has been written, regardless of whether the app-space had structural
- * changes (an extension bump alone should still re-pin its artefacts).
- */
-export interface ContractSpaceMigratePassInputs {
-  readonly migrationsDir: string;
-  readonly extensionPacks: ReadonlyArray<MigrateExtensionInput>;
-}
-
-export interface ContractSpaceMigratePassResult {
-  readonly drifts: readonly SpaceContractDriftResult[];
-  readonly emittedSpaceIds: readonly string[];
-}
-
-/**
- * Run drift detection + on-disk artefact emission for every loaded
- * extension space at `migrate` time.
- *
- * Per sub-spec § 3:
- *
- * - For each declared extension that exposes a `contractSpace`:
- *   - Read the on-disk head hash from `migrations/<spaceId>/refs/head.json`
- *     (returns `null` on first emit).
- *   - Compare against the descriptor's `headRef.hash` via
- *     `detectSpaceContractDrift`. The `kind` discriminant decides whether
- *     the user sees a warning (`drift`), a no-op silent emit (`firstEmit`,
- *     `noDrift`), or nothing at all.
- *   - Always re-emit the on-disk artefacts (`contract.json`, `contract.d.ts`,
- *     `refs/head.json`). The framework owns these files and the helper is
- *     idempotent.
- *
- * Drift warnings are returned to the caller for formatting (TerminalUI,
- * structured-output envelope, etc.) — the helper does not print directly,
- * keeping it framework-neutral and unit-testable.
- *
- * Extension migration packages (the descriptor's pre-canned `migrations`
- * array → `migrations/<spaceId>/<dirName>/`) are intentionally not
- * materialised here — that interaction will be wired in a follow-on round
- * once the runner-side single-tx slice (sub-spec § 6) is in place.
- * On-disk artefacts are sufficient to lock the drift-warning behaviour
- * and the always-on re-emit AC for R2.
- *
- * @see specs/framework-mechanism.spec.md § 3 — Drift detection (T1.9).
- */
-export async function runContractSpaceMigratePass(
-  inputs: ContractSpaceMigratePassInputs,
-): Promise<ContractSpaceMigratePassResult> {
-  const drifts: SpaceContractDriftResult[] = [];
-  const emittedSpaceIds: string[] = [];
-
-  for (const pack of inputs.extensionPacks) {
-    if (pack.contractSpace === undefined) continue;
-    const { contractJson, headRef } = pack.contractSpace;
-
-    const onDiskHeadRef = await readContractSpaceHeadRef(inputs.migrationsDir, pack.id);
-    const drift = detectSpaceContractDrift(pack.id, {
-      descriptorHash: headRef.hash,
-      priorHeadHash: onDiskHeadRef?.hash ?? null,
-    });
-    drifts.push(drift);
-
-    await emitContractSpaceArtefacts(inputs.migrationsDir, pack.id, {
-      contract: contractJson,
-      contractDts: buildPlaceholderContractDts(pack.id),
-      headRef: { hash: headRef.hash, invariants: headRef.invariants },
-    });
-    emittedSpaceIds.push(pack.id);
-  }
-
-  return { drifts, emittedSpaceIds };
-}
-
-/**
- * Format the user-facing drift warning for a single space. Callers
- * funnel this through their preferred output channel (TerminalUI line,
- * structured-output envelope `warnings[]`, etc.).
- *
- * Locks AM7 — drift warning surfaces the extension name and the diff
- * direction (descriptor → on-disk head).
- */
-export function formatContractSpaceDriftWarning(drift: SpaceContractDriftResult): string {
-  if (drift.kind !== 'drift') {
-    throw new Error(`formatContractSpaceDriftWarning called with non-drift result: ${drift.kind}`);
-  }
-  return (
-    `Contract-space drift detected for "${drift.spaceId}": descriptor hash ` +
-    `${drift.descriptorHash} differs from on-disk head hash ${drift.priorHeadHash ?? '<none>'}. ` +
-    `The on-disk artefacts under migrations/${drift.spaceId}/ will be refreshed to match the descriptor.`
-  );
-}
-
-/**
- * Placeholder `.d.ts` content for an extension space's on-disk mirror.
- *
- * Rendering a fully-typed `.d.ts` for an extension contract requires the
- * SQL-family renderer with the codec / typemap registry threaded
- * through; that integration is tracked under sub-spec Open Question 3
- * (see `projects/extension-contract-spaces/specs/framework-mechanism.spec.md`).
- *
- * Until that ships, the on-disk `.d.ts` is a `@ts-nocheck` stub. The
- * spec gap closing alongside the typed renderer is **AC2 / AC14**
- * (byte-equivalence of per-space artefacts under `migrate`):
- * a placeholder cannot be byte-equal to a fully-rendered `.d.ts` from
- * the same descriptor, so AC2 / AC14 are PARTIAL today and become
- * fully-PASS once OQ3 closes.
- *
- * Scheduled to close in **M3** (cipherstash editor tooling) — that's
- * the milestone where the typed renderer gets its first real
- * extension-space consumer and the byte-equivalence guarantee is
- * practically required.
- */
-function buildPlaceholderContractDts(spaceId: string): string {
-  return [
-    '// @ts-nocheck',
-    '/**',
-    ` * Placeholder \`.d.ts\` for extension space "${spaceId}".`,
-    ' *',
-    ' * The framework re-emits this file on every `migrate` run alongside',
-    ' * `contract.json` and `refs/head.json`. A typed `.d.ts` rendering',
-    " * pass for extension contracts is tracked under the project's open",
-    ' * questions; until that ships, consumers should import',
-    ' * `contract.json` directly with `validateContract<…>(…)`.',
-    ' */',
-    'export {};',
-    '',
-  ].join('\n');
-}