Breaking changes

// Compares two versions of an OpenAPI document and lists the changes that would break existing clients.
//
// The rule behind every check: a response may give clients more than before, but not less; a request may ask
// clients for less than before, but not more.

import { resolveRef } from "./openapi.mjs";

const METHODS = ["get", "put", "post", "delete", "patch", "head", "options"];

export function breakingChanges(before, after) {
  const problems = [];

  for (const [path, item] of Object.entries(before.paths ?? {})) {
    for (const method of METHODS) {
      const old = item[method];
      if (!old) continue;
      const now = after.paths?.[path]?.[method];
      const op = `${method.toUpperCase()} ${path}`;

      if (!now) {
        problems.push(`${op}: operation removed`);
        continue;
      }

      // Requests: anything clients now have to send, that they didn't before, breaks the ones that don't send it.
      const oldParams = new Set((old.parameters ?? []).map((p) => `${p.in}:${p.name}`));
      for (const p of now.parameters ?? []) {
        if (p.required && !oldParams.has(`${p.in}:${p.name}`)) problems.push(`${op}: new required ${p.in} parameter "${p.name}"`);
      }
      if (now.requestBody?.required && !old.requestBody?.required) problems.push(`${op}: a request body is now required`);
      const oldBody = jsonSchema(old.requestBody);
      const newBody = jsonSchema(now.requestBody);
      if (oldBody && newBody) compare(oldBody, newBody, before, after, `${op} request body`, "request", problems);

      // Responses: anything clients relied on receiving, that they might no longer receive.
      for (const [status, response] of Object.entries(old.responses ?? {})) {
        if (!status.startsWith("2")) continue;
        const newResponse = now.responses?.[status];
        if (!newResponse) {
          problems.push(`${op}: response ${status} removed`);
          continue;
        }
        const oldSchema = jsonSchema(response);
        const newSchema = jsonSchema(newResponse);
        if (oldSchema && newSchema) compare(oldSchema, newSchema, before, after, `${op} ${status} response`, "response", problems);
      }
    }
  }

  return problems;
}

function jsonSchema(part) {
  return part?.content?.["application/json"]?.schema;
}

function compare(oldSchema, newSchema, before, after, at, direction, problems, seen = new Set()) {
  const key = `${oldSchema.$ref ?? ""}|${newSchema.$ref ?? ""}|${at}`;
  if (seen.has(key)) return;
  seen.add(key);

  const o = oldSchema.$ref ? resolveRef(before, oldSchema.$ref) : oldSchema;
  const n = newSchema.$ref ? resolveRef(after, newSchema.$ref) : newSchema;

  if (o.type && n.type && o.type !== n.type) {
    problems.push(`${at}: type changed from ${o.type} to ${n.type}`);
    return;
  }

  if (direction === "response" && !o.nullable && n.nullable) problems.push(`${at}: can now be null`);
  if (direction === "request" && o.nullable && !n.nullable) problems.push(`${at}: no longer accepts null`);

  if (o.enum && n.enum) {
    // A client sending a value that's gone is refused; a client receiving a value it never heard of may break.
    const lost = o.enum.filter((v) => !n.enum.includes(v));
    const gained = n.enum.filter((v) => !o.enum.includes(v));
    if (direction === "request" && lost.length) problems.push(`${at}: no longer accepts ${lost.map((v) => JSON.stringify(v)).join(", ")}`);
    if (direction === "response" && gained.length) problems.push(`${at}: can now be ${gained.map((v) => JSON.stringify(v)).join(", ")}`);
  }

  if (o.items && n.items) compare(o.items, n.items, before, after, `${at}[]`, direction, problems, seen);

  const oldProps = o.properties ?? {};
  const newProps = n.properties ?? {};
  const oldRequired = new Set(o.required ?? []);
  const newRequired = new Set(n.required ?? []);

  if (direction === "response") {
    for (const name of Object.keys(oldProps)) {
      if (!(name in newProps)) problems.push(`${at}: property "${name}" removed`);
      else {
        if (oldRequired.has(name) && !newRequired.has(name)) problems.push(`${at}: property "${name}" is no longer always present`);
        compare(oldProps[name], newProps[name], before, after, `${at}.${name}`, direction, problems, seen);
      }
    }
  } else {
    for (const name of newRequired) if (!oldRequired.has(name)) problems.push(`${at}: property "${name}" is now required`);
    for (const name of Object.keys(oldProps)) {
      if (name in newProps) compare(oldProps[name], newProps[name], before, after, `${at}.${name}`, direction, problems, seen);
      else if (n.additionalProperties === false) problems.push(`${at}: property "${name}" removed, so clients that send it are refused`);
    }
  }
}

// Makes four changes to a copy of the real spec, two safe and two breaking, and prints what the diff finds.
// Run: node demos/breaking.mjs

import { breakingChanges } from "../src/diff.mjs";
import { loadSpec } from "../src/openapi.mjs";

const before = await loadSpec();
const after = structuredClone(before);
const product = after.components.schemas.ProductResponse;

product.properties.discount = { type: "number" }; // 1. a new response field: safe
after.paths["/api/Products/featured"] = structuredClone(after.paths["/api/Products/categories"]); // 2. a new operation: safe
product.properties.price = { type: "string" }; // 3. price becomes a string: breaking
after.components.schemas.Todo.required = ["title", "dueDate"]; // 4. todos now need a due date: breaking

const problems = breakingChanges(before, after);
console.log(`${problems.length} breaking change(s):`);
for (const problem of problems) console.log(`  ${problem}`);

$ node demos/breaking.mjs
9 breaking change(s):
  GET /api/Products 200 response[].price: type changed from number to string
  POST /api/Products 201 response.data.price: type changed from number to string
  GET /api/Products/{id} 200 response.price: type changed from number to string
  PUT /api/Products/{id} 200 response.data.price: type changed from number to string
  GET /api/Products/category/{name} 200 response[].price: type changed from number to string
  POST /api/Todos request body: property "title" is now required
  POST /api/Todos request body: property "dueDate" is now required
  PUT /api/Todos/{id} request body: property "title" is now required
  PUT /api/Todos/{id} request body: property "dueDate" is now required

test("a response field that can now be null breaks clients that don't expect null", () => {
  const next = copy();
  productResponse(next).properties.title = { type: "string", nullable: true };
  assert.ok(breakingChanges(spec, next).includes("GET /api/Products/{id} 200 response.title: can now be null"));
});

test("a newly required request field breaks clients that don't send it", () => {
  const next = copy();
  productRequest(next).required = ["title", "price"];
  const problems = breakingChanges(spec, next);
  assert.ok(problems.includes('POST /api/Products request body: property "title" is now required'));
  assert.ok(problems.includes('POST /api/Products request body: property "price" is now required'));
});