@rawan-temo/prisma-zod-generator 3.3.1-config-coercion.0

package/src/config/typed-json.ts

@@ -0,0 +1,219 @@
+/**
+ * `typedJson`: reading prisma-json-types-generator's annotations.
+ *
+ * PJTG annotates a column with `/// [TypeName]` or `/// ![<ts type>]` and types the
+ * generated Prisma Client from it. It validates nothing at runtime. PZG validates at
+ * runtime but has never seen those annotations, because `detectZodAnnotations` matches
+ * only `/@zod\s*\./i`. Users therefore maintain the same shape twice, which is the drift
+ * issue #386 actually reported.
+ *
+ * This module owns the configuration half of the fix: the shape of the `typedJson`
+ * block, its defaults, and the rule that turns a `[TypeName]` into a schema expression.
+ * It deliberately contains no emission logic, so both the CRUD path and the pure-model
+ * path can resolve a type name the same way.
+ *
+ * The contract that outranks the feature: **when `typedJson` is absent, this module
+ * answers `null`**, not "enabled with defaults". Nothing downstream may switch on, so
+ * output stays byte-identical to 3.0.0.
+ */
+
+/** Suffix appended to a `[TypeName]` to find its schema. `[Foo]` -> `FooSchema`. */
+export const DEFAULT_TYPED_JSON_SCHEMA_SUFFIX = 'Schema';
+
+/** Global namespace the emitted declarations live in. Matches PJTG's own default. */
+export const DEFAULT_TYPED_JSON_NAMESPACE = 'PrismaJson';
+
+/** Where the `declare global` file goes, relative to the generator output directory. */
+export const DEFAULT_TYPED_JSON_NAMESPACE_OUTPUT = './prisma-json-types.d.ts';
+
+/** A TypeScript identifier, which is all a type name or a namespace name may be. */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * User-facing `typedJson` configuration block.
+ *
+ * Named `typedJson` deliberately, not `jsonTypes`: `jsonSchemaCompatible` and
+ * `jsonSchemaOptions` already exist here and concern JSON Schema as an *output format*,
+ * an unrelated feature.
+ */
+export interface TypedJsonConfig {
+  /**
+   * Module that `[TypeName]` resolves from. With `schemaModule: './json-types'`,
+   * `/// [WorkflowNode]` uses `WorkflowNodeSchema` imported from there.
+   *
+   * A relative specifier is relative to the generator output directory, and is rewritten
+   * per emitted file so it resolves from wherever that file sits. A bare or scoped
+   * package specifier is used verbatim.
+   */
+  schemaModule?: string;
+
+  /** Suffix appended to the annotation's type name. Default: `Schema`. May be empty. */
+  schemaSuffix?: string;
+
+  /** Namespace the emitted `declare global` block declares. Default: `PrismaJson`. */
+  namespace?: string;
+
+  /**
+   * Apply the annotation to `schemas/results/*` as well. **Default: false.**
+   *
+   * Off by default deliberately, and the reasoning is the point rather than the setting.
+   * Without it PZG is self-inconsistent: the same field with the same annotation is
+   * `z.enum(['A','B'])` in `WorkflowCreateInput` and `z.string()` in
+   * `WorkflowFindManyResult`. That is a defect on its own terms.
+   *
+   * It is still not worth defaulting to true, because result schemas are emitted by
+   * default - thirteen per model, with no `emit` config at all. So typing them by default
+   * would not be a quiet nicety for people who opted into result validation; it would
+   * change the READ path for everyone who turns `typedJson` on. A row written before the
+   * annotation existed then throws on read, which is a production incident in someone
+   * else's data, triggered by adding a comment to a schema.
+   *
+   * Weigh the two failure modes rather than the two principles. Default true breaks
+   * reads of existing rows. Default false leaves the result schema disagreeing with the
+   * input schema until the user opts in: confusing, documented, breaks nothing. The
+   * second is the lesser harm and the only one that cannot page someone at night.
+   */
+  applyToResults?: boolean;
+
+  /** Emit the `declare global` namespace file. Default: false. */
+  emitNamespace?: boolean;
+
+  /**
+   * Path of the emitted namespace file, relative to the generator output directory.
+   * Default: `./prisma-json-types.d.ts`.
+   */
+  namespaceOutput?: string;
+
+  /**
+   * Explicit `TypeName` -> Zod expression overrides, checked before `schemaModule`.
+   * The escape hatch for anything the convention cannot express.
+   */
+  map?: Record<string, string>;
+}
+
+/** `TypedJsonConfig` with every default filled in. */
+export interface ResolvedTypedJsonConfig {
+  schemaModule: string | undefined;
+  schemaSuffix: string;
+  namespace: string;
+  applyToResults: boolean;
+  emitNamespace: boolean;
+  namespaceOutput: string;
+  map: Record<string, string>;
+}
+
+/**
+ * How a `[TypeName]` resolved.
+ *
+ * `unresolved` is a first-class outcome, not an error: a schema annotated for PJTG alone
+ * must keep generating unchanged when PZG is not configured for it. Callers leave the
+ * field exactly as it is today and record the reason.
+ */
+export type TypedJsonTypeResolution =
+  | { kind: 'mapped'; expression: string }
+  | { kind: 'module'; importName: string; module: string; expression: string }
+  | { kind: 'unresolved'; reason: string };
+
+/**
+ * Fill in the defaults for a configured `typedJson` block, or answer `null` when the key
+ * is absent. `null` means "behave exactly as 3.0.0 did".
+ */
+export function resolveTypedJsonConfig(
+  config: { typedJson?: TypedJsonConfig } | null | undefined,
+): ResolvedTypedJsonConfig | null {
+  const typedJson = config?.typedJson;
+  if (!typedJson || typeof typedJson !== 'object') {
+    return null;
+  }
+
+  return {
+    schemaModule:
+      typeof typedJson.schemaModule === 'string' && typedJson.schemaModule.trim().length > 0
+        ? typedJson.schemaModule.trim()
+        : undefined,
+    // `??`, not `||`: an explicitly empty suffix means `[Foo]` -> `Foo`, which is a
+    // legitimate convention and is not the same thing as leaving the key unset.
+    schemaSuffix: typedJson.schemaSuffix ?? DEFAULT_TYPED_JSON_SCHEMA_SUFFIX,
+    namespace: typedJson.namespace || DEFAULT_TYPED_JSON_NAMESPACE,
+    // `=== true`, so anything short of an explicit opt-in leaves the read path alone.
+    applyToResults: typedJson.applyToResults === true,
+    emitNamespace: typedJson.emitNamespace === true,
+    namespaceOutput: typedJson.namespaceOutput || DEFAULT_TYPED_JSON_NAMESPACE_OUTPUT,
+    map: { ...(typedJson.map ?? {}) },
+  };
+}
+
+/**
+ * Resolve one `[TypeName]` to a Zod expression, by the order in the design:
+ *
+ * 1. `typedJson.map[TypeName]`, an exact expression.
+ * 2. `<TypeName><schemaSuffix>` imported from `typedJson.schemaModule`.
+ * 3. Neither: unresolved, with a reason worth putting in a warning.
+ *
+ * Accepts a raw `typedJson` block as well as a resolved one, and normalises before
+ * reading anything. Not politeness: a raw block has no `schemaSuffix`, and reading it
+ * unnormalised composes the import name `FooSchema` as `Fooundefined` - an identifier
+ * that looks plausible in the emitted file, is missing from the user's module, and only
+ * fails when *they* build. `resolveTypedJsonConfig` is idempotent, so normalising an
+ * already-resolved config is free.
+ */
+export function resolveTypedJsonType(
+  typeName: string,
+  config: ResolvedTypedJsonConfig | TypedJsonConfig,
+): TypedJsonTypeResolution {
+  const name = typeName?.trim() ?? '';
+
+  if (!IDENTIFIER.test(name)) {
+    return {
+      kind: 'unresolved',
+      reason: `"${typeName}" is not a TypeScript identifier, so it cannot name a schema`,
+    };
+  }
+
+  const settings = resolveTypedJsonConfig({ typedJson: config ?? {} }) ?? {
+    schemaModule: undefined,
+    schemaSuffix: DEFAULT_TYPED_JSON_SCHEMA_SUFFIX,
+    namespace: DEFAULT_TYPED_JSON_NAMESPACE,
+    applyToResults: false,
+    emitNamespace: false,
+    namespaceOutput: DEFAULT_TYPED_JSON_NAMESPACE_OUTPUT,
+    map: {},
+  };
+
+  const mapped = settings.map[name];
+  if (typeof mapped === 'string' && mapped.trim().length > 0) {
+    return { kind: 'mapped', expression: mapped.trim() };
+  }
+
+  if (settings.schemaModule) {
+    const importName = `${name}${settings.schemaSuffix}`;
+    return {
+      kind: 'module',
+      importName,
+      module: settings.schemaModule,
+      expression: importName,
+    };
+  }
+
+  return {
+    kind: 'unresolved',
+    reason:
+      `no typedJson.schemaModule is configured and typedJson.map has no entry for "${name}", ` +
+      `so there is nothing to resolve it to`,
+  };
+}
+
+/** Whether two resolutions name the same schema, for conflict detection. */
+export function sameTypedJsonResolution(
+  a: TypedJsonTypeResolution,
+  b: TypedJsonTypeResolution,
+): boolean {
+  if (a.kind !== b.kind) return false;
+  if (a.kind === 'module' && b.kind === 'module') {
+    return a.importName === b.importName && a.module === b.module;
+  }
+  if (a.kind === 'mapped' && b.kind === 'mapped') {
+    return a.expression === b.expression;
+  }
+  return true;
+}

package/src/config/validator.ts

@@ -0,0 +1,469 @@
+import Ajv, { JSONSchemaType, ValidateFunction, ErrorObject } from 'ajv';
+import addFormats from 'ajv-formats';
+import {
+  ConfigurationSchema,
+  ValidationError,
+  ValidationErrorType,
+  isValidOperation,
+  isValidVariant,
+  PRISMA_OPERATIONS,
+  SCHEMA_VARIANTS,
+  DEFAULT_CONFIG,
+} from './schema';
+import { GeneratorConfig } from './parser';
+
+/**
+ * The built-in pure/input/result variants, or undefined when the caller used the array
+ * form of custom variants. `variants` accepts both, and the pure/input/result keys only
+ * exist on the object form.
+ */
+function builtInVariants(
+  config: GeneratorConfig,
+): Exclude<GeneratorConfig['variants'], unknown[]> | undefined {
+  return Array.isArray(config.variants) ? undefined : config.variants;
+}
+
+/**
+ * Configuration validation result
+ */
+export interface ValidationResult {
+  /** Whether the configuration is valid */
+  valid: boolean;
+
+  /** Array of validation errors (empty if valid) */
+  errors: ValidationError[];
+
+  /** The validated configuration (potentially with defaults applied) */
+  config?: GeneratorConfig;
+
+  /** Warnings that don't prevent usage but should be noted */
+  warnings: string[];
+}
+
+/**
+ * Validation context for cross-field validation
+ */
+interface ValidationContext {
+  config: GeneratorConfig;
+  errors: ValidationError[];
+  warnings: string[];
+  modelNames?: string[];
+}
+
+/**
+ * Configuration validator class
+ */
+export class ConfigurationValidator {
+  private readonly ajv: Ajv;
+  private readonly validateConfig: ValidateFunction<GeneratorConfig>;
+
+  constructor() {
+    // Initialize AJV with strict mode and additional formats
+    this.ajv = new Ajv({
+      strict: true,
+      allErrors: true,
+      verbose: true,
+      discriminator: true,
+      removeAdditional: false,
+    });
+
+    // Add format validation (email, uri, etc.)
+    addFormats(this.ajv);
+
+    // Compile the configuration schema
+    this.validateConfig = this.ajv.compile(ConfigurationSchema as JSONSchemaType<GeneratorConfig>);
+  }
+
+  /**
+   * Validate a configuration object
+   */
+  public validate(config: unknown, modelNames?: string[]): ValidationResult {
+    const result: ValidationResult = {
+      valid: false,
+      errors: [],
+      warnings: [],
+    };
+
+    // First, validate against JSON Schema
+    const schemaValid = this.validateConfig(config);
+
+    if (!schemaValid && this.validateConfig.errors) {
+      result.errors.push(...this.convertAjvErrors(this.validateConfig.errors));
+    }
+
+    // If basic schema validation fails, return early
+    if (!schemaValid) {
+      return result;
+    }
+
+    // Cast to GeneratorConfig for further validation
+    const typedConfig = config as GeneratorConfig;
+
+    // Create validation context
+    const context: ValidationContext = {
+      config: typedConfig,
+      errors: [...result.errors],
+      warnings: [...result.warnings],
+      modelNames,
+    };
+
+    // Perform cross-field and business logic validation
+    this.validateCrossFieldConstraints(context);
+    this.validateModelReferences(context);
+    this.validateVariantConsistency(context);
+    this.validateOperationConsistency(context);
+
+    // Update result
+    result.errors = context.errors;
+    result.warnings = context.warnings;
+    result.valid = result.errors.length === 0;
+
+    if (result.valid) {
+      result.config = this.applyDefaults(typedConfig);
+    }
+
+    return result;
+  }
+
+  /**
+   * Validate configuration with Prisma model names
+   */
+  public validateWithModels(config: unknown, modelNames: string[]): ValidationResult {
+    return this.validate(config, modelNames);
+  }
+
+  /**
+   * Convert AJV validation errors to our error format
+   */
+  private convertAjvErrors(ajvErrors: ErrorObject[]): ValidationError[] {
+    return ajvErrors.map((error) => this.convertSingleAjvError(error));
+  }
+
+  /**
+   * Convert a single AJV error to our error format
+   */
+  private convertSingleAjvError(error: ErrorObject): ValidationError {
+    const path = error.instancePath || 'root';
+
+    switch (error.keyword) {
+      case 'enum':
+        return {
+          type: ValidationErrorType.INVALID_JSON_SCHEMA,
+          message: `Invalid value at ${path}. Expected one of: ${error.schema}`,
+          path,
+          value: error.data,
+          allowedValues: Array.isArray(error.schema) ? error.schema : [error.schema],
+        };
+
+      case 'pattern':
+        return {
+          type: ValidationErrorType.INVALID_JSON_SCHEMA,
+          message: `Invalid format at ${path}. ${this.getPatternErrorMessage(path, error.schema as string)}`,
+          path,
+          value: error.data,
+        };
+
+      case 'required':
+        return {
+          type: ValidationErrorType.MISSING_REQUIRED,
+          message: `Missing required property: ${error.params?.missingProperty}`,
+          path: `${path}/${error.params?.missingProperty}`,
+          value: error.data,
+        };
+
+      case 'additionalProperties':
+        return {
+          type: ValidationErrorType.INVALID_JSON_SCHEMA,
+          message: `Unknown property: ${error.params?.additionalProperty}`,
+          path: `${path}/${error.params?.additionalProperty}`,
+          value: error.data,
+        };
+
+      default:
+        return {
+          type: ValidationErrorType.INVALID_JSON_SCHEMA,
+          message: error.message || 'Unknown validation error',
+          path,
+          value: error.data,
+        };
+    }
+  }
+
+  /**
+   * Get human-readable error message for pattern validation failures
+   */
+  private getPatternErrorMessage(_path: string, pattern: string): string {
+    if (pattern === '^[a-zA-Z_][a-zA-Z0-9_]*$') {
+      return 'Must be a valid identifier (letters, numbers, underscores, cannot start with number)';
+    }
+
+    if (pattern === '^[A-Z][a-zA-Z0-9_]*$') {
+      return 'Must be a valid model name (PascalCase, letters, numbers, underscores)';
+    }
+
+    if (pattern === '^\\.[a-zA-Z][a-zA-Z0-9_]*$') {
+      return 'Must be a valid file suffix (start with dot, followed by identifier)';
+    }
+
+    if (pattern === '^[^<>:"|?*\\x00-\\x1f]+$') {
+      return 'Must be a valid file path (no invalid characters)';
+    }
+
+    return `Must match pattern: ${pattern}`;
+  }
+
+  /**
+   * Validate cross-field constraints
+   */
+  private validateCrossFieldConstraints(context: ValidationContext): void {
+    const { config } = context;
+
+    // Validate mode-specific constraints
+    if (config.mode === 'minimal') {
+      // In minimal mode, certain configurations don't make sense
+      const builtIn = Array.isArray(config.variants) ? undefined : config.variants;
+      if (builtIn?.result?.enabled) {
+        context.warnings.push('Result variants are not typically used in minimal mode');
+      }
+
+      if (config.models && Object.keys(config.models).length > 0) {
+        // Check if any model has non-minimal operations
+        Object.entries(config.models).forEach(([modelName, modelConfig]) => {
+          if (modelConfig.operations) {
+            const nonMinimalOps = modelConfig.operations.filter(
+              (op) =>
+                !['findMany', 'findUnique', 'create', 'update', 'delete', 'upsert'].includes(op),
+            );
+            if (nonMinimalOps.length > 0) {
+              context.warnings.push(
+                `Model ${modelName} has non-minimal operations in minimal mode: ${nonMinimalOps.join(', ')}`,
+              );
+            }
+          }
+        });
+      }
+    }
+
+    // Validate variant suffix uniqueness
+    if (config.variants) {
+      const suffixes = new Set<string>();
+      // Deliberately over both forms: for the array of custom variants, Object.entries
+      // yields index keys and each element carries `suffix`, so duplicates are caught there
+      // too (the reported path is then variants.0.suffix).
+      const variantEntries = Object.entries(config.variants) as Array<
+        [string, { suffix?: string } | undefined]
+      >;
+      variantEntries.forEach(([variantName, variantConfig]) => {
+        if (variantConfig?.suffix) {
+          if (suffixes.has(variantConfig.suffix)) {
+            context.errors.push({
+              type: ValidationErrorType.DUPLICATE_VALUES,
+              message: `Duplicate suffix "${variantConfig.suffix}" found in variants`,
+              path: `variants.${variantName}.suffix`,
+              value: variantConfig.suffix,
+            });
+          }
+          suffixes.add(variantConfig.suffix);
+        }
+      });
+    }
+  }
+
+  /**
+   * Validate model references against actual Prisma models
+   */
+  private validateModelReferences(context: ValidationContext): void {
+    const { config, modelNames } = context;
+
+    if (!modelNames || !config.models) {
+      return;
+    }
+
+    // Check if configured models exist in Prisma schema
+    Object.keys(config.models).forEach((configuredModel) => {
+      if (!modelNames.includes(configuredModel)) {
+        context.errors.push({
+          type: ValidationErrorType.INVALID_MODEL_NAME,
+          message: `Model "${configuredModel}" not found in Prisma schema`,
+          path: `models.${configuredModel}`,
+          value: configuredModel,
+          allowedValues: modelNames,
+        });
+      }
+    });
+
+    // Warn about Prisma models not explicitly configured
+    const unconfiguredModels = modelNames.filter(
+      (modelName) => !config.models || !config.models[modelName],
+    );
+
+    if (unconfiguredModels.length > 0 && config.mode === 'custom') {
+      context.warnings.push(
+        `The following models are not configured and will use defaults: ${unconfiguredModels.join(', ')}`,
+      );
+    }
+  }
+
+  /**
+   * Validate variant consistency
+   */
+  private validateVariantConsistency(context: ValidationContext): void {
+    const { config } = context;
+
+    if (!config.variants && !config.models) {
+      return;
+    }
+
+    // Check for variant-specific field exclusions that reference non-existent variants
+    if (config.models) {
+      Object.entries(config.models).forEach(([modelName, modelConfig]) => {
+        if (modelConfig.variants) {
+          Object.keys(modelConfig.variants).forEach((variantName) => {
+            if (!isValidVariant(variantName)) {
+              context.errors.push({
+                type: ValidationErrorType.INVALID_VARIANT,
+                message: `Invalid variant name "${variantName}" in model ${modelName}`,
+                path: `models.${modelName}.variants.${variantName}`,
+                value: variantName,
+                allowedValues: [...SCHEMA_VARIANTS],
+              });
+            }
+          });
+        }
+      });
+    }
+  }
+
+  /**
+   * Validate operation consistency
+   */
+  private validateOperationConsistency(context: ValidationContext): void {
+    const { config } = context;
+
+    if (!config.models) {
+      return;
+    }
+
+    Object.entries(config.models).forEach(([modelName, modelConfig]) => {
+      if (modelConfig.operations) {
+        // Check for invalid operations
+        modelConfig.operations.forEach((operation) => {
+          if (!isValidOperation(operation)) {
+            context.errors.push({
+              type: ValidationErrorType.INVALID_OPERATION,
+              message: `Invalid operation "${operation}" for model ${modelName}`,
+              path: `models.${modelName}.operations`,
+              value: operation,
+              allowedValues: [...PRISMA_OPERATIONS],
+            });
+          }
+        });
+
+        // Check for duplicate operations
+        const uniqueOperations = new Set(modelConfig.operations);
+        if (uniqueOperations.size !== modelConfig.operations.length) {
+          context.errors.push({
+            type: ValidationErrorType.DUPLICATE_VALUES,
+            message: `Duplicate operations found for model ${modelName}`,
+            path: `models.${modelName}.operations`,
+            value: modelConfig.operations,
+          });
+        }
+      }
+    });
+  }
+
+  /**
+   * Apply default values to configuration
+   */
+  private applyDefaults(config: GeneratorConfig): GeneratorConfig {
+    return {
+      mode: config.mode || DEFAULT_CONFIG.mode,
+      output: config.output || DEFAULT_CONFIG.output,
+      globalExclusions: config.globalExclusions || DEFAULT_CONFIG.globalExclusions,
+      variants: {
+        pure: {
+          enabled: builtInVariants(config)?.pure?.enabled ?? DEFAULT_CONFIG.variants.pure.enabled,
+          suffix: builtInVariants(config)?.pure?.suffix || DEFAULT_CONFIG.variants.pure.suffix,
+          excludeFields: builtInVariants(config)?.pure?.excludeFields || [],
+        },
+        input: {
+          enabled: builtInVariants(config)?.input?.enabled ?? DEFAULT_CONFIG.variants.input.enabled,
+          suffix: builtInVariants(config)?.input?.suffix || DEFAULT_CONFIG.variants.input.suffix,
+          excludeFields: builtInVariants(config)?.input?.excludeFields || [],
+        },
+        result: {
+          enabled:
+            builtInVariants(config)?.result?.enabled ?? DEFAULT_CONFIG.variants.result.enabled,
+          suffix: builtInVariants(config)?.result?.suffix || DEFAULT_CONFIG.variants.result.suffix,
+          excludeFields: builtInVariants(config)?.result?.excludeFields || [],
+        },
+      },
+      models: config.models || DEFAULT_CONFIG.models,
+    };
+  }
+}
+
+/**
+ * Convenience function to validate configuration
+ */
+export function validateConfiguration(config: unknown, modelNames?: string[]): ValidationResult {
+  const validator = new ConfigurationValidator();
+  return validator.validate(config, modelNames);
+}
+
+/**
+ * Convenience function to validate configuration with model names
+ */
+export function validateConfigurationWithModels(
+  config: unknown,
+  modelNames: string[],
+): ValidationResult {
+  const validator = new ConfigurationValidator();
+  return validator.validateWithModels(config, modelNames);
+}
+
+/**
+ * Create human-readable validation error message
+ */
+export function formatValidationErrors(errors: ValidationError[]): string {
+  if (errors.length === 0) {
+    return 'No validation errors';
+  }
+
+  let message = `Configuration validation failed with ${errors.length} error(s):\n\n`;
+
+  errors.forEach((error, index) => {
+    message += `${index + 1}. ${error.message}\n`;
+    message += `   Path: ${error.path}\n`;
+
+    if (error.value !== undefined) {
+      message += `   Value: ${JSON.stringify(error.value)}\n`;
+    }
+
+    if (error.allowedValues && error.allowedValues.length > 0) {
+      message += `   Allowed values: ${error.allowedValues.join(', ')}\n`;
+    }
+
+    message += '\n';
+  });
+
+  return message.trim();
+}
+
+/**
+ * Create human-readable validation warnings message
+ */
+export function formatValidationWarnings(warnings: string[]): string {
+  if (warnings.length === 0) {
+    return '';
+  }
+
+  let message = `Configuration warnings (${warnings.length}):\n\n`;
+
+  warnings.forEach((warning, index) => {
+    message += `${index + 1}. ${warning}\n`;
+  });
+
+  return message.trim();
+}