specdiff 0.0.0-stage → 0.1.1

package/dist/cli.js

@@ -0,0 +1,1628 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { parseArgs } from "util";
+
+// package.json
+var package_default = {
+  name: "specdiff",
+  version: "0.1.0",
+  description: "Compare two OpenAPI 3.x documents and classify every change as breaking, warning or safe.",
+  keywords: [
+    "openapi",
+    "openapi3",
+    "swagger",
+    "api",
+    "diff",
+    "breaking-changes",
+    "api-compatibility",
+    "contract",
+    "cli",
+    "ci"
+  ],
+  homepage: "https://specdiff.netlify.app/",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/yagnang-vyas/spec-diff.git"
+  },
+  bugs: {
+    url: "https://github.com/yagnang-vyas/spec-diff/issues"
+  },
+  license: "MIT",
+  author: "Yagnang Vyas",
+  type: "module",
+  bin: {
+    specdiff: "./dist/cli.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  engines: {
+    node: ">=22.19.0"
+  },
+  scripts: {
+    build: "tsup",
+    typecheck: "tsc --noEmit",
+    lint: "eslint . && prettier --check .",
+    test: "vitest run --coverage",
+    check: "npm run typecheck && npm run lint && npm run build && publint && npm run test",
+    prepack: "npm run build",
+    prepublishOnly: "npm run check"
+  },
+  dependencies: {
+    "@apidevtools/swagger-parser": "^13.1.0"
+  },
+  devDependencies: {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.5",
+    "@vitest/coverage-v8": "^5.0.5",
+    eslint: "^10.13.0",
+    "openapi-types": "^12.1.3",
+    prettier: "^3.9.10",
+    publint: "^0.3.25",
+    tsup: "^9.0.0",
+    typescript: "~5.9.3",
+    "typescript-eslint": "^8.72.0",
+    vitest: "^5.0.5",
+    yaml: "^2.9.1"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/load.ts
+import SwaggerParser from "@apidevtools/swagger-parser";
+
+// src/errors.ts
+var SpecdiffError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SpecdiffError";
+  }
+};
+
+// src/load.ts
+var SUPPORTED = /^3\.[01](\.\d+)?(-.+)?$/;
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function loadSpec(file) {
+  let document;
+  try {
+    document = await SwaggerParser.validate(file, {
+      // Stay offline and deterministic: only local files are resolved.
+      resolve: { http: false }
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SpecdiffError(`${file}: ${message}`);
+  }
+  const root = isObject(document) ? document : {};
+  const openapi = root.openapi;
+  if (typeof openapi !== "string" || !SUPPORTED.test(openapi)) {
+    const found = typeof openapi === "string" ? `OpenAPI ${openapi}` : `Swagger ${String(root.swagger)}`;
+    throw new SpecdiffError(
+      `${file}: unsupported specification (found ${found}); SpecDiff supports OpenAPI 3.0.x and 3.1.x`
+    );
+  }
+  const info = isObject(root.info) ? root.info : {};
+  return {
+    info: {
+      file,
+      openapi,
+      title: String(info.title),
+      version: String(info.version)
+    },
+    document: root
+  };
+}
+
+// src/model.ts
+var HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+];
+
+// src/normalize.ts
+function isObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function pathShape(template) {
+  return template.replace(/\{[^}]*\}/g, "{}");
+}
+function pathParamNames(template) {
+  return [...template.matchAll(/\{([^}]*)\}/g)].map((m) => m[1] ?? "");
+}
+function normalizeMediaType(mediaType) {
+  return (mediaType.split(";")[0] ?? "").trim().toLowerCase();
+}
+function normalizeStatus(status) {
+  return status.trim().toUpperCase() === "DEFAULT" ? "default" : status.trim().toUpperCase();
+}
+function parameterKey(param, paramNames) {
+  const location = String(param.in);
+  const name = String(param.name);
+  if (location === "path") {
+    const index = paramNames.indexOf(name);
+    return index >= 0 ? `path:#${index}` : `path:${name}`;
+  }
+  return `${location}:${location === "header" ? name.toLowerCase() : name}`;
+}
+function serialization(param) {
+  if (isObject2(param.content)) return "content";
+  const location = String(param.in);
+  const style = typeof param.style === "string" ? param.style : location === "query" || location === "cookie" ? "form" : "simple";
+  const explode = typeof param.explode === "boolean" ? param.explode : style === "form";
+  return `style=${style}, explode=${String(explode)}`;
+}
+function parameterSchema(param) {
+  if (isObject2(param.schema)) return { schema: param.schema, path: ["schema"] };
+  if (isObject2(param.content)) {
+    const [mediaType, entry] = Object.entries(param.content)[0] ?? [];
+    if (mediaType !== void 0) {
+      const schema = isObject2(entry) && isObject2(entry.schema) ? entry.schema : void 0;
+      return { schema, path: ["content", mediaType, "schema"] };
+    }
+  }
+  return { schema: void 0, path: ["schema"] };
+}
+function normalizeParameter(param, paramNames) {
+  const location = String(param.in);
+  const { schema, path } = parameterSchema(param);
+  return {
+    key: parameterKey(param, paramNames),
+    name: String(param.name),
+    in: location,
+    required: location === "path" ? true : param.required === true,
+    schema,
+    schemaPath: path,
+    serialization: serialization(param)
+  };
+}
+function mergeParameters(pathLevel, operationLevel, paramNames) {
+  const result = /* @__PURE__ */ new Map();
+  for (const list of [pathLevel, operationLevel]) {
+    for (const param of asArray(list)) {
+      if (!isObject2(param)) continue;
+      const normalized = normalizeParameter(param, paramNames);
+      result.set(normalized.key, normalized);
+    }
+  }
+  return result;
+}
+function normalizeContent(content) {
+  const result = /* @__PURE__ */ new Map();
+  if (!isObject2(content)) return result;
+  for (const [key, entry] of Object.entries(content)) {
+    const schema = isObject2(entry) && isObject2(entry.schema) ? entry.schema : void 0;
+    result.set(normalizeMediaType(key), { key, schema });
+  }
+  return result;
+}
+function normalizeBody(body) {
+  if (!isObject2(body)) return void 0;
+  return { required: body.required === true, content: normalizeContent(body.content) };
+}
+function normalizeResponses(responses) {
+  const result = /* @__PURE__ */ new Map();
+  if (!isObject2(responses)) return result;
+  for (const [key, response] of Object.entries(responses)) {
+    if (key.startsWith("x-")) continue;
+    const content = isObject2(response) ? normalizeContent(response.content) : /* @__PURE__ */ new Map();
+    result.set(normalizeStatus(key), { key, content });
+  }
+  return result;
+}
+function normalizeSecurity(security) {
+  return asArray(security).filter(isObject2).map((requirement) => {
+    const entries = Object.entries(requirement).sort(([a], [b]) => a.localeCompare(b)).map(([scheme, scopes]) => [scheme, asArray(scopes).map(String).sort()]);
+    return new Map(entries);
+  });
+}
+function normalizeOperation(method, operation, pathItem, paramNames, documentSecurity) {
+  return {
+    method,
+    deprecated: operation.deprecated === true,
+    parameters: mergeParameters(pathItem.parameters, operation.parameters, paramNames),
+    requestBody: normalizeBody(operation.requestBody),
+    responses: normalizeResponses(operation.responses),
+    security: "security" in operation ? normalizeSecurity(operation.security) : documentSecurity
+  };
+}
+function normalizeSpec(spec) {
+  const paths = /* @__PURE__ */ new Map();
+  const documentSecurity = normalizeSecurity(spec.document.security);
+  const rawPaths = isObject2(spec.document.paths) ? spec.document.paths : {};
+  for (const [template, pathItem] of Object.entries(rawPaths)) {
+    if (template.startsWith("x-") || !isObject2(pathItem)) continue;
+    const key = pathShape(template);
+    const existing = paths.get(key);
+    if (existing) {
+      throw new SpecdiffError(
+        `${spec.info.file}: paths "${existing.template}" and "${template}" have the same template shape and cannot be told apart`
+      );
+    }
+    const paramNames = pathParamNames(template);
+    const operations = /* @__PURE__ */ new Map();
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (isObject2(operation)) {
+        operations.set(
+          method,
+          normalizeOperation(method, operation, pathItem, paramNames, documentSecurity)
+        );
+      }
+    }
+    paths.set(key, { key, template, paramNames, operations });
+  }
+  return { info: spec.info, paths };
+}
+var UNSUPPORTED_KEYWORDS = [
+  "oneOf",
+  "anyOf",
+  "not",
+  "if",
+  "then",
+  "else",
+  "patternProperties",
+  "dependentSchemas",
+  "dependentRequired",
+  "prefixItems",
+  "contains",
+  "propertyNames",
+  "unevaluatedProperties",
+  "unevaluatedItems"
+];
+var SCALAR_CONSTRAINTS = [
+  "maxLength",
+  "minLength",
+  "maxItems",
+  "minItems",
+  "maxProperties",
+  "minProperties",
+  "uniqueItems",
+  "pattern",
+  "format",
+  "multipleOf"
+];
+function canonicalJson(value) {
+  const stack = [];
+  const walk = (v) => {
+    if (typeof v !== "object" || v === null) return JSON.stringify(v) ?? "undefined";
+    if (stack.includes(v)) return '"[Circular]"';
+    stack.push(v);
+    let out;
+    if (Array.isArray(v)) {
+      out = `[${v.map(walk).join(",")}]`;
+    } else {
+      const keys = Object.keys(v).sort();
+      out = `{${keys.map((k) => `${JSON.stringify(k)}:${walk(v[k])}`).join(",")}}`;
+    }
+    stack.pop();
+    return out;
+  };
+  return walk(value);
+}
+function asSchema(value) {
+  if (isObject2(value)) return value;
+  if (value === true) return {};
+  if (value === false) return { not: {} };
+  return void 0;
+}
+function typeList(type) {
+  if (typeof type === "string") return [type];
+  return asArray(type).filter((t) => typeof t === "string");
+}
+function collectMembers(schema, seen, out) {
+  if (seen.has(schema)) return;
+  seen.add(schema);
+  for (const member of asArray(schema.allOf)) {
+    const resolved = asSchema(member);
+    if (resolved) collectMembers(resolved, seen, out);
+  }
+  out.push(schema);
+}
+function boundOf(schema, limit, exclusiveKey) {
+  const plain = schema[limit];
+  const exclusive = schema[exclusiveKey];
+  if (typeof exclusive === "number") {
+    const base = typeof plain === "number" ? plain : void 0;
+    const upper = limit === "maximum";
+    if (base !== void 0 && (upper ? base < exclusive : base > exclusive)) {
+      return { value: base, exclusive: false };
+    }
+    return { value: exclusive, exclusive: true };
+  }
+  if (typeof plain === "number") return { value: plain, exclusive: exclusive === true };
+  return void 0;
+}
+var viewCache = /* @__PURE__ */ new WeakMap();
+function describeSchema(schema) {
+  const cached = viewCache.get(schema);
+  if (cached) return cached;
+  const view = buildView(schema);
+  viewCache.set(schema, view);
+  return view;
+}
+function emptyView() {
+  return {
+    anyType: true,
+    types: /* @__PURE__ */ new Set(),
+    nullable: false,
+    properties: /* @__PURE__ */ new Map(),
+    required: /* @__PURE__ */ new Set(),
+    items: [],
+    additionalProperties: void 0,
+    enumValues: void 0,
+    constraints: /* @__PURE__ */ new Map(),
+    upper: void 0,
+    lower: void 0,
+    readOnly: false,
+    writeOnly: false,
+    unsupported: /* @__PURE__ */ new Map()
+  };
+}
+function mergeType(view, member) {
+  let typed = false;
+  if (member.type !== void 0) {
+    const declared = typeList(member.type);
+    typed = true;
+    view.types = new Set(declared.filter((t) => t !== "null"));
+    view.nullable = declared.includes("null");
+  }
+  if (member.nullable === true) view.nullable = true;
+  if (member.readOnly === true) view.readOnly = true;
+  if (member.writeOnly === true) view.writeOnly = true;
+  return typed;
+}
+function mergeStructure(view, member, additional) {
+  if (isObject2(member.properties)) {
+    for (const [name, prop] of Object.entries(member.properties)) {
+      const resolved = asSchema(prop);
+      if (!resolved) continue;
+      const list = view.properties.get(name) ?? [];
+      list.push(resolved);
+      view.properties.set(name, list);
+    }
+  }
+  for (const name of asArray(member.required)) view.required.add(String(name));
+  const items = asSchema(member.items);
+  if (items) view.items.push(items);
+  if (member.additionalProperties === false) additional.forbidden = true;
+  else if (member.additionalProperties === true) additional.allowed = true;
+  else if (isObject2(member.additionalProperties))
+    additional.schemas.push(member.additionalProperties);
+}
+function mergeEnum(view, member) {
+  const values = Array.isArray(member.enum) ? member.enum : "const" in member ? [member.const] : void 0;
+  if (!values) return;
+  const next = new Map(values.map((v) => [canonicalJson(v), v]));
+  view.enumValues = view.enumValues ? new Map([...view.enumValues].filter(([k]) => next.has(k))) : next;
+}
+function mergeConstraints(view, member) {
+  for (const key of SCALAR_CONSTRAINTS) {
+    if (member[key] !== void 0) view.constraints.set(key, member[key]);
+  }
+  view.upper = boundOf(member, "maximum", "exclusiveMaximum") ?? view.upper;
+  view.lower = boundOf(member, "minimum", "exclusiveMinimum") ?? view.lower;
+  for (const key of UNSUPPORTED_KEYWORDS) {
+    if (member[key] !== void 0) {
+      view.unsupported.set(key, [...view.unsupported.get(key) ?? [], member[key]]);
+    }
+  }
+}
+function inferType(view) {
+  if (view.properties.size > 0 || view.additionalProperties !== void 0) {
+    view.anyType = false;
+    view.types = /* @__PURE__ */ new Set(["object"]);
+  } else if (view.items.length > 0) {
+    view.anyType = false;
+    view.types = /* @__PURE__ */ new Set(["array"]);
+  }
+}
+function buildView(schema) {
+  const members = [];
+  collectMembers(schema, /* @__PURE__ */ new Set(), members);
+  const view = emptyView();
+  const additional = { forbidden: false, allowed: false, schemas: [] };
+  let typed = false;
+  for (const member of members) {
+    typed = mergeType(view, member) || typed;
+    mergeStructure(view, member, additional);
+    mergeEnum(view, member);
+    mergeConstraints(view, member);
+  }
+  if (additional.forbidden) view.additionalProperties = false;
+  else if (additional.schemas.length > 0) view.additionalProperties = additional.schemas;
+  else if (additional.allowed) view.additionalProperties = true;
+  if (typed) view.anyType = false;
+  else inferType(view);
+  return view;
+}
+function typeLabel(view) {
+  if (view.anyType) return "any";
+  if (view.types.size === 0) return "null";
+  return [...view.types].sort().join(" | ");
+}
+
+// src/rules.ts
+var RULES = {
+  // Paths and operations
+  PATH_REMOVED: {
+    severity: "breaking",
+    summary: "path removed",
+    template: "path {path} removed"
+  },
+  PATH_ADDED: { severity: "safe", summary: "path added", template: "path {path} added" },
+  PATH_PARAM_RENAMED: {
+    severity: "info",
+    summary: "path template renamed with the same shape",
+    template: "path template renamed from {from} to {to} (same shape, treated as the same path)"
+  },
+  OP_REMOVED: {
+    severity: "breaking",
+    summary: "HTTP method removed from a path that still exists",
+    template: "operation {method} {path} removed"
+  },
+  OP_ADDED: {
+    severity: "safe",
+    summary: "HTTP method added",
+    template: "operation {method} {path} added"
+  },
+  OP_DEPRECATED: {
+    severity: "warning",
+    summary: "operation newly deprecated",
+    template: "operation is now deprecated"
+  },
+  // Parameters
+  PARAM_ADDED_REQUIRED: {
+    severity: "breaking",
+    summary: "new required parameter",
+    template: 'required {in} parameter "{name}" added'
+  },
+  PARAM_ADDED_OPTIONAL: {
+    severity: "safe",
+    summary: "new optional parameter",
+    template: 'optional {in} parameter "{name}" added'
+  },
+  PARAM_BECAME_REQUIRED: {
+    severity: "breaking",
+    summary: "parameter became required",
+    template: '{in} parameter "{name}" is now required'
+  },
+  PARAM_BECAME_OPTIONAL: {
+    severity: "safe",
+    summary: "parameter became optional",
+    template: '{in} parameter "{name}" is now optional'
+  },
+  PARAM_REMOVED: {
+    severity: "warning",
+    summary: "parameter removed",
+    template: '{in} parameter "{name}" removed'
+  },
+  PARAM_LOCATION_CHANGED: {
+    severity: "breaking",
+    summary: "parameter moved to a different location",
+    template: 'parameter "{name}" moved from {from} to {to}'
+  },
+  PARAM_SERIALIZATION_CHANGED: {
+    severity: "breaking",
+    summary: "effective style/explode changed",
+    template: '{in} parameter "{name}" serialization changed from ({from}) to ({to})'
+  },
+  // Request bodies
+  REQ_BODY_BECAME_REQUIRED: {
+    severity: "breaking",
+    summary: "request body became required, or a required body was added",
+    template: "request body is now required"
+  },
+  REQ_BODY_BECAME_OPTIONAL: {
+    severity: "safe",
+    summary: "request body became optional",
+    template: "request body is now optional"
+  },
+  REQ_BODY_ADDED: {
+    severity: "safe",
+    summary: "optional request body added",
+    template: "optional request body added"
+  },
+  REQ_BODY_REMOVED: {
+    severity: "warning",
+    summary: "request body removed",
+    template: "request body removed (servers may now reject or ignore it)"
+  },
+  REQ_MEDIA_TYPE_REMOVED: {
+    severity: "breaking",
+    summary: "request content type removed",
+    template: 'request content type "{mediaType}" removed'
+  },
+  REQ_MEDIA_TYPE_ADDED: {
+    severity: "safe",
+    summary: "request content type added",
+    template: 'request content type "{mediaType}" added'
+  },
+  // Request schemas (parameters and request bodies): stricter is breaking
+  REQ_PROPERTY_REQUIRED_ADDED: {
+    severity: "breaking",
+    summary: "property became required, or a required property was added",
+    template: "property {at} {what}"
+  },
+  REQ_PROPERTY_REQUIRED_REMOVED: {
+    severity: "safe",
+    summary: "property is no longer required",
+    template: "property {at} is no longer required"
+  },
+  REQ_PROPERTY_ADDED: {
+    severity: "safe",
+    summary: "optional property added",
+    template: "optional property {at} added"
+  },
+  REQ_PROPERTY_REMOVED: {
+    severity: "warning",
+    summary: "property removed",
+    template: "property {at} removed (servers may now reject or ignore it)"
+  },
+  REQ_ENUM_NARROWED: {
+    severity: "breaking",
+    summary: "enum value removed, or enum added to a free value",
+    template: "enum of {at} narrowed: {detail}"
+  },
+  REQ_ENUM_WIDENED: {
+    severity: "safe",
+    summary: "enum value added, or enum removed",
+    template: "enum of {at} widened: {detail}"
+  },
+  REQ_CONSTRAINT_TIGHTENED: {
+    severity: "breaking",
+    summary: "constraint tightened, or an opaque constraint added or changed",
+    template: "{constraint} of {at} {change}"
+  },
+  REQ_CONSTRAINT_LOOSENED: {
+    severity: "safe",
+    summary: "constraint loosened or removed",
+    template: "{constraint} of {at} {change}"
+  },
+  REQ_ADDITIONAL_PROPERTIES_DISALLOWED: {
+    severity: "breaking",
+    summary: "additionalProperties changed to false",
+    template: "additional properties of {at} are no longer allowed"
+  },
+  REQ_ADDITIONAL_PROPERTIES_ALLOWED: {
+    severity: "safe",
+    summary: "additionalProperties changed from false",
+    template: "additional properties of {at} are now allowed"
+  },
+  REQ_BECAME_NON_NULLABLE: {
+    severity: "breaking",
+    summary: "value that could be null no longer can",
+    template: "{at} no longer accepts null"
+  },
+  REQ_BECAME_NULLABLE: {
+    severity: "safe",
+    summary: "value that could not be null now can",
+    template: "{at} now accepts null"
+  },
+  // Responses: looser or lossy is breaking
+  RESP_STATUS_REMOVED: {
+    severity: "breaking",
+    summary: "documented status code removed (warning unless 2xx)",
+    template: "response status {status} removed"
+  },
+  RESP_STATUS_ADDED: {
+    severity: "safe",
+    summary: "status code added",
+    template: "response status {status} added"
+  },
+  RESP_MEDIA_TYPE_REMOVED: {
+    severity: "breaking",
+    summary: "response content type removed",
+    template: 'response content type "{mediaType}" removed'
+  },
+  RESP_MEDIA_TYPE_ADDED: {
+    severity: "safe",
+    summary: "response content type added",
+    template: 'response content type "{mediaType}" added'
+  },
+  RESP_PROPERTY_REMOVED: {
+    severity: "breaking",
+    summary: "property removed",
+    template: "property {at} removed"
+  },
+  RESP_PROPERTY_ADDED: {
+    severity: "safe",
+    summary: "property added",
+    template: "property {at} added"
+  },
+  RESP_PROPERTY_BECAME_OPTIONAL: {
+    severity: "breaking",
+    summary: "property removed from required",
+    template: "property {at} is no longer always present (removed from required)"
+  },
+  RESP_PROPERTY_BECAME_REQUIRED: {
+    severity: "safe",
+    summary: "property added to required",
+    template: "property {at} is now always present (added to required)"
+  },
+  RESP_BECAME_NULLABLE: {
+    severity: "breaking",
+    summary: "value can now be null",
+    template: "{at} can now be null"
+  },
+  RESP_BECAME_NON_NULLABLE: {
+    severity: "safe",
+    summary: "value can no longer be null",
+    template: "{at} can no longer be null"
+  },
+  RESP_ENUM_WIDENED: {
+    severity: "warning",
+    summary: "enum value added, or enum removed",
+    template: "enum of {at} widened: {detail}"
+  },
+  RESP_ENUM_NARROWED: {
+    severity: "safe",
+    summary: "enum value removed, or enum added to a free value",
+    template: "enum of {at} narrowed: {detail}"
+  },
+  RESP_CONSTRAINT_LOOSENED: {
+    severity: "breaking",
+    summary: "constraint loosened or removed (warning for opaque changes)",
+    template: "{constraint} of {at} {change}"
+  },
+  RESP_CONSTRAINT_TIGHTENED: {
+    severity: "safe",
+    summary: "constraint tightened or added",
+    template: "{constraint} of {at} {change}"
+  },
+  // Both directions
+  TYPE_CHANGED: {
+    severity: "breaking",
+    summary: "type changed (safe when the change is compatible in this direction)",
+    template: "type of {at} changed from {from} to {to}"
+  },
+  UNSUPPORTED_CONSTRUCT: {
+    severity: "info",
+    summary: "an unanalyzed keyword differs between versions",
+    template: "{what} at {at} (not analyzed, review manually)"
+  },
+  // Security
+  SECURITY_ADDED: {
+    severity: "breaking",
+    summary: "security requirement became stricter",
+    template: "security requirement became stricter (was {from}, now {to})"
+  },
+  SECURITY_RELAXED: {
+    severity: "safe",
+    summary: "security requirement became less strict",
+    template: "security requirement became less strict (was {from}, now {to})"
+  }
+};
+var RULE_IDS = Object.keys(RULES);
+function isRuleId(value) {
+  return Object.hasOwn(RULES, value);
+}
+function formatMessage(id, params = {}) {
+  return RULES[id].template.replace(/\{(\w+)\}/g, (_, name) => {
+    const value = params[name];
+    if (value === void 0) throw new Error(`rule ${id}: missing message parameter "${name}"`);
+    return String(value);
+  });
+}
+
+// src/diff/context.ts
+var Loc = class _Loc {
+  constructor(base, head) {
+    this.base = base;
+    this.head = head;
+  }
+  base;
+  head;
+  /** Descend into the same key in both documents (or different keys, e.g. a renamed path). */
+  child(baseKey, headKey = baseKey) {
+    return new _Loc(this.base && [...this.base, baseKey], this.head && [...this.head, headKey]);
+  }
+  /** An element that exists only in the base document. */
+  removed(...keys) {
+    return new _Loc(this.base && [...this.base, ...keys], null);
+  }
+  /** An element that exists only in the head document. */
+  added(...keys) {
+    return new _Loc(null, this.head && [...this.head, ...keys]);
+  }
+  /** Descend by independent key sequences, e.g. a parameter that moved. */
+  descend(baseKeys, headKeys) {
+    return new _Loc(
+      this.base && [...this.base, ...baseKeys],
+      this.head && [...this.head, ...headKeys]
+    );
+  }
+  toJSON() {
+    return { base: this.base?.join(".") ?? null, head: this.head?.join(".") ?? null };
+  }
+};
+function createEmitter(changes, operation) {
+  return (id, loc, params, options) => {
+    const text = formatMessage(id, params);
+    changes.push({
+      id,
+      severity: options?.severity ?? RULES[id].severity,
+      operation,
+      location: loc.toJSON(),
+      message: options?.scope ? `${options.scope}: ${text}` : text
+    });
+  };
+}
+
+// src/diff/schema.ts
+var MAX_DEPTH = 100;
+var ANY_SCHEMA = Object.freeze({});
+function diffSchema(base, head, loc, emit, direction, scope) {
+  const state = {
+    emit: (...args) => {
+      state.emitted += 1;
+      emit(...args);
+    },
+    direction,
+    scope,
+    active: /* @__PURE__ */ new Map(),
+    clean: /* @__PURE__ */ new Map(),
+    emitted: 0
+  };
+  compareSchemas(base ?? ANY_SCHEMA, head ?? ANY_SCHEMA, loc, [], state, 0);
+}
+function display(path) {
+  if (path.length === 0) return "value";
+  let text = "";
+  for (const segment of path) {
+    if (segment === "[]") text = `${text || "value"}[]`;
+    else text = text ? `${text}.${segment}` : segment;
+  }
+  return `"${text}"`;
+}
+function merged(list) {
+  return list.length === 1 && list[0] ? list[0] : { allOf: list };
+}
+function visibleProperties(view, direction) {
+  const hidden = direction === "request" ? "readOnly" : "writeOnly";
+  const result = /* @__PURE__ */ new Map();
+  for (const [name, list] of view.properties) {
+    const schema = merged(list);
+    if (!describeSchema(schema)[hidden]) result.set(name, schema);
+  }
+  return result;
+}
+function typesSubset(a, b) {
+  if (b.anyType) return true;
+  if (a.anyType) return false;
+  return [...a.types].every((t) => b.types.has(t) || t === "integer" && b.types.has("number"));
+}
+function typesDisjoint(a, b) {
+  if (a.anyType || b.anyType) return false;
+  const related = (t, other) => other.has(t) || t === "integer" && other.has("number") || t === "number" && other.has("integer");
+  return [...a.types].every((t) => !related(t, b.types));
+}
+function sameTypes(a, b) {
+  return a.anyType === b.anyType && a.types.size === b.types.size && [...a.types].every((t) => b.types.has(t));
+}
+function compareSchemas(base, head, loc, path, state, depth) {
+  const seen = state.active.get(base);
+  if (seen?.has(head) || state.clean.get(base)?.has(head)) return;
+  if (depth > MAX_DEPTH) {
+    state.emit(
+      "UNSUPPORTED_CONSTRUCT",
+      loc,
+      {
+        what: `nesting deeper than ${MAX_DEPTH} levels`,
+        at: display(path)
+      },
+      { scope: state.scope }
+    );
+    return;
+  }
+  const set = seen ?? /* @__PURE__ */ new Set();
+  set.add(head);
+  state.active.set(base, set);
+  const before = state.emitted;
+  try {
+    compareContents(base, head, loc, path, state, depth);
+  } finally {
+    set.delete(head);
+  }
+  if (state.emitted === before) {
+    const clean = state.clean.get(base) ?? /* @__PURE__ */ new Set();
+    clean.add(head);
+    state.clean.set(base, clean);
+  }
+}
+function compareContents(base, head, loc, path, state, depth) {
+  const b = describeSchema(base);
+  const h = describeSchema(head);
+  const at = display(path);
+  const emit = (id, where2, params, severity) => state.emit(id, where2, { at, ...params }, { scope: state.scope, severity });
+  compareTypes(b, h, loc, emit, state.direction);
+  compareNullability(b, h, loc, emit, state.direction);
+  compareUnsupported(b, h, loc, emit);
+  if (typesDisjoint(b, h)) return;
+  compareEnums(b, h, loc, emit, state.direction);
+  compareConstraints(b, h, loc, emit, state.direction);
+  if (b.types.has("object") && h.types.has("object")) {
+    compareObjects(b, h, loc, path, state, depth, emit);
+  }
+  if (b.types.has("array") && h.types.has("array") && b.items.length > 0 && h.items.length > 0) {
+    compareSchemas(
+      merged(b.items),
+      merged(h.items),
+      loc.child("items"),
+      [...path, "[]"],
+      state,
+      depth + 1
+    );
+  }
+}
+function compareTypes(b, h, loc, emit, direction) {
+  if (sameTypes(b, h)) return;
+  const compatible = direction === "request" ? typesSubset(b, h) : typesSubset(h, b);
+  emit(
+    "TYPE_CHANGED",
+    loc,
+    { from: typeLabel(b), to: typeLabel(h) },
+    compatible ? "safe" : "breaking"
+  );
+}
+function compareNullability(b, h, loc, emit, direction) {
+  if (b.anyType || h.anyType || b.nullable === h.nullable) return;
+  if (direction === "request") {
+    emit(h.nullable ? "REQ_BECAME_NULLABLE" : "REQ_BECAME_NON_NULLABLE", loc, {});
+  } else {
+    emit(h.nullable ? "RESP_BECAME_NULLABLE" : "RESP_BECAME_NON_NULLABLE", loc, {});
+  }
+}
+function listValues(values) {
+  return [...values].map((v) => canonicalJson(v)).sort().join(", ");
+}
+function compareEnums(b, h, loc, emit, direction) {
+  const be = b.enumValues;
+  const he = h.enumValues;
+  if (!be && !he) return;
+  const request = direction === "request";
+  const narrowed = request ? "REQ_ENUM_NARROWED" : "RESP_ENUM_NARROWED";
+  const widened = request ? "REQ_ENUM_WIDENED" : "RESP_ENUM_WIDENED";
+  if (!be && he) {
+    emit(narrowed, loc, { detail: `enum constraint added (${listValues(he.values())})` });
+  } else if (be && !he) {
+    emit(widened, loc, { detail: `enum constraint removed (was ${listValues(be.values())})` });
+  } else if (be && he) {
+    const removed = [...be].filter(([key]) => !he.has(key)).map(([, v]) => v);
+    const added = [...he].filter(([key]) => !be.has(key)).map(([, v]) => v);
+    if (removed.length > 0) emit(narrowed, loc, { detail: `removed ${listValues(removed)}` });
+    if (added.length > 0) emit(widened, loc, { detail: `added ${listValues(added)}` });
+  }
+}
+var MAX_KEYS = /* @__PURE__ */ new Set(["maxLength", "maxItems", "maxProperties"]);
+var MIN_KEYS = /* @__PURE__ */ new Set(["minLength", "minItems", "minProperties"]);
+function showBound(bound) {
+  return bound.exclusive ? `${bound.value} (exclusive)` : String(bound.value);
+}
+function describeChange(verdict, from, to) {
+  if (from === void 0) return `added (${String(to)})`;
+  if (to === void 0) return `removed (was ${from})`;
+  const word = verdict === "tighter" ? "tightened" : verdict === "looser" ? "loosened" : "changed";
+  return `${word} from ${from} to ${to}`;
+}
+function numericChange(constraint, from, to, upper, unsetValue) {
+  if (from === to) return void 0;
+  const effectiveFrom = from ?? unsetValue;
+  const effectiveTo = to ?? unsetValue;
+  if (effectiveFrom === effectiveTo) return void 0;
+  const tighter = upper ? effectiveTo < effectiveFrom : effectiveTo > effectiveFrom;
+  const verdict = tighter ? "tighter" : "looser";
+  return {
+    constraint,
+    verdict,
+    text: describeChange(verdict, from?.toString(), to?.toString())
+  };
+}
+function boundChange(constraint, from, to, upper) {
+  if (!from && !to) return void 0;
+  if (from && to && from.value === to.value && from.exclusive === to.exclusive) return void 0;
+  let verdict;
+  if (!from) verdict = "tighter";
+  else if (!to) verdict = "looser";
+  else if (from.value !== to.value) {
+    verdict = (upper ? to.value < from.value : to.value > from.value) ? "tighter" : "looser";
+  } else {
+    verdict = to.exclusive ? "tighter" : "looser";
+  }
+  return {
+    constraint,
+    verdict,
+    text: describeChange(verdict, from && showBound(from), to && showBound(to))
+  };
+}
+function opaqueChange(constraint, from, to) {
+  if (from === void 0 && to === void 0) return void 0;
+  if (canonicalJson(from) === canonicalJson(to)) return void 0;
+  const verdict = from === void 0 ? "tighter" : to === void 0 ? "looser" : "changed";
+  return {
+    constraint,
+    verdict,
+    text: describeChange(
+      verdict,
+      from === void 0 ? void 0 : canonicalJson(from),
+      to === void 0 ? void 0 : canonicalJson(to)
+    )
+  };
+}
+function constraintChanges(b, h) {
+  const out = [];
+  for (const key of SCALAR_CONSTRAINTS) {
+    const from = b.constraints.get(key);
+    const to = h.constraints.get(key);
+    if (MAX_KEYS.has(key) || MIN_KEYS.has(key)) {
+      out.push(
+        numericChange(
+          key,
+          typeof from === "number" ? from : void 0,
+          typeof to === "number" ? to : void 0,
+          MAX_KEYS.has(key),
+          MAX_KEYS.has(key) ? Infinity : 0
+        )
+      );
+    } else if (key === "uniqueItems") {
+      if (from === true !== (to === true)) {
+        const verdict = to === true ? "tighter" : "looser";
+        out.push({
+          constraint: key,
+          verdict,
+          text: describeChange(verdict, String(from === true), String(to === true))
+        });
+      }
+    } else {
+      out.push(opaqueChange(key, from, to));
+    }
+  }
+  out.push(
+    boundChange("maximum", b.upper, h.upper, true),
+    boundChange("minimum", b.lower, h.lower, false)
+  );
+  return out.filter((c) => c !== void 0);
+}
+function compareConstraints(b, h, loc, emit, direction) {
+  for (const { constraint, verdict, text } of constraintChanges(b, h)) {
+    const params = { constraint, change: text };
+    if (direction === "request") {
+      if (verdict === "looser") emit("REQ_CONSTRAINT_LOOSENED", loc, params);
+      else
+        emit(
+          "REQ_CONSTRAINT_TIGHTENED",
+          loc,
+          params,
+          verdict === "changed" ? "warning" : void 0
+        );
+    } else if (verdict === "tighter") {
+      emit("RESP_CONSTRAINT_TIGHTENED", loc, params);
+    } else {
+      emit("RESP_CONSTRAINT_LOOSENED", loc, params, verdict === "changed" ? "warning" : void 0);
+    }
+  }
+}
+function relevantNames(b, h, bProps, hProps) {
+  const hidden = (name, props, view) => view.properties.has(name) && !props.has(name);
+  return [.../* @__PURE__ */ new Set([...bProps.keys(), ...hProps.keys(), ...b.required, ...h.required])].filter((name) => !hidden(name, bProps, b) && !hidden(name, hProps, h)).sort();
+}
+function compareObjects(b, h, loc, path, state, depth, emit) {
+  const direction = state.direction;
+  const bProps = visibleProperties(b, direction);
+  const hProps = visibleProperties(h, direction);
+  for (const name of relevantNames(b, h, bProps, hProps)) {
+    const bs = bProps.get(name);
+    const hs = hProps.get(name);
+    const where2 = [...path, name];
+    const at = display(where2);
+    if (bs && !hs) {
+      const id = direction === "request" ? "REQ_PROPERTY_REMOVED" : "RESP_PROPERTY_REMOVED";
+      emit(id, loc.removed("properties", name), { at });
+    } else if (!bs && hs) {
+      emitPropertyAdded(h.required.has(name), loc.added("properties", name), at, direction, emit);
+    } else {
+      if (bs && hs) {
+        const here = loc.descend(["properties", name], ["properties", name]);
+        compareSchemas(bs, hs, here, where2, state, depth + 1);
+      }
+      const was = b.required.has(name);
+      compareRequired(was, h.required.has(name), loc.child("required"), at, direction, emit);
+    }
+  }
+  compareAdditionalProperties(b, h, loc, path, state, depth, emit);
+}
+function emitPropertyAdded(required, loc, at, direction, emit) {
+  if (direction === "response") emit("RESP_PROPERTY_ADDED", loc, { at });
+  else if (required) emit("REQ_PROPERTY_REQUIRED_ADDED", loc, { at, what: "added as required" });
+  else emit("REQ_PROPERTY_ADDED", loc, { at });
+}
+function compareRequired(was, now, loc, at, direction, emit) {
+  if (was === now) return;
+  if (direction === "request") {
+    if (now) emit("REQ_PROPERTY_REQUIRED_ADDED", loc, { at, what: "is now required" });
+    else emit("REQ_PROPERTY_REQUIRED_REMOVED", loc, { at });
+  } else {
+    emit(now ? "RESP_PROPERTY_BECAME_REQUIRED" : "RESP_PROPERTY_BECAME_OPTIONAL", loc, { at });
+  }
+}
+function additionalOf(view) {
+  if (view.additionalProperties === false) return false;
+  if (Array.isArray(view.additionalProperties)) return merged(view.additionalProperties);
+  return void 0;
+}
+function compareAdditionalProperties(b, h, loc, path, state, depth, emit) {
+  const from = additionalOf(b);
+  const to = additionalOf(h);
+  if (from === false && to === false) return;
+  if (from === false || to === false) {
+    if (state.direction === "request") {
+      emit(
+        to === false ? "REQ_ADDITIONAL_PROPERTIES_DISALLOWED" : "REQ_ADDITIONAL_PROPERTIES_ALLOWED",
+        loc.child("additionalProperties"),
+        {}
+      );
+    }
+    return;
+  }
+  if (from === void 0 && to === void 0) return;
+  compareSchemas(
+    from ?? ANY_SCHEMA,
+    to ?? ANY_SCHEMA,
+    loc.child("additionalProperties"),
+    [...path, "*"],
+    state,
+    depth + 1
+  );
+}
+function compareUnsupported(b, h, loc, emit) {
+  for (const keyword of UNSUPPORTED_KEYWORDS) {
+    const from = b.unsupported.get(keyword);
+    const to = h.unsupported.get(keyword);
+    if (!from && !to) continue;
+    if (from && to && canonicalJson(from) === canonicalJson(to)) continue;
+    const where2 = !from ? loc.added(keyword) : !to ? loc.removed(keyword) : loc.child(keyword);
+    emit("UNSUPPORTED_CONSTRUCT", where2, { what: `"${keyword}" differs between versions` });
+  }
+}
+
+// src/diff/parameters.ts
+function where(param) {
+  return ["parameters", param.in, param.name];
+}
+function extractMoves(removed, added) {
+  const moves = [];
+  for (const gone of [...removed]) {
+    const moved = added.find(
+      (p) => p.name.toLowerCase() === gone.name.toLowerCase() && p.in !== gone.in
+    );
+    if (!moved) continue;
+    removed.splice(removed.indexOf(gone), 1);
+    added.splice(added.indexOf(moved), 1);
+    moves.push([gone, moved]);
+  }
+  return moves;
+}
+function diffParameters(base, head, loc, emit) {
+  const removed = [...base.parameters.values()].filter((p) => !head.parameters.has(p.key));
+  const added = [...head.parameters.values()].filter((p) => !base.parameters.has(p.key));
+  for (const [from, to] of extractMoves(removed, added)) {
+    const params = { name: from.name, from: from.in, to: to.in };
+    emit("PARAM_LOCATION_CHANGED", loc.descend(where(from), where(to)), params);
+  }
+  for (const param of removed) {
+    emit("PARAM_REMOVED", loc.removed(...where(param)), { in: param.in, name: param.name });
+  }
+  for (const param of added) {
+    const id = param.required ? "PARAM_ADDED_REQUIRED" : "PARAM_ADDED_OPTIONAL";
+    emit(id, loc.added(...where(param)), { in: param.in, name: param.name });
+  }
+  for (const [key, b] of base.parameters) {
+    const h = head.parameters.get(key);
+    if (h) diffSharedParameter(b, h, loc, emit);
+  }
+}
+function diffSharedParameter(base, head, loc, emit) {
+  const here = loc.descend(where(base), where(head));
+  const names = { in: head.in, name: head.name };
+  if (!base.required && head.required) emit("PARAM_BECAME_REQUIRED", here, names);
+  if (base.required && !head.required) emit("PARAM_BECAME_OPTIONAL", here, names);
+  if (base.serialization !== head.serialization) {
+    const params = { ...names, from: base.serialization, to: head.serialization };
+    emit("PARAM_SERIALIZATION_CHANGED", here, params);
+  }
+  diffSchema(
+    base.schema,
+    head.schema,
+    loc.descend([...where(base), ...base.schemaPath], [...where(head), ...head.schemaPath]),
+    emit,
+    "request",
+    `${head.in} parameter "${head.name}"`
+  );
+}
+
+// src/diff/requestBody.ts
+function diffRequestBody(base, head, loc, emit) {
+  if (!base || !head) {
+    if (head) {
+      emit(head.required ? "REQ_BODY_BECAME_REQUIRED" : "REQ_BODY_ADDED", loc.added("requestBody"));
+    } else if (base) {
+      emit("REQ_BODY_REMOVED", loc.removed("requestBody"));
+    }
+    return;
+  }
+  const here = loc.child("requestBody");
+  if (!base.required && head.required) emit("REQ_BODY_BECAME_REQUIRED", here.child("required"));
+  if (base.required && !head.required) emit("REQ_BODY_BECAME_OPTIONAL", here.child("required"));
+  const content = here.child("content");
+  for (const [mediaType, entry] of base.content) {
+    if (!head.content.has(mediaType)) {
+      emit("REQ_MEDIA_TYPE_REMOVED", content.removed(entry.key), { mediaType: entry.key });
+    }
+  }
+  for (const [mediaType, entry] of head.content) {
+    const before = base.content.get(mediaType);
+    if (!before) {
+      emit("REQ_MEDIA_TYPE_ADDED", content.added(entry.key), { mediaType: entry.key });
+      continue;
+    }
+    diffSchema(
+      before.schema,
+      entry.schema,
+      content.descend([before.key, "schema"], [entry.key, "schema"]),
+      emit,
+      "request",
+      `request body ${entry.key}`
+    );
+  }
+}
+
+// src/diff/responses.ts
+function diffResponses(base, head, loc, emit) {
+  const statuses = [.../* @__PURE__ */ new Set([...base.responses.keys(), ...head.responses.keys()])].sort();
+  for (const status of statuses) {
+    const b = base.responses.get(status);
+    const h = head.responses.get(status);
+    if (b && !h) {
+      emit(
+        "RESP_STATUS_REMOVED",
+        loc.removed("responses", b.key),
+        { status: b.key },
+        {
+          // Only a documented success path is a hard contract; error responses are best-effort.
+          severity: status.startsWith("2") ? "breaking" : "warning"
+        }
+      );
+    } else if (!b && h) {
+      emit("RESP_STATUS_ADDED", loc.added("responses", h.key), { status: h.key });
+    } else if (b && h) {
+      diffResponseContent(b, h, loc.descend(["responses", b.key], ["responses", h.key]), emit);
+    }
+  }
+}
+function diffResponseContent(base, head, loc, emit) {
+  const content = loc.child("content");
+  for (const [mediaType, entry] of base.content) {
+    if (!head.content.has(mediaType)) {
+      const params = { mediaType: entry.key };
+      emit("RESP_MEDIA_TYPE_REMOVED", content.removed(entry.key), params, { scope: head.key });
+    }
+  }
+  for (const [mediaType, entry] of head.content) {
+    const before = base.content.get(mediaType);
+    if (!before) {
+      const params = { mediaType: entry.key };
+      emit("RESP_MEDIA_TYPE_ADDED", content.added(entry.key), params, { scope: head.key });
+      continue;
+    }
+    const here = content.descend([before.key, "schema"], [entry.key, "schema"]);
+    diffSchema(before.schema, entry.schema, here, emit, "response", `${head.key} ${entry.key}`);
+  }
+}
+
+// src/diff/security.ts
+var ANONYMOUS = /* @__PURE__ */ new Map();
+function satisfiedBy(needs, credentials) {
+  for (const [scheme, scopes] of needs) {
+    const held = credentials.get(scheme);
+    if (!held || !scopes.every((scope) => held.includes(scope))) return false;
+  }
+  return true;
+}
+function accepts(requirement, client) {
+  return requirement.length === 0 || requirement.some((alt) => satisfiedBy(alt, client));
+}
+function clients(requirement) {
+  return requirement.length === 0 ? [ANONYMOUS] : requirement;
+}
+function describeSecurity(requirement) {
+  if (requirement.length === 0) return "none";
+  return requirement.map((alt) => {
+    if (alt.size === 0) return "anonymous";
+    return [...alt].map(([scheme, scopes]) => scopes.length > 0 ? `${scheme}[${scopes.join(",")}]` : scheme).join(" + ");
+  }).join(" | ");
+}
+function diffSecurity(base, head, loc, emit) {
+  const params = { from: describeSecurity(base.security), to: describeSecurity(head.security) };
+  if (clients(base.security).some((client) => !accepts(head.security, client))) {
+    emit("SECURITY_ADDED", loc.child("security"), params);
+  } else if (clients(head.security).some((client) => !accepts(base.security, client))) {
+    emit("SECURITY_RELAXED", loc.child("security"), params);
+  }
+}
+
+// src/diff/operations.ts
+function diffPathOperations(base, head, pathLoc, changes) {
+  for (const method of HTTP_METHODS) {
+    const b = base.operations.get(method);
+    const h = head.operations.get(method);
+    const label = `${method.toUpperCase()} ${head.template}`;
+    const params = { method: method.toUpperCase(), path: head.template };
+    if (b && !h) {
+      createEmitter(changes, label)("OP_REMOVED", pathLoc.removed(method), params);
+    } else if (h && !b) {
+      createEmitter(changes, label)("OP_ADDED", pathLoc.added(method), params);
+    } else if (b && h) {
+      diffOperation(b, h, pathLoc.child(method), createEmitter(changes, label));
+    }
+  }
+}
+function diffOperation(base, head, loc, emit) {
+  if (!base.deprecated && head.deprecated) emit("OP_DEPRECATED", loc.child("deprecated"));
+  diffParameters(base, head, loc, emit);
+  diffRequestBody(base.requestBody, head.requestBody, loc, emit);
+  diffResponses(base, head, loc, emit);
+  diffSecurity(base, head, loc, emit);
+}
+
+// src/diff/paths.ts
+function diffPaths(base, head, changes) {
+  const keys = [.../* @__PURE__ */ new Set([...base.paths.keys(), ...head.paths.keys()])].sort();
+  for (const key of keys) {
+    const b = base.paths.get(key);
+    const h = head.paths.get(key);
+    if (b && !h) {
+      createEmitter(changes, b.template)("PATH_REMOVED", new Loc(["paths", b.template], null), {
+        path: b.template
+      });
+    } else if (h && !b) {
+      createEmitter(changes, h.template)("PATH_ADDED", new Loc(null, ["paths", h.template]), {
+        path: h.template
+      });
+    } else if (b && h) {
+      const loc = new Loc(["paths", b.template], ["paths", h.template]);
+      if (b.template !== h.template) {
+        createEmitter(changes, h.template)("PATH_PARAM_RENAMED", loc, {
+          from: b.template,
+          to: h.template
+        });
+      }
+      diffPathOperations(b, h, loc, changes);
+    }
+  }
+}
+
+// src/diff/index.ts
+var METHOD_RANK = new Map(HTTP_METHODS.map((m, i) => [m.toUpperCase(), i]));
+function splitOperation(operation) {
+  const match = /^([A-Z]+) (\/.*)$/.exec(operation);
+  if (!match) return { path: operation, rank: -1 };
+  return { path: match[2] ?? operation, rank: METHOD_RANK.get(match[1] ?? "") ?? 99 };
+}
+function compare(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function sortChanges(changes) {
+  const key = (c) => c.location.head ?? c.location.base ?? "";
+  return [...changes].sort((a, b) => {
+    const oa = splitOperation(a.operation);
+    const ob = splitOperation(b.operation);
+    return compare(oa.path, ob.path) || oa.rank - ob.rank || compare(key(a), key(b)) || compare(a.id, b.id) || compare(a.message, b.message) || compare(a.location.base ?? "", b.location.base ?? "");
+  });
+}
+function diffSpecs(base, head) {
+  const changes = [];
+  diffPaths(base, head, changes);
+  return sortChanges(changes);
+}
+async function compareFiles(baseFile, headFile) {
+  const [base, head] = await Promise.all([loadSpec(baseFile), loadSpec(headFile)]);
+  return {
+    base: base.info,
+    head: head.info,
+    changes: diffSpecs(normalizeSpec(base), normalizeSpec(head))
+  };
+}
+
+// src/report/index.ts
+var FORMATS = ["text", "json", "markdown"];
+function summarize(changes) {
+  const summary = { breaking: 0, warning: 0, safe: 0, info: 0, total: changes.length };
+  for (const change of changes) summary[change.severity] += 1;
+  return summary;
+}
+function visibleChanges(report) {
+  return report.includeSafe ? report.changes : report.changes.filter((c) => c.severity !== "safe");
+}
+function groupByOperation(changes) {
+  const groups = [];
+  for (const change of changes) {
+    const last = groups[groups.length - 1];
+    if (last && last[0] === change.operation) last[1].push(change);
+    else groups.push([change.operation, [change]]);
+  }
+  return groups;
+}
+function describeSpec(info) {
+  const name = [info.title, info.version].filter((part) => part !== "").join(" ");
+  return `${info.file} (${name ? `${name}, ` : ""}OpenAPI ${info.openapi})`;
+}
+
+// src/report/json.ts
+function renderJson(report) {
+  const visible = visibleChanges(report);
+  const summary = summarize(report.changes);
+  const output = {
+    schemaVersion: 1,
+    tool: report.tool,
+    base: report.base,
+    head: report.head,
+    changes: visible.map((c) => ({
+      id: c.id,
+      severity: c.severity,
+      operation: c.operation,
+      location: { base: c.location.base, head: c.location.head },
+      message: c.message
+    })),
+    summary: { ...summary, hiddenSafe: report.includeSafe ? 0 : summary.safe }
+  };
+  return `${JSON.stringify(output, null, 2)}
+`;
+}
+
+// src/report/markdown.ts
+function escapeMarkdown(text) {
+  return text.replace(/\r?\n/g, " ").replace(/[\\`*_[\]<>&|]/g, (ch) => {
+    if (ch === "<") return "&lt;";
+    if (ch === ">") return "&gt;";
+    if (ch === "&") return "&amp;";
+    return `\\${ch}`;
+  });
+}
+function codeSpan(text) {
+  const escaped = text.replace(/\|/g, "\\|");
+  return text.includes("`") ? `\`\` ${escaped} \`\`` : `\`${escaped}\``;
+}
+var LABELS = { breaking: "Breaking", warning: "Warning", safe: "Safe", info: "Info" };
+function renderMarkdown(report) {
+  const visible = visibleChanges(report);
+  const summary = summarize(report.changes);
+  const lines = [
+    "## SpecDiff report",
+    "",
+    `- Base: ${codeSpan(describeSpec(report.base))}`,
+    `- Head: ${codeSpan(describeSpec(report.head))}`,
+    "",
+    "| Severity | Changes |",
+    "| --- | ---: |",
+    `| Breaking | ${summary.breaking} |`,
+    `| Warning | ${summary.warning} |`,
+    `| Safe | ${summary.safe}${report.includeSafe || summary.safe === 0 ? "" : " (hidden)"} |`,
+    `| Info | ${summary.info} |`,
+    ""
+  ];
+  if (visible.length === 0) lines.push("No API changes detected.", "");
+  for (const [operation, changes] of groupByOperation(visible)) {
+    lines.push(
+      `### ${codeSpan(operation)}`,
+      "",
+      "| Severity | Rule | Change |",
+      "| --- | --- | --- |"
+    );
+    for (const c of changes) {
+      lines.push(`| ${LABELS[c.severity]} | ${codeSpan(c.id)} | ${escapeMarkdown(c.message)} |`);
+    }
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+
+// src/report/text.ts
+function renderText(report) {
+  const visible = visibleChanges(report);
+  const summary = summarize(report.changes);
+  const idWidth = Math.max(0, ...visible.map((c) => c.id.length));
+  const lines = [
+    `${report.tool.name} ${report.tool.version}`,
+    `base: ${describeSpec(report.base)}`,
+    `head: ${describeSpec(report.head)}`,
+    ""
+  ];
+  if (visible.length === 0) lines.push("No API changes detected.", "");
+  for (const [operation, changes] of groupByOperation(visible)) {
+    lines.push(operation);
+    for (const c of changes) {
+      lines.push(`  ${c.severity.toUpperCase().padEnd(8)}  ${c.id.padEnd(idWidth)}  ${c.message}`);
+    }
+    lines.push("");
+  }
+  const parts = [`${summary.breaking} breaking`, `${summary.warning} warning`];
+  if (report.includeSafe) parts.push(`${summary.safe} safe`);
+  parts.push(`${summary.info} info`);
+  let line = `Summary: ${parts.join(", ")}`;
+  if (!report.includeSafe && summary.safe > 0) {
+    line += ` (${summary.safe} safe hidden, use --include-safe to list them)`;
+  }
+  lines.push(line);
+  return `${lines.join("\n")}
+`;
+}
+
+// src/cli.ts
+var FAIL_ON = ["breaking", "warning", "never"];
+var EXIT = { ok: 0, changes: 1, usage: 2, interrupted: 130, pipeClosed: 141 };
+var HELP = `specdiff ${package_default.version}
+Compare two OpenAPI 3.x documents and classify every change as breaking, warning or safe.
+
+Usage:
+  specdiff <base> <head> [options]
+
+Options:
+  --format <text|json|markdown>   Output format (default: text)
+  --fail-on <breaking|warning|never>
+                                  Exit 1 when a change at or above this severity exists
+                                  (default: breaking)
+  --include-safe                  List safe changes (hidden by default)
+  --ignore <RULE_ID,...>          Ignore rules by ID (repeatable)
+  --version                       Print the version
+  --help                          Print this help
+
+Exit codes:
+  0    nothing at or above the --fail-on threshold
+  1    changes at or above the threshold
+  2    usage or input error (including invalid specs)
+  130  interrupted
+  141  output pipe closed early
+`;
+var UsageError = class extends Error {
+};
+function choice(flag, value, allowed) {
+  const found = allowed.find((candidate) => candidate === value);
+  if (found === void 0) {
+    throw new UsageError(`invalid ${flag} "${value}" (expected ${allowed.join(", ")})`);
+  }
+  return found;
+}
+function ignoredRules(entries) {
+  const ids = new Set(
+    entries.flatMap((entry) => entry.split(",")).map((id) => id.trim()).filter((id) => id !== "")
+  );
+  const unknown = [...ids].filter((id) => !isRuleId(id));
+  if (unknown.length > 0)
+    throw new UsageError(`unknown rule ID in --ignore: ${unknown.join(", ")}`);
+  return ids;
+}
+function parseOptions(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        format: { type: "string", default: "text" },
+        "fail-on": { type: "string", default: "breaking" },
+        "include-safe": { type: "boolean", default: false },
+        ignore: { type: "string", multiple: true },
+        version: { type: "boolean", default: false },
+        help: { type: "boolean", default: false }
+      }
+    });
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message : String(error));
+  }
+  const { values, positionals } = parsed;
+  if (values.help) return "help";
+  if (values.version) return "version";
+  const format = choice("--format", values.format, FORMATS);
+  const failOn = choice("--fail-on", values["fail-on"], FAIL_ON);
+  const ignore = ignoredRules(values.ignore ?? []);
+  const [base, head, ...extra] = positionals;
+  if (base === void 0 || head === void 0 || extra.length > 0) {
+    throw new UsageError("expected exactly two arguments: <base> <head>");
+  }
+  return { base, head, format, failOn, includeSafe: values["include-safe"], ignore };
+}
+var RENDERERS = {
+  text: renderText,
+  json: renderJson,
+  markdown: renderMarkdown
+};
+var FAILING = {
+  breaking: ["breaking"],
+  warning: ["breaking", "warning"],
+  never: []
+};
+async function run(argv, io) {
+  try {
+    const options = parseOptions(argv);
+    if (options === "help") {
+      io.stdout(HELP);
+      return EXIT.ok;
+    }
+    if (options === "version") {
+      io.stdout(`${package_default.version}
+`);
+      return EXIT.ok;
+    }
+    const comparison = await compareFiles(options.base, options.head);
+    const changes = comparison.changes.filter((c) => !options.ignore.has(c.id));
+    const report = {
+      tool: { name: "specdiff", version: package_default.version },
+      base: comparison.base,
+      head: comparison.head,
+      changes,
+      includeSafe: options.includeSafe
+    };
+    io.stdout(RENDERERS[options.format](report));
+    const failing = FAILING[options.failOn];
+    return changes.some((c) => failing.includes(c.severity)) ? EXIT.changes : EXIT.ok;
+  } catch (error) {
+    if (error instanceof UsageError) {
+      io.stderr(`specdiff: ${error.message}
+Run "specdiff --help" for usage.
+`);
+      return EXIT.usage;
+    }
+    if (error instanceof SpecdiffError) {
+      io.stderr(`specdiff: ${error.message}
+`);
+      return EXIT.usage;
+    }
+    const detail = error instanceof Error ? error.stack ?? error.message : String(error);
+    io.stderr(`specdiff: unexpected error: ${detail}
+`);
+    return EXIT.usage;
+  }
+}
+function isMain() {
+  const entry = process.argv[1];
+  if (entry === void 0) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (isMain()) {
+  process.on("SIGINT", () => process.exit(EXIT.interrupted));
+  process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE") process.exit(EXIT.pipeClosed);
+    throw error;
+  });
+  process.exitCode = await run(process.argv.slice(2), {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text)
+  });
+}
+export {
+  EXIT,
+  run
+};