@apidiff/core 1.0.0

package/src/config/index.ts

@@ -0,0 +1,44 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { ApidiffConfig } from '../types/index.js';
+
+export const DEFAULT_CONFIG: ApidiffConfig = {
+  failOn: 'breaking',
+  ignorePaths: [],
+  ruleSeverityOverrides: {},
+  disabledRules: [],
+  customRules: [],
+  output: {
+    format: 'terminal',
+    color: true,
+    summary: false,
+    quiet: false
+  }
+};
+
+export async function loadConfig(options: { config?: string, format?: string, failOn?: string, ignorePath?: string[] }): Promise<ApidiffConfig> {
+  let config = { ...DEFAULT_CONFIG, output: { ...DEFAULT_CONFIG.output } };
+  
+  if (options.config) {
+    const configPath = resolve(process.cwd(), options.config);
+    if (existsSync(configPath)) {
+      const fileContent = readFileSync(configPath, 'utf8');
+      try {
+        const fileConfig = JSON.parse(fileContent);
+        config = { ...config, ...fileConfig, output: { ...config.output, ...(fileConfig.output || {}) } };
+      } catch (e) {
+        throw new Error(`Failed to parse config file at ${configPath}`);
+      }
+    } else {
+      throw new Error(`Config file not found at ${configPath}`);
+    }
+  }
+
+  if (options.format) config.output.format = options.format as any;
+  if (options.failOn) config.failOn = options.failOn as any;
+  if (options.ignorePath && options.ignorePath.length > 0) {
+    config.ignorePaths = [...config.ignorePaths, ...options.ignorePath];
+  }
+
+  return config;
+}

package/src/diff/auth-differ.ts

@@ -0,0 +1,72 @@
+import type { SecurityScheme, SecurityRequirement, SecurityDiff, FieldChange } from '../types/index.js';
+
+export function diffSecuritySchemes(oldSchemes: SecurityScheme[], newSchemes: SecurityScheme[]): SecurityDiff[] {
+  const diffs: SecurityDiff[] = [];
+  const oldMap = new Map(oldSchemes.map(s => [s.id, s]));
+  const newMap = new Map(newSchemes.map(s => [s.id, s]));
+
+  const allIds = new Set([...oldMap.keys(), ...newMap.keys()]);
+
+  for (const id of allIds) {
+    const oldScheme = oldMap.get(id);
+    const newScheme = newMap.get(id);
+
+    if (oldScheme && !newScheme) {
+      diffs.push({ schemeId: id, changeType: 'removed', fieldChanges: [] });
+    } else if (!oldScheme && newScheme) {
+      diffs.push({ schemeId: id, changeType: 'added', fieldChanges: [] });
+    } else if (oldScheme && newScheme) {
+      const fieldChanges: FieldChange[] = [];
+      if (oldScheme.type !== newScheme.type) {
+        fieldChanges.push({ fieldPath: ['type'], changeType: 'changed', oldValue: oldScheme.type, newValue: newScheme.type });
+      }
+      if (oldScheme.scheme !== newScheme.scheme) {
+        fieldChanges.push({ fieldPath: ['scheme'], changeType: 'changed', oldValue: oldScheme.scheme, newValue: newScheme.scheme });
+      }
+      if (oldScheme.in !== newScheme.in) {
+        fieldChanges.push({ fieldPath: ['in'], changeType: 'changed', oldValue: oldScheme.in, newValue: newScheme.in });
+      }
+      if (fieldChanges.length > 0) {
+        diffs.push({ schemeId: id, changeType: 'changed', fieldChanges });
+      }
+    }
+  }
+
+  return diffs;
+}
+
+export function diffSecurityRequirements(oldReqs: SecurityRequirement[], newReqs: SecurityRequirement[], path: string[], changes: FieldChange[]): void {
+  const oldSet = new Set(oldReqs.map(r => r.schemeId));
+  const newSet = new Set(newReqs.map(r => r.schemeId));
+
+  for (const schemeId of newSet) {
+    if (!oldSet.has(schemeId)) {
+      changes.push({ fieldPath: [...path, schemeId], changeType: 'added', newValue: schemeId });
+    }
+  }
+
+  for (const schemeId of oldSet) {
+    if (!newSet.has(schemeId)) {
+      changes.push({ fieldPath: [...path, schemeId], changeType: 'removed', oldValue: schemeId });
+    }
+  }
+
+  const oldMap = new Map(oldReqs.map(r => [r.schemeId, new Set(r.scopes)]));
+  const newMap = new Map(newReqs.map(r => [r.schemeId, new Set(r.scopes)]));
+
+  for (const [schemeId, oldScopes] of oldMap.entries()) {
+    const newScopes = newMap.get(schemeId);
+    if (newScopes) {
+      for (const scope of newScopes) {
+        if (!oldScopes.has(scope)) {
+          changes.push({ fieldPath: [...path, schemeId, 'scopes', scope], changeType: 'added', newValue: scope });
+        }
+      }
+      for (const scope of oldScopes) {
+        if (!newScopes.has(scope)) {
+          changes.push({ fieldPath: [...path, schemeId, 'scopes', scope], changeType: 'removed', oldValue: scope });
+        }
+      }
+    }
+  }
+}

package/src/diff/endpoint-differ.ts

@@ -0,0 +1,144 @@
+import type { Endpoint, EndpointDiff, FieldChange, Parameter, ResponseDef, RequestBody } from '../types/index.js';
+import { diffSchema } from './schema-differ.js';
+import { diffSecurityRequirements } from './auth-differ.js';
+
+export function diffEndpoints(oldEndpoints: Endpoint[], newEndpoints: Endpoint[]): EndpointDiff[] {
+  const diffs: EndpointDiff[] = [];
+  const oldMap = new Map(oldEndpoints.map(e => [e.id, e]));
+  const newMap = new Map(newEndpoints.map(e => [e.id, e]));
+
+  const allIds = new Set([...oldMap.keys(), ...newMap.keys()]);
+
+  for (const id of allIds) {
+    const oldE = oldMap.get(id);
+    const newE = newMap.get(id);
+
+    if (oldE && !newE) {
+      diffs.push({ type: 'removed', endpointId: id, path: oldE.path, method: oldE.method, oldEndpoint: oldE, fieldChanges: [] });
+    } else if (!oldE && newE) {
+      diffs.push({ type: 'added', endpointId: id, path: newE.path, method: newE.method, newEndpoint: newE, fieldChanges: [] });
+    } else if (oldE && newE) {
+      const fieldChanges: FieldChange[] = [];
+      
+      if (oldE.method !== newE.method) {
+        fieldChanges.push({ fieldPath: ['method'], changeType: 'changed', oldValue: oldE.method, newValue: newE.method });
+      }
+
+      if (oldE.path !== newE.path) {
+        fieldChanges.push({ fieldPath: ['path'], changeType: 'changed', oldValue: oldE.path, newValue: newE.path });
+      }
+
+      if (!!oldE.deprecated !== !!newE.deprecated) {
+        fieldChanges.push({ fieldPath: ['deprecated'], changeType: 'changed', oldValue: !!oldE.deprecated, newValue: !!newE.deprecated });
+      }
+
+      diffSecurityRequirements(oldE.security, newE.security, ['security'], fieldChanges);
+      diffParameters(oldE.parameters, newE.parameters, ['parameters'], fieldChanges);
+      diffRequestBody(oldE.requestBody, newE.requestBody, ['requestBody'], fieldChanges);
+      diffResponses(oldE.responses, newE.responses, ['responses'], fieldChanges);
+
+      if (fieldChanges.length > 0) {
+        diffs.push({ type: 'changed', endpointId: id, path: newE.path, method: newE.method, oldEndpoint: oldE, newEndpoint: newE, fieldChanges });
+      }
+    }
+  }
+
+  return diffs;
+}
+
+function diffParameters(oldParams: Parameter[], newParams: Parameter[], path: string[], changes: FieldChange[]) {
+  const oldMap = new Map(oldParams.map(p => [`${p.name}:${p.in}`, p]));
+  const newMap = new Map(newParams.map(p => [`${p.name}:${p.in}`, p]));
+  const allIds = new Set([...oldMap.keys(), ...newMap.keys()]);
+
+  for (const id of allIds) {
+    const o = oldMap.get(id);
+    const n = newMap.get(id);
+    if (o && !n) {
+      changes.push({ fieldPath: [...path, id], changeType: 'removed', oldValue: o });
+    } else if (!o && n) {
+      changes.push({ fieldPath: [...path, id], changeType: 'added', newValue: n });
+    } else if (o && n) {
+      if (!!o.required !== !!n.required) {
+        changes.push({ fieldPath: [...path, id, 'required'], changeType: 'changed', oldValue: !!o.required, newValue: !!n.required });
+      }
+      if (!!o.deprecated !== !!n.deprecated) {
+        changes.push({ fieldPath: [...path, id, 'deprecated'], changeType: 'changed', oldValue: !!o.deprecated, newValue: !!n.deprecated });
+      }
+      diffSchema(o.schema, n.schema, [...path, id, 'schema'], changes);
+    }
+  }
+}
+
+function diffRequestBody(oldReq: RequestBody | undefined, newReq: RequestBody | undefined, path: string[], changes: FieldChange[]) {
+  if (!oldReq && !newReq) return;
+  if (oldReq && !newReq) {
+    changes.push({ fieldPath: path, changeType: 'removed', oldValue: oldReq });
+    return;
+  }
+  if (!oldReq && newReq) {
+    changes.push({ fieldPath: path, changeType: 'added', newValue: newReq });
+    return;
+  }
+  if (oldReq && newReq) {
+    if (!!oldReq.required !== !!newReq.required) {
+      changes.push({ fieldPath: [...path, 'required'], changeType: 'changed', oldValue: !!oldReq.required, newValue: !!newReq.required });
+    }
+    const oldMedia = new Set(Object.keys(oldReq.content));
+    const newMedia = new Set(Object.keys(newReq.content));
+    for (const m of newMedia) {
+      if (!oldMedia.has(m)) changes.push({ fieldPath: [...path, 'content', m], changeType: 'added', newValue: newReq.content[m] });
+    }
+    for (const m of oldMedia) {
+      if (!newMedia.has(m)) {
+        changes.push({ fieldPath: [...path, 'content', m], changeType: 'removed', oldValue: oldReq.content[m] });
+      } else {
+        diffSchema(oldReq.content[m].schema, newReq.content[m].schema, [...path, 'content', m, 'schema'], changes);
+      }
+    }
+  }
+}
+
+function diffResponses(oldRes: ResponseDef[], newRes: ResponseDef[], path: string[], changes: FieldChange[]) {
+  const oldMap = new Map(oldRes.map(r => [r.statusCode, r]));
+  const newMap = new Map(newRes.map(r => [r.statusCode, r]));
+  const allCodes = new Set([...oldMap.keys(), ...newMap.keys()]);
+
+  for (const code of allCodes) {
+    const o = oldMap.get(code);
+    const n = newMap.get(code);
+    if (o && !n) {
+      changes.push({ fieldPath: [...path, code], changeType: 'removed', oldValue: o });
+    } else if (!o && n) {
+      changes.push({ fieldPath: [...path, code], changeType: 'added', newValue: n });
+    } else if (o && n) {
+      const oldMedia = new Set(Object.keys(o.content || {}));
+      const newMedia = new Set(Object.keys(n.content || {}));
+      for (const m of newMedia) {
+        if (!oldMedia.has(m)) changes.push({ fieldPath: [...path, code, 'content', m], changeType: 'added', newValue: n.content[m] });
+      }
+      for (const m of oldMedia) {
+        if (!newMedia.has(m)) {
+          changes.push({ fieldPath: [...path, code, 'content', m], changeType: 'removed', oldValue: o.content[m] });
+        } else {
+          diffSchema(o.content[m].schema, n.content[m].schema, [...path, code, 'content', m, 'schema'], changes);
+        }
+      }
+      const oldHeaders = new Set(Object.keys(o.headers || {}));
+      const newHeaders = new Set(Object.keys(n.headers || {}));
+      for (const h of newHeaders) {
+        if (!oldHeaders.has(h)) changes.push({ fieldPath: [...path, code, 'headers', h], changeType: 'added', newValue: n.headers![h] });
+      }
+      for (const h of oldHeaders) {
+        if (!newHeaders.has(h)) {
+          changes.push({ fieldPath: [...path, code, 'headers', h], changeType: 'removed', oldValue: o.headers![h] });
+        } else {
+          if (!!o.headers![h].required !== !!n.headers![h].required) {
+            changes.push({ fieldPath: [...path, code, 'headers', h, 'required'], changeType: 'changed', oldValue: !!o.headers![h].required, newValue: !!n.headers![h].required });
+          }
+          diffSchema(o.headers![h].schema, n.headers![h].schema, [...path, code, 'headers', h, 'schema'], changes);
+        }
+      }
+    }
+  }
+}

package/src/diff/index.ts

@@ -0,0 +1,13 @@
+import type { NormalizedAST, DiffSet } from '../types/index.js';
+import { diffEndpoints } from './endpoint-differ.js';
+import { diffSecuritySchemes } from './auth-differ.js';
+import { diffServers } from './server-differ.js';
+
+export function computeDiff(oldAST: NormalizedAST, newAST: NormalizedAST): DiffSet {
+  return {
+    endpointDiffs: diffEndpoints(oldAST.endpoints, newAST.endpoints),
+    schemaDiffs: [], 
+    securityDiffs: diffSecuritySchemes(oldAST.security, newAST.security),
+    serverDiffs: diffServers(oldAST.servers, newAST.servers)
+  };
+}

package/src/diff/schema-differ.ts

@@ -0,0 +1,70 @@
+import type { Schema, FieldChange } from '../types/index.js';
+
+export function diffSchema(oldSchema: Schema | undefined, newSchema: Schema | undefined, path: string[], changes: FieldChange[]): void {
+  if (!oldSchema && !newSchema) return;
+  
+  if (!oldSchema && newSchema) {
+    changes.push({ fieldPath: path, changeType: 'added', newValue: newSchema });
+    return;
+  }
+  
+  if (oldSchema && !newSchema) {
+    changes.push({ fieldPath: path, changeType: 'removed', oldValue: oldSchema });
+    return;
+  }
+  
+  if (oldSchema && newSchema) {
+    if (oldSchema.type !== newSchema.type) {
+      const oldTypes = Array.isArray(oldSchema.type) ? oldSchema.type : [oldSchema.type].filter(Boolean);
+      const newTypes = Array.isArray(newSchema.type) ? newSchema.type : [newSchema.type].filter(Boolean);
+      
+      const oldTypeStr = oldTypes.sort().join(',');
+      const newTypeStr = newTypes.sort().join(',');
+      
+      if (oldTypeStr !== newTypeStr) {
+        changes.push({ fieldPath: [...path, 'type'], changeType: 'changed', oldValue: oldSchema.type, newValue: newSchema.type });
+      }
+    }
+
+    if (oldSchema.nullable !== newSchema.nullable) {
+      changes.push({ fieldPath: [...path, 'nullable'], changeType: 'changed', oldValue: oldSchema.nullable, newValue: newSchema.nullable });
+    }
+
+    const oldReq = new Set(oldSchema.required || []);
+    const newReq = new Set(newSchema.required || []);
+    for (const req of newReq) {
+      if (!oldReq.has(req)) {
+        changes.push({ fieldPath: [...path, 'required', req], changeType: 'added', newValue: req });
+      }
+    }
+    for (const req of oldReq) {
+      if (!newReq.has(req)) {
+        changes.push({ fieldPath: [...path, 'required', req], changeType: 'removed', oldValue: req });
+      }
+    }
+
+    const oldEnum = new Set(oldSchema.enum || []);
+    const newEnum = new Set(newSchema.enum || []);
+    for (const val of newEnum) {
+      if (!oldEnum.has(val)) {
+        changes.push({ fieldPath: [...path, 'enum', String(val)], changeType: 'added', newValue: val });
+      }
+    }
+    for (const val of oldEnum) {
+      if (!newEnum.has(val)) {
+        changes.push({ fieldPath: [...path, 'enum', String(val)], changeType: 'removed', oldValue: val });
+      }
+    }
+
+    const oldProps = oldSchema.properties || {};
+    const newProps = newSchema.properties || {};
+    const allProps = new Set([...Object.keys(oldProps), ...Object.keys(newProps)]);
+    for (const prop of allProps) {
+      diffSchema(oldProps[prop], newProps[prop], [...path, 'properties', prop], changes);
+    }
+
+    if (oldSchema.items || newSchema.items) {
+      diffSchema(oldSchema.items, newSchema.items, [...path, 'items'], changes);
+    }
+  }
+}

package/src/diff/server-differ.ts

@@ -0,0 +1,22 @@
+import type { Server, ServerDiff } from '../types/index.js';
+
+export function diffServers(oldServers: Server[], newServers: Server[]): ServerDiff[] {
+  const diffs: ServerDiff[] = [];
+  const oldUrls = new Set(oldServers.map(s => s.url));
+  const newUrls = new Set(newServers.map(s => s.url));
+
+  for (const server of oldServers) {
+    if (!newUrls.has(server.url)) {
+      diffs.push({ changeType: 'removed', oldServer: server });
+    }
+  }
+
+  for (const server of newServers) {
+    if (!oldUrls.has(server.url)) {
+      diffs.push({ changeType: 'added', newServer: server });
+    }
+  }
+
+  // We could diff server variables or descriptions, but the main semantic change is added/removed
+  return diffs;
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+import type { ApidiffConfig, RunResult, SemanticChange } from './types/index.js';
+import { loadSpec } from './loader/index.js';
+import { parseSpec } from './parsers/index.js';
+import { computeDiff } from './diff/index.js';
+import { runRules } from './rules/index.js';
+import { DEFAULT_CONFIG } from './config/index.js';
+
+export * from './types/index.js';
+export { loadConfig } from './config/index.js';
+export { formatOutput } from './output/index.js';
+
+/**
+ * Runs the semantic API diffing process between two specifications.
+ * 
+ * @param oldSource - The path, URL, git ref, or raw string of the base specification
+ * @param newSource - The path, URL, git ref, or raw string of the head specification
+ * @param config - Optional configuration to override default rules and output settings
+ * @returns A promise that resolves to the RunResult containing the changes and statistics
+ */
+export async function runContent(
+  oldContent: string,
+  newContent: string,
+  config: Partial<ApidiffConfig> = {}
+): Promise<RunResult> {
+  const fullConfig = { ...DEFAULT_CONFIG, ...config } as ApidiffConfig;
+  const startMs = Date.now();
+
+  const [oldAST, newAST] = await Promise.all([
+    parseSpec({ content: oldContent }),
+    parseSpec({ content: newContent }),
+  ]);
+
+  const diffSet = computeDiff(oldAST, newAST);
+  const allChanges = runRules(diffSet, { oldAST, newAST, config: fullConfig });
+  const changes = filterChanges(allChanges, fullConfig);
+
+  return {
+    changes,
+    stats: computeStats(changes),
+    oldSpecMeta: oldAST.meta,
+    newSpecMeta: newAST.meta,
+    durationMs: Date.now() - startMs,
+  };
+}
+
+export async function run(
+  oldSource: string,
+  newSource: string,
+  config: Partial<ApidiffConfig> = {}
+): Promise<RunResult> {
+  const fullConfig = { ...DEFAULT_CONFIG, ...config } as ApidiffConfig;
+  const startMs = Date.now();
+
+  const [oldRaw, newRaw] = await Promise.all([
+    loadSpec(oldSource),
+    loadSpec(newSource),
+  ]);
+
+  const [oldAST, newAST] = await Promise.all([
+    parseSpec(oldRaw),
+    parseSpec(newRaw),
+  ]);
+
+  const diffSet = computeDiff(oldAST, newAST);
+
+  const allChanges = runRules(diffSet, { oldAST, newAST, config: fullConfig });
+
+  const changes = filterChanges(allChanges, fullConfig);
+
+  return {
+    changes,
+    stats: computeStats(changes),
+    oldSpecMeta: oldAST.meta,
+    newSpecMeta: newAST.meta,
+    durationMs: Date.now() - startMs,
+  };
+}
+
+function filterChanges(changes: SemanticChange[], config: ApidiffConfig): SemanticChange[] {
+  return changes;
+}
+
+function computeStats(changes: SemanticChange[]) {
+  const stats = { breaking: 0, warning: 0, info: 0, total: 0 };
+  for (const c of changes) {
+    if (c.severity === 'breaking') stats.breaking++;
+    else if (c.severity === 'warning') stats.warning++;
+    else stats.info++;
+    stats.total++;
+  }
+  return stats;
+}

package/src/loader/file-loader.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { LoadError } from '../types/errors.js';
+
+export function loadFile(source: string): { content: string; sourcePath: string } {
+  try {
+    const sourcePath = resolve(source);
+    const content = readFileSync(sourcePath, 'utf8');
+    return { content, sourcePath };
+  } catch (err: any) {
+    if (err.code === 'ENOENT') {
+      throw new LoadError(`file not found: ${source}`, err);
+    }
+    if (err.code === 'EACCES') {
+      throw new LoadError(`permission denied: ${source}`, err);
+    }
+    throw new LoadError(`failed to read file: ${source}`, err);
+  }
+}

package/src/loader/git-loader.ts

@@ -0,0 +1,22 @@
+import { execSync } from 'node:child_process';
+import { LoadError } from '../types/errors.js';
+
+export function loadGit(source: string): { content: string; sourcePath: string } {
+  // source format: "git:HEAD~1:path/to/api.yaml"
+  const match = source.match(/^git:([^:]+):(.+)$/);
+  if (!match) {
+    throw new LoadError(`invalid git source format: ${source}`);
+  }
+  const [, ref, filePath] = match;
+
+  try {
+    const content = execSync(`git show ${ref}:${filePath}`, { encoding: 'utf-8', stdio: 'pipe' });
+    return { content, sourcePath: filePath };
+  } catch (err: any) {
+    const stderr = err.stderr?.toString() || '';
+    if (stderr.includes('Not a valid object name') || stderr.includes('does not exist')) {
+      throw new LoadError(`git ref or path not found: ${ref}:${filePath}`, err);
+    }
+    throw new LoadError(`git command failed: ${source}`, err);
+  }
+}

package/src/loader/index.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { loadFile } from './file-loader.js';
+import { loadUrl } from './url-loader.js';
+import { loadGit } from './git-loader.js';
+import { LoadError } from '../types/errors.js';
+
+export interface RawSpec {
+  content: string;
+  sourcePath?: string;
+  format?: 'openapi3' | 'openapi2' | 'protobuf' | 'graphql';
+}
+
+export async function loadSpec(source: string): Promise<RawSpec> {
+  if (source === '-') {
+    try {
+      const content = readFileSync(0, 'utf-8');
+      return { content, sourcePath: undefined };
+    } catch (err: any) {
+      throw new LoadError('failed to read from stdin', err);
+    }
+  }
+
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    return await loadUrl(source);
+  }
+
+  if (source.startsWith('git:')) {
+    return loadGit(source);
+  }
+
+  return loadFile(source);
+}

package/src/loader/url-loader.ts

@@ -0,0 +1,25 @@
+import { LoadError } from '../types/errors.js';
+
+export async function loadUrl(source: string): Promise<{ content: string; sourcePath: string }> {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 10000);
+    const response = await fetch(source, { signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new LoadError(`failed to fetch url: ${source} (status: ${response.status})`);
+    }
+
+    const content = await response.text();
+    return { content, sourcePath: source };
+  } catch (err: any) {
+    if (err instanceof LoadError) {
+      throw err;
+    }
+    if (err.name === 'AbortError') {
+      throw new LoadError(`timeout fetching url: ${source}`, err);
+    }
+    throw new LoadError(`network error fetching url: ${source}`, err instanceof Error ? err : undefined);
+  }
+}