@apidiff/core 1.0.0

package/src/parsers/openapi2/index.ts

@@ -0,0 +1,218 @@
+import type { NormalizedAST, Endpoint, Parameter, RequestBody, ResponseDef, ComponentMap, HttpMethod, Server } from '../../types/index.js';
+import type { RawSpec } from '../../loader/index.js';
+import type { ISpecParser } from '../base.js';
+import { ParseError } from '../../types/errors.js';
+import { normalizeSchema } from '../openapi3/schema-normalizer.js';
+import yaml from 'js-yaml';
+
+export class OpenApi2Parser implements ISpecParser {
+  readonly format = 'openapi2';
+
+  canParse(raw: RawSpec): boolean {
+    return raw.format === 'openapi2';
+  }
+
+  async parse(raw: RawSpec): Promise<NormalizedAST> {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(raw.content);
+    } catch {
+      try {
+        parsed = yaml.load(raw.content);
+      } catch (err: any) {
+        throw new ParseError('Failed to parse OpenAPI 2.x spec', undefined, undefined, raw.sourcePath, err);
+      }
+    }
+
+    if (!parsed || typeof parsed !== 'object' || !parsed.swagger || !parsed.swagger.startsWith('2.')) {
+      throw new ParseError('Not a valid OpenAPI 2.x spec', undefined, undefined, raw.sourcePath);
+    }
+
+    // In a real implementation we would resolve refs, but for now we'll assume they are resolved or handle them simply.
+    // We should use the same ref-resolver used in openapi3 if possible, but Swagger 2.0 has different structure.
+    // For this implementation, we will use the raw parsed object.
+    const resolved = parsed; // TODO: proper ref resolution
+
+    const meta = {
+      title: resolved.info?.title || 'Unknown API',
+      version: resolved.info?.version || '1.0.0',
+      format: 'openapi2' as const,
+      rawVersion: resolved.swagger
+    };
+
+    const servers: Server[] = [];
+    if (resolved.host) {
+      const schemes = Array.isArray(resolved.schemes) && resolved.schemes.length > 0 ? resolved.schemes : ['https'];
+      const basePath = resolved.basePath || '';
+      for (const scheme of schemes) {
+        servers.push({ url: `${scheme}://${resolved.host}${basePath}` });
+      }
+    }
+
+    const components: ComponentMap = {
+      schemas: {},
+      securitySchemes: {},
+      parameters: {},
+      responses: {},
+      headers: {},
+      requestBodies: {}
+    };
+
+    if (resolved.definitions) {
+      for (const [k, v] of Object.entries(resolved.definitions)) {
+        components.schemas[k] = normalizeSchema(v as any);
+      }
+    }
+
+    const securitySchemes = resolved.securityDefinitions || {};
+    for (const [k, v] of Object.entries(securitySchemes)) {
+      components.securitySchemes[k] = v as any;
+    }
+
+    const endpoints: Endpoint[] = [];
+    const paths = resolved.paths || {};
+    const globalSecurity = resolved.security || [];
+
+    const allowedMethods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
+
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
+      if (!pathItem || typeof pathItem !== 'object') continue;
+
+      const pathParams = Array.isArray((pathItem as any).parameters) ? (pathItem as any).parameters : [];
+
+      for (const methodStr of Object.keys(pathItem)) {
+        if (!allowedMethods.includes(methodStr)) continue;
+        const op = (pathItem as any)[methodStr];
+        if (!op || typeof op !== 'object') continue;
+
+        const method = methodStr.toUpperCase() as HttpMethod;
+        const id = `${method}:${normalizePathForId(pathStr)}`;
+
+        const opParams = Array.isArray(op.parameters) ? op.parameters : [];
+        const { parameters, requestBody } = buildParametersAndBody(pathParams, opParams, resolved.consumes || op.consumes || ['application/json']);
+
+        const endpoint: Endpoint = {
+          id,
+          path: pathStr,
+          method,
+          summary: op.summary,
+          description: op.description,
+          operationId: op.operationId,
+          tags: Array.isArray(op.tags) ? op.tags : [],
+          deprecated: !!op.deprecated,
+          security: op.security || globalSecurity,
+          parameters,
+          requestBody,
+          responses: buildResponses(op.responses, resolved.produces || op.produces || ['application/json']),
+          extensions: extractExtensions(op)
+        };
+
+        endpoints.push(endpoint);
+      }
+    }
+
+    return {
+      meta,
+      servers,
+      endpoints,
+      components,
+      security: Object.values(components.securitySchemes)
+    } as unknown as NormalizedAST;
+  }
+}
+
+function normalizePathForId(path: string): string {
+  return path
+    .toLowerCase()
+    .replace(/\/$/, '')
+    .replace(/\{[^}]+\}/g, '{*}');
+}
+
+function buildParametersAndBody(pathParams: any[], opParams: any[], consumes: string[]): { parameters: Parameter[], requestBody?: RequestBody } {
+  const paramMap = new Map<string, Parameter>();
+  let requestBody: RequestBody | undefined = undefined;
+
+  const allParams = [...pathParams, ...opParams];
+
+  for (const p of allParams) {
+    if (p.in === 'body') {
+      const content: Record<string, any> = {};
+      for (const mime of consumes) {
+        content[mime] = { schema: normalizeSchema(p.schema || {}) };
+      }
+      requestBody = {
+        required: !!p.required,
+        description: p.description,
+        content
+      };
+    } else if (p.in === 'formData') {
+      // In OpenAPI 3, formData becomes requestBody with application/x-www-form-urlencoded or multipart/form-data
+      if (!requestBody) {
+        requestBody = { required: false, content: {} };
+      }
+      const mime = consumes.includes('multipart/form-data') ? 'multipart/form-data' : 'application/x-www-form-urlencoded';
+      if (!requestBody.content[mime]) {
+        requestBody.content[mime] = { schema: { type: 'object', properties: {} } };
+      }
+      const schema = requestBody.content[mime].schema;
+      if (!schema.properties) schema.properties = {};
+      schema.properties[p.name] = normalizeSchema(p);
+      if (p.required) {
+        if (!schema.required) schema.required = [];
+        schema.required.push(p.name);
+      }
+    } else {
+      paramMap.set(`${p.name}:${p.in}`, {
+        name: p.name,
+        in: p.in as any,
+        required: !!p.required,
+        deprecated: false,
+        description: p.description,
+        schema: normalizeSchema(p)
+      });
+    }
+  }
+
+  return { parameters: Array.from(paramMap.values()), requestBody };
+}
+
+function buildResponses(responses: any, produces: string[]): ResponseDef[] {
+  if (!responses || typeof responses !== 'object') return [];
+  const res: ResponseDef[] = [];
+  for (const [code, r] of Object.entries<any>(responses)) {
+    const content: Record<string, any> = {};
+    if (r.schema) {
+      for (const mime of produces) {
+        content[mime] = { schema: normalizeSchema(r.schema) };
+      }
+    }
+    const headers: Record<string, any> = {};
+    if (r.headers) {
+      for (const [k, v] of Object.entries<any>(r.headers)) {
+        headers[k] = {
+          schema: normalizeSchema(v as any),
+          description: (v as any).description
+        };
+      }
+    }
+    res.push({
+      statusCode: code,
+      description: r.description,
+      content,
+      headers
+    });
+  }
+  return res;
+}
+
+function extractExtensions(obj: any): Record<string, unknown> {
+  const ext: Record<string, unknown> = {};
+  if (obj && typeof obj === 'object') {
+    for (const k of Object.keys(obj)) {
+      if (k.startsWith('x-')) {
+        ext[k] = obj[k];
+      }
+    }
+  }
+  return ext;
+}

package/src/parsers/openapi3/index.ts

@@ -0,0 +1,223 @@
+import { resolveRefs } from './ref-resolver.js';
+import { normalizeSchema } from './schema-normalizer.js';
+import { normalizeSecurity } from './security-normalizer.js';
+import type { NormalizedAST, Endpoint, Parameter, RequestBody, ResponseDef, ComponentMap, HttpMethod } from '../../types/index.js';
+import type { RawSpec } from '../../loader/index.js';
+import type { ISpecParser } from '../base.js';
+import { ParseError } from '../../types/errors.js';
+import yaml from 'js-yaml';
+
+export class OpenApi3Parser implements ISpecParser {
+  readonly format = 'openapi3';
+
+  canParse(raw: RawSpec): boolean {
+    return raw.format === 'openapi3';
+  }
+
+  async parse(raw: RawSpec): Promise<NormalizedAST> {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(raw.content);
+    } catch {
+      try {
+        parsed = yaml.load(raw.content);
+      } catch (err: any) {
+        throw new ParseError('Failed to parse OpenAPI 3.x spec', undefined, undefined, raw.sourcePath, err);
+      }
+    }
+
+    if (!parsed || typeof parsed !== 'object' || !parsed.openapi || !parsed.openapi.startsWith('3.')) {
+      throw new ParseError('Not a valid OpenAPI 3.x spec', undefined, undefined, raw.sourcePath);
+    }
+
+    const resolved = resolveRefs(parsed, parsed, raw.sourcePath);
+
+    const meta = {
+      title: resolved.info?.title || 'Unknown API',
+      version: resolved.info?.version || '1.0.0',
+      format: 'openapi3' as const,
+      rawVersion: resolved.openapi
+    };
+
+    const servers = (resolved.servers || []).map((s: any) => ({
+      url: s.url,
+      description: s.description,
+      variables: s.variables
+    }));
+
+    const components: ComponentMap = {
+      schemas: {},
+      securitySchemes: {},
+      parameters: {},
+      responses: {},
+      headers: {},
+      requestBodies: {}
+    };
+
+    if (resolved.components?.schemas) {
+      for (const [k, v] of Object.entries(resolved.components.schemas)) {
+        components.schemas[k] = normalizeSchema(v);
+      }
+    }
+    
+    const securitySchemes = resolved.components?.securitySchemes || {};
+    for (const [k, v] of Object.entries(securitySchemes)) {
+      components.securitySchemes[k] = v as any;
+    }
+
+    const endpoints: Endpoint[] = [];
+    const paths = resolved.paths || {};
+
+    const globalSecurity = resolved.security;
+
+    const allowedMethods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
+
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
+      if (!pathItem || typeof pathItem !== 'object') continue;
+
+      const pathParams = Array.isArray((pathItem as any).parameters) ? (pathItem as any).parameters : [];
+
+      for (const methodStr of Object.keys(pathItem)) {
+        if (!allowedMethods.includes(methodStr)) continue;
+        const op = pathItem[methodStr as keyof typeof pathItem] as any;
+        if (!op || typeof op !== 'object') continue;
+
+        const method = methodStr.toUpperCase() as HttpMethod;
+        const id = `${method}:${normalizePathForId(pathStr)}`;
+
+        const opParams = Array.isArray(op.parameters) ? op.parameters : [];
+        const parameters = buildParameters(pathParams, opParams);
+
+        const security = op.security !== undefined 
+          ? normalizeSecurity(op.security) 
+          : normalizeSecurity(globalSecurity);
+
+        const endpoint: Endpoint = {
+          id,
+          path: pathStr,
+          method,
+          summary: op.summary,
+          description: op.description,
+          operationId: op.operationId,
+          tags: Array.isArray(op.tags) ? op.tags : [],
+          deprecated: !!op.deprecated,
+          security,
+          parameters,
+          requestBody: op.requestBody ? buildRequestBody(op.requestBody) : undefined,
+          responses: buildResponses(op.responses),
+          extensions: extractExtensions(op)
+        };
+
+        endpoints.push(endpoint);
+      }
+    }
+
+    return {
+      meta,
+      servers,
+      endpoints,
+      components,
+      security: Object.values(components.securitySchemes)
+    };
+  }
+}
+
+function normalizePathForId(path: string): string {
+  return path
+    .toLowerCase()
+    .replace(/\/$/, '')
+    .replace(/\{[^}]+\}/g, '{*}');
+}
+
+function buildParameters(pathParams: any[], opParams: any[]): Parameter[] {
+  const paramMap = new Map<string, Parameter>();
+  
+  for (const p of pathParams) {
+    paramMap.set(`${p.name}:${p.in}`, {
+      name: p.name,
+      in: p.in,
+      required: !!p.required,
+      deprecated: !!p.deprecated,
+      description: p.description,
+      schema: normalizeSchema(p.schema || {}),
+      example: p.example
+    });
+  }
+
+  for (const p of opParams) {
+    paramMap.set(`${p.name}:${p.in}`, {
+      name: p.name,
+      in: p.in,
+      required: !!p.required,
+      deprecated: !!p.deprecated,
+      description: p.description,
+      schema: normalizeSchema(p.schema || {}),
+      example: p.example
+    });
+  }
+
+  return Array.from(paramMap.values());
+}
+
+function buildRequestBody(rb: any): RequestBody {
+  const content: Record<string, any> = {};
+  if (rb.content) {
+    for (const [k, v] of Object.entries<any>(rb.content)) {
+      content[k] = {
+        schema: normalizeSchema(v.schema || {}),
+        example: v.example
+      };
+    }
+  }
+  return {
+    required: !!rb.required,
+    description: rb.description,
+    content
+  };
+}
+
+function buildResponses(responses: any): ResponseDef[] {
+  if (!responses || typeof responses !== 'object') return [];
+  const res: ResponseDef[] = [];
+  for (const [code, r] of Object.entries<any>(responses)) {
+    const content: Record<string, any> = {};
+    if (r.content) {
+      for (const [k, v] of Object.entries<any>(r.content)) {
+        content[k] = {
+          schema: normalizeSchema(v.schema || {}),
+          example: v.example
+        };
+      }
+    }
+    const headers: Record<string, any> = {};
+    if (r.headers) {
+      for (const [k, v] of Object.entries<any>(r.headers)) {
+        headers[k] = {
+          required: !!v.required,
+          deprecated: !!v.deprecated,
+          schema: normalizeSchema(v.schema || {}),
+          description: v.description
+        };
+      }
+    }
+    res.push({
+      statusCode: code,
+      description: r.description,
+      content,
+      headers
+    });
+  }
+  return res;
+}
+
+function extractExtensions(obj: any): Record<string, unknown> {
+  const ext: Record<string, unknown> = {};
+  if (obj && typeof obj === 'object') {
+    for (const k of Object.keys(obj)) {
+      if (k.startsWith('x-')) {
+        ext[k] = obj[k];
+      }
+    }
+  }
+  return ext;
+}

package/src/parsers/openapi3/ref-resolver.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import yaml from 'js-yaml';
+import { RefError } from '../../types/errors.js';
+
+const fileCache = new Map<string, any>();
+
+export function resolveRefs(obj: any, root: any, sourcePath?: string): any {
+  if (!obj || typeof obj !== 'object') return obj;
+
+  const stack: Array<{ node: any; parent: any | null; key: string | null }> = [
+    { node: obj, parent: null, key: null }
+  ];
+  const visitedRefs = new Set<string>();
+  const visitedNodes = new WeakSet<any>();
+
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    const { node, parent, key } = current;
+
+    if (!node || typeof node !== 'object') continue;
+
+    if (visitedNodes.has(node)) continue;
+    visitedNodes.add(node);
+
+    if (Array.isArray(node)) {
+      for (let i = node.length - 1; i >= 0; i--) {
+        stack.push({ node: node[i], parent: node, key: i.toString() });
+      }
+      continue;
+    }
+
+    if ('$ref' in node && typeof node.$ref === 'string') {
+      const ref = node.$ref;
+      
+      if (visitedRefs.has(ref)) {
+        if (parent && key !== null) {
+          parent[key] = { ...node, $circular: true };
+        }
+        continue;
+      }
+      visitedRefs.add(ref);
+
+      let resolved: any;
+      if (ref.startsWith('#')) {
+        resolved = resolveLocalRef(ref, root);
+      } else if (ref.startsWith('./') || ref.startsWith('../')) {
+        if (!sourcePath) {
+          throw new RefError(`Cannot resolve relative ref without sourcePath`, ref);
+        }
+        const refPath = resolve(dirname(sourcePath), ref.split('#')[0]);
+        try {
+          let parsed = fileCache.get(refPath);
+          if (!parsed) {
+            const content = readFileSync(refPath, 'utf8');
+            parsed = refPath.endsWith('.json') ? JSON.parse(content) : yaml.load(content);
+            fileCache.set(refPath, parsed);
+          }
+          resolved = ref.includes('#') ? resolveLocalRef('#' + ref.split('#')[1], parsed) : parsed;
+        } catch (err: any) {
+          throw new RefError(`Failed to load external ref`, ref, err);
+        }
+      } else if (ref.startsWith('http://') || ref.startsWith('https://')) {
+         throw new RefError(`URL refs not implemented synchronously`, ref);
+      } else {
+        throw new RefError(`Unsupported ref format`, ref);
+      }
+
+      if (parent && key !== null) {
+        parent[key] = resolved;
+        stack.push({ node: resolved, parent, key }); 
+      }
+      continue;
+    }
+
+    const keys = Object.keys(node);
+    for (let i = keys.length - 1; i >= 0; i--) {
+      const k = keys[i];
+      if (k !== '$ref' && typeof node[k] === 'object' && node[k] !== null) {
+        stack.push({ node: node[k], parent: node, key: k });
+      }
+    }
+  }
+
+  return obj;
+}
+
+function resolveLocalRef(ref: string, root: any): any {
+  const parts = ref.replace(/^#\/?/, '').split('/');
+  let current = root;
+  for (const part of parts) {
+    if (!part) continue;
+    const key = part.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (current && typeof current === 'object' && key in current) {
+      current = current[key];
+    } else {
+      throw new RefError(`Local ref not found`, ref);
+    }
+  }
+  return current;
+}

package/src/parsers/openapi3/schema-normalizer.ts

@@ -0,0 +1,52 @@
+import type { Schema } from '../../types/index.js';
+
+export function normalizeSchema(schema: any): Schema {
+  if (!schema || typeof schema !== 'object') return schema;
+
+  if (Array.isArray(schema.allOf)) {
+    const merged = flattenAllOf(schema.allOf);
+    schema = { ...schema, ...merged };
+    delete schema.allOf;
+  }
+
+  if (schema.nullable === true) {
+    if (typeof schema.type === 'string') {
+      schema.type = [schema.type, 'null'];
+    } else if (Array.isArray(schema.type) && !schema.type.includes('null')) {
+      schema.type = [...schema.type, 'null'];
+    }
+    delete schema.nullable;
+  }
+
+  if (schema.properties) {
+    for (const key of Object.keys(schema.properties)) {
+      schema.properties[key] = normalizeSchema(schema.properties[key]);
+    }
+  }
+  if (schema.items) {
+    schema.items = normalizeSchema(schema.items);
+  }
+  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+    schema.additionalProperties = normalizeSchema(schema.additionalProperties);
+  }
+  if (Array.isArray(schema.oneOf)) {
+    schema.oneOf = schema.oneOf.map(normalizeSchema);
+  }
+  if (Array.isArray(schema.anyOf)) {
+    schema.anyOf = schema.anyOf.map(normalizeSchema);
+  }
+
+  return schema as Schema;
+}
+
+function flattenAllOf(schemas: any[]): any {
+  return schemas.reduce((merged, subSchema) => {
+    const normalized = normalizeSchema(subSchema);
+    return {
+      ...merged,
+      ...normalized,
+      properties: { ...(merged.properties || {}), ...(normalized.properties || {}) },
+      required: [...new Set([...(merged.required || []), ...(normalized.required || [])])]
+    };
+  }, {});
+}

package/src/parsers/openapi3/security-normalizer.ts

@@ -0,0 +1,18 @@
+import type { SecurityRequirement } from '../../types/index.js';
+
+export function normalizeSecurity(securityArray?: any[]): SecurityRequirement[] {
+  if (!securityArray || !Array.isArray(securityArray)) {
+    return [];
+  }
+
+  const result: SecurityRequirement[] = [];
+  for (const req of securityArray) {
+    for (const [schemeId, scopes] of Object.entries(req)) {
+      result.push({
+        schemeId,
+        scopes: Array.isArray(scopes) ? scopes.map(String) : []
+      });
+    }
+  }
+  return result;
+}