@pikku/openapi-parser 0.12.3

package/dist/openapi-to-zod-schema.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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;
+    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 declare function createContext(schemaRefs?: Map<string, string>): ZodCodegenContext;
+/**
+ * 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 declare function schemaToZod(schema: OpenAPISchema, ctx: ZodCodegenContext, opts?: {
+    optional?: boolean;
+}): string;
+/**
+ * Generate the Zod variable name for a component schema.
+ * e.g. "PaginatedResponse" → "PaginatedResponseSchema"
+ */
+export declare function sanitizeTypeName(name: string): string;
+export declare function schemaVarName(name: string): string;

package/dist/openapi-to-zod-schema.js

@@ -0,0 +1,261 @@
+/**
+ * Converts OpenAPI schemas into Zod code strings.
+ *
+ * Chaining order: base → refinements → .nullable() → .optional() → .default() → .describe()
+ */
+export function createContext(schemaRefs) {
+    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, ctx, opts = {}) {
+    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, ctx) {
+    // 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) {
+    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) {
+    // 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, ctx) {
+    const itemsZod = schema.items
+        ? schemaToZodBase(schema.items, ctx)
+        : 'z.unknown()';
+    return `z.array(${itemsZod})`;
+}
+function indent(ctx) {
+    return '  '.repeat(ctx.indent);
+}
+function handleObject(schema, ctx) {
+    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 = { ...ctx, indent: ctx.indent + 1 };
+    const pad = indent(inner);
+    const closePad = indent(ctx);
+    const requiredSet = new Set(schema.required ?? []);
+    const entries = [];
+    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, ctx) {
+    // Collect all properties from all schemas
+    const mergedProps = {};
+    const mergedRequired = [];
+    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, ctx) {
+    const members = schemas.map((s) => schemaToZodBase(s, ctx));
+    if (members.length === 1)
+        return members[0];
+    return `z.union([${members.join(', ')}])`;
+}
+function applyRefinements(code, schema) {
+    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) {
+    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) {
+    return name.replace(/[^a-zA-Z0-9_$]/g, '');
+}
+export function schemaVarName(name) {
+    const sanitized = sanitizeTypeName(name);
+    return sanitized.endsWith('Schema') ? sanitized : `${sanitized}Schema`;
+}

package/dist/parse-openapi.d.ts

@@ -0,0 +1,67 @@
+import type { OpenAPISchema } from './zod-codegen.js';
+export interface ErrorResponse {
+    statusCode: number;
+    description: string;
+}
+export interface SecuritySchemeInfo {
+    type: 'oauth2' | 'http' | 'apiKey';
+    scheme?: string;
+    bearerFormat?: string;
+    name?: string;
+    in?: string;
+    flows?: {
+        authorizationUrl?: string;
+        tokenUrl?: string;
+        scopes?: Record<string, string>;
+    };
+}
+export interface ParsedSpec {
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    baseUrl: string;
+    serverUrls: string[];
+    authType: 'bearer' | 'oauth2' | 'apiKey' | 'none';
+    operations: ParsedOperation[];
+    componentSchemas: Record<string, OpenAPISchema>;
+    securitySchemes: Record<string, SecuritySchemeInfo>;
+    tagDescriptions: Record<string, string>;
+}
+export interface ParsedOperation {
+    operationId?: string;
+    method: string;
+    path: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    pathParams: ParsedParam[];
+    queryParams: ParsedParam[];
+    headerParams: ParsedParam[];
+    requestBody?: OpenAPISchema;
+    requestBodyDescription?: string;
+    requestBodyRequired?: boolean;
+    responseSchema?: OpenAPISchema;
+    responseDescription?: string;
+    errorResponses: ErrorResponse[];
+    deprecated: boolean;
+}
+export interface ParsedParam {
+    name: string;
+    required: boolean;
+    schema: OpenAPISchema;
+    description?: string;
+    example?: unknown;
+}
+/**
+ * Read and parse an OpenAPI spec from a file path.
+ * Supports both YAML (.yaml, .yml) and JSON (.json) files.
+ */
+export declare function parseOpenAPISpec(filePath: string): Promise<ParsedSpec>;
+/**
+ * Compute a SHA-256 hash of the contract-relevant parts of a parsed spec.
+ * Excludes presentation fields (summary, description, tags, operationId)
+ * so that only structural API changes produce a different hash.
+ */
+export declare function computeContractHash(spec: ParsedSpec): string;