@prisma-next/cli 0.14.0 → 0.15.0-dev.1

package/src/control-api/operations/contract-emit.ts

@@ -1,16 +1,14 @@
 import { mkdir } from 'node:fs/promises';
+import { loadConfig } from '@prisma-next/config-loader';
 import type { Contract } from '@prisma-next/contract/types';
 import { emit, getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { createControlStack } from '@prisma-next/framework-components/control';
 import { abortable } from '@prisma-next/utils/abortable';
-import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { JsonObject } from '@prisma-next/utils/json';
 import { dirname, join } from 'pathe';
-import { loadConfig } from '../../config-loader';
 import { errorContractConfigMissing, errorRuntime } from '../../utils/cli-errors';
 import { queueEmitByOutput } from '../../utils/emit-queue';
-import { toExtensionInputs } from '../../utils/extension-pack-inputs';
 import { assertFrameworkComponentsCompatible } from '../../utils/framework-components';
 import { publishContractArtifactPair } from '../../utils/publish-contract-artifact-pair';
 import { validateContractDeps } from '../../utils/validate-contract-deps';
@@ -196,31 +194,15 @@ export async function executeContractEmit(
   return queueEmitByOutput(outputJsonPath, async () => {
     const stack = createControlStack(config);
 
-    const extensionInputs = toExtensionInputs(
-      blindCast<
-        readonly unknown[],
-        'toExtensionInputs accepts readonly unknown[] per its documented structural cast boundary'
-      >(stack.extensionPacks),
-    );
-    const composedExtensionContracts = new Map<string, Contract>(
-      extensionInputs
-        .filter((p) => p.contractSpace !== undefined)
-        .map((p) => [
-          p.id,
-          blindCast<
-            Contract,
-            'contractSpace.contractJson is the typed contract for this extension space'
-          >(p.contractSpace!.contractJson),
-        ]),
-    );
     const sourceContext = {
       composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
-      composedExtensionContracts,
+      composedExtensionContracts: stack.extensionContracts,
       scalarTypeDescriptors: stack.scalarTypeDescriptors,
       authoringContributions: stack.authoringContributions,
       codecLookup: stack.codecLookup,
       controlMutationDefaults: stack.controlMutationDefaults,
       resolvedInputs: contractConfig.source.inputs ?? [],
+      capabilities: stack.capabilities,
     };
 
     startSpan(onProgress, 'resolveSource', 'Resolving contract source...');
@@ -258,16 +240,16 @@ export async function executeContractEmit(
       // Blind cast: `validateProviderResult` upstream has already
       // pinned `validatedContract.value` to the provider's loose
       // `Contract` envelope, but the local `Contract` type at this
-      // call site is the precise structural interface. Re-narrowing
-      // the envelope into the precise type is exactly what the
-      // `familyInstance.deserializeContract(enrichedIR)` call on the
-      // next line does — the cast just defers the structural check
-      // by one statement so `enrichContract` can decorate first.
+      // call site is the precise structural interface. The cast just
+      // defers the structural check by one statement so `enrichContract`
+      // can decorate first; the subsequent serialize→deserialize round-trip
+      // re-narrows the envelope into the precise type.
       const enrichedIR = enrichContract(
         validatedContract.value as unknown as Contract,
         frameworkComponents,
       );
-      const deserializedContract = familyInstance.deserializeContract(enrichedIR);
+      const rawContractJson = config.target.contractSerializer.serializeContract(enrichedIR);
+      const deserializedContract = familyInstance.deserializeContract(rawContractJson);
       // Each target's descriptor ships a `contractSerializer` SPI; the
       // framework canonicalizer threads its `serializeContract` so the
       // on-disk JSON envelope is constructed by target-owned code

package/src/control-api/operations/db-init.ts

@@ -20,7 +20,7 @@ import { executeRun } from './db-run';
  *    {@link import('@prisma-next/migration-tools/aggregate').loadContractSpaceAggregate}
  *    from the supplied descriptor set + on-disk on-disk artefacts.
  * 2. The aggregate planner runs with `callerPolicy.ignoreGraphFor`
- *    locked to the app member — synth strategy for the app, graph-walk
+ *    locked to the app space — synth strategy for the app, graph-walk
  *    for every extension.
  * 3. The runner's `execute` applies the per-space plans
  *    inside one outer transaction.
@@ -53,7 +53,7 @@ export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extend
   /**
    * Declared extension descriptors. Defaults to an empty list, which
    * routes through the same loader → planner → runner pipeline with no
-   * extension members in the aggregate.
+   * extension spaces in the aggregate.
    */
   readonly extensionPacks?: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   /** Optional progress callback for observing operation progress */

package/src/control-api/operations/db-run.ts

@@ -1,5 +1,5 @@
 /**
- * Backs `db init` / `db update`. Strategy: introspect → planMigration; synth-for-app + graph-walk-extensions; plan-mode + orphan-marker preflight.
+ * Backs `db init` / `db update`. Strategy: introspect → planMigration; planFromDiff-for-app + resolveRecordedPath-extensions; plan-mode + orphan-marker preflight.
  */
 
 import type { Contract } from '@prisma-next/contract/types';
@@ -97,10 +97,11 @@ export interface ExecuteRunOptions<TFamilyId extends string, TTargetId extends s
  *    integrity violation short-circuits with a structured error.
  * 2. **Read DB state**: marker rows (`familyInstance.readAllMarkers`)
  *    + introspected schema (`familyInstance.introspect`).
- * 3. **Plan**: {@link planMigration} chooses graph-walk vs synth per
- *    member according to `callerPolicy.ignoreGraphFor`. The app member
- *    is forced through synth (today's daily-driver behaviour); every
- *    extension member walks its on-disk graph.
+ * 3. **Plan**: {@link planMigration} chooses `resolveRecordedPath` vs
+ *    `planFromDiff` per space according to `callerPolicy.ignoreGraphFor`.
+ *    The app space is forced through `planFromDiff` (today's daily-driver
+ *    behaviour); every extension space walks its on-disk graph via
+ *    `resolveRecordedPath`.
  * 4. **Apply** (when `mode === 'apply'`): every per-space `MigrationPlan`
  *    feeds into the runner's `execute` — one outer
  *    transaction across every space; failure on any space rolls back
@@ -168,9 +169,9 @@ export async function executeRun<TFamilyId extends string, TTargetId extends str
   });
   onProgress?.({ action, kind: 'spanEnd', spanId: SPAN_IDS.introspect, outcome: 'ok' });
 
-  // 3. Plan via aggregate planner. App is forced through synth (today's
-  // `db init` / `db update` daily-driver behaviour); extensions walk
-  // their on-disk migration graphs.
+  // 3. Plan via aggregate planner. App is forced through planFromDiff
+  // (today's `db init` / `db update` daily-driver behaviour); extensions
+  // walk their on-disk migration graphs via resolveRecordedPath.
   onProgress?.({
     action,
     kind: 'spanStart',
@@ -200,7 +201,7 @@ export async function executeRun<TFamilyId extends string, TTargetId extends str
   const appResolution = orderedResolutions.find((r) => r.spaceId === aggregate.app.spaceId);
   if (!appResolution) {
     throw new Error(
-      'Aggregate planner returned no plan for the app member — the planner is supposed to always emit one.',
+      'Aggregate planner returned no plan for the app space — the planner is supposed to always emit one.',
     );
   }
   const appPlan = appResolution.entry.plan;
@@ -228,9 +229,9 @@ export async function executeRun<TFamilyId extends string, TTargetId extends str
   // 5. Run mode: hand off to the shared `runMigration` primitive.
   // The runner-driving tail is identical for `db init` / `db update` /
   // `migrate` — only how each caller produces `perSpacePlans`
-  // differs (synth + graph-walk via planMigration here; graph-walk
-  // only for migrate). Each caller produces perSpacePlans differently;
-  // this helper handles the shared run tail.
+  // differs (planFromDiff + resolveRecordedPath via planMigration here;
+  // resolveRecordedPath only for migrate). Each caller produces
+  // perSpacePlans differently; this helper handles the shared run tail.
   const applied = await runMigration({
     aggregate,
     perSpacePlans: planResult.value.perSpace,
@@ -280,14 +281,14 @@ function aggregatePlannerWarnings(
 
 /**
  * Compare the live `_prisma_marker` rows against the aggregate's
- * declared members. Any marker row whose `space` is not a member of
+ * declared contract spaces. Any marker row whose `space` is not a space of
  * the aggregate is an "orphan" — typically a marker left behind by
  * an extension that was removed from `extensionPacks` without first
  * cleaning up its on-disk migrations / database tables.
  *
  * Returns a {@link CliStructuredError} envelope (code `5002`,
  * `kind: 'orphanMarker'`) for the first orphan it finds, or `null`
- * when every marker row maps to a declared member. Mirrors the M2
+ * when every marker row maps to a declared contract space. Mirrors the M2
  * `runContractSpaceVerifierMarkerCheck` envelope so downstream
  * tooling (integration tests, JSON consumers) keeps asserting on the
  * same shape.
@@ -296,13 +297,13 @@ function detectOrphanMarkers(
   aggregate: ContractSpaceAggregate,
   markerRows: ReadonlyMap<string, unknown>,
 ): CliStructuredError | null {
-  const memberSpaceIds = new Set<string>([
+  const aggregateSpaceIds = new Set<string>([
     aggregate.app.spaceId,
     ...aggregate.extensions.map((m) => m.spaceId),
   ]);
   const orphans: string[] = [];
   for (const [spaceId, row] of markerRows) {
-    if (row !== null && row !== undefined && !memberSpaceIds.has(spaceId)) {
+    if (row !== null && row !== undefined && !aggregateSpaceIds.has(spaceId)) {
       orphans.push(spaceId);
     }
   }
@@ -328,7 +329,7 @@ function detectOrphanMarkers(
 }
 
 function mapPlannerError(error: PlannerError): DbInitResult | DbUpdateResult {
-  if (error.kind === 'appSynthFailure') {
+  if (error.kind === 'planFromDiffFailed') {
     const failure: DbInitFailure | DbUpdateFailure = {
       code: 'PLANNING_FAILED',
       summary: 'Migration planning failed due to conflicts',

package/src/control-api/operations/db-verify.ts

@@ -4,16 +4,19 @@ import type {
   ControlDriverInstance,
   ControlExtensionDescriptor,
   ControlFamilyInstance,
+  SchemaDiffIssue,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
+import { hasSchemaSubjectClassifier } from '@prisma-next/framework-components/control';
 import {
-  type ContractSpaceMember,
+  type AggregateContractSpace,
   collectAggregateNamespaces,
   requireHeadRef,
   type VerifierOutput,
   verifyMigration,
 } from '@prisma-next/migration-tools/aggregate';
-import { blindCast, castAs } from '@prisma-next/utils/casts';
+import { castAs } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { CliStructuredError } from '../../utils/cli-errors';
 import {
@@ -37,9 +40,9 @@ const SPAN_IDS = {
  *
  * Loader → verifier pipeline. The loader (sole descriptor-import
  * boundary) builds a {@link import('@prisma-next/migration-tools/aggregate').ContractSpaceAggregate};
- * the aggregate verifier bundles `markerCheck` + per-space pre-projected
- * `schemaCheck`. `mode: 'strict' | 'lenient'` maps directly to the user
- * facing `--strict` flag.
+ * the aggregate verifier bundles `markerCheck` + per-space `schemaCheck`
+ * (each contract space verified against the full schema; extras stripped to its own view).
+ * `mode: 'strict' | 'lenient'` maps directly to the user facing `--strict` flag.
  */
 export interface ExecuteDbVerifyOptions<TFamilyId extends string, TTargetId extends string> {
   readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
@@ -63,13 +66,19 @@ export interface ExecuteDbVerifyOptions<TFamilyId extends string, TTargetId exte
  * emitted, so downstream tooling and integration tests assert on the
  * same shape).
  *
- * On success, the per-space schema results are returned for the CLI to
+ * On success, the per-space verify results are returned for the CLI to
  * render. When `skipSchema` is true (`--marker-only`), the schema map
  * is empty.
  */
 export interface ExecuteDbVerifySuccess {
   readonly schemaResults: ReadonlyMap<string, VerifyDatabaseSchemaResult>;
-  readonly memberOrder: readonly string[];
+  /**
+   * Live element names no contract space declares, deduplicated and reported
+   * once for the whole database (never per space). Strict mode fails on a
+   * non-empty list; lenient mode surfaces it informationally.
+   */
+  readonly unclaimed: readonly string[];
+  readonly spaceOrder: readonly string[];
   readonly appSpaceId: string;
 }
 
@@ -85,11 +94,11 @@ export type ExecuteDbVerifyResult = Result<ExecuteDbVerifySuccess, CliStructured
  *    structured CLI error.
  * 2. **Read DB state**: marker rows + (when `skipSchema` is `false`)
  *    schema introspection.
- * 3. **Verify**: {@link verifyMigration} returns per-space
- *    `markerCheck` + per-space pre-projected `schemaCheck` (closes F23).
- *    Marker mismatches map to `CliStructuredError` (code `5002`) so
- *    callers (CLI command) can render and exit. Schema results are
- *    returned to the caller verbatim.
+ * 3. **Verify**: {@link verifyMigration} returns per-space `markerCheck` +
+ *    per-space `schemaCheck` (each contract space verified against the full schema,
+ *    then scoped to its own contract space). Marker mismatches map to
+ *    `CliStructuredError` (code `5002`) so callers (CLI command) can render
+ *    and exit. Verify results are returned to the caller verbatim.
  */
 export async function executeDbVerify<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteDbVerifyOptions<TFamilyId, TTargetId>,
@@ -109,13 +118,26 @@ export async function executeDbVerify<TFamilyId extends string, TTargetId extend
         contract: collectAggregateNamespaces(aggregate),
       });
 
+  // The subject-granularity + entity-kind classifiers are an injected
+  // capability — not every family provides one — detected the same way the
+  // other optional per-family capabilities are (`hasSchemaView`, …), never
+  // assumed.
+  const classifySubjectGranularity = hasSchemaSubjectClassifier(familyInstance)
+    ? (issue: SchemaDiffIssue) => familyInstance.classifySubjectGranularity(issue)
+    : undefined;
+  const classifyEntityKind = hasSchemaSubjectClassifier(familyInstance)
+    ? (issue: SchemaDiffIssue) => familyInstance.classifyEntityKind(issue)
+    : undefined;
+
   emitVerifySpan(onProgress, 'spanStart');
   const verifyResult = verifyMigration({
     aggregate,
     markersBySpaceId,
     schemaIntrospection,
     mode: options.mode,
-    verifySchemaForMember: createPerMemberVerifier(options),
+    verifySchemaForSpace: createPerSpaceVerifier(options),
+    ...ifDefined('classifySubjectGranularity', classifySubjectGranularity),
+    ...ifDefined('classifyEntityKind', classifyEntityKind),
   });
   return finaliseVerifyResult({ verifyResult, aggregate, skipMarker, onProgress });
 }
@@ -166,30 +188,27 @@ async function runIntrospection<TFamilyId extends string, TTargetId extends stri
 }
 
 /**
- * Build the per-member schema callback handed to the aggregate verifier.
+ * Build the per-space schema callback handed to the aggregate verifier.
  * When `skipSchema` is true the callback short-circuits with a synthetic
  * `ok` result so the verifier still runs the (cheap) schemaCheck loop
  * without invoking the family's verification path.
  */
-export function createPerMemberVerifier<TFamilyId extends string, TTargetId extends string>(
+export function createPerSpaceVerifier<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteDbVerifyOptions<TFamilyId, TTargetId>,
 ): (
-  projectedSchema: unknown,
-  member: ContractSpaceMember,
+  schema: unknown,
+  space: AggregateContractSpace,
   verifyMode: 'strict' | 'lenient',
 ) => VerifyDatabaseSchemaResult {
   const { skipSchema, familyInstance, frameworkComponents } = options;
-  return (projectedSchema, member, verifyMode) => {
-    if (skipSchema) return buildSkippedSchemaResult(member);
+  return (schema, space, verifyMode) => {
+    if (skipSchema) return buildSkippedSchemaResult(space);
     return familyInstance.verifySchema({
-      contract: member.contract(),
-      // The family's `TSchemaIR` is opaque to migration-tools; the
-      // aggregate verifier passes through whatever we hand it. The
-      // family expects its own IR shape on the way back.
-      schema: blindCast<
-        never,
-        'family TSchemaIR is opaque to migration-tools; projectedSchema is passed straight through'
-      >(projectedSchema),
+      contract: space.contract(),
+      // `familyInstance` is `ControlFamilyInstance<_, unknown>`, so `verifySchema`
+      // takes its `TSchemaIR` as `unknown` — the introspected schema passes
+      // straight through; the family narrows to its own IR node internally.
+      schema,
       strict: verifyMode === 'strict',
       frameworkComponents,
     });
@@ -223,7 +242,7 @@ function emitVerifySpan(
  * by the CLI's `--schema-only` mode.
  */
 function finaliseVerifyResult(args: {
-  verifyResult: VerifierOutput<VerifyDatabaseSchemaResult>;
+  verifyResult: VerifierOutput;
   aggregate: {
     readonly app: { readonly spaceId: string };
     readonly extensions: ReadonlyArray<{ readonly spaceId: string }>;
@@ -253,14 +272,15 @@ function finaliseVerifyResult(args: {
   emitVerifySpan(onProgress, 'spanEndOk');
   return ok({
     schemaResults: verifyResult.value.schemaCheck.perSpace,
-    memberOrder: [aggregate.app.spaceId, ...aggregate.extensions.map((e) => e.spaceId)],
+    unclaimed: verifyResult.value.schemaCheck.unclaimed,
+    spaceOrder: [aggregate.app.spaceId, ...aggregate.extensions.map((e) => e.spaceId)],
     appSpaceId: aggregate.app.spaceId,
   });
 }
 
-function buildSkippedSchemaResult(member: ContractSpaceMember): VerifyDatabaseSchemaResult {
-  const contract = member.contract();
-  const headRef = requireHeadRef(member);
+function buildSkippedSchemaResult(space: AggregateContractSpace): VerifyDatabaseSchemaResult {
+  const contract = space.contract();
+  const headRef = requireHeadRef(space);
   const profileHash = castAs<{ profileHash?: string }>(contract).profileHash;
   return {
     ok: true,
@@ -272,18 +292,6 @@ function buildSkippedSchemaResult(member: ContractSpaceMember): VerifyDatabaseSc
     target: { expected: contract.target },
     schema: {
       issues: [],
-      root: {
-        status: 'pass',
-        kind: 'skipped',
-        name: member.spaceId,
-        contractPath: '',
-        code: 'SKIPPED',
-        message: 'Schema verification skipped',
-        expected: undefined,
-        actual: undefined,
-        children: [],
-      },
-      counts: { pass: 0, warn: 0, fail: 0, totalNodes: 0 },
     },
     timings: { total: 0 },
   };

package/src/control-api/operations/format.ts

@@ -0,0 +1,98 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { EOL } from 'node:os';
+import { loadConfig } from '@prisma-next/config-loader';
+import { type FormatOptions, format, PslFormatError } from '@prisma-next/psl-parser/format';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { CliStructuredError, errorRuntime, errorUnexpected } from '../../utils/cli-errors';
+
+export interface FormatOperationOptions {
+  readonly configPath?: string;
+  readonly eol?: string;
+}
+
+export interface FormatOperationResult {
+  readonly formatted: boolean;
+  readonly path?: string;
+}
+
+export function resolveNewline(
+  formatterNewline: 'LF' | 'CRLF' | undefined,
+  eol: string,
+): 'LF' | 'CRLF' {
+  if (formatterNewline !== undefined) {
+    return formatterNewline;
+  }
+  return eol === '\r\n' ? 'CRLF' : 'LF';
+}
+
+export async function executeFormat(
+  options: FormatOperationOptions,
+): Promise<Result<FormatOperationResult, CliStructuredError>> {
+  const eol = options.eol ?? EOL;
+
+  let config: Awaited<ReturnType<typeof loadConfig>>;
+  try {
+    config = await loadConfig(options.configPath);
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    return notOk(errorUnexpected(error instanceof Error ? error.message : String(error)));
+  }
+
+  const source = config.contract?.source;
+  if (source?.sourceFormat !== 'psl') {
+    return ok({ formatted: false });
+  }
+
+  const inputPath = source.inputs?.[0];
+  if (inputPath === undefined) {
+    return ok({ formatted: false });
+  }
+
+  let contents: string;
+  try {
+    contents = await readFile(inputPath, 'utf-8');
+  } catch (error) {
+    return notOk(
+      errorRuntime('Failed to read contract source file', {
+        why: error instanceof Error ? error.message : String(error),
+        fix: `Check that ${inputPath} exists and is readable.`,
+      }),
+    );
+  }
+
+  const formatOptions: FormatOptions = {
+    indent: config.formatter?.indent ?? 2,
+    newline: resolveNewline(config.formatter?.newline, eol),
+  };
+
+  let formatted: string;
+  try {
+    formatted = format(contents, formatOptions);
+  } catch (error) {
+    if (error instanceof PslFormatError) {
+      return notOk(
+        errorRuntime('Cannot format PSL with parse errors', {
+          why: error.message,
+          fix: 'Fix the parse errors in your schema and try again.',
+          meta: { diagnostics: error.diagnostics },
+        }),
+      );
+    }
+    return notOk(errorUnexpected(error instanceof Error ? error.message : String(error)));
+  }
+
+  try {
+    await writeFile(inputPath, formatted, 'utf-8');
+  } catch (error) {
+    return notOk(
+      errorRuntime('Failed to write formatted contract source file', {
+        why: error instanceof Error ? error.message : String(error),
+        fix: `Check that ${inputPath} is writable.`,
+      }),
+    );
+  }
+
+  return ok({ formatted: true, path: inputPath });
+}