@prisma-next/migration-tools 0.11.0-dev.9 → 0.12.0-dev.1

package/src/aggregate/aggregate.ts

@@ -0,0 +1,266 @@
+import { readFile } from 'node:fs/promises';
+import type { Contract } from '@prisma-next/contract/types';
+import { join } from 'pathe';
+import {
+  errorBundleNotFoundForGraphNode,
+  errorContractDeserializationFailed,
+  errorHashNotInGraph,
+  errorInvalidJson,
+  errorMissingFile,
+  errorSnapshotMissing,
+  MigrationToolsError,
+} from '../errors';
+import type { MigrationGraph } from '../graph';
+import { isGraphNode } from '../graph-membership';
+import type { IntegrityQueryOptions, IntegrityViolation } from '../integrity-violation';
+import { reconstructGraph } from '../migration-graph';
+import type { OnDiskMigrationPackage } from '../package';
+import type { Refs } from '../refs';
+import { readRefSnapshot } from '../refs/snapshot';
+import type { ContractSpaceHeadRecord } from '../verify-contract-spaces';
+import type {
+  ContractAtOptions,
+  ContractAtResult,
+  ContractSpaceAggregate,
+  ContractSpaceMember,
+} from './types';
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return error instanceof Error && (error as { code?: string }).code === code;
+}
+
+function contractAtMemoKey(hash: string, refName: string | undefined): string {
+  return `${hash}\0${refName ?? ''}`;
+}
+
+function deserializeContractAtPath(
+  filePath: string,
+  contractJson: unknown,
+  deserializeContract: (raw: unknown) => Contract,
+): Contract {
+  try {
+    return deserializeContract(contractJson);
+  } catch (error) {
+    if (MigrationToolsError.is(error)) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw errorContractDeserializationFailed(filePath, message);
+  }
+}
+
+async function readGraphNodeEndContract(
+  packageDir: string,
+  deserializeContract: (raw: unknown) => Contract,
+): Promise<{ contractJson: unknown; contractDts: string; contract: Contract }> {
+  const jsonPath = join(packageDir, 'end-contract.json');
+  const dtsPath = join(packageDir, 'end-contract.d.ts');
+
+  let rawJson: string;
+  try {
+    rawJson = await readFile(jsonPath, 'utf-8');
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) {
+      throw errorMissingFile('end-contract.json', packageDir);
+    }
+    throw error;
+  }
+
+  let contractJson: unknown;
+  try {
+    contractJson = JSON.parse(rawJson);
+  } catch (error) {
+    throw errorInvalidJson(jsonPath, error instanceof Error ? error.message : String(error));
+  }
+
+  let contractDts: string;
+  try {
+    contractDts = await readFile(dtsPath, 'utf-8');
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) {
+      throw errorMissingFile('end-contract.d.ts', packageDir);
+    }
+    throw error;
+  }
+
+  const contract = deserializeContractAtPath(jsonPath, contractJson, deserializeContract);
+  return { contractJson, contractDts, contract };
+}
+
+async function resolveContractAt(args: {
+  readonly hash: string;
+  readonly opts: ContractAtOptions | undefined;
+  readonly refsDir: string;
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly graph: MigrationGraph;
+  readonly deserializeContract: (raw: unknown) => Contract;
+}): Promise<ContractAtResult> {
+  const { hash, opts, refsDir, packages, graph, deserializeContract } = args;
+  const refName = opts?.refName;
+
+  if (refName !== undefined) {
+    const snapshot = await readRefSnapshot(refsDir, refName);
+    if (snapshot) {
+      const jsonPath = join(refsDir, `${refName}.contract.json`);
+      return {
+        hash,
+        contractJson: snapshot.contract,
+        contractDts: snapshot.contractDts,
+        contract: deserializeContractAtPath(jsonPath, snapshot.contract, deserializeContract),
+        provenance: 'snapshot',
+      };
+    }
+
+    if (isGraphNode(hash, graph)) {
+      return resolveGraphNodeContractAt({
+        hash,
+        packages,
+        deserializeContract,
+        explicitLabel: refName,
+      });
+    }
+
+    throw errorSnapshotMissing(refName);
+  }
+
+  if (isGraphNode(hash, graph)) {
+    return resolveGraphNodeContractAt({ hash, packages, deserializeContract });
+  }
+
+  throw errorHashNotInGraph(hash, graph);
+}
+
+async function resolveGraphNodeContractAt(args: {
+  readonly hash: string;
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly deserializeContract: (raw: unknown) => Contract;
+  readonly explicitLabel?: string;
+}): Promise<ContractAtResult> {
+  const { hash, packages, deserializeContract, explicitLabel } = args;
+  const matchingBundle = packages.find((pkg) => pkg.metadata.to === hash);
+  if (!matchingBundle) {
+    throw errorBundleNotFoundForGraphNode(hash, explicitLabel);
+  }
+
+  const { contractJson, contractDts, contract } = await readGraphNodeEndContract(
+    matchingBundle.dirPath,
+    deserializeContract,
+  );
+  return {
+    hash,
+    contractJson,
+    contractDts,
+    contract,
+    provenance: 'graph-node',
+    sourceDir: matchingBundle.dirPath,
+  };
+}
+
+/**
+ * Resolve a member's head ref, asserting it is present. The apply/verify
+ * engine only runs after `checkIntegrity` has refused on `headRefMissing`,
+ * so a member reaching the planner / verifier without a head ref is a
+ * programming error (the integrity gate was skipped), not a user-facing
+ * state. The app member's head ref is always synthesised, so this only
+ * ever guards an ungated extension space.
+ */
+export function requireHeadRef(member: ContractSpaceMember): ContractSpaceHeadRecord {
+  if (member.headRef === null) {
+    throw new Error(
+      `Contract space "${member.spaceId}" has no head ref; the integrity gate must refuse a missing head ref before planning or verifying.`,
+    );
+  }
+  return member.headRef;
+}
+
+/**
+ * Build a {@link ContractSpaceMember} with lazily-memoised `graph()`,
+ * `contract()`, and `contractAt()` facets.
+ *
+ * `graph()` reconstructs the migration graph from `packages` on first
+ * call and caches it. `contract()` calls `resolveContract` on first call
+ * and caches the result; a throwing `resolveContract` (e.g. a missing or
+ * undeserializable on-disk contract) re-throws on each call rather than
+ * caching a value — `checkIntegrity` surfaces that as `contractUnreadable`.
+ * `contractAt()` materializes the contract at an arbitrary graph node with
+ * the same resolution order as plan-time ref resolution: ref snapshot first
+ * (when `opts.refName` is set), else the matching package's `end-contract.*`.
+ */
+export function createContractSpaceMember(args: {
+  readonly spaceId: string;
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly refs: Refs;
+  readonly headRef: ContractSpaceHeadRecord | null;
+  readonly refsDir: string;
+  readonly resolveContract: () => Contract;
+  readonly deserializeContract: (raw: unknown) => Contract;
+}): ContractSpaceMember {
+  const { spaceId, packages, refs, headRef, refsDir, resolveContract, deserializeContract } = args;
+  let graphMemo: MigrationGraph | undefined;
+  let contractMemo: Contract | undefined;
+  const contractAtMemo = new Map<string, ContractAtResult>();
+
+  function memberGraph(): MigrationGraph {
+    graphMemo ??= reconstructGraph(packages);
+    return graphMemo;
+  }
+
+  return {
+    spaceId,
+    packages,
+    refs,
+    headRef,
+    graph: memberGraph,
+    contract() {
+      contractMemo ??= resolveContract();
+      return contractMemo;
+    },
+    async contractAt(hash, opts) {
+      const key = contractAtMemoKey(hash, opts?.refName);
+      const cached = contractAtMemo.get(key);
+      if (cached) {
+        return cached;
+      }
+
+      const result = await resolveContractAt({
+        hash,
+        opts,
+        refsDir,
+        packages,
+        graph: memberGraph(),
+        deserializeContract,
+      });
+      contractAtMemo.set(key, result);
+      return result;
+    },
+  };
+}
+
+/**
+ * Assemble a {@link ContractSpaceAggregate} value from its members and a
+ * `checkIntegrity` implementation. The query methods (`listSpaces` /
+ * `hasSpace` / `space` / `spaces`) are derived here so every aggregate —
+ * loader-built or test-built — shares one query surface: `app` first,
+ * then `extensions` in the order supplied (the loader sorts them
+ * lex-ascending by `spaceId`).
+ */
+export function createContractSpaceAggregate(args: {
+  readonly targetId: string;
+  readonly app: ContractSpaceMember;
+  readonly extensions: readonly ContractSpaceMember[];
+  readonly checkIntegrity: (opts?: IntegrityQueryOptions) => readonly IntegrityViolation[];
+}): ContractSpaceAggregate {
+  const { targetId, app, extensions, checkIntegrity } = args;
+  const ordered: readonly ContractSpaceMember[] = [app, ...extensions];
+  const byId = new Map(ordered.map((m) => [m.spaceId, m]));
+  return {
+    targetId,
+    app,
+    extensions,
+    listSpaces: () => ordered.map((m) => m.spaceId),
+    hasSpace: (id) => byId.has(id),
+    space: (id) => byId.get(id),
+    spaces: () => ordered,
+    checkIntegrity,
+  };
+}

package/src/aggregate/check-integrity.ts

@@ -0,0 +1,243 @@
+import { elementCoordinates } from '@prisma-next/framework-components/ir';
+import { EMPTY_CONTRACT_HASH } from '../constants';
+import { MigrationToolsError } from '../errors';
+import type {
+  DeclaredExtensionEntry,
+  IntegrityQueryOptions,
+  IntegrityViolation,
+} from '../integrity-violation';
+import type { PackageLoadProblem } from '../io';
+import type { OnDiskMigrationPackage } from '../package';
+import type { RefLoadProblem } from '../refs';
+import type { ContractSpaceMember } from './types';
+
+/**
+ * One space's load-time facts that `checkIntegrity` judges: the loaded
+ * member, the load-time problems `readMigrationsDir` surfaced for it, and
+ * whether it is the app space (the app head ref is synthesised, so the
+ * head-ref checks are skipped for it).
+ */
+export interface IntegritySpaceState {
+  readonly member: ContractSpaceMember;
+  readonly problems: readonly PackageLoadProblem[];
+  /** Per-ref problems: a user ref `*.json` that exists but is unparseable. */
+  readonly refProblems: readonly RefLoadProblem[];
+  /**
+   * The space's `refs/head.json` problem when it exists but is unparseable.
+   * `null` means the head ref was read cleanly or is genuinely absent —
+   * the absent case is judged `headRefMissing`, the corrupt case here is
+   * judged `refUnreadable` (and suppresses `headRefMissing`).
+   */
+  readonly headRefProblem: RefLoadProblem | null;
+  readonly isApp: boolean;
+}
+
+export interface IntegrityComputationInput {
+  readonly targetId: string;
+  readonly spaces: readonly IntegritySpaceState[];
+}
+
+/**
+ * Walk the loaded model and return **every** integrity violation — never
+ * bailing at the first. Structurally-derivable violations (load-time
+ * problems, self-edges, missing / unreachable head refs) are always
+ * produced; layout-drift checks require `declaredExtensions`, and
+ * contract / target / disjointness checks require `checkContracts`.
+ */
+export function computeIntegrityViolations(
+  input: IntegrityComputationInput,
+  opts?: IntegrityQueryOptions,
+): readonly IntegrityViolation[] {
+  const violations: IntegrityViolation[] = [];
+
+  for (const { member, problems, refProblems, headRefProblem, isApp } of input.spaces) {
+    const { spaceId } = member;
+
+    for (const problem of problems) {
+      violations.push(loadProblemToViolation(spaceId, problem));
+    }
+
+    for (const refProblem of refProblems) {
+      violations.push({
+        kind: 'refUnreadable',
+        spaceId,
+        refName: refProblem.refName,
+        detail: refProblem.detail,
+      });
+    }
+    if (headRefProblem !== null) {
+      violations.push({
+        kind: 'refUnreadable',
+        spaceId,
+        refName: headRefProblem.refName,
+        detail: headRefProblem.detail,
+      });
+    }
+
+    for (const pkg of member.packages) {
+      const from = pkg.metadata.from ?? EMPTY_CONTRACT_HASH;
+      const isSelfEdge = from === pkg.metadata.to;
+      const hasDataOp = pkg.ops.some((op) => op.operationClass === 'data');
+      if (isSelfEdge && !hasDataOp) {
+        violations.push({ kind: 'sameSourceAndTarget', spaceId, dirName: pkg.dirName, hash: from });
+      }
+    }
+
+    violations.push(...duplicateMigrationHashViolations(spaceId, member.packages));
+
+    // The app head ref is synthesised from the live contract, so it is
+    // always present and reachable; only extension spaces read their head
+    // ref from disk and can be missing or point outside the graph. A head
+    // ref that exists but is unparseable is already surfaced above as
+    // `refUnreadable`, so it is not also reported as `headRefMissing`.
+    if (!isApp && headRefProblem === null) {
+      if (member.headRef === null) {
+        violations.push({ kind: 'headRefMissing', spaceId });
+      } else if (!headRefPresentInGraph(member, member.headRef.hash)) {
+        violations.push({ kind: 'headRefNotInGraph', spaceId, hash: member.headRef.hash });
+      }
+    }
+  }
+
+  if (opts?.declaredExtensions !== undefined) {
+    violations.push(...layoutViolations(input.spaces, opts.declaredExtensions));
+  }
+
+  if (opts?.checkContracts === true) {
+    violations.push(...contractViolations(input));
+  }
+
+  return violations;
+}
+
+export function loadProblemToViolation(
+  spaceId: string,
+  problem: PackageLoadProblem,
+): IntegrityViolation {
+  switch (problem.kind) {
+    case 'hashMismatch':
+      return {
+        kind: 'hashMismatch',
+        spaceId,
+        dirName: problem.dirName,
+        stored: problem.stored,
+        computed: problem.computed,
+      };
+    case 'providedInvariantsMismatch':
+      return { kind: 'providedInvariantsMismatch', spaceId, dirName: problem.dirName };
+    case 'packageUnloadable':
+      return {
+        kind: 'packageUnloadable',
+        spaceId,
+        dirName: problem.dirName,
+        detail: problem.detail,
+      };
+  }
+}
+
+function duplicateMigrationHashViolations(
+  spaceId: string,
+  packages: readonly OnDiskMigrationPackage[],
+): readonly IntegrityViolation[] {
+  const dirNamesByHash = new Map<string, string[]>();
+  for (const pkg of packages) {
+    const hash = pkg.metadata.migrationHash;
+    const dirNames = dirNamesByHash.get(hash);
+    if (dirNames) dirNames.push(pkg.dirName);
+    else dirNamesByHash.set(hash, [pkg.dirName]);
+  }
+
+  const out: IntegrityViolation[] = [];
+  for (const [migrationHash, dirNames] of dirNamesByHash) {
+    if (dirNames.length > 1) {
+      out.push({
+        kind: 'duplicateMigrationHash',
+        spaceId,
+        migrationHash,
+        dirNames: [...dirNames].sort(),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether a space's head-ref hash is present in its reconstructed graph.
+ * An empty graph is reachable only by the empty-contract sentinel.
+ */
+function headRefPresentInGraph(member: ContractSpaceMember, headHash: string): boolean {
+  const graph = member.graph();
+  if (graph.nodes.size === 0) {
+    return headHash === EMPTY_CONTRACT_HASH;
+  }
+  return graph.nodes.has(headHash);
+}
+
+function layoutViolations(
+  spaces: readonly IntegritySpaceState[],
+  declaredExtensions: readonly DeclaredExtensionEntry[],
+): readonly IntegrityViolation[] {
+  const out: IntegrityViolation[] = [];
+  const extensionSpaceIds = new Set(spaces.filter((s) => !s.isApp).map((s) => s.member.spaceId));
+  const declaredIds = new Set(declaredExtensions.map((d) => d.id));
+
+  for (const id of [...extensionSpaceIds].sort()) {
+    if (!declaredIds.has(id)) {
+      out.push({ kind: 'orphanSpaceDir', spaceId: id });
+    }
+  }
+  for (const id of [...declaredIds].sort()) {
+    if (!extensionSpaceIds.has(id)) {
+      out.push({ kind: 'declaredButUnmigrated', spaceId: id });
+    }
+  }
+  return out;
+}
+
+function contractViolations(input: IntegrityComputationInput): readonly IntegrityViolation[] {
+  const out: IntegrityViolation[] = [];
+  const elementClaimedBy = new Map<string, string[]>();
+
+  for (const { member } of input.spaces) {
+    let contract: ReturnType<ContractSpaceMember['contract']>;
+    try {
+      contract = member.contract();
+    } catch (error) {
+      out.push({ kind: 'contractUnreadable', spaceId: member.spaceId, detail: detailOf(error) });
+      continue;
+    }
+
+    if (contract.target !== input.targetId) {
+      out.push({
+        kind: 'targetMismatch',
+        spaceId: member.spaceId,
+        expected: input.targetId,
+        actual: contract.target,
+      });
+    }
+
+    for (const { entityName: elementName } of elementCoordinates(contract.storage)) {
+      const claimers = elementClaimedBy.get(elementName);
+      if (claimers) claimers.push(member.spaceId);
+      else elementClaimedBy.set(elementName, [member.spaceId]);
+    }
+  }
+
+  const disjointness: IntegrityViolation[] = [];
+  for (const [element, claimedBy] of elementClaimedBy) {
+    if (claimedBy.length > 1) {
+      disjointness.push({ kind: 'disjointness', element, claimedBy: [...claimedBy].sort() });
+    }
+  }
+  disjointness.sort((a, b) =>
+    a.kind === 'disjointness' && b.kind === 'disjointness' ? a.element.localeCompare(b.element) : 0,
+  );
+  out.push(...disjointness);
+  return out;
+}
+
+function detailOf(error: unknown): string {
+  if (MigrationToolsError.is(error)) return error.why;
+  if (error instanceof Error) return error.message;
+  return String(error);
+}