@pikku/openapi-parser 0.12.3

package/dist/parse-openapi.js

@@ -0,0 +1,346 @@
+/**
+ * Parses OpenAPI YAML/JSON specs, resolves $ref pointers, and produces a normalized IR.
+ */
+import { createHash } from 'crypto';
+import { readFile } from 'fs/promises';
+import { parse as parseYAML } from 'yaml';
+/**
+ * Read and parse an OpenAPI spec from a file path.
+ * Supports both YAML (.yaml, .yml) and JSON (.json) files.
+ */
+export async function parseOpenAPISpec(filePath) {
+    const content = await readFile(filePath, 'utf-8');
+    let doc;
+    if (filePath.endsWith('.json')) {
+        doc = JSON.parse(content);
+    }
+    else {
+        doc = parseYAML(content);
+    }
+    // Validate spec version
+    const specVersion = doc.openapi ?? doc.swagger;
+    if (!specVersion) {
+        throw new Error('Not a valid OpenAPI/Swagger spec: missing "openapi" or "swagger" version field.');
+    }
+    const major = String(specVersion).split('.')[0];
+    if (major !== '2' && major !== '3') {
+        throw new Error(`Unsupported spec version "${specVersion}". Only OpenAPI 3.x and Swagger 2.x are supported.`);
+    }
+    // Resolve all $ref pointers in-place
+    resolveRefs(doc, doc);
+    const info = {
+        title: doc.info?.title ?? 'Unknown API',
+        version: doc.info?.version ?? '1.0.0',
+        description: doc.info?.description,
+    };
+    const serverUrls = extractServerUrls(doc);
+    const baseUrl = serverUrls[0] ?? '';
+    const authType = detectAuthType(doc);
+    const securitySchemes = extractSecuritySchemes(doc);
+    const tagDescriptions = extractTagDescriptions(doc);
+    // Extract component schemas
+    const componentSchemas = {};
+    if (doc.components?.schemas) {
+        for (const [name, schema] of Object.entries(doc.components.schemas)) {
+            componentSchemas[name] = schema;
+        }
+    }
+    // Extract operations (skip deprecated)
+    const operations = [];
+    if (doc.paths) {
+        for (const [path, pathItem] of Object.entries(doc.paths)) {
+            // Shared parameters at the path level
+            const sharedParams = pathItem.parameters ?? [];
+            for (const method of ['get', 'post', 'put', 'patch', 'delete']) {
+                const op = pathItem[method];
+                if (!op)
+                    continue;
+                // Skip deprecated operations
+                if (op.deprecated === true)
+                    continue;
+                const allParams = [...sharedParams, ...(op.parameters ?? [])];
+                const body = op.requestBody;
+                operations.push({
+                    operationId: op.operationId,
+                    method,
+                    path,
+                    summary: op.summary,
+                    description: op.description,
+                    tags: op.tags ?? [],
+                    pathParams: extractParams(allParams, 'path'),
+                    queryParams: extractParams(allParams, 'query'),
+                    headerParams: extractParams(allParams, 'header'),
+                    requestBody: extractRequestBody(op),
+                    requestBodyDescription: body?.description,
+                    requestBodyRequired: body?.required,
+                    responseSchema: extractResponseSchema(op),
+                    responseDescription: extractResponseDescription(op),
+                    errorResponses: extractErrorResponses(op),
+                    deprecated: false,
+                });
+            }
+        }
+    }
+    return {
+        info,
+        baseUrl,
+        serverUrls,
+        authType,
+        operations,
+        componentSchemas,
+        securitySchemes,
+        tagDescriptions,
+    };
+}
+/** Recursively resolve $ref pointers in-place */
+function resolveRefs(node, root) {
+    if (node === null || typeof node !== 'object')
+        return node;
+    if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i++) {
+            node[i] = resolveRefs(node[i], root);
+        }
+        return node;
+    }
+    if (typeof node.$ref === 'string') {
+        const resolved = resolveRefPath(node.$ref, root);
+        if (resolved && typeof resolved === 'object') {
+            // Merge any sibling properties (like description overrides)
+            const { $ref, ...siblings } = node;
+            const result = { ...resolved, ...siblings };
+            // Don't recurse infinitely — mark as resolved
+            return result;
+        }
+        return node;
+    }
+    for (const key of Object.keys(node)) {
+        node[key] = resolveRefs(node[key], root);
+    }
+    return node;
+}
+function resolveRefPath(ref, root) {
+    if (!ref.startsWith('#/'))
+        return undefined;
+    const parts = ref.slice(2).split('/');
+    let current = root;
+    for (const part of parts) {
+        const decoded = part.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[decoded];
+    }
+    return current;
+}
+function extractServerUrls(doc) {
+    // OpenAPI 3.x
+    if (doc.servers && doc.servers.length > 0) {
+        return doc.servers.map((s) => s.url).filter((url) => !!url);
+    }
+    // Swagger 2.x
+    if (doc.host) {
+        const schemes = doc.schemes?.length ? doc.schemes : ['https'];
+        const basePath = doc.basePath ?? '';
+        return schemes.map((scheme) => `${scheme}://${doc.host}${basePath}`);
+    }
+    return [];
+}
+function detectAuthType(doc) {
+    const securitySchemes = doc.components?.securitySchemes ?? doc.securityDefinitions ?? {};
+    for (const scheme of Object.values(securitySchemes)) {
+        if (scheme.type === 'oauth2')
+            return 'oauth2';
+        if (scheme.type === 'http' && scheme.scheme === 'bearer')
+            return 'bearer';
+        if (scheme.type === 'apiKey')
+            return 'apiKey';
+    }
+    return 'none';
+}
+/**
+ * Build an OpenAPI schema object from v2-style parameter-level properties
+ * (type, enum, items, format, default) that aren't nested under `schema`.
+ */
+function paramToSchema(p) {
+    const schema = { type: p.type ?? 'string' };
+    if (p.enum)
+        schema.enum = p.enum;
+    if (p.items)
+        schema.items = p.items;
+    if (p.format)
+        schema.format = p.format;
+    if (p.default !== undefined)
+        schema.default = p.default;
+    return schema;
+}
+function extractParams(params, location) {
+    return params
+        .filter((p) => p.in === location)
+        .map((p) => ({
+        name: p.name,
+        required: p.required ?? location === 'path',
+        schema: (p.schema ?? paramToSchema(p)),
+        description: p.description,
+        example: p.example,
+    }));
+}
+function extractRequestBody(op) {
+    const body = op.requestBody;
+    if (!body)
+        return undefined;
+    const content = body.content;
+    if (!content)
+        return undefined;
+    // Prefer JSON
+    const jsonContent = content['application/json'];
+    if (jsonContent?.schema)
+        return jsonContent.schema;
+    // Fallback to first content type
+    const firstKey = Object.keys(content)[0];
+    if (firstKey && content[firstKey]?.schema) {
+        return content[firstKey].schema;
+    }
+    return undefined;
+}
+function extractResponseDescription(op) {
+    const responses = op.responses;
+    if (!responses)
+        return undefined;
+    for (const code of ['200', '201', '202']) {
+        const resp = responses[code];
+        if (resp?.description)
+            return resp.description;
+    }
+    return undefined;
+}
+function extractResponseSchema(op) {
+    const responses = op.responses;
+    if (!responses)
+        return undefined;
+    // Look for 2xx responses in order of preference
+    for (const code of ['200', '201', '202', '204']) {
+        const resp = responses[code];
+        if (!resp)
+            continue;
+        const content = resp.content;
+        if (!content)
+            continue;
+        const jsonContent = content['application/json'];
+        if (jsonContent?.schema)
+            return jsonContent.schema;
+        const firstKey = Object.keys(content)[0];
+        if (firstKey && content[firstKey]?.schema) {
+            return content[firstKey].schema;
+        }
+    }
+    // Fallback: any 2xx
+    for (const [code, resp] of Object.entries(responses)) {
+        if (code.startsWith('2') && resp.content) {
+            const jsonContent = resp.content['application/json'];
+            if (jsonContent?.schema)
+                return jsonContent.schema;
+        }
+    }
+    return undefined;
+}
+function extractErrorResponses(op) {
+    const responses = op.responses;
+    if (!responses)
+        return [];
+    const errors = [];
+    for (const [code, resp] of Object.entries(responses)) {
+        const statusCode = parseInt(code, 10);
+        if (isNaN(statusCode))
+            continue;
+        if (statusCode >= 400) {
+            errors.push({
+                statusCode,
+                description: resp.description ?? `Error ${statusCode}`,
+            });
+        }
+    }
+    return errors;
+}
+function extractSecuritySchemes(doc) {
+    const raw = doc.components?.securitySchemes ?? doc.securityDefinitions ?? {};
+    const result = {};
+    for (const [name, scheme] of Object.entries(raw)) {
+        const info = {
+            type: scheme.type === 'http' ? 'http' : scheme.type,
+        };
+        if (scheme.type === 'http') {
+            info.scheme = scheme.scheme;
+            info.bearerFormat = scheme.bearerFormat;
+        }
+        if (scheme.type === 'apiKey') {
+            info.name = scheme.name;
+            info.in = scheme.in;
+        }
+        if (scheme.type === 'oauth2') {
+            // Extract flows — prefer authorizationCode, then implicit, then clientCredentials
+            const flows = scheme.flows ?? {};
+            const flow = flows.authorizationCode ??
+                flows.implicit ??
+                flows.clientCredentials ??
+                flows.password;
+            if (flow) {
+                info.flows = {
+                    authorizationUrl: flow.authorizationUrl,
+                    tokenUrl: flow.tokenUrl,
+                    scopes: flow.scopes,
+                };
+            }
+        }
+        result[name] = info;
+    }
+    return result;
+}
+/**
+ * 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 function computeContractHash(spec) {
+    const contract = {
+        operations: spec.operations.map((op) => ({
+            method: op.method,
+            path: op.path,
+            pathParams: op.pathParams.map((p) => ({
+                name: p.name,
+                required: p.required,
+                schema: p.schema,
+            })),
+            queryParams: op.queryParams.map((p) => ({
+                name: p.name,
+                required: p.required,
+                schema: p.schema,
+            })),
+            headerParams: op.headerParams.map((p) => ({
+                name: p.name,
+                required: p.required,
+                schema: p.schema,
+            })),
+            requestBody: op.requestBody,
+            requestBodyRequired: op.requestBodyRequired,
+            responseSchema: op.responseSchema,
+            errorResponses: op.errorResponses,
+        })),
+        componentSchemas: spec.componentSchemas,
+        securitySchemes: spec.securitySchemes,
+        serverUrls: spec.serverUrls,
+    };
+    return createHash('sha256')
+        .update(JSON.stringify(contract))
+        .digest('hex')
+        .slice(0, 16);
+}
+function extractTagDescriptions(doc) {
+    const result = {};
+    if (Array.isArray(doc.tags)) {
+        for (const tag of doc.tags) {
+            if (tag.name && tag.description) {
+                result[tag.name] = tag.description;
+            }
+        }
+    }
+    return result;
+}

package/dist/zod-codegen.d.ts

@@ -0,0 +1 @@
+export { type OpenAPISchema, type ZodCodegenContext, createContext, schemaToZod, schemaVarName, sanitizeTypeName, } from './openapi-to-zod-schema.js';

package/dist/zod-codegen.js

@@ -0,0 +1 @@
+export { createContext, schemaToZod, schemaVarName, sanitizeTypeName, } from './openapi-to-zod-schema.js';

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@pikku/openapi-parser",
+  "version": "0.12.3",
+  "description": "OpenAPI spec parser and code generator for Pikku",
+  "author": "yasser.fadl@gmail.com",
+  "license": "MIT",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "tsc": "tsc",
+    "ncu": "npx npm-check-updates",
+    "build": "tsc -b",
+    "test": "node --import tsx --test src/**/*.test.ts",
+    "prepublishOnly": "yarn build"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "yaml": "^2.7.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9"
+  }
+}