@prisma-next/migration-tools 0.11.0-dev.46 → 0.11.0-dev.47

package/dist/verify-contract-spaces-BdysZdQk.d.mts

@@ -0,0 +1,132 @@
+//#region src/verify-contract-spaces.d.ts
+/**
+ * List the per-space subdirectories under
+ * `<projectRoot>/migrations/`. Returns space-id directory names (sorted
+ * alphabetically) — i.e. any non-dot-prefixed subdirectory whose root
+ * does **not** contain a `migration.json` manifest. The manifest is the
+ * structural marker of a user-authored migration directory (see
+ * `readMigrationsDir` in `./io`); directory names themselves belong to
+ * the user and are not part of the contract.
+ *
+ * Returns `[]` if the migrations directory does not exist (greenfield
+ * project).
+ *
+ * Reads only the user's repo. **No descriptor import.** The caller
+ * (verifier) feeds the result into {@link verifyContractSpaces} alongside
+ * the loaded-space set and the marker rows.
+ */
+declare function listContractSpaceDirectories(projectMigrationsDir: string): Promise<readonly string[]>;
+/**
+ * On-disk head value (`(hash, invariants)`) for one contract space.
+ * The verifier compares this against the marker row for the same space
+ * to detect drift between the user-emitted artefacts and the live DB
+ * marker.
+ */
+interface ContractSpaceHeadRecord {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+/**
+ * Marker row read from `prisma_contract.marker` (one per `space`).
+ * Caller resolves these via the family runtime's marker reader before
+ * invoking {@link verifyContractSpaces}.
+ */
+interface SpaceMarkerRecord {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+interface VerifyContractSpacesInputs {
+  /**
+   * Set of contract spaces the project declares: `'app'` plus each
+   * extension space in `extensionPacks`. The caller's discovery path
+   * never reads the extension descriptor module — it walks the
+   * `extensionPacks` configuration in `prisma-next.config.ts` for the
+   * space ids.
+   */
+  readonly loadedSpaces: ReadonlySet<string>;
+  /**
+   * Per-space subdirectories observed under
+   * `<projectRoot>/migrations/`. Resolved via
+   * {@link listContractSpaceDirectories}.
+   */
+  readonly spaceDirsOnDisk: readonly string[];
+  /**
+   * Head ref per space, keyed by space id. Caller reads
+   * `<projectRoot>/migrations/<space-id>/contract.json` and
+   * `<projectRoot>/migrations/<space-id>/refs/head.json` to construct
+   * this map. Spaces with no contract-space dir on disk simply omit a
+   * map entry.
+   */
+  readonly headRefsBySpace: ReadonlyMap<string, ContractSpaceHeadRecord>;
+  /**
+   * Marker rows keyed by `space`. Caller reads them from the
+   * `prisma_contract.marker` table.
+   */
+  readonly markerRowsBySpace: ReadonlyMap<string, SpaceMarkerRecord>;
+}
+type SpaceVerifierViolation = {
+  readonly kind: 'declaredButUnmigrated';
+  readonly spaceId: string;
+  readonly remediation: string;
+} | {
+  readonly kind: 'orphanMarker';
+  readonly spaceId: string;
+  readonly remediation: string;
+} | {
+  readonly kind: 'orphanSpaceDir';
+  readonly spaceId: string;
+  readonly remediation: string;
+} | {
+  readonly kind: 'hashMismatch';
+  readonly spaceId: string;
+  readonly priorHeadHash: string;
+  readonly markerHash: string;
+  readonly remediation: string;
+} | {
+  readonly kind: 'invariantsMismatch';
+  readonly spaceId: string;
+  readonly onDiskInvariants: readonly string[];
+  readonly markerInvariants: readonly string[];
+  readonly remediation: string;
+};
+type VerifyContractSpacesResult = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly violations: readonly SpaceVerifierViolation[];
+};
+/**
+ * Pure structural verifier for the per-space mechanism. Aggregates the
+ * three orphan / missing checks plus per-space hash and invariant
+ * comparison.
+ *
+ * Algorithm:
+ *
+ * - For every extension space declared in `loadedSpaces` (`'app'`
+ *   excluded — the per-space verifier is scoped to extension members;
+ *   the app is verified through the aggregate path):
+ *   - If no contract-space dir on disk → `declaredButUnmigrated`.
+ *   - Else if `markerRowsBySpace` lacks an entry → no violation here;
+ *     the live-DB compare done outside this helper is where the
+ *     absence shows up.
+ *   - Else compare marker hash / invariants vs. on-disk head hash /
+ *     invariants → `hashMismatch` / `invariantsMismatch` on drift.
+ * - For every contract-space dir on disk that is not in `loadedSpaces` →
+ *   `orphanSpaceDir`.
+ * - For every marker row whose `space` is not in `loadedSpaces` →
+ *   `orphanMarker`. The app-space marker is always loaded (`'app'` is
+ *   in `loadedSpaces` by definition).
+ *
+ * Output is deterministic: violations are sorted first by `kind`
+ * (`declaredButUnmigrated` → `orphanMarker` → `orphanSpaceDir` →
+ * `hashMismatch` → `invariantsMismatch`) then by `spaceId`. Two callers
+ * passing equivalent inputs see byte-identical violation lists.
+ *
+ * Synchronous, pure, no I/O. **Does not import the extension descriptor**
+ * (the inputs are pre-resolved by the caller); the verifier reads only
+ * the user repo, not `node_modules`.
+ */
+declare function verifyContractSpaces(inputs: VerifyContractSpacesInputs): VerifyContractSpacesResult;
+//#endregion
+export { VerifyContractSpacesResult as a, VerifyContractSpacesInputs as i, SpaceMarkerRecord as n, listContractSpaceDirectories as o, SpaceVerifierViolation as r, verifyContractSpaces as s, ContractSpaceHeadRecord as t };
+//# sourceMappingURL=verify-contract-spaces-BdysZdQk.d.mts.map

package/dist/verify-contract-spaces-BdysZdQk.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-contract-spaces-BdysZdQk.d.mts","names":[],"sources":["../src/verify-contract-spaces.ts"],"mappings":";;AAyBA;;;;AAEU;AAyCV;;;;AAEqB;AAQrB;;;;AAEqB;iBAvDC,4BAAA,CACpB,oBAAA,WACC,OAAO;;;;;;;UAyCO,uBAAA;EAAA,SACN,IAAA;EAAA,SACA,UAAU;AAAA;;;;;;UAQJ,iBAAA;EAAA,SACN,IAAA;EAAA,SACA,UAAU;AAAA;AAAA,UAGJ,0BAAA;EAiCL;;;;;;;EAAA,SAzBD,YAAA,EAAc,WAAA;EAiCV;;;;;EAAA,SA1BJ,eAAA;EAoCI;;;;;;;EAAA,SA3BJ,eAAA,EAAiB,WAAA,SAAoB,uBAAA;EAqCjC;;AAAW;AAG1B;EAHe,SA/BJ,iBAAA,EAAmB,WAAA,SAAoB,iBAAA;AAAA;AAAA,KAGtC,sBAAA;EAAA,SAEG,IAAA;EAAA,SACA,OAAA;EAAA,SACA,WAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,OAAA;EAAA,SACA,WAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,OAAA;EAAA,SACA,WAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,OAAA;EAAA,SACA,aAAA;EAAA,SACA,UAAA;EAAA,SACA,WAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,OAAA;EAAA,SACA,gBAAA;EAAA,SACA,gBAAA;EAAA,SACA,WAAA;AAAA;AAAA,KAGH,0BAAA;EAAA,SACG,EAAA;AAAA;EAAA,SACA,EAAA;EAAA,SAAoB,UAAA,WAAqB,sBAAsB;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC9D,oBAAA,CACd,MAAA,EAAQ,0BAAA,GACP,0BAA0B"}

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.11.0-dev.46",
+  "version": "0.11.0-dev.47",
   "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.46",
-    "@prisma-next/framework-components": "0.11.0-dev.46",
-    "@prisma-next/utils": "0.11.0-dev.46",
+    "@prisma-next/contract": "0.11.0-dev.47",
+    "@prisma-next/framework-components": "0.11.0-dev.47",
+    "@prisma-next/utils": "0.11.0-dev.47",
     "arktype": "^2.2.0",
     "pathe": "^2.0.3",
     "prettier": "^3.8.3"
   },
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.11.0-dev.46",
-    "@prisma-next/tsdown": "0.11.0-dev.46",
+    "@prisma-next/tsconfig": "0.11.0-dev.47",
+    "@prisma-next/tsdown": "0.11.0-dev.47",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.6"

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);
+}