@apidiff/core 1.0.0

package/src/rules/response/response-field-added.ts

@@ -0,0 +1,34 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseFieldAddedRule extends BaseRule {
+  id = 'RESPONSE_FIELD_ADDED';
+  description = 'A field was added to the response body';
+  severity = 'info' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.changeType === 'added') {
+          const propsIdx = fc.fieldPath.lastIndexOf('properties');
+          if (propsIdx !== -1 && fc.fieldPath.length === propsIdx + 2) {
+            const fieldName = fc.fieldPath[propsIdx + 1];
+            changes.push(this.makeChange({
+              severity: 'info',
+              category: 'response',
+              message: `Response field '${fieldName}' was added to status code ${fc.fieldPath[1]}.`,
+              consequence: 'Clients parsing responses strictly might fail if they do not ignore unknown fields.',
+              migration: 'Clients should ensure their JSON parsers ignore unknown fields.',
+              location: { path: ed.path, method: ed.method, field: fc.fieldPath.join('.') }
+            }, context));
+          }
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/response/response-field-removed.ts

@@ -0,0 +1,34 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseFieldRemovedRule extends BaseRule {
+  id = 'RESPONSE_FIELD_REMOVED';
+  description = 'A field was removed from a response payload';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.changeType === 'removed') {
+          if (fc.fieldPath.includes('properties')) {
+            const fieldName = fc.fieldPath[fc.fieldPath.length - 1];
+            const statusCode = fc.fieldPath[1] || 'unknown';
+            changes.push(this.makeChange({
+              severity: 'breaking',
+              category: 'response',
+              message: `Field '${fieldName}' was removed from the response.`,
+              consequence: `Clients depending on '${fieldName}' will encounter missing data errors.`,
+              migration: `Ensure clients no longer require '${fieldName}' before removing it.`,
+              location: { path: ed.path, method: ed.method, field: fieldName, statusCode }
+            }, context));
+          }
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/response/response-field-type-changed.ts

@@ -0,0 +1,37 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseFieldTypeChangedRule extends BaseRule {
+  id = 'RESPONSE_FIELD_TYPE_CHANGED';
+  description = 'The data type of a response body field changed';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.changeType === 'changed') {
+          const typeIdx = fc.fieldPath.lastIndexOf('type');
+          if (typeIdx !== -1 && typeIdx === fc.fieldPath.length - 1) {
+            const propsIdx = fc.fieldPath.lastIndexOf('properties');
+            if (propsIdx !== -1 && typeIdx > propsIdx + 1) {
+              const fieldName = fc.fieldPath[propsIdx + 1];
+              changes.push(this.makeChange({
+                severity: 'breaking',
+                category: 'response',
+                message: `Response body field '${fieldName}' changed type from ${fc.oldValue} to ${fc.newValue} for status code ${fc.fieldPath[1]}.`,
+                consequence: 'Clients expecting the old type will fail to parse the response.',
+                migration: `Update clients to expect the new type (${fc.newValue}) for '${fieldName}'.`,
+                location: { path: ed.path, method: ed.method, field: fc.fieldPath.slice(0, -1).join('.') }
+              }, context));
+            }
+          }
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/response/response-header-added-required.ts

@@ -0,0 +1,47 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseHeaderAddedRequiredRule extends BaseRule {
+  id = 'RESPONSE_HEADER_ADDED_REQUIRED';
+  description = 'A required response header was added';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.fieldPath[2] === 'headers' && fc.changeType === 'added' && fc.fieldPath.length === 4) {
+          const statusCode = fc.fieldPath[1];
+          const headerName = fc.fieldPath[3];
+          const headerDef = fc.newValue as { required?: boolean };
+          
+          if (headerDef.required) {
+            changes.push(this.makeChange({
+              severity: 'breaking',
+              category: 'response',
+              message: `Required response header '${headerName}' was added to status code ${statusCode}.`,
+              consequence: `Clients not designed to handle the new required header may fail or reject the response.`,
+              migration: `Update clients to accept and process the new '${headerName}' header.`,
+              location: { path: ed.path, method: ed.method, field: fc.fieldPath.join('.') }
+            }, context));
+          }
+        } else if (fc.fieldPath[0] === 'responses' && fc.fieldPath[2] === 'headers' && fc.fieldPath[4] === 'required' && fc.changeType === 'changed' && fc.oldValue === false && fc.newValue === true) {
+          const statusCode = fc.fieldPath[1];
+          const headerName = fc.fieldPath[3];
+          changes.push(this.makeChange({
+            severity: 'breaking',
+            category: 'response',
+            message: `Optional response header '${headerName}' was made required for status code ${statusCode}.`,
+            consequence: `Clients not designed to handle the required header may fail or reject the response.`,
+            migration: `Update clients to accept and process the '${headerName}' header.`,
+            location: { path: ed.path, method: ed.method, field: fc.fieldPath.join('.') }
+          }, context));
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/response/response-header-removed.ts

@@ -0,0 +1,32 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseHeaderRemovedRule extends BaseRule {
+  id = 'RESPONSE_HEADER_REMOVED';
+  description = 'A response header was removed';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.fieldPath[2] === 'headers' && fc.fieldPath.length === 4 && fc.changeType === 'removed') {
+          const statusCode = fc.fieldPath[1];
+          const headerName = fc.fieldPath[3];
+          changes.push(this.makeChange({
+            severity: 'breaking',
+            category: 'response',
+            message: `Response header '${headerName}' was removed from status code ${statusCode}.`,
+            consequence: `Clients depending on the '${headerName}' header will no longer receive it.`,
+            migration: `Update clients to not expect the '${headerName}' header.`,
+            location: { path: ed.path, method: ed.method, field: fc.fieldPath.join('.') }
+          }, context));
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/response/response-media-type-added.ts

@@ -0,0 +1,32 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseMediaTypeAddedRule extends BaseRule {
+  id = 'RESPONSE_MEDIA_TYPE_ADDED';
+  description = 'A response media type was added';
+  severity = 'info' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.fieldPath[2] === 'content' && fc.fieldPath.length === 4 && fc.changeType === 'added') {
+          const statusCode = fc.fieldPath[1];
+          const mediaType = fc.fieldPath[3];
+          changes.push(this.makeChange({
+            severity: 'info',
+            category: 'response',
+            message: `Response media type '${mediaType}' was added to status code ${statusCode}.`,
+            consequence: 'Clients can now request the new media type.',
+            migration: `Update clients to request '${mediaType}' if desired.`,
+            location: { path: ed.path, method: ed.method, field: fc.fieldPath.join('.') }
+          }, context));
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/response/response-media-type-removed.ts

@@ -0,0 +1,32 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseMediaTypeRemovedRule extends BaseRule {
+  id = 'RESPONSE_MEDIA_TYPE_REMOVED';
+  description = 'A response media type was removed';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.fieldPath[2] === 'content' && fc.fieldPath.length === 4 && fc.changeType === 'removed') {
+          const statusCode = fc.fieldPath[1];
+          const mediaType = fc.fieldPath[3];
+          changes.push(this.makeChange({
+            severity: 'breaking',
+            category: 'response',
+            message: `Response media type '${mediaType}' was removed for status code ${statusCode}.`,
+            consequence: `Clients requesting '${mediaType}' will no longer receive it and may fail to process the response.`,
+            migration: `Update clients to accept one of the remaining supported media types.`,
+            location: { path: ed.path, method: ed.method, field: fc.fieldPath.join('.') }
+          }, context));
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/response/response-status-added.ts

@@ -0,0 +1,31 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseStatusAddedRule extends BaseRule {
+  id = 'RESPONSE_STATUS_ADDED';
+  description = 'A response status code was added';
+  severity = 'info' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.fieldPath.length === 2 && fc.changeType === 'added') {
+          const statusCode = fc.fieldPath[1];
+          changes.push(this.makeChange({
+            severity: 'info',
+            category: 'response',
+            message: `Response status code ${statusCode} was added.`,
+            consequence: `Clients may receive a ${statusCode} response they weren't previously expecting.`,
+            migration: `Update clients to gracefully handle the ${statusCode} response.`,
+            location: { path: ed.path, method: ed.method, field: `responses['${statusCode}']` }
+          }, context));
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/response/response-status-removed.ts

@@ -0,0 +1,31 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ResponseStatusRemovedRule extends BaseRule {
+  id = 'RESPONSE_STATUS_REMOVED';
+  description = 'A response status code was removed';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'changed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+
+      for (const fc of ed.fieldChanges) {
+        if (fc.fieldPath[0] === 'responses' && fc.fieldPath.length === 2 && fc.changeType === 'removed') {
+          const statusCode = fc.fieldPath[1];
+          changes.push(this.makeChange({
+            severity: 'breaking',
+            category: 'response',
+            message: `Response status code ${statusCode} was removed.`,
+            consequence: `Clients explicitly expecting a ${statusCode} response might fail or behave unexpectedly.`,
+            migration: `Update clients to no longer rely on the ${statusCode} response.`,
+            location: { path: ed.path, method: ed.method, field: `responses['${statusCode}']` }
+          }, context));
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/types/ast.ts

@@ -0,0 +1,164 @@
+export type SpecFormat = 'openapi3' | 'openapi2' | 'protobuf' | 'graphql';
+
+export type HttpMethod =
+  | 'GET' | 'POST' | 'PUT' | 'PATCH'
+  | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
+
+export interface NormalizedAST {
+  meta: SpecMeta;
+  servers: Server[];
+  endpoints: Endpoint[];
+  components: ComponentMap;
+  security: SecurityScheme[];
+}
+
+export interface SpecMeta {
+  title: string;
+  version: string;
+  format: SpecFormat;
+  rawVersion: string;
+}
+
+export interface Server {
+  url: string;
+  description?: string;
+  variables?: Record<string, ServerVariable>;
+}
+
+export interface ServerVariable {
+  default: string;
+  enum?: string[];
+  description?: string;
+}
+
+export interface Endpoint {
+  id: string;
+  path: string;
+  method: HttpMethod | 'RPC';
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  tags: string[];
+  deprecated: boolean;
+  security: SecurityRequirement[];
+  parameters: Parameter[];
+  requestBody?: RequestBody;
+  responses: ResponseDef[];
+  extensions: Record<string, unknown>;
+}
+
+export interface Parameter {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  required: boolean;
+  deprecated: boolean;
+  schema: Schema;
+  description?: string;
+  example?: unknown;
+}
+
+export interface RequestBody {
+  required: boolean;
+  description?: string;
+  content: Record<string, MediaTypeObject>;
+}
+
+export interface MediaTypeObject {
+  schema: Schema;
+  example?: unknown;
+}
+
+export interface ResponseDef {
+  statusCode: string;
+  description?: string;
+  content: Record<string, MediaTypeObject>;
+  headers: Record<string, HeaderDef>;
+}
+
+export interface HeaderDef {
+  required?: boolean;
+  deprecated?: boolean;
+  schema: Schema;
+  description?: string;
+}
+
+export interface Schema {
+  type?: string | string[];
+  format?: string;
+  nullable?: boolean;
+  description?: string;
+  default?: unknown;
+  example?: unknown;
+  deprecated?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+
+  required?: string[];
+  properties?: Record<string, Schema>;
+  additionalProperties?: boolean | Schema;
+  items?: Schema;
+  enum?: unknown[];
+  const?: unknown;
+
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number | boolean;
+  exclusiveMaximum?: number | boolean;
+  multipleOf?: number;
+
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+
+  allOf?: Schema[];
+  oneOf?: Schema[];
+  anyOf?: Schema[];
+  not?: Schema;
+
+  $circular?: true;
+  $ref?: string;
+}
+
+export interface SecurityRequirement {
+  schemeId: string;
+  scopes: string[];
+}
+
+export interface SecurityScheme {
+  id: string;
+  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect' | 'mutualTLS';
+  description?: string;
+  name?: string;
+  in?: 'header' | 'query' | 'cookie' | string;
+  scheme?: string;
+  bearerFormat?: string;
+  flows?: OAuthFlows;
+  openIdConnectUrl?: string;
+}
+
+export interface OAuthFlows {
+  implicit?: OAuthFlow;
+  password?: OAuthFlow;
+  clientCredentials?: OAuthFlow;
+  authorizationCode?: OAuthFlow;
+}
+
+export interface OAuthFlow {
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  refreshUrl?: string;
+  scopes: Record<string, string>;
+}
+
+export interface ComponentMap {
+  schemas: Record<string, Schema>;
+  securitySchemes: Record<string, SecurityScheme>;
+  parameters: Record<string, Parameter>;
+  responses: Record<string, ResponseDef>;
+  headers: Record<string, HeaderDef>;
+  requestBodies: Record<string, RequestBody>;
+}

package/src/types/config.ts

@@ -0,0 +1,31 @@
+import type { Severity } from './semantic.js';
+
+export interface ApidiffConfig {
+  failOn: 'breaking' | 'warning';
+  ignorePaths: string[];
+  ruleSeverityOverrides: Record<string, Severity>;
+  disabledRules: string[];
+  customRules: string[];
+  output: OutputConfig;
+}
+
+export interface OutputConfig {
+  format: 'terminal' | 'json' | 'markdown' | 'html';
+  color: boolean;
+  summary: boolean;
+  quiet: boolean;
+}
+
+export const DEFAULT_CONFIG: ApidiffConfig = {
+  failOn: 'breaking',
+  ignorePaths: [],
+  ruleSeverityOverrides: {},
+  disabledRules: [],
+  customRules: [],
+  output: {
+    format: 'terminal',
+    color: true,
+    summary: false,
+    quiet: false,
+  }
+};

package/src/types/diff.ts

@@ -0,0 +1,49 @@
+import type { Endpoint, Schema, SecurityScheme, Server } from './ast.js';
+
+export type ChangeType = 'added' | 'removed' | 'changed';
+
+export interface DiffSet {
+  endpointDiffs: EndpointDiff[];
+  schemaDiffs: SchemaDiff[];
+  securityDiffs: SecurityDiff[];
+  serverDiffs: ServerDiff[];
+}
+
+export interface EndpointDiff {
+  type: ChangeType;
+  endpointId: string;
+  path: string;
+  method: string;
+  oldEndpoint?: Endpoint;
+  newEndpoint?: Endpoint;
+  fieldChanges: FieldChange[];
+}
+
+export interface SchemaDiff {
+  schemaName: string;
+  changeType: ChangeType;
+  oldSchema?: Schema;
+  newSchema?: Schema;
+  fieldChanges: FieldChange[];
+}
+
+export interface SecurityDiff {
+  schemeId: string;
+  changeType: ChangeType;
+  oldScheme?: SecurityScheme;
+  newScheme?: SecurityScheme;
+  fieldChanges: FieldChange[];
+}
+
+export interface ServerDiff {
+  changeType: ChangeType;
+  oldServer?: Server;
+  newServer?: Server;
+}
+
+export interface FieldChange {
+  fieldPath: string[];
+  changeType: ChangeType;
+  oldValue?: unknown;
+  newValue?: unknown;
+}

package/src/types/errors.ts

@@ -0,0 +1,26 @@
+export class ApidiffError extends Error {
+  constructor(message: string, public cause?: Error) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+export class LoadError extends ApidiffError {}
+export class ParseError extends ApidiffError {
+  constructor(
+    message: string,
+    public line?: number,
+    public col?: number,
+    public filePath?: string,
+    cause?: Error
+  ) {
+    super(message, cause);
+  }
+}
+export class RefError extends ApidiffError {
+  constructor(message: string, public ref: string, cause?: Error) {
+    super(message, cause);
+  }
+}
+export class ConfigError extends ApidiffError {}
+export class FormatError extends ApidiffError {}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './ast.js';
+export * from './diff.js';
+export * from './semantic.js';
+export * from './config.js';

package/src/types/semantic.ts

@@ -0,0 +1,60 @@
+import type { NormalizedAST, SpecMeta } from './ast.js';
+import type { DiffSet } from './diff.js';
+import type { ApidiffConfig } from './config.js';
+
+export type Severity = 'breaking' | 'warning' | 'info';
+
+export type RuleCategory =
+  | 'endpoint'
+  | 'parameter'
+  | 'request-body'
+  | 'response'
+  | 'schema'
+  | 'authentication'
+  | 'deprecation'
+  | 'server'
+  | 'rate-limit';
+
+export interface SemanticChange {
+  ruleId: string;
+  severity: Severity;
+  category: RuleCategory;
+  message: string;
+  consequence: string;
+  migration?: string;
+  location: ChangeLocation;
+}
+
+export interface ChangeLocation {
+  path?: string;
+  method?: string;
+  field?: string;
+  statusCode?: string;
+  paramName?: string;
+}
+
+export interface RunResult {
+  changes: SemanticChange[];
+  stats: {
+    breaking: number;
+    warning: number;
+    info: number;
+    total: number;
+  };
+  oldSpecMeta: SpecMeta;
+  newSpecMeta: SpecMeta;
+  durationMs: number;
+}
+
+export interface IRule {
+  id: string;
+  description: string;
+  severity: Severity;
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[];
+}
+
+export interface RuleContext {
+  oldAST: NormalizedAST;
+  newAST: NormalizedAST;
+  config: ApidiffConfig;
+}