@prisma-next/migration-tools 0.11.0-dev.5 → 0.11.0-dev.50

package/src/aggregate/aggregate.ts

@@ -0,0 +1,90 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { MigrationGraph } from '../graph';
+import type { IntegrityQueryOptions, IntegrityViolation } from '../integrity-violation';
+import { reconstructGraph } from '../migration-graph';
+import type { OnDiskMigrationPackage } from '../package';
+import type { Refs } from '../refs';
+import type { ContractSpaceHeadRecord } from '../verify-contract-spaces';
+import type { ContractSpaceAggregate, ContractSpaceMember } from './types';
+
+/**
+ * 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()` and
+ * `contract()` 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`.
+ */
+export function createContractSpaceMember(args: {
+  readonly spaceId: string;
+  readonly packages: readonly OnDiskMigrationPackage[];
+  readonly refs: Refs;
+  readonly headRef: ContractSpaceHeadRecord | null;
+  readonly resolveContract: () => Contract;
+}): ContractSpaceMember {
+  const { spaceId, packages, refs, headRef, resolveContract } = args;
+  let graphMemo: MigrationGraph | undefined;
+  let contractMemo: Contract | undefined;
+  return {
+    spaceId,
+    packages,
+    refs,
+    headRef,
+    graph() {
+      graphMemo ??= reconstructGraph(packages);
+      return graphMemo;
+    },
+    contract() {
+      contractMemo ??= resolveContract();
+      return contractMemo;
+    },
+  };
+}
+
+/**
+ * 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 { 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 { extractStorageElementNames } from './extract-storage-element-names';
+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 elementName of extractStorageElementNames(contract)) {
+      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);
+}