@apidiff/core 1.0.0

package/src/parsers/protobuf/index.ts

@@ -0,0 +1,208 @@
+import protobuf from 'protobufjs';
+import type { NormalizedAST, Endpoint, Parameter, RequestBody, ResponseDef, ComponentMap, Schema } from '../../types/index.js';
+import type { RawSpec } from '../../loader/index.js';
+import type { ISpecParser } from '../base.js';
+import { ParseError } from '../../types/errors.js';
+
+export class ProtobufParser implements ISpecParser {
+  readonly format = 'protobuf';
+
+  canParse(raw: RawSpec): boolean {
+    return raw.format === 'protobuf' || raw.content.trim().startsWith('syntax = "proto');
+  }
+
+  async parse(raw: RawSpec): Promise<NormalizedAST> {
+    let root: protobuf.Root;
+    try {
+      // Create a virtual file to parse the content string
+      const parsed = protobuf.parse(raw.content, { keepCase: true });
+      root = parsed.root;
+    } catch (err: any) {
+      throw new ParseError('Failed to parse Protobuf spec', err.line, err.column, raw.sourcePath, err);
+    }
+
+    const meta = {
+      title: 'Protobuf API',
+      version: '1.0.0', // Protobuf doesn't have a standard version field
+      format: 'protobuf' as const,
+      rawVersion: '3' // Assume proto3 for now
+    };
+
+    const components: ComponentMap = {
+      schemas: {},
+      securitySchemes: {},
+      parameters: {},
+      responses: {},
+      headers: {},
+      requestBodies: {}
+    };
+
+    const endpoints: Endpoint[] = [];
+
+    // Recursively walk the AST
+    this.walkRoot(root, '', components, endpoints);
+
+    return {
+      meta,
+      servers: [],
+      endpoints,
+      components,
+      security: []
+    };
+  }
+
+  private walkRoot(node: protobuf.ReflectionObject, namespace: string, components: ComponentMap, endpoints: Endpoint[]) {
+    if (node instanceof protobuf.Type) {
+      // It's a Message
+      components.schemas[`${namespace}${node.name}`] = this.messageToSchema(node);
+    } else if (node instanceof protobuf.Enum) {
+      // It's an Enum
+      components.schemas[`${namespace}${node.name}`] = this.enumToSchema(node);
+    } else if (node instanceof protobuf.Service) {
+      // It's a Service
+      for (const method of node.methodsArray) {
+        endpoints.push(this.methodToEndpoint(method, `${namespace}${node.name}`));
+      }
+    } else if (node instanceof protobuf.Namespace) {
+      // Walk namespace children
+      const newNamespace = node.name ? `${namespace}${node.name}.` : namespace;
+      for (const child of node.nestedArray) {
+        this.walkRoot(child, newNamespace, components, endpoints);
+      }
+    }
+  }
+
+  private messageToSchema(message: protobuf.Type): Schema {
+    const properties: Record<string, Schema> = {};
+    const required: string[] = [];
+
+    for (const field of message.fieldsArray) {
+      const fieldSchema = this.typeToSchema(field);
+      // We attach the protobuf field number to an internal property so we can diff it
+      (fieldSchema as any).$protobufNumber = field.id;
+      
+      properties[field.name] = fieldSchema;
+      if (field.required) {
+        required.push(field.name);
+      }
+    }
+
+    const schema: Schema = {
+      type: 'object',
+      properties
+    };
+
+    if (required.length > 0) {
+      schema.required = required;
+    }
+
+    return schema;
+  }
+
+  private enumToSchema(enumObj: protobuf.Enum): Schema {
+    return {
+      type: 'string',
+      enum: Object.keys(enumObj.values)
+    };
+  }
+
+  private typeToSchema(field: protobuf.Field): Schema {
+    let schema: Schema = {};
+    
+    switch (field.type) {
+      case 'double':
+      case 'float':
+        schema.type = 'number';
+        schema.format = field.type;
+        break;
+      case 'int32':
+      case 'uint32':
+      case 'sint32':
+      case 'fixed32':
+      case 'sfixed32':
+        schema.type = 'integer';
+        schema.format = field.type;
+        break;
+      case 'int64':
+      case 'uint64':
+      case 'sint64':
+      case 'fixed64':
+      case 'sfixed64':
+        schema.type = 'integer';
+        schema.format = 'int64'; // or field.type
+        break;
+      case 'bool':
+        schema.type = 'boolean';
+        break;
+      case 'string':
+        schema.type = 'string';
+        break;
+      case 'bytes':
+        schema.type = 'string';
+        schema.format = 'byte';
+        break;
+      default:
+        // It's a reference to another message or enum
+        // In a real implementation we'd use a $ref, but we are flattening
+        // For simplicity, we just mark it as object and we could potentially reference it.
+        // Or if we can find the resolved type in the parent namespace:
+        schema.type = 'object'; // It's a message type ref
+        (schema as any).$ref = `#/components/schemas/${field.type}`;
+        break;
+    }
+
+    if (field.repeated) {
+      return {
+        type: 'array',
+        items: schema
+      };
+    }
+
+    return schema;
+  }
+
+  private methodToEndpoint(method: protobuf.Method, servicePath: string): Endpoint {
+    const id = `RPC:${servicePath}/${method.name}`;
+    const path = `${servicePath}/${method.name}`;
+
+    const requestBody: RequestBody = {
+      required: true,
+      content: {
+        'application/protobuf': {
+          schema: {
+            $ref: `#/components/schemas/${method.requestType}`
+          } as any
+        }
+      }
+    };
+
+    const responses: ResponseDef[] = [
+      {
+        statusCode: '200',
+        description: 'Successful response',
+        content: {
+          'application/protobuf': {
+            schema: {
+              $ref: `#/components/schemas/${method.responseType}`
+            } as any
+          }
+        },
+        headers: {}
+      }
+    ];
+
+    return {
+      id,
+      path,
+      method: 'RPC',
+      summary: method.comment || undefined,
+      tags: [servicePath],
+      deprecated: !!method.options?.deprecated,
+      security: [], // Protobuf doesn't specify security natively
+      parameters: [],
+      requestBody,
+      responses,
+      extensions: {}
+    };
+  }
+}

package/src/rules/auth/oauth-scope-removed.ts

@@ -0,0 +1,34 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class OauthScopeRemovedRule extends BaseRule {
+  id = 'OAUTH_SCOPE_REMOVED';
+  description = 'An OAuth scope was removed from a security requirement';
+  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] === 'security' && fc.fieldPath[2] === 'scopes' && fc.changeType === 'removed') {
+          const schemeId = fc.fieldPath[1];
+          const scope = fc.oldValue as string;
+          
+          changes.push(this.makeChange({
+            severity: 'breaking',
+            category: 'authentication',
+            message: `OAuth scope '${scope}' was removed from security requirement '${schemeId}'.`,
+            consequence: `Tokens granted with only the '${scope}' scope may no longer be accepted.`,
+            migration: `Ensure clients request one of the remaining supported scopes.`,
+            location: { path: ed.path, method: ed.method, field: fc.fieldPath.join('.') }
+          }, context));
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/auth/security-added.ts

@@ -0,0 +1,32 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class SecurityAddedRule extends BaseRule {
+  id = 'SECURITY_ADDED';
+  description = 'Authentication added to previously public endpoint';
+  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;
+      
+      const oldSec = ed.oldEndpoint?.security ?? [];
+      const newSec = ed.newEndpoint?.security ?? [];
+      
+      if (oldSec.length === 0 && newSec.length > 0) {
+        const schemes = newSec.map(s => s.schemeId).join(', ');
+        changes.push(this.makeChange({
+          severity: 'breaking',
+          category: 'authentication',
+          message: `${ed.method} ${ed.path} now requires authentication (${schemes}).`,
+          consequence: 'Clients without credentials receive 401 Unauthorized.',
+          migration: `Add Authorization header with required credentials to all ${ed.method} ${ed.path} requests.`,
+          location: { path: ed.path, method: ed.method }
+        }, context));
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/auth/security-removed.ts

@@ -0,0 +1,47 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class SecurityRemovedRule extends BaseRule {
+  id = 'SECURITY_REMOVED';
+  description = 'A global security scheme was removed';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    
+    // Check global security scheme definitions
+    for (const sd of diff.securityDiffs) {
+      if (sd.changeType === 'removed') {
+        changes.push(this.makeChange({
+          severity: 'breaking',
+          category: 'authentication',
+          message: `Security scheme '${sd.schemeId}' was removed.`,
+          consequence: `Clients using '${sd.schemeId}' for authentication will fail to authenticate.`,
+          migration: `Update clients to use a different, supported security scheme.`,
+          location: { field: `securitySchemes['${sd.schemeId}']` }
+        }, context));
+      }
+    }
+
+    // Check endpoint-level security requirements removed
+    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] === 'security' && fc.fieldPath.length === 2 && fc.changeType === 'removed') {
+          const schemeId = fc.oldValue as string;
+          changes.push(this.makeChange({
+            severity: 'breaking',
+            category: 'authentication',
+            message: `Security requirement '${schemeId}' was removed from the endpoint.`,
+            consequence: `Clients trying to authenticate with '${schemeId}' might fail if the server no longer accepts it.`,
+            migration: `Update clients to use one of the remaining security requirements.`,
+            location: { path: ed.path, method: ed.method, field: `security['${schemeId}']` }
+          }, context));
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/auth/security-scheme-type-changed.ts

@@ -0,0 +1,30 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class SecuritySchemeTypeChangedRule extends BaseRule {
+  id = 'SECURITY_SCHEME_TYPE_CHANGED';
+  description = 'The type of a security scheme was changed';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    
+    for (const sd of diff.securityDiffs) {
+      if (sd.changeType === 'changed') {
+        for (const fc of sd.fieldChanges) {
+          if (fc.fieldPath[0] === 'type') {
+            changes.push(this.makeChange({
+              severity: 'breaking',
+              category: 'authentication',
+              message: `Security scheme '${sd.schemeId}' changed type from '${fc.oldValue}' to '${fc.newValue}'.`,
+              consequence: `Clients using the old authentication type will fail to authenticate.`,
+              migration: `Update clients to authenticate using the new type '${fc.newValue}'.`,
+              location: { field: `securitySchemes['${sd.schemeId}'].type` }
+            }, context));
+          }
+        }
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/base.ts

@@ -0,0 +1,29 @@
+import type { DiffSet, RuleContext, SemanticChange, IRule, Severity, RuleCategory } from '../types/index.js';
+
+export abstract class BaseRule implements IRule {
+  abstract id: string;
+  abstract description: string;
+  abstract severity: Severity;
+
+  abstract apply(diff: DiffSet, context: RuleContext): SemanticChange[];
+
+  protected isIgnored(path: string, context: RuleContext): boolean {
+    for (const glob of context.config.ignorePaths) {
+      if (this.matchGlob(path, glob)) return true;
+    }
+    return false;
+  }
+
+  private matchGlob(path: string, glob: string): boolean {
+    const regex = glob.replace(/\*/g, '.*').replace(/\//g, '\\/');
+    return new RegExp(`^${regex}$`).test(path);
+  }
+
+  protected makeChange(details: { severity: Severity; category: RuleCategory; message: string; consequence: string; migration: string; location: SemanticChange['location']; ruleId?: string }, context: RuleContext): SemanticChange {
+    const { ruleId, ...rest } = details;
+    return {
+      ruleId: ruleId || this.id,
+      ...rest
+    };
+  }
+}

package/src/rules/endpoint/endpoint-added.ts

@@ -0,0 +1,26 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class EndpointAddedRule extends BaseRule {
+  id = 'ENDPOINT_ADDED';
+  description = 'A new endpoint was added';
+  severity = 'info' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'added') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+      
+      changes.push(this.makeChange({
+        severity: 'info',
+        category: 'endpoint',
+        message: `Endpoint ${ed.method} ${ed.path} was added.`,
+        consequence: 'Clients can now use this new endpoint.',
+        migration: 'No migration required.',
+        location: { path: ed.path, method: ed.method }
+      }, context));
+    }
+    return changes;
+  }
+}

package/src/rules/endpoint/endpoint-deprecated.ts

@@ -0,0 +1,29 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class EndpointDeprecatedRule extends BaseRule {
+  id = 'ENDPOINT_DEPRECATED';
+  description = 'An existing endpoint was marked as deprecated';
+  severity = 'warning' 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;
+      
+      const deprecatedChange = ed.fieldChanges.find(c => c.fieldPath[0] === 'deprecated' && c.newValue === true && c.oldValue === false);
+      if (deprecatedChange) {
+        changes.push(this.makeChange({
+          severity: 'warning',
+          category: 'endpoint',
+          message: `Endpoint ${ed.method} ${ed.path} was deprecated.`,
+          consequence: 'This endpoint is slated for future removal.',
+          migration: 'Plan to migrate away from this endpoint to its recommended alternative.',
+          location: { path: ed.path, method: ed.method }
+        }, context));
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/endpoint/endpoint-removed.ts

@@ -0,0 +1,26 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class EndpointRemovedRule extends BaseRule {
+  id = 'ENDPOINT_REMOVED';
+  description = 'An existing endpoint was removed entirely';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    for (const ed of diff.endpointDiffs) {
+      if (ed.type !== 'removed') continue;
+      if (this.isIgnored(ed.path, context)) continue;
+      
+      changes.push(this.makeChange({
+        severity: 'breaking',
+        category: 'endpoint',
+        message: `Endpoint ${ed.method} ${ed.path} was removed.`,
+        consequence: 'Clients calling this endpoint will receive a 404 Not Found error.',
+        migration: 'Migrate clients to use an alternative endpoint before removing this one.',
+        location: { path: ed.path, method: ed.method }
+      }, context));
+    }
+    return changes;
+  }
+}

package/src/rules/endpoint/http-method-changed.ts

@@ -0,0 +1,29 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class HttpMethodChangedRule extends BaseRule {
+  id = 'HTTP_METHOD_CHANGED';
+  description = 'The HTTP method for an endpoint 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;
+      
+      const methodChange = ed.fieldChanges.find(c => c.fieldPath[0] === 'method');
+      if (methodChange) {
+        changes.push(this.makeChange({
+          severity: 'breaking',
+          category: 'endpoint',
+          message: `Endpoint HTTP method changed from ${methodChange.oldValue} to ${methodChange.newValue}.`,
+          consequence: 'Clients using the old HTTP method will fail.',
+          migration: `Update client requests to use the ${methodChange.newValue} method.`,
+          location: { path: ed.path, method: ed.method }
+        }, context));
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/endpoint/path-changed.ts

@@ -0,0 +1,29 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class PathChangedRule extends BaseRule {
+  id = 'PATH_CHANGED';
+  description = 'The path string for an endpoint changed (e.g. parameter renamed)';
+  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;
+      
+      const pathChange = ed.fieldChanges.find(c => c.fieldPath[0] === 'path');
+      if (pathChange) {
+        changes.push(this.makeChange({
+          severity: 'info',
+          category: 'endpoint',
+          message: `Endpoint path changed from ${pathChange.oldValue} to ${pathChange.newValue}.`,
+          consequence: 'Clients may need to update routing or parameter names.',
+          migration: 'Review the path syntax changes.',
+          location: { path: ed.path, method: ed.method }
+        }, context));
+      }
+    }
+    return changes;
+  }
+}

package/src/rules/index.ts

@@ -0,0 +1,83 @@
+import type { IRule, DiffSet, RuleContext, SemanticChange } from '../types/index.js';
+import { SecurityAddedRule } from './auth/security-added.js';
+import { EndpointRemovedRule } from './endpoint/endpoint-removed.js';
+import { EndpointAddedRule } from './endpoint/endpoint-added.js';
+import { EndpointDeprecatedRule } from './endpoint/endpoint-deprecated.js';
+import { HttpMethodChangedRule } from './endpoint/http-method-changed.js';
+import { PathChangedRule } from './endpoint/path-changed.js';
+import { ResponseFieldRemovedRule } from './response/response-field-removed.js';
+import { ParamRequiredAddedRule } from './param/param-required-added.js';
+import { ParamRemovedRule } from './param/param-removed.js';
+import { ParamAddedRule } from './param/param-added.js';
+import { ParamDeprecatedRule } from './param/param-deprecated.js';
+import { ParamTypeChangedRule } from './param/param-type-changed.js';
+import { ParamLocationChangedRule } from './param/param-location-changed.js';
+import { ParamEnumValueRemovedRule } from './param/param-enum-value-removed.js';
+import { ParamEnumValueAddedRule } from './param/param-enum-value-added.js';
+import { ParamRequiredTrueToFalseRule } from './param/param-required-true-to-false.js';
+import { RequestBodyAddedRequiredRule } from './request/request-body-added-required.js';
+import { RequestBodyRemovedRule } from './request/request-body-removed.js';
+import { RequestContentTypeAddedRule } from './request/request-content-type-added.js';
+import { RequestContentTypeRemovedRule } from './request/request-content-type-removed.js';
+import { RequestFieldRemovedRule } from './request/request-field-removed.js';
+import { RequestFieldAddedRequiredRule } from './request/request-field-added-required.js';
+import { RequestFieldTypeChangedRule } from './request/request-field-type-changed.js';
+import { RequestRequiredFalseToTrueRule } from './request/request-required-false-to-true.js';
+import { ResponseFieldAddedRule } from './response/response-field-added.js';
+import { ResponseFieldTypeChangedRule } from './response/response-field-type-changed.js';
+import { ResponseStatusRemovedRule } from './response/response-status-removed.js';
+import { ResponseStatusAddedRule } from './response/response-status-added.js';
+import { ResponseMediaTypeRemovedRule } from './response/response-media-type-removed.js';
+import { ResponseMediaTypeAddedRule } from './response/response-media-type-added.js';
+import { ResponseHeaderRemovedRule } from './response/response-header-removed.js';
+import { ResponseHeaderAddedRequiredRule } from './response/response-header-added-required.js';
+import { SecurityRemovedRule } from './auth/security-removed.js';
+import { SecuritySchemeTypeChangedRule } from './auth/security-scheme-type-changed.js';
+import { OauthScopeRemovedRule } from './auth/oauth-scope-removed.js';
+import { ServerRemovedRule } from './meta/server-removed.js';
+
+export const BUILT_IN_RULES: IRule[] = [
+  new SecurityAddedRule(),
+  new EndpointRemovedRule(),
+  new EndpointAddedRule(),
+  new EndpointDeprecatedRule(),
+  new HttpMethodChangedRule(),
+  new PathChangedRule(),
+  new ResponseFieldRemovedRule(),
+  new ParamRequiredAddedRule(),
+  new ParamRemovedRule(),
+  new ParamAddedRule(),
+  new ParamDeprecatedRule(),
+  new ParamTypeChangedRule(),
+  new ParamLocationChangedRule(),
+  new ParamEnumValueRemovedRule(),
+  new ParamEnumValueAddedRule(),
+  new ParamRequiredTrueToFalseRule(),
+  new RequestBodyAddedRequiredRule(),
+  new RequestBodyRemovedRule(),
+  new RequestContentTypeAddedRule(),
+  new RequestContentTypeRemovedRule(),
+  new RequestFieldRemovedRule(),
+  new RequestFieldAddedRequiredRule(),
+  new RequestFieldTypeChangedRule(),
+  new RequestRequiredFalseToTrueRule(),
+  new ResponseFieldAddedRule(),
+  new ResponseFieldTypeChangedRule(),
+  new ResponseStatusRemovedRule(),
+  new ResponseStatusAddedRule(),
+  new ResponseMediaTypeRemovedRule(),
+  new ResponseMediaTypeAddedRule(),
+  new ResponseHeaderRemovedRule(),
+  new ResponseHeaderAddedRequiredRule(),
+  new SecurityRemovedRule(),
+  new SecuritySchemeTypeChangedRule(),
+  new OauthScopeRemovedRule(),
+  new ServerRemovedRule()
+];
+
+export function runRules(diff: DiffSet, context: RuleContext): SemanticChange[] {
+  const enabledRules = BUILT_IN_RULES.filter(
+    r => !context.config.disabledRules.includes(r.id)
+  );
+  return enabledRules.flatMap(r => r.apply(diff, context));
+}

package/src/rules/meta/server-removed.ts

@@ -0,0 +1,26 @@
+import { BaseRule } from '../base.js';
+import type { DiffSet, RuleContext, SemanticChange } from '../../types/index.js';
+
+export class ServerRemovedRule extends BaseRule {
+  id = 'SERVER_REMOVED';
+  description = 'A server was removed from the API';
+  severity = 'breaking' as const;
+
+  apply(diff: DiffSet, context: RuleContext): SemanticChange[] {
+    const changes: SemanticChange[] = [];
+    
+    for (const sd of diff.serverDiffs) {
+      if (sd.changeType === 'removed' && sd.oldServer) {
+        changes.push(this.makeChange({
+          severity: 'breaking',
+          category: 'server',
+          message: `Server URL '${sd.oldServer.url}' was removed.`,
+          consequence: `Clients routing traffic to '${sd.oldServer.url}' will eventually fail if the server is decommissioned.`,
+          migration: `Update clients to use one of the remaining server URLs.`,
+          location: { field: `servers` }
+        }, context));
+      }
+    }
+    return changes;
+  }
+}