codehooks-js 1.3.25 → 1.4.0

package/openapi/schema-converter.mjs

@@ -0,0 +1,668 @@
+/**
+ * Schema conversion utilities
+ * Converts Zod, Yup, and JSON-Schema to OpenAPI-compatible JSON Schema
+ */
+
+/**
+ * Detect the schema type
+ * @param {object} schema - The schema object
+ * @returns {'zod' | 'yup' | 'json-schema' | 'unknown'}
+ */
+export function detectSchemaType(schema) {
+  if (!schema || typeof schema !== 'object') {
+    return 'unknown';
+  }
+
+  // Zod detection - multiple checks for robustness
+  // Check 1: has .parse method and _def
+  if (typeof schema.parse === 'function' && schema._def) {
+    return 'zod';
+  }
+  // Check 2: has _def with typeName (Zod internal)
+  if (schema._def && typeof schema._def.typeName === 'string' && schema._def.typeName.startsWith('Zod')) {
+    return 'zod';
+  }
+  // Check 3: has .safeParse (Zod v3 method)
+  if (typeof schema.safeParse === 'function' && typeof schema.parse === 'function') {
+    return 'zod';
+  }
+
+  // Yup detection - has .validate method and .fields or __isYupSchema__
+  if (typeof schema.validate === 'function' && (schema.fields || schema.__isYupSchema__)) {
+    return 'yup';
+  }
+  // Yup also has .isValid and .cast
+  if (typeof schema.validate === 'function' && typeof schema.isValid === 'function' && typeof schema.cast === 'function') {
+    return 'yup';
+  }
+
+  // JSON-Schema detection - has type or properties at top level
+  if (schema.type || schema.properties || schema.$schema) {
+    return 'json-schema';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Convert any supported schema to JSON Schema
+ * @param {object} schema - Zod, Yup, or JSON-Schema object
+ * @param {string} [schemaType] - Override schema type detection
+ * @returns {Promise<object>} JSON Schema
+ */
+export async function convertToJsonSchema(schema, schemaType) {
+  const type = schemaType || detectSchemaType(schema);
+
+  try {
+    switch (type) {
+      case 'zod':
+        return await convertZodSchema(schema);
+      case 'yup':
+        return await convertYupSchema(schema);
+      case 'json-schema':
+        return cleanJsonSchema(schema);
+      default:
+        console.warn('[OpenAPI] Unknown schema type, using generic object schema');
+        return { type: 'object' };
+    }
+  } catch (error) {
+    console.warn('[OpenAPI] Schema conversion failed:', error.message);
+    return { type: 'object' };
+  }
+}
+
+/**
+ * Convert Zod schema to JSON Schema
+ * Uses built-in converter for serverless compatibility
+ * @param {object} zodSchema - Zod schema
+ * @returns {Promise<object>} JSON Schema
+ */
+async function convertZodSchema(zodSchema) {
+  return convertZodManually(zodSchema);
+}
+
+/**
+ * Infer Zod type from schema properties when typeName isn't reliable
+ * @param {object} schema - Zod schema
+ * @param {object} def - Schema _def
+ * @param {string} typeName - The typeName (may be empty/different after bundling)
+ * @returns {object|null} JSON Schema or null if can't infer
+ */
+function inferZodType(schema, def, typeName) {
+  // Check if typeName contains type hints (case insensitive)
+  const typeNameLower = (typeName || '').toLowerCase();
+
+  // Method-based detection (survives webpack bundling)
+  // ZodString has .email(), .url(), .uuid(), .trim() methods
+  // ZodNumber has .int(), .positive(), .negative(), .finite() methods
+  // ZodBoolean has no unique methods but we check for it
+  const hasStringMethods = typeof schema?.email === 'function' ||
+                           typeof schema?.url === 'function' ||
+                           typeof schema?.uuid === 'function' ||
+                           typeof schema?.trim === 'function' ||
+                           typeof schema?.toLowerCase === 'function';
+
+  const hasNumberMethods = typeof schema?.int === 'function' ||
+                           typeof schema?.positive === 'function' ||
+                           typeof schema?.negative === 'function' ||
+                           typeof schema?.finite === 'function' ||
+                           typeof schema?.multipleOf === 'function';
+
+  const hasArrayMethods = typeof schema?.element === 'function' ||
+                          typeof schema?.nonempty === 'function';
+
+  // Boolean detection: has no distinguishing methods, but check _def structure
+  // ZodBoolean has _def with typeName and optionally coerce, but no innerType/values/type/shape/schema
+  const looksLikeBoolean = typeof schema?.parse === 'function' &&
+                           !hasStringMethods &&
+                           !hasNumberMethods &&
+                           !hasArrayMethods &&
+                           !schema.shape &&
+                           !def?.innerType &&
+                           !def?.values &&
+                           !def?.type &&
+                           !def?.schema &&
+                           def?.typeName; // Has a typeName but nothing else distinctive
+
+  // String detection
+  if (typeNameLower.includes('string') || hasStringMethods) {
+    const result = { type: 'string' };
+    if (def.checks) {
+      for (const check of def.checks) {
+        // Support both old Zod (check.kind/check.value) and new Zod (check._zod.def)
+        const checkDef = check._zod?.def || check;
+        const kind = checkDef.check || checkDef.kind;
+        if (kind === 'email') result.format = 'email';
+        if (kind === 'url') result.format = 'uri';
+        if (kind === 'uuid') result.format = 'uuid';
+        if (kind === 'min' || kind === 'min_length') result.minLength = checkDef.minimum ?? checkDef.value;
+        if (kind === 'max' || kind === 'max_length') result.maxLength = checkDef.maximum ?? checkDef.value;
+      }
+    }
+    // Description can be on def or on schema object directly
+    if (def.description || schema.description) result.description = def.description || schema.description;
+    return result;
+  }
+
+  // Number/Integer detection
+  if (typeNameLower.includes('number') || typeNameLower.includes('int') || hasNumberMethods) {
+    const result = { type: 'number' };
+    if (def.checks) {
+      for (const check of def.checks) {
+        // Support both old Zod (check.kind/check.value) and new Zod (check._zod.def)
+        const checkDef = check._zod?.def || check;
+        const kind = checkDef.check || checkDef.kind;
+        if (kind === 'int') result.type = 'integer';
+        // Old Zod: min/max, New Zod: greater_than/less_than
+        if (kind === 'min' || kind === 'greater_than') result.minimum = checkDef.value ?? checkDef.minimum;
+        if (kind === 'max' || kind === 'less_than') result.maximum = checkDef.value ?? checkDef.maximum;
+      }
+    }
+    // Description can be on def or on schema object directly
+    if (def.description || schema.description) result.description = def.description || schema.description;
+    return result;
+  }
+
+  // Boolean detection
+  if (typeNameLower.includes('boolean') || typeNameLower.includes('bool') || looksLikeBoolean) {
+    const result = { type: 'boolean' };
+    if (def.description || schema.description) result.description = def.description || schema.description;
+    return result;
+  }
+
+  // Date detection
+  if (typeNameLower.includes('date')) {
+    return { type: 'string', format: 'date-time' };
+  }
+
+  // Array detection
+  if (typeNameLower.includes('array') || hasArrayMethods) {
+    // Support both old (def.type) and new (def.element) Zod structures
+    const elementSchema = def.element || (typeof def.type === 'object' ? def.type : null);
+    return {
+      type: 'array',
+      items: elementSchema ? convertZodManually(elementSchema) : {}
+    };
+  }
+
+  // Enum detection
+  if (typeNameLower.includes('enum') || (def.values && Array.isArray(def.values))) {
+    return { type: 'string', enum: def.values };
+  }
+
+  // Literal detection
+  if (typeNameLower.includes('literal') || (def.value !== undefined && !def.innerType)) {
+    const value = def.value;
+    return { type: typeof value, enum: [value] };
+  }
+
+  // Optional/Nullable detection
+  if (typeNameLower.includes('optional') || typeNameLower.includes('nullable')) {
+    if (def.innerType) {
+      return convertZodManually(def.innerType);
+    }
+  }
+
+  // Default detection - check for defaultValue property (more reliable than typeName)
+  if ((typeNameLower.includes('default') || def.defaultValue !== undefined) && def.innerType) {
+    const inner = convertZodManually(def.innerType);
+    try {
+      inner.default = typeof def.defaultValue === 'function' ? def.defaultValue() : def.defaultValue;
+    } catch (e) {
+      // Ignore
+    }
+    // Preserve description from outer schema
+    if (!inner.description && schema.description) {
+      inner.description = schema.description;
+    }
+    return inner;
+  }
+
+  // Effects detection (refine, transform)
+  if (typeNameLower.includes('effect') && def.schema) {
+    return convertZodManually(def.schema);
+  }
+
+  // If we have an innerType but couldn't match, try to unwrap it
+  if (def.innerType) {
+    return convertZodManually(def.innerType);
+  }
+
+  return null; // Couldn't infer, let the main function handle it
+}
+
+/**
+ * Manual Zod conversion (handles Zod v3.x)
+ * @param {object} zodSchema - Zod schema
+ * @returns {object} JSON Schema
+ */
+function convertZodManually(zodSchema) {
+  if (!zodSchema) return { type: 'object' };
+
+  // Try multiple approaches to get the shape (Zod v3 compatibility)
+  let shape = null;
+
+  // Approach 1: Direct .shape property (getter in Zod v3)
+  try {
+    if (zodSchema.shape && typeof zodSchema.shape === 'object') {
+      shape = zodSchema.shape;
+    }
+  } catch (e) {
+    // .shape getter might throw
+  }
+
+  // Approach 2: _def.shape (might be function or object)
+  if (!shape && zodSchema._def) {
+    try {
+      if (typeof zodSchema._def.shape === 'function') {
+        shape = zodSchema._def.shape();
+      } else if (zodSchema._def.shape && typeof zodSchema._def.shape === 'object') {
+        shape = zodSchema._def.shape;
+      }
+    } catch (e) {
+      // _def.shape() might throw
+    }
+  }
+
+  // Approach 3: Check if it's ZodObject and try _cached property
+  if (!shape && zodSchema._def?.typeName === 'ZodObject') {
+    try {
+      // Some Zod versions cache the shape
+      if (zodSchema._cached?.shape) {
+        shape = zodSchema._cached.shape;
+      }
+    } catch (e) {
+      // Ignore
+    }
+  }
+
+  // If we found a shape, convert it
+  if (shape && typeof shape === 'object' && Object.keys(shape).length > 0) {
+    const properties = {};
+    const required = [];
+
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+      if (fieldSchema) {
+        properties[key] = convertZodManually(fieldSchema);
+
+        // Check if optional (support both old and new Zod structures)
+        // Fields with defaults are also not required
+        const fieldDef = fieldSchema._def;
+        const fieldType = fieldDef?.typeName || fieldDef?.type || '';
+        const isOptional = fieldType === 'ZodOptional' || fieldType === 'optional' ||
+                          fieldType === 'ZodNullable' || fieldType === 'nullable' ||
+                          fieldType === 'ZodDefault' || fieldType === 'default';
+        if (!isOptional) {
+          required.push(key);
+        }
+      }
+    }
+
+    return {
+      type: 'object',
+      properties,
+      ...(required.length > 0 && { required })
+    };
+  }
+
+  const def = zodSchema._def;
+  if (!def) return { type: 'object' };
+
+  // Support both old Zod (typeName) and new Zod (type) structures
+  const typeName = def.typeName || def.type || '';
+
+  // Fallback type detection if typeName is missing or different
+  // Check for characteristic Zod properties
+  const inferredType = inferZodType(zodSchema, def, typeName);
+  if (inferredType) {
+    return inferredType;
+  }
+
+  // Handle string with refinements (like .email())
+  if (typeName === 'ZodString' || typeName === 'string') {
+    const result = { type: 'string' };
+    // Check for email, url, uuid checks
+    if (def.checks) {
+      for (const check of def.checks) {
+        // Support both old Zod (check.kind/check.value) and new Zod (check._zod.def)
+        const checkDef = check._zod?.def || check;
+        const kind = checkDef.check || checkDef.kind;
+        if (kind === 'email') result.format = 'email';
+        if (kind === 'url') result.format = 'uri';
+        if (kind === 'uuid') result.format = 'uuid';
+        if (kind === 'min' || kind === 'min_length') result.minLength = checkDef.minimum ?? checkDef.value;
+        if (kind === 'max' || kind === 'max_length') result.maxLength = checkDef.maximum ?? checkDef.value;
+      }
+    }
+    // Description can be on def or on schema object directly
+    if (def.description || zodSchema.description) result.description = def.description || zodSchema.description;
+    return result;
+  }
+
+  if (typeName === 'ZodNumber' || typeName === 'number') {
+    const result = { type: 'number' };
+    if (def.checks) {
+      for (const check of def.checks) {
+        // Support both old Zod (check.kind/check.value) and new Zod (check._zod.def)
+        const checkDef = check._zod?.def || check;
+        const kind = checkDef.check || checkDef.kind;
+        if (kind === 'int') result.type = 'integer';
+        // Old Zod: min/max, New Zod: greater_than/less_than
+        if (kind === 'min' || kind === 'greater_than') result.minimum = checkDef.value ?? checkDef.minimum;
+        if (kind === 'max' || kind === 'less_than') result.maximum = checkDef.value ?? checkDef.maximum;
+      }
+    }
+    // Description can be on def or on schema object directly
+    if (def.description || zodSchema.description) result.description = def.description || zodSchema.description;
+    return result;
+  }
+
+  if (typeName === 'ZodBoolean' || typeName === 'boolean') {
+    const result = { type: 'boolean' };
+    if (def.description || zodSchema.description) result.description = def.description || zodSchema.description;
+    return result;
+  }
+
+  if (typeName === 'ZodArray' || typeName === 'array') {
+    // Support both old (def.type) and new (def.element) Zod structures
+    const elementSchema = def.element || def.type;
+    return {
+      type: 'array',
+      items: elementSchema && typeof elementSchema === 'object' ? convertZodManually(elementSchema) : {}
+    };
+  }
+
+  // Fallback for ZodObject if .shape wasn't available earlier
+  if (typeName === 'ZodObject' || typeName === 'object') {
+    const properties = {};
+    const required = [];
+
+    // Try _def.shape as fallback
+    let shape = null;
+    if (def.shape) {
+      shape = typeof def.shape === 'function' ? def.shape() : def.shape;
+    }
+
+    if (shape && typeof shape === 'object') {
+      for (const [key, fieldSchema] of Object.entries(shape)) {
+        if (fieldSchema) {
+          properties[key] = convertZodManually(fieldSchema);
+          const fieldType = fieldSchema._def?.typeName || fieldSchema._def?.type || '';
+          const isOptional = fieldType === 'ZodOptional' || fieldType === 'optional' ||
+                            fieldType === 'ZodNullable' || fieldType === 'nullable' ||
+                            fieldType === 'ZodDefault' || fieldType === 'default';
+          if (!isOptional) {
+            required.push(key);
+          }
+        }
+      }
+    }
+
+    return {
+      type: 'object',
+      properties,
+      ...(required.length > 0 && { required })
+    };
+  }
+
+  if (typeName === 'ZodEnum' || typeName === 'enum') {
+    return { type: 'string', enum: def.values };
+  }
+
+  if (typeName === 'ZodLiteral' || typeName === 'literal') {
+    const value = def.value;
+    return { type: typeof value, enum: [value] };
+  }
+
+  if (typeName === 'ZodOptional' || typeName === 'optional' ||
+      typeName === 'ZodNullable' || typeName === 'nullable') {
+    return convertZodManually(def.innerType);
+  }
+
+  if (typeName === 'ZodDefault' || typeName === 'default') {
+    const inner = convertZodManually(def.innerType);
+    try {
+      inner.default = typeof def.defaultValue === 'function' ? def.defaultValue() : def.defaultValue;
+    } catch (e) {
+      // Ignore default value errors
+    }
+    // Preserve description from outer schema if inner doesn't have one
+    if (!inner.description && zodSchema.description) {
+      inner.description = zodSchema.description;
+    }
+    return inner;
+  }
+
+  if (typeName === 'ZodEffects' || typeName === 'effects') {
+    // .refine(), .transform(), etc - use inner schema
+    return convertZodManually(def.schema);
+  }
+
+  // Structural fallbacks when typeName is mangled/missing
+
+  // Default: has defaultValue and innerType
+  if (def.defaultValue !== undefined && def.innerType) {
+    const inner = convertZodManually(def.innerType);
+    try {
+      inner.default = typeof def.defaultValue === 'function' ? def.defaultValue() : def.defaultValue;
+    } catch (e) {
+      // Ignore
+    }
+    // Preserve description from outer schema
+    if (!inner.description && zodSchema.description) {
+      inner.description = zodSchema.description;
+    }
+    return inner;
+  }
+
+  // Optional/Nullable: has innerType but no defaultValue
+  if (def.innerType) {
+    return convertZodManually(def.innerType);
+  }
+
+  // Effects: has schema property
+  if (def.schema) {
+    return convertZodManually(def.schema);
+  }
+
+  // Boolean: simple schema with no distinctive properties
+  // (no innerType, no values, no type, no shape, no schema)
+  if (!def.innerType && !def.values && !def.type && !def.schema) {
+    // Could be boolean - check if coerce exists (Zod boolean feature)
+    // or if it's truly a simple primitive
+    if (def.coerce !== undefined || Object.keys(def).length <= 3) {
+      return { type: 'boolean' };
+    }
+  }
+
+  // Fallback
+  return { type: 'object' };
+}
+
+/**
+ * Convert Yup schema to JSON Schema
+ * Uses built-in converter for serverless compatibility
+ * @param {object} yupSchema - Yup schema
+ * @returns {Promise<object>} JSON Schema
+ */
+async function convertYupSchema(yupSchema) {
+  return convertYupManually(yupSchema);
+}
+
+/**
+ * Manual Yup conversion fallback using .describe()
+ * @param {object} yupSchema - Yup schema
+ * @returns {object} JSON Schema
+ */
+function convertYupManually(yupSchema) {
+  if (!yupSchema.describe) {
+    return { type: 'object' };
+  }
+
+  const desc = yupSchema.describe();
+  return yupDescToJsonSchema(desc);
+}
+
+/**
+ * Convert Yup describe() output to JSON Schema
+ * @param {object} desc - Yup description object
+ * @returns {object} JSON Schema
+ */
+function yupDescToJsonSchema(desc) {
+  const schema = {};
+
+  switch (desc.type) {
+    case 'string':
+      schema.type = 'string';
+      // Extract string constraints from tests
+      if (desc.tests) {
+        for (const test of desc.tests) {
+          if (test.name === 'min' && test.params?.min !== undefined) {
+            schema.minLength = test.params.min;
+          }
+          if (test.name === 'max' && test.params?.max !== undefined) {
+            schema.maxLength = test.params.max;
+          }
+          if (test.name === 'email') {
+            schema.format = 'email';
+          }
+          if (test.name === 'url') {
+            schema.format = 'uri';
+          }
+          if (test.name === 'uuid') {
+            schema.format = 'uuid';
+          }
+        }
+      }
+      break;
+    case 'number':
+      schema.type = 'number';
+      // Extract number constraints from tests
+      if (desc.tests) {
+        for (const test of desc.tests) {
+          if (test.name === 'min' && test.params?.min !== undefined) {
+            schema.minimum = test.params.min;
+          }
+          if (test.name === 'max' && test.params?.max !== undefined) {
+            schema.maximum = test.params.max;
+          }
+          if (test.name === 'integer') {
+            schema.type = 'integer';
+          }
+        }
+      }
+      break;
+    case 'boolean':
+      schema.type = 'boolean';
+      break;
+    case 'date':
+      schema.type = 'string';
+      schema.format = 'date-time';
+      break;
+    case 'array':
+      schema.type = 'array';
+      if (desc.innerType) {
+        schema.items = yupDescToJsonSchema(desc.innerType);
+      }
+      // Extract array constraints from tests
+      if (desc.tests) {
+        for (const test of desc.tests) {
+          if (test.name === 'min' && test.params?.min !== undefined) {
+            schema.minItems = test.params.min;
+          }
+          if (test.name === 'max' && test.params?.max !== undefined) {
+            schema.maxItems = test.params.max;
+          }
+        }
+      }
+      break;
+    case 'object':
+      schema.type = 'object';
+      if (desc.fields) {
+        schema.properties = {};
+        const required = [];
+        for (const [key, fieldDesc] of Object.entries(desc.fields)) {
+          schema.properties[key] = yupDescToJsonSchema(fieldDesc);
+          if (!fieldDesc.optional && !fieldDesc.nullable) {
+            required.push(key);
+          }
+        }
+        if (required.length > 0) {
+          schema.required = required;
+        }
+      }
+      break;
+    default:
+      schema.type = 'object';
+  }
+
+  // Add metadata
+  if (desc.label) {
+    schema.title = desc.label;
+  }
+  if (desc.meta?.description) {
+    schema.description = desc.meta.description;
+  }
+  if (desc.default !== undefined) {
+    schema.default = desc.default;
+  }
+  if (desc.oneOf && desc.oneOf.length > 0) {
+    schema.enum = desc.oneOf;
+  }
+
+  return schema;
+}
+
+/**
+ * Clean JSON Schema for OpenAPI compatibility
+ * @param {object} schema - JSON Schema
+ * @returns {object} Cleaned schema
+ */
+function cleanJsonSchema(schema) {
+  if (!schema || typeof schema !== 'object') {
+    return schema;
+  }
+
+  const cleaned = { ...schema };
+
+  // Remove $schema as it's not needed in OpenAPI components
+  delete cleaned.$schema;
+
+  // Remove $id if present
+  delete cleaned.$id;
+
+  // Recursively clean nested schemas
+  if (cleaned.properties) {
+    cleaned.properties = {};
+    for (const [key, value] of Object.entries(schema.properties)) {
+      cleaned.properties[key] = cleanJsonSchema(value);
+    }
+  }
+
+  if (cleaned.items) {
+    cleaned.items = cleanJsonSchema(schema.items);
+  }
+
+  if (cleaned.additionalProperties && typeof cleaned.additionalProperties === 'object') {
+    cleaned.additionalProperties = cleanJsonSchema(schema.additionalProperties);
+  }
+
+  return cleaned;
+}
+
+/**
+ * Convert multiple schemas (collection map)
+ * @param {object} schemas - Map of collection name to schema
+ * @returns {Promise<object>} Map of collection name to JSON Schema
+ */
+export async function convertSchemas(schemas) {
+  const result = {};
+
+  for (const [name, schema] of Object.entries(schemas)) {
+    if (schema) {
+      result[name] = await convertToJsonSchema(schema);
+    }
+  }
+
+  return result;
+}