@pikku/openapi-parser 0.12.3 → 0.12.5

package/src/index.ts

@@ -0,0 +1,28 @@
+export {
+  parseOpenAPISpec,
+  computeContractHash,
+  type ParsedSpec,
+  type ParsedOperation,
+  type ParsedParam,
+  type ErrorResponse,
+  type SecuritySchemeInfo,
+} from './parse-openapi.js'
+
+export {
+  generateAddonFromOpenAPI,
+} from './codegen.js'
+
+export {
+  generateOperationNames,
+  detectCommonPrefix,
+  type NamedOperation,
+} from './naming.js'
+
+export {
+  type OpenAPISchema,
+  type ZodCodegenContext,
+  createContext,
+  schemaToZod,
+  schemaVarName,
+  sanitizeTypeName,
+} from './openapi-to-zod-schema.js'

package/src/naming.ts

@@ -0,0 +1,214 @@
+/**
+ * Derives function/method names from HTTP method + path.
+ * Uses operationId when available, otherwise generates from path segments.
+ */
+
+const IRREGULAR_PLURALS: Record<string, string> = {
+  addresses: 'address',
+  statuses: 'status',
+  indices: 'index',
+  analyses: 'analysis',
+  quizzes: 'quiz',
+  matrices: 'matrix',
+  vertices: 'vertex',
+  aliases: 'alias',
+  buses: 'bus',
+}
+
+export function singularize(word: string): string {
+  const lower = word.toLowerCase()
+  if (IRREGULAR_PLURALS[lower]) {
+    const singular = IRREGULAR_PLURALS[lower]
+    return word[0] === word[0].toUpperCase()
+      ? singular.charAt(0).toUpperCase() + singular.slice(1)
+      : singular
+  }
+  if (lower.endsWith('ies') && lower.length > 4) {
+    return word.slice(0, -3) + 'y'
+  }
+  // -shes, -ches, -xes, -zes, -sses → drop "es"
+  if (lower.endsWith('shes') || lower.endsWith('ches') || lower.endsWith('xes') || lower.endsWith('zes') || lower.endsWith('sses')) {
+    return word.slice(0, -2)
+  }
+  // General: drop trailing "s" (covers courses→course, products→product, etc.)
+  if (lower.endsWith('s') && !lower.endsWith('ss') && !lower.endsWith('us') && lower.length > 2) {
+    return word.slice(0, -1)
+  }
+  return word
+}
+
+export function toCamelCase(str: string): string {
+  return str
+    .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^[A-Z]/, (c) => c.toLowerCase())
+}
+
+export function toPascalCase(str: string): string {
+  const camel = toCamelCase(str)
+  return camel.charAt(0).toUpperCase() + camel.slice(1)
+}
+
+/**
+ * Strip common API prefix from paths (e.g. /api/v2/).
+ * Uses majority voting — a prefix shared by >75% of paths is stripped,
+ * so a few outlier paths (e.g. /oauth/...) don't break detection.
+ */
+export function detectCommonPrefix(paths: string[]): string {
+  if (paths.length === 0) return ''
+
+  const segments = paths.map((p) => p.replace(/^\//, '').split('/'))
+  const threshold = Math.ceil(paths.length * 0.75)
+
+  // Find the longest prefix shared by at least `threshold` paths
+  let prefixLen = 0
+  for (let i = 0; i < 10; i++) {
+    // Count how many paths have the same segment at position i as the first path
+    const candidateSeg = segments[0][i]
+    if (!candidateSeg || candidateSeg.startsWith('{')) break
+
+    const count = segments.filter(
+      (s) => s.length > i + 1 && s[i] === candidateSeg
+    ).length
+
+    if (count >= threshold) {
+      prefixLen = i + 1
+    } else {
+      break
+    }
+  }
+
+  if (prefixLen === 0) return ''
+  return '/' + segments[0].slice(0, prefixLen).join('/') + '/'
+}
+
+/** Convert operationId to camelCase function name */
+function fromOperationId(operationId: string): string {
+  // operationId might be snake_case, camelCase, PascalCase, or kebab-case
+  return toCamelCase(
+    operationId
+      .replace(/[^a-zA-Z0-9_-]/g, '_')
+      .replace(/_+/g, '_')
+      .replace(/^_|_$/g, '')
+  )
+}
+
+const METHOD_PREFIXES: Record<string, string> = {
+  get: 'get',
+  post: 'create',
+  put: 'update',
+  patch: 'update',
+  delete: 'delete',
+}
+
+interface OperationForNaming {
+  method: string
+  path: string
+  operationId?: string
+}
+
+export interface NamedOperation {
+  method: string
+  path: string
+  functionName: string
+  methodName: string
+}
+
+/**
+ * Generate function names for a list of operations.
+ * Handles collision detection and auto-deduplication.
+ */
+export function generateOperationNames(
+  operations: OperationForNaming[],
+  commonPrefix: string
+): NamedOperation[] {
+  const results: NamedOperation[] = []
+  const usedNames = new Map<string, number>()
+
+  for (const op of operations) {
+    let name: string
+
+    if (op.operationId) {
+      name = fromOperationId(op.operationId)
+    } else {
+      name = deriveNameFromPath(op.method, op.path, commonPrefix)
+    }
+
+    // Handle collisions
+    const existing = usedNames.get(name) ?? 0
+    if (existing > 0) {
+      usedNames.set(name, existing + 1)
+      name = `${name}${existing + 1}`
+    }
+    usedNames.set(name, (usedNames.get(name) ?? 0) || 1)
+
+    results.push({
+      method: op.method,
+      path: op.path,
+      functionName: name,
+      methodName: name,
+    })
+  }
+
+  return results
+}
+
+function deriveNameFromPath(
+  method: string,
+  path: string,
+  commonPrefix: string
+): string {
+  // Strip common prefix
+  let cleanPath = path
+  if (commonPrefix && cleanPath.startsWith(commonPrefix)) {
+    cleanPath = '/' + cleanPath.slice(commonPrefix.length)
+  }
+
+  const segments = cleanPath
+    .replace(/^\//, '')
+    .split('/')
+    .filter(Boolean)
+
+  const methodLower = method.toLowerCase()
+  const prefix = METHOD_PREFIXES[methodLower] || methodLower
+
+  // Separate param and non-param segments
+  const nonParams: string[] = []
+  let hasTrailingParam = false
+
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i].startsWith('{')) {
+      if (i === segments.length - 1) {
+        hasTrailingParam = true
+      }
+    } else {
+      nonParams.push(segments[i])
+    }
+  }
+
+  if (nonParams.length === 0) {
+    return prefix
+  }
+
+  // For GET with trailing param: singularize the last non-param segment
+  // For GET without trailing param: keep plural (list)
+  // For POST without trailing param: use prefix (create)
+  const parts = nonParams.map((seg, i) => {
+    const isLast = i === nonParams.length - 1
+    let word = seg
+
+    if (isLast && hasTrailingParam) {
+      word = singularize(word)
+    }
+
+    // For GET on collection (no trailing param), use "list" prefix instead of "get"
+    return toPascalCase(word)
+  })
+
+  // For GET on collection, use "list" instead of "get"
+  let finalPrefix = prefix
+  if (methodLower === 'get' && !hasTrailingParam) {
+    finalPrefix = 'list'
+  }
+
+  return finalPrefix + parts.join('')
+}

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

@@ -0,0 +1,348 @@
+/**
+ * Converts OpenAPI schemas into Zod code strings.
+ *
+ * Chaining order: base → refinements → .nullable() → .optional() → .default() → .describe()
+ */
+
+export interface OpenAPISchema {
+  type?: string
+  format?: string
+  description?: string
+  enum?: unknown[]
+  items?: OpenAPISchema
+  properties?: Record<string, OpenAPISchema>
+  required?: string[]
+  nullable?: boolean
+  default?: unknown
+  minimum?: number
+  maximum?: number
+  exclusiveMinimum?: number
+  exclusiveMaximum?: number
+  minLength?: number
+  maxLength?: number
+  pattern?: string
+  minItems?: number
+  maxItems?: number
+  oneOf?: OpenAPISchema[]
+  anyOf?: OpenAPISchema[]
+  allOf?: OpenAPISchema[]
+  additionalProperties?: boolean | OpenAPISchema
+  $ref?: string
+  // Zod-relevant extensions
+  readOnly?: boolean
+  writeOnly?: boolean
+}
+
+export interface ZodCodegenContext {
+  /** Map from component schema name to its Zod variable name */
+  schemaRefs: Map<string, string>
+  /** Track which refs are actually used */
+  usedRefs: Set<string>
+  /** Indent level for readability */
+  indent: number
+}
+
+export function createContext(
+  schemaRefs?: Map<string, string>
+): ZodCodegenContext {
+  return {
+    schemaRefs: schemaRefs ?? new Map(),
+    usedRefs: new Set(),
+    indent: 0,
+  }
+}
+
+/**
+ * Convert a single OpenAPI schema to a Zod expression string.
+ * Does NOT include .optional() — that's handled at the property level based on `required`.
+ */
+export function schemaToZod(
+  schema: OpenAPISchema,
+  ctx: ZodCodegenContext,
+  opts: { optional?: boolean } = {}
+): string {
+  let code = schemaToZodBase(schema, ctx)
+
+  // Refinements
+  code = applyRefinements(code, schema)
+
+  // Nullable
+  if (schema.nullable) {
+    code += '.nullable()'
+  }
+
+  // Optional
+  if (opts.optional) {
+    code += '.optional()'
+  }
+
+  // Default
+  if (schema.default !== undefined) {
+    code += `.default(${JSON.stringify(schema.default)})`
+  }
+
+  // Description
+  if (schema.description) {
+    code += `.describe(${JSON.stringify(schema.description)})`
+  }
+
+  return code
+}
+
+function schemaToZodBase(
+  schema: OpenAPISchema,
+  ctx: ZodCodegenContext
+): string {
+  // Handle $ref
+  if (schema.$ref) {
+    const refName = schema.$ref.split('/').pop()!
+    const zodName = ctx.schemaRefs.get(refName)
+    if (zodName) {
+      ctx.usedRefs.add(refName)
+      return zodName
+    }
+    // Unknown ref — fallback to z.unknown()
+    return 'z.unknown()'
+  }
+
+  // Handle allOf — merge into single object
+  if (schema.allOf && schema.allOf.length > 0) {
+    return handleAllOf(schema.allOf, ctx)
+  }
+
+  // Handle oneOf/anyOf — union
+  if (schema.oneOf && schema.oneOf.length > 0) {
+    return handleUnion(schema.oneOf, ctx)
+  }
+  if (schema.anyOf && schema.anyOf.length > 0) {
+    return handleUnion(schema.anyOf, ctx)
+  }
+
+  // Handle enum
+  if (schema.enum && schema.enum.length > 0) {
+    return handleEnum(schema.enum)
+  }
+
+  // Handle by type
+  switch (schema.type) {
+    case 'string':
+      return handleString(schema)
+    case 'integer':
+      return 'z.number().int()'
+    case 'number':
+      return 'z.number()'
+    case 'boolean':
+      return 'z.boolean()'
+    case 'array':
+      return handleArray(schema, ctx)
+    case 'object':
+      return handleObject(schema, ctx)
+    default:
+      // No type specified but has properties — treat as object
+      if (schema.properties) {
+        return handleObject(schema, ctx)
+      }
+      return 'z.unknown()'
+  }
+}
+
+function handleString(schema: OpenAPISchema): string {
+  switch (schema.format) {
+    case 'uuid':
+      return 'z.string().uuid()'
+    case 'date-time':
+      return 'z.string().datetime()'
+    case 'date':
+      return 'z.string().date()'
+    case 'email':
+      return 'z.string().email()'
+    case 'uri':
+    case 'url':
+      return 'z.string().url()'
+    default:
+      return 'z.string()'
+  }
+}
+
+function handleEnum(values: unknown[]): string {
+  // Single value — use z.literal
+  if (values.length === 1) {
+    return `z.literal(${JSON.stringify(values[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(', ')
+    return `z.enum([${enumValues}])`
+  }
+  // Mixed types — use z.union of z.literal
+  const literals = values
+    .map((v) => `z.literal(${JSON.stringify(v)})`)
+    .join(', ')
+  return `z.union([${literals}])`
+}
+
+function handleArray(schema: OpenAPISchema, ctx: ZodCodegenContext): string {
+  const itemsZod = schema.items
+    ? schemaToZodBase(schema.items, ctx)
+    : 'z.unknown()'
+  return `z.array(${itemsZod})`
+}
+
+function indent(ctx: ZodCodegenContext): string {
+  return '  '.repeat(ctx.indent)
+}
+
+function handleObject(schema: OpenAPISchema, ctx: ZodCodegenContext): string {
+  if (!schema.properties || Object.keys(schema.properties).length === 0) {
+    // Object with no defined properties
+    if (schema.additionalProperties) {
+      const valueSchema =
+        typeof schema.additionalProperties === 'object'
+          ? schemaToZod(schema.additionalProperties, ctx)
+          : 'z.unknown()'
+      return `z.record(z.string(), ${valueSchema})`
+    }
+    return 'z.record(z.string(), z.unknown())'
+  }
+
+  const inner: ZodCodegenContext = { ...ctx, indent: ctx.indent + 1 }
+  const pad = indent(inner)
+  const closePad = indent(ctx)
+  const requiredSet = new Set(schema.required ?? [])
+  const entries: 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},`)
+  }
+
+  return `z.object({\n${entries.join('\n')}\n${closePad}})`
+}
+
+function handleAllOf(schemas: OpenAPISchema[], ctx: ZodCodegenContext): string {
+  // 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 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) {
+      Object.assign(mergedProps, sub.properties)
+    }
+    if (sub.required) {
+      mergedRequired.push(...sub.required)
+    }
+  }
+
+  // If we have only refs, use .merge()
+  const refSchemas = schemas.filter((s) => s.$ref)
+  const objSchemas = schemas.filter(
+    (s) => !s.$ref && (s.properties || s.type === 'object')
+  )
+
+  if (refSchemas.length > 0 && objSchemas.length === 0) {
+    const parts = refSchemas.map((s) => {
+      const refName = s.$ref!.split('/').pop()!
+      ctx.usedRefs.add(refName)
+      return ctx.schemaRefs.get(refName) || 'z.object({})'
+    })
+    if (parts.length === 1) return parts[0]
+    return parts.reduce((acc, part) => `${acc}.merge(${part})`)
+  }
+
+  // Otherwise, merge into a single object
+  if (Object.keys(mergedProps).length > 0) {
+    return handleObject(
+      {
+        type: 'object',
+        properties: mergedProps,
+        required: [...new Set(mergedRequired)],
+      },
+      ctx
+    )
+  }
+
+  // Fallback
+  return 'z.unknown()'
+}
+
+function handleUnion(schemas: OpenAPISchema[], ctx: ZodCodegenContext): string {
+  const members = schemas.map((s) => schemaToZodBase(s, ctx))
+  if (members.length === 1) return members[0]
+  return `z.union([${members.join(', ')}])`
+}
+
+function applyRefinements(code: string, schema: OpenAPISchema): string {
+  let result = code
+
+  // String refinements
+  if (schema.type === 'string' || (!schema.type && !schema.format)) {
+    if (schema.minLength !== undefined) {
+      result += `.min(${schema.minLength})`
+    }
+    if (schema.maxLength !== undefined) {
+      result += `.max(${schema.maxLength})`
+    }
+    if (schema.pattern) {
+      result += `.regex(new RegExp(${JSON.stringify(schema.pattern)}))`
+    }
+  }
+
+  // Number refinements
+  if (schema.type === 'number' || schema.type === 'integer') {
+    if (schema.minimum !== undefined) {
+      result += `.min(${schema.minimum})`
+    }
+    if (schema.maximum !== undefined) {
+      result += `.max(${schema.maximum})`
+    }
+    if (schema.exclusiveMinimum !== undefined) {
+      result += `.gt(${schema.exclusiveMinimum})`
+    }
+    if (schema.exclusiveMaximum !== undefined) {
+      result += `.lt(${schema.exclusiveMaximum})`
+    }
+  }
+
+  // Array refinements
+  if (schema.type === 'array') {
+    if (schema.minItems !== undefined) {
+      result += `.min(${schema.minItems})`
+    }
+    if (schema.maxItems !== undefined) {
+      result += `.max(${schema.maxItems})`
+    }
+  }
+
+  return result
+}
+
+/** Ensure property keys are safe identifiers, or quote them */
+function safeKey(key: string): string {
+  if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
+    return key
+  }
+  return JSON.stringify(key)
+}
+
+/**
+ * Generate the Zod variable name for a component schema.
+ * e.g. "PaginatedResponse" → "PaginatedResponseSchema"
+ */
+export function sanitizeTypeName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_$]/g, '')
+}
+
+export function schemaVarName(name: string): string {
+  const sanitized = sanitizeTypeName(name)
+  return sanitized.endsWith('Schema') ? sanitized : `${sanitized}Schema`
+}