@prisma-next/cli 0.5.0-dev.9 → 0.6.0-dev.1

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

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { emit, getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { createControlStack } from '@prisma-next/framework-components/control';
@@ -7,57 +7,156 @@ import { ifDefined } from '@prisma-next/utils/defined';
 import { dirname } from 'pathe';
 import { loadConfig } from '../../config-loader';
 import { errorContractConfigMissing, errorRuntime } from '../../utils/cli-errors';
+import { queueEmitByOutput } from '../../utils/emit-queue';
 import { assertFrameworkComponentsCompatible } from '../../utils/framework-components';
+import { publishContractArtifactPair } from '../../utils/publish-contract-artifact-pair';
+import { validateContractDeps } from '../../utils/validate-contract-deps';
 import { enrichContract } from '../contract-enrichment';
-import type { ContractEmitOptions, ContractEmitResult } from '../types';
+import type {
+  ContractEmitOptions,
+  ContractEmitResult,
+  ControlActionName,
+  OnControlProgress,
+} from '../types';
 
-interface ProviderFailureLike {
-  readonly summary: string;
-  readonly diagnostics: readonly unknown[];
-  readonly meta?: unknown;
-}
+const EMIT_ACTION: ControlActionName = 'emit';
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-function isAbortError(error: unknown): boolean {
-  return isRecord(error) && typeof error['name'] === 'string' && error['name'] === 'AbortError';
+function startSpan(onProgress: OnControlProgress | undefined, spanId: string, label: string): void {
+  onProgress?.({ action: EMIT_ACTION, kind: 'spanStart', spanId, label });
+}
+
+function endSpan(
+  onProgress: OnControlProgress | undefined,
+  spanId: string,
+  outcome: 'ok' | 'error',
+): void {
+  onProgress?.({ action: EMIT_ACTION, kind: 'spanEnd', spanId, outcome });
+}
+
+function failedToResolveContractSource(why: string, fix: string, meta?: Record<string, unknown>) {
+  return errorRuntime('Failed to resolve contract source', {
+    why,
+    fix,
+    ...ifDefined('meta', meta),
+  });
+}
+
+type ValidatedProviderResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly error: ReturnType<typeof errorRuntime> };
+
+function diagnosticLocationSuffix(diagnostic: Record<string, unknown>): string {
+  const sourceId = typeof diagnostic['sourceId'] === 'string' ? diagnostic['sourceId'] : undefined;
+  const span = isRecord(diagnostic['span']) ? diagnostic['span'] : undefined;
+  const start = span && isRecord(span['start']) ? span['start'] : undefined;
+  const line = start && typeof start['line'] === 'number' ? start['line'] : undefined;
+  const column = start && typeof start['column'] === 'number' ? start['column'] : undefined;
+  if (sourceId && line !== undefined && column !== undefined) {
+    return ` (${sourceId}:${line}:${column})`;
+  }
+  if (sourceId) {
+    return ` (${sourceId})`;
+  }
+  return '';
 }
 
-function isProviderFailureLike(value: unknown): value is ProviderFailureLike {
-  return (
-    isRecord(value) && typeof value['summary'] === 'string' && Array.isArray(value['diagnostics'])
-  );
+function mapDiagnosticsToIssues(
+  diagnostics: readonly unknown[],
+): ReadonlyArray<{ readonly kind: string; readonly message: string }> {
+  const issues: { readonly kind: string; readonly message: string }[] = [];
+  for (const raw of diagnostics) {
+    if (!isRecord(raw)) continue;
+    const code = typeof raw['code'] === 'string' ? raw['code'] : 'diagnostic';
+    const message = typeof raw['message'] === 'string' ? raw['message'] : '';
+    issues.push({ kind: code, message: `${message}${diagnosticLocationSuffix(raw)}` });
+  }
+  return issues;
+}
+
+function validateProviderResult(providerResult: unknown): ValidatedProviderResult {
+  if (!isRecord(providerResult) || typeof providerResult['ok'] !== 'boolean') {
+    return {
+      ok: false,
+      error: failedToResolveContractSource(
+        'Contract source provider returned malformed result shape.',
+        'Ensure contract.source.load resolves to ok(Contract) or notOk({ summary, diagnostics }).',
+      ),
+    };
+  }
+
+  if (providerResult['ok']) {
+    if (!('value' in providerResult)) {
+      return {
+        ok: false,
+        error: failedToResolveContractSource(
+          'Contract source provider returned malformed success result: missing value.',
+          'Ensure contract.source.load success payload is ok(Contract).',
+        ),
+      };
+    }
+    return { ok: true, value: providerResult['value'] };
+  }
+
+  const failure = providerResult['failure'];
+  if (
+    !isRecord(failure) ||
+    typeof failure['summary'] !== 'string' ||
+    !Array.isArray(failure['diagnostics'])
+  ) {
+    return {
+      ok: false,
+      error: failedToResolveContractSource(
+        'Contract source provider returned malformed failure result: expected summary and diagnostics.',
+        'Ensure contract.source.load failure payload is notOk({ summary, diagnostics, meta? }).',
+      ),
+    };
+  }
+  return {
+    ok: false,
+    error: failedToResolveContractSource(
+      String(failure['summary']),
+      'Fix contract source diagnostics and return ok(Contract).',
+      {
+        diagnostics: failure['diagnostics'],
+        issues: mapDiagnosticsToIssues(failure['diagnostics']),
+        ...ifDefined('providerMeta', failure['meta']),
+      },
+    ),
+  };
 }
 
 /**
- * Executes the contract emit operation.
+ * Canonical contract emit operation.
  *
- * This is an offline operation that:
- * 1. Loads the Prisma Next config from the specified path
- * 2. Resolves the contract source from config
- * 3. Creates a control plane stack and family instance
- * 4. Emits contract artifacts (JSON and DTS)
- * 5. Writes files to the paths specified in config
+ * This is the SINGLE publication path used by both the CLI command
+ * (`prisma-next contract emit`) and the Vite plugin
+ * (`@prisma-next/vite-plugin-contract-emit`). New callers must go through this
+ * function rather than re-implementing load → emit → publish.
  *
- * Supports AbortSignal for cancellation, enabling "last change wins" behavior.
+ * The whole flow (load config → resolve source → emit bytes → atomic publish)
+ * is serialized per output JSON path via `queueEmitByOutput`. Concurrent calls
+ * for the same output line up FIFO; the user-visible outcome is "last
+ * submission wins on disk" without any supersession bookkeeping. Within a
+ * single emit, `publishContractArtifactPair` stages temp files, renames
+ * `contract.d.ts` before `contract.json`, and attempts to restore the previous
+ * pair if either rename fails — so type-only consumers never observe a
+ * mismatched pair.
  *
- * @param options - Options including configPath and optional signal
- * @returns File paths and hashes of emitted artifacts
- * @throws If config loading fails, contract is invalid, or file I/O fails
- * @throws signal.reason if cancelled via AbortSignal (typically DOMException with name 'AbortError')
+ * @throws {CliStructuredError} on config/source/validation problems
+ * @throws {DOMException} `AbortError` if cancelled via `signal`
  */
 export async function executeContractEmit(
   options: ContractEmitOptions,
 ): Promise<ContractEmitResult> {
-  const { configPath, signal = new AbortController().signal } = options;
+  const { configPath, signal = new AbortController().signal, onProgress } = options;
   const unlessAborted = abortable(signal);
 
-  // Load config using the existing config loader
   const config = await unlessAborted(loadConfig(configPath));
 
-  // Validate contract config is present
   if (!config.contract) {
     throw errorContractConfigMissing({
       why: 'Config.contract is required for emit. Define it in your config: contract: { source: ..., output: ... }',
@@ -66,14 +165,12 @@ export async function executeContractEmit(
 
   const contractConfig = config.contract;
 
-  // Validate output path is present and ends with .json
   if (!contractConfig.output) {
     throw errorContractConfigMissing({
       why: 'Contract config must have output path. This should not happen if defineConfig() was used.',
     });
   }
 
-  // Validate source exists and is callable
   if (typeof contractConfig.source?.load !== 'function') {
     throw errorContractConfigMissing({
       why: 'Contract config must include a valid source provider object',
@@ -90,98 +187,84 @@ export async function executeContractEmit(
   }
   const { jsonPath: outputJsonPath, dtsPath: outputDtsPath } = outputPaths;
 
-  const stack = createControlStack(config);
+  return queueEmitByOutput(outputJsonPath, async () => {
+    const stack = createControlStack(config);
 
-  const sourceContext = {
-    composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
-    scalarTypeDescriptors: stack.scalarTypeDescriptors,
-    authoringContributions: stack.authoringContributions,
-    codecLookup: stack.codecLookup,
-    controlMutationDefaults: stack.controlMutationDefaults,
-    resolvedInputs: contractConfig.source.inputs ?? [],
-  };
+    const sourceContext = {
+      composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
+      scalarTypeDescriptors: stack.scalarTypeDescriptors,
+      authoringContributions: stack.authoringContributions,
+      codecLookup: stack.codecLookup,
+      controlMutationDefaults: stack.controlMutationDefaults,
+      resolvedInputs: contractConfig.source.inputs ?? [],
+    };
 
-  let providerResult: Awaited<ReturnType<typeof contractConfig.source.load>>;
-  try {
-    providerResult = await unlessAborted(contractConfig.source.load(sourceContext));
-  } catch (error) {
-    if (signal.aborted || isAbortError(error)) {
-      throw error;
+    startSpan(onProgress, 'resolveSource', 'Resolving contract source...');
+    let providerResult: Awaited<ReturnType<typeof contractConfig.source.load>>;
+    try {
+      providerResult = await unlessAborted(contractConfig.source.load(sourceContext));
+    } catch (error) {
+      endSpan(onProgress, 'resolveSource', 'error');
+      if (signal.aborted || (isRecord(error) && error['name'] === 'AbortError')) {
+        throw error;
+      }
+      throw failedToResolveContractSource(
+        error instanceof Error ? error.message : String(error),
+        'Ensure contract.source.load resolves to ok(Contract) or returns structured diagnostics.',
+      );
     }
-    throw errorRuntime('Failed to resolve contract source', {
-      why: error instanceof Error ? error.message : String(error),
-      fix: 'Ensure contract.source.load resolves to ok(Contract) or returns structured diagnostics.',
-    });
-  }
 
-  if (!isRecord(providerResult) || typeof providerResult.ok !== 'boolean') {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed result shape.',
-      fix: 'Ensure contract.source.load resolves to ok(Contract) or notOk({ summary, diagnostics }).',
-    });
-  }
-
-  if (providerResult.ok && !('value' in providerResult)) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed success result: missing value.',
-      fix: 'Ensure contract.source.load success payload is ok(Contract).',
-    });
-  }
+    const validatedContract = validateProviderResult(providerResult);
+    if (!validatedContract.ok) {
+      endSpan(onProgress, 'resolveSource', 'error');
+      throw validatedContract.error;
+    }
+    endSpan(onProgress, 'resolveSource', 'ok');
 
-  if (!providerResult.ok && !isProviderFailureLike(providerResult.failure)) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed failure result: expected summary and diagnostics.',
-      fix: 'Ensure contract.source.load failure payload is notOk({ summary, diagnostics, meta? }).',
-    });
-  }
+    startSpan(onProgress, 'emit', 'Emitting contract...');
+    let emitResult: Awaited<ReturnType<typeof emit>>;
+    try {
+      const familyInstance = config.family.create(stack);
+      const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+      const frameworkComponents = assertFrameworkComponentsCompatible(
+        config.family.familyId,
+        config.target.targetId,
+        rawComponents,
+      );
+      const enrichedIR = enrichContract(validatedContract.value as Contract, frameworkComponents);
+      familyInstance.validateContract(enrichedIR);
+      emitResult = await unlessAborted(
+        emit(enrichedIR, stack, config.family.emission, { outputJsonPath }),
+      );
+    } catch (error) {
+      endSpan(onProgress, 'emit', 'error');
+      throw error;
+    }
+    endSpan(onProgress, 'emit', 'ok');
 
-  if (!providerResult.ok) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: providerResult.failure.summary,
-      fix: 'Fix contract source diagnostics and return ok(Contract).',
-      meta: {
-        diagnostics: providerResult.failure.diagnostics,
-        ...ifDefined('providerMeta', providerResult.failure.meta),
-      },
+    await unlessAborted(mkdir(dirname(outputJsonPath), { recursive: true }));
+    await publishContractArtifactPair({
+      outputJsonPath,
+      outputDtsPath,
+      contractJson: emitResult.contractJson,
+      contractDts: emitResult.contractDts,
+      publicationToken: String(process.hrtime.bigint()),
     });
-  }
 
-  const familyInstance = config.family.create(stack);
-
-  const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
-  const frameworkComponents = assertFrameworkComponentsCompatible(
-    config.family.familyId,
-    config.target.targetId,
-    rawComponents,
-  );
-  const enrichedIR = enrichContract(providerResult.value as Contract, frameworkComponents);
-
-  familyInstance.validateContract(enrichedIR);
-  const emitResult = await unlessAborted(
-    emit(enrichedIR, stack, config.family.emission, {
-      outputJsonPath: outputJsonPath,
-    }),
-  );
-
-  // Create directory if needed and write files (both colocated)
-  await unlessAborted(mkdir(dirname(outputJsonPath), { recursive: true }));
-  await unlessAborted(writeFile(outputJsonPath, emitResult.contractJson, 'utf-8'));
-  await unlessAborted(writeFile(outputDtsPath, emitResult.contractDts, 'utf-8'));
-
-  // Validate that contract.d.ts type imports are resolvable
-  const { validateContractDeps } = await import('../../utils/validate-contract-deps');
-  const depsValidation = validateContractDeps(emitResult.contractDts, dirname(outputDtsPath));
-  if (depsValidation.warning) {
-    process.stderr.write(`\n⚠ ${depsValidation.warning}\n`);
-  }
+    const validationWarning = validateContractDeps(
+      emitResult.contractDts,
+      dirname(outputDtsPath),
+    ).warning;
 
-  return {
-    storageHash: emitResult.storageHash,
-    ...ifDefined('executionHash', emitResult.executionHash),
-    profileHash: emitResult.profileHash,
-    files: {
-      json: outputJsonPath,
-      dts: outputDtsPath,
-    },
-  };
+    return {
+      storageHash: emitResult.storageHash,
+      ...ifDefined('executionHash', emitResult.executionHash),
+      profileHash: emitResult.profileHash,
+      files: {
+        json: outputJsonPath,
+        dts: outputDtsPath,
+      },
+      ...ifDefined('validationWarning', validationWarning),
+    };
+  });
 }