@pikku/openapi-parser 0.12.9 → 0.12.10

package/src/openapi-to-zod-schema.ts

@@ -16,8 +16,8 @@ export interface OpenAPISchema {
   default?: unknown
   minimum?: number
   maximum?: number
-  exclusiveMinimum?: number
-  exclusiveMaximum?: number
+  exclusiveMinimum?: number | boolean
+  exclusiveMaximum?: number | boolean
   minLength?: number
   maxLength?: number
   pattern?: string
@@ -40,18 +40,42 @@ export interface ZodCodegenContext {
   usedRefs: Set<string>
   /** Indent level for readability */
   indent: number
+  /** Track schemas currently being processed to detect cycles */
+  seen: Set<OpenAPISchema>
+  /**
+   * Map from resolved schema object identity to its component name.
+   * After $ref resolution, many references lose their $ref string and
+   * become the same JS object as the component schema. This map lets
+   * schemaToZod detect those resolved references by identity.
+   */
+  schemaIdentityMap: Map<object, string>
+  /** Current nesting depth for preventing excessively deep types */
+  depth: number
+  /** When true, convert snake_case property keys to camelCase in z.object() */
+  camelCase?: boolean
 }
 
 export function createContext(
-  schemaRefs?: Map<string, string>
+  schemaRefs?: Map<string, string>,
+  schemaIdentityMap?: Map<object, string>,
+  opts?: { camelCase?: boolean }
 ): ZodCodegenContext {
   return {
     schemaRefs: schemaRefs ?? new Map(),
     usedRefs: new Set(),
     indent: 0,
+    seen: new Set(),
+    schemaIdentityMap: schemaIdentityMap ?? new Map(),
+    depth: 0,
+    camelCase: opts?.camelCase,
   }
 }
 
+/** Convert a snake_case or kebab-case string to camelCase */
+export function snakeToCamel(s: string): string {
+  return s.replace(/[-_]+(.)/g, (_, c) => c.toUpperCase())
+}
+
 /**
  * Convert a single OpenAPI schema to a Zod expression string.
  * Does NOT include .optional() — that's handled at the property level based on `required`.
@@ -61,6 +85,17 @@ export function schemaToZod(
   ctx: ZodCodegenContext,
   opts: { optional?: boolean } = {}
 ): string {
+  // Bug 5: Depth limit to prevent TS2589 "excessively deep" type errors
+  if (ctx.depth > 10) {
+    let code = 'z.any()'
+    if (schema.nullable) code += '.nullable()'
+    if (opts.optional) code += '.optional()'
+    if (schema.description) {
+      const safeDesc = schema.description.replace(/\*\//g, '* /')
+      code += `.describe(${JSON.stringify(safeDesc)})`
+    }
+    return code
+  }
   let code = schemaToZodBase(schema, ctx)
 
   // Refinements
@@ -76,14 +111,84 @@ export function schemaToZod(
     code += '.optional()'
   }
 
-  // Default
+  // Default — validate type compatibility and coerce mismatches
   if (schema.default !== undefined) {
-    code += `.default(${JSON.stringify(schema.default)})`
+    let defaultValue = schema.default
+    if (schema.enum && schema.enum.length > 0) {
+      // For enum schemas, the default must exactly match one of the enum values.
+      // Don't apply type coercion — the Zod schema uses the original enum types
+      // (e.g. z.literal(1) not z.literal("1")), so coercing would cause TS2769.
+      const enumValues = new Set(
+        schema.enum.map((v: unknown) => JSON.stringify(v))
+      )
+      if (enumValues.has(JSON.stringify(defaultValue))) {
+        code += `.default(${JSON.stringify(defaultValue)})`
+      }
+      // else: default not in enum — skip it entirely
+    } else if (defaultValue === null && !schema.nullable) {
+      // skip null defaults unless nullable
+    } else if (schema.type === 'object' && typeof defaultValue === 'string') {
+      // skip string defaults on object types (often a stray description)
+    } else if (
+      schema.properties &&
+      typeof defaultValue === 'object' &&
+      defaultValue !== null &&
+      !Array.isArray(defaultValue)
+    ) {
+      // For object schemas with properties, validate default keys match schema properties.
+      // Extra keys in the default cause TS2769 because z.object() rejects unknown keys.
+      const schemaKeys = new Set(Object.keys(schema.properties))
+      const defaultKeys = Object.keys(defaultValue as Record<string, unknown>)
+      const hasExtraKeys = defaultKeys.some((k) => !schemaKeys.has(k))
+      if (!hasExtraKeys) {
+        code += `.default(${JSON.stringify(defaultValue)})`
+      }
+      // else: default has keys not in schema — skip it
+    } else if (
+      schema.type === 'string' &&
+      typeof defaultValue === 'object' &&
+      defaultValue !== null
+    ) {
+      // skip object/array defaults on string types
+    } else if (
+      (!schema.type || schema.type === 'object') &&
+      schema.properties &&
+      typeof defaultValue === 'string'
+    ) {
+      // skip string defaults on implicit object types (has properties but no explicit type)
+    } else if (schema.type === 'array' && !Array.isArray(defaultValue)) {
+      // skip type-mismatched defaults (non-array default on array type)
+    } else if (schema.type !== 'array' && Array.isArray(defaultValue)) {
+      // skip array defaults on non-array types
+    } else if (schema.type === 'boolean' && typeof defaultValue === 'string') {
+      defaultValue = defaultValue === 'true'
+      code += `.default(${JSON.stringify(defaultValue)})`
+    } else if (
+      (schema.type === 'number' || schema.type === 'integer') &&
+      typeof defaultValue === 'string'
+    ) {
+      const parsed = Number(defaultValue)
+      if (!isNaN(parsed)) code += `.default(${JSON.stringify(parsed)})`
+    } else if (schema.type === 'string' && typeof defaultValue === 'number') {
+      code += `.default(${JSON.stringify(String(defaultValue))})`
+    } else if (schema.type === 'string' && typeof defaultValue === 'boolean') {
+      code += `.default(${JSON.stringify(String(defaultValue))})`
+    } else if (schema.type === 'boolean' && typeof defaultValue !== 'boolean') {
+      code += `.default(${defaultValue === 'true' || defaultValue === 1})`
+    } else if (
+      (schema.type === 'number' || schema.type === 'integer') &&
+      typeof defaultValue === 'boolean'
+    ) {
+      code += `.default(${defaultValue ? 1 : 0})`
+    } else {
+      code += `.default(${JSON.stringify(defaultValue)})`
+    }
   }
 
-  // Description
+  // Description — sanitize */ to prevent breaking JSDoc comments downstream
   if (schema.description) {
-    code += `.describe(${JSON.stringify(schema.description)})`
+    const safeDesc = schema.description.replace(/\*\//g, '* /')
+    code += `.describe(${JSON.stringify(safeDesc)})`
   }
 
   return code
@@ -93,7 +198,25 @@ function schemaToZodBase(
   schema: OpenAPISchema,
   ctx: ZodCodegenContext
 ): string {
-  // Handle $ref
+  // Cycle detection: if we've already started processing this exact schema
+  // object, return z.any() to break infinite recursion
+  if (ctx.seen.has(schema)) {
+    return 'z.any()'
+  }
+  ctx.seen.add(schema)
+
+  try {
+    return schemaToZodBaseInner(schema, ctx)
+  } finally {
+    ctx.seen.delete(schema)
+  }
+}
+
+function schemaToZodBaseInner(
+  schema: OpenAPISchema,
+  ctx: ZodCodegenContext
+): string {
+  // Handle $ref (surviving after resolution)
   if (schema.$ref) {
     const refName = schema.$ref.split('/').pop()!
     const zodName = ctx.schemaRefs.get(refName)
@@ -105,6 +228,19 @@ function schemaToZodBase(
     return 'z.unknown()'
   }
 
+  // Handle resolved $ref by object identity: if this schema object IS a
+  // known component schema, reference the variable instead of inlining.
+  if (ctx.schemaIdentityMap.size > 0) {
+    const identityName = ctx.schemaIdentityMap.get(schema as object)
+    if (identityName) {
+      const zodName = ctx.schemaRefs.get(identityName)
+      if (zodName) {
+        ctx.usedRefs.add(identityName)
+        return zodName
+      }
+    }
+  }
+
   // Handle allOf — merge into single object
   if (schema.allOf && schema.allOf.length > 0) {
     return handleAllOf(schema.allOf, ctx)
@@ -142,6 +278,15 @@ function schemaToZodBase(
       if (schema.properties) {
         return handleObject(schema, ctx)
       }
+      // Bug 4: Infer number type when minimum/maximum present but no type
+      if (
+        schema.minimum !== undefined ||
+        schema.maximum !== undefined ||
+        schema.exclusiveMinimum !== undefined ||
+        schema.exclusiveMaximum !== undefined
+      ) {
+        return 'z.number()'
+      }
       return 'z.unknown()'
   }
 }
@@ -165,25 +310,31 @@ function handleString(schema: OpenAPISchema): string {
 }
 
 function handleEnum(values: unknown[]): string {
-  // Single value — use z.literal
-  if (values.length === 1) {
-    return `z.literal(${JSON.stringify(values[0])})`
+  const primitives = values.filter(
+    (v) =>
+      v === null ||
+      typeof v === 'string' ||
+      typeof v === 'number' ||
+      typeof v === 'boolean'
+  )
+  if (primitives.length === 0) return 'z.unknown()'
+  if (primitives.length === 1) {
+    return `z.literal(${JSON.stringify(primitives[0])})`
   }
-  // If all values are strings, use z.enum
-  if (values.every((v) => typeof v === 'string')) {
-    const enumValues = values.map((v) => JSON.stringify(v)).join(', ')
+  if (primitives.every((v) => typeof v === 'string')) {
+    const enumValues = primitives.map((v) => JSON.stringify(v)).join(', ')
     return `z.enum([${enumValues}])`
   }
-  // Mixed types — use z.union of z.literal
-  const literals = values
+  const literals = primitives
     .map((v) => `z.literal(${JSON.stringify(v)})`)
     .join(', ')
   return `z.union([${literals}])`
 }
 
 function handleArray(schema: OpenAPISchema, ctx: ZodCodegenContext): string {
+  const innerCtx = { ...ctx, depth: ctx.depth + 1 }
   const itemsZod = schema.items
-    ? schemaToZodBase(schema.items, ctx)
+    ? schemaToZodBase(schema.items, innerCtx)
     : 'z.unknown()'
   return `z.array(${itemsZod})`
 }
@@ -205,7 +356,11 @@ function handleObject(schema: OpenAPISchema, ctx: ZodCodegenContext): string {
     return 'z.record(z.string(), z.unknown())'
   }
 
-  const inner: ZodCodegenContext = { ...ctx, indent: ctx.indent + 1 }
+  const inner: ZodCodegenContext = {
+    ...ctx,
+    indent: ctx.indent + 1,
+    depth: ctx.depth + 1,
+  }
   const pad = indent(inner)
   const closePad = indent(ctx)
   const requiredSet = new Set(schema.required ?? [])
@@ -214,25 +369,38 @@ function handleObject(schema: OpenAPISchema, ctx: ZodCodegenContext): string {
   for (const [key, propSchema] of Object.entries(schema.properties)) {
     const isOptional = !requiredSet.has(key)
     const propZod = schemaToZod(propSchema, inner, { optional: isOptional })
-    entries.push(`${pad}${safeKey(key)}: ${propZod},`)
+    const outputKey = ctx.camelCase ? snakeToCamel(key) : key
+    entries.push(`${pad}${safeKey(outputKey)}: ${propZod},`)
   }
 
   return `z.object({\n${entries.join('\n')}\n${closePad}})`
 }
 
 function handleAllOf(schemas: OpenAPISchema[], ctx: ZodCodegenContext): string {
+  // Helper to check if a sub-schema is a reference (by $ref or identity map)
+  function getRefName(sub: OpenAPISchema): string | undefined {
+    if (sub.$ref) {
+      return sub.$ref.split('/').pop()!
+    }
+    if (ctx.schemaIdentityMap.size > 0) {
+      const identityName = ctx.schemaIdentityMap.get(sub as object)
+      if (identityName && ctx.schemaRefs.has(identityName)) {
+        return identityName
+      }
+    }
+    return undefined
+  }
+
   // Collect all properties from all schemas
   const mergedProps: Record<string, OpenAPISchema> = {}
   const mergedRequired: string[] = []
 
   for (const sub of schemas) {
-    if (sub.$ref) {
-      const refName = sub.$ref.split('/').pop()!
+    const refName = getRefName(sub)
+    if (refName) {
       const zodName = ctx.schemaRefs.get(refName)
       if (zodName) {
         ctx.usedRefs.add(refName)
-        // If it's a pure ref in an allOf, we'd need to merge/extend
-        // For simplicity, if we have refs mixed with objects, use .merge()
       }
     }
     if (sub.properties) {
@@ -244,14 +412,14 @@ function handleAllOf(schemas: OpenAPISchema[], ctx: ZodCodegenContext): string {
   }
 
   // If we have only refs, use .merge()
-  const refSchemas = schemas.filter((s) => s.$ref)
+  const refSchemas = schemas.filter((s) => getRefName(s) !== undefined)
   const objSchemas = schemas.filter(
-    (s) => !s.$ref && (s.properties || s.type === 'object')
+    (s) => getRefName(s) === undefined && (s.properties || s.type === 'object')
   )
 
   if (refSchemas.length > 0 && objSchemas.length === 0) {
     const parts = refSchemas.map((s) => {
-      const refName = s.$ref!.split('/').pop()!
+      const refName = getRefName(s)!
       ctx.usedRefs.add(refName)
       return ctx.schemaRefs.get(refName) || 'z.object({})'
     })
@@ -282,10 +450,26 @@ function handleUnion(schemas: OpenAPISchema[], ctx: ZodCodegenContext): string {
 }
 
 function applyRefinements(code: string, schema: OpenAPISchema): string {
+  // Don't apply refinements to types that don't support .min()/.max()/.regex() etc.
+  // This includes z.any(), z.unknown(), z.union(...), z.literal(...), z.enum(...),
+  // z.lazy(...), z.record(...), and schema references (variable names without z. prefix).
+  if (
+    code === 'z.any()' ||
+    code === 'z.unknown()' ||
+    code.startsWith('z.union(') ||
+    code.startsWith('z.literal(') ||
+    code.startsWith('z.enum(') ||
+    code.startsWith('z.lazy(') ||
+    code.startsWith('z.record(') ||
+    // Schema variable references (e.g. FooSchema) — no z. prefix
+    (!code.startsWith('z.') && /^[a-zA-Z_$]/.test(code))
+  ) {
+    return code
+  }
   let result = code
 
-  // String refinements
-  if (schema.type === 'string' || (!schema.type && !schema.format)) {
+  // String refinements — only apply to explicit string types
+  if (schema.type === 'string' && !schema.enum) {
     if (schema.minLength !== undefined) {
       result += `.min(${schema.minLength})`
     }
@@ -297,18 +481,37 @@ function applyRefinements(code: string, schema: OpenAPISchema): string {
     }
   }
 
-  // Number refinements
-  if (schema.type === 'number' || schema.type === 'integer') {
+  // Number refinements — also apply when no type but min/max present (inferred number)
+  const isNumberType =
+    schema.type === 'number' ||
+    schema.type === 'integer' ||
+    (!schema.type &&
+      !schema.properties &&
+      (schema.minimum !== undefined ||
+        schema.maximum !== undefined ||
+        schema.exclusiveMinimum !== undefined ||
+        schema.exclusiveMaximum !== undefined))
+  if (isNumberType && !schema.enum) {
+    const exMinIsBoolean = typeof schema.exclusiveMinimum === 'boolean'
+    const exMaxIsBoolean = typeof schema.exclusiveMaximum === 'boolean'
     if (schema.minimum !== undefined) {
-      result += `.min(${schema.minimum})`
+      if (exMinIsBoolean && schema.exclusiveMinimum) {
+        result += `.gt(${schema.minimum})`
+      } else {
+        result += `.min(${schema.minimum})`
+      }
     }
     if (schema.maximum !== undefined) {
-      result += `.max(${schema.maximum})`
+      if (exMaxIsBoolean && schema.exclusiveMaximum) {
+        result += `.lt(${schema.maximum})`
+      } else {
+        result += `.max(${schema.maximum})`
+      }
     }
-    if (schema.exclusiveMinimum !== undefined) {
+    if (!exMinIsBoolean && schema.exclusiveMinimum !== undefined) {
       result += `.gt(${schema.exclusiveMinimum})`
     }
-    if (schema.exclusiveMaximum !== undefined) {
+    if (!exMaxIsBoolean && schema.exclusiveMaximum !== undefined) {
       result += `.lt(${schema.exclusiveMaximum})`
     }
   }
@@ -338,8 +541,40 @@ function safeKey(key: string): string {
  * Generate the Zod variable name for a component schema.
  * e.g. "PaginatedResponse" → "PaginatedResponseSchema"
  */
+const RESERVED_TYPE_NAMES = new Set([
+  'object',
+  'string',
+  'number',
+  'boolean',
+  'symbol',
+  'undefined',
+  'null',
+  'void',
+  'never',
+  'any',
+  'unknown',
+  'bigint',
+  'function',
+  'class',
+  'enum',
+  'interface',
+  'type',
+  'import',
+  'export',
+])
+
 export function sanitizeTypeName(name: string): string {
-  return name.replace(/[^a-zA-Z0-9_$]/g, '')
+  // Strip numeric separator patterns (e.g. 1_000 → 1000)
+  let cleaned = name.replace(/(\d)_(\d)/g, '$1$2')
+  cleaned = cleaned.replace(/[^a-zA-Z0-9_$]/g, '')
+  // Prefix with 'n' if starts with a digit
+  if (/^[0-9]/.test(cleaned)) {
+    cleaned = 'n' + cleaned
+  }
+  if (RESERVED_TYPE_NAMES.has(cleaned.toLowerCase())) {
+    return `${cleaned}Type`
+  }
+  return cleaned
 }
 
 export function schemaVarName(name: string): string {

package/src/parse-openapi.ts

@@ -169,13 +169,17 @@ export async function parseOpenAPISpec(filePath: string): Promise<ParsedSpec> {
   }
 }
 
-/** Recursively resolve $ref pointers in-place */
-function resolveRefs(node: any, root: any): any {
+/** Recursively resolve $ref pointers in-place, with cycle detection */
+function resolveRefs(node: any, root: any, visited?: Set<any>): any {
   if (node === null || typeof node !== 'object') return node
 
+  const seen = visited ?? new Set<any>()
+  if (seen.has(node)) return node
+  seen.add(node)
+
   if (Array.isArray(node)) {
     for (let i = 0; i < node.length; i++) {
-      node[i] = resolveRefs(node[i], root)
+      node[i] = resolveRefs(node[i], root, seen)
     }
     return node
   }
@@ -186,14 +190,15 @@ function resolveRefs(node: any, root: any): any {
       // Merge any sibling properties (like description overrides)
       const { $ref, ...siblings } = node
       const result = { ...resolved, ...siblings }
-      // Don't recurse infinitely — mark as resolved
+      // Don't recurse into the merged result — it shares structure with
+      // the original resolved object and may be circular
       return result
     }
     return node
   }
 
   for (const key of Object.keys(node)) {
-    node[key] = resolveRefs(node[key], root)
+    node[key] = resolveRefs(node[key], root, seen)
   }
 
   return node
@@ -435,10 +440,18 @@ export function computeContractHash(spec: ParsedSpec): string {
     serverUrls: spec.serverUrls,
   }
 
-  return createHash('sha256')
-    .update(JSON.stringify(contract))
-    .digest('hex')
-    .slice(0, 16)
+  // Use a cycle-safe JSON serializer since resolved $ref schemas
+  // can contain circular object references
+  const seen = new WeakSet()
+  const json = JSON.stringify(contract, (_key, value) => {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) return '[Circular]'
+      seen.add(value)
+    }
+    return value
+  })
+
+  return createHash('sha256').update(json).digest('hex').slice(0, 16)
 }
 
 function extractTagDescriptions(doc: any): Record<string, string> {

package/src/zod-codegen.ts

@@ -5,4 +5,5 @@ export {
   schemaToZod,
   schemaVarName,
   sanitizeTypeName,
+  snakeToCamel,
 } from './openapi-to-zod-schema.js'