@opengroundplan/core 0.1.1

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/negotiate.py

@@ -0,0 +1,94 @@
+"""Version negotiation: a pure function of the request, so it is testable without a server
+and reusable from any framework. Nothing here reads the environment."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from urllib.parse import parse_qs
+
+from .errors import UnsupportedApiVersionError
+from .versions import VersionPolicy, get_policy
+
+# Shapes a path segment must have to count as a version attempt. Without this,
+# `/api/orders` under the path strategy reads as a request for version "orders".
+_VERSION_SHAPED = re.compile(r"^(v\d+(\.\d+)?|\d{4}-\d{2}-\d{2})$", re.IGNORECASE)
+
+
+@dataclass(frozen=True, slots=True)
+class VersionResolution:
+    version: str
+    source: str
+    # What the client actually asked for. None when it asked for nothing.
+    requested: str | None = None
+
+
+def header_value(headers: Mapping[str, str], name: str) -> str | None:
+    wanted = name.lower()
+    for key, value in headers.items():
+        if key.lower() == wanted and value and value.strip():
+            return value.strip()
+    return None
+
+
+def version_from_accept(accept: str | None) -> str | None:
+    """Pulls ``version=<value>`` out of any media range in an Accept header."""
+    if not accept:
+        return None
+    for media_range in accept.split(","):
+        for parameter in media_range.split(";")[1:]:
+            name, _, value = parameter.partition("=")
+            if name.strip().lower() != "version":
+                continue
+            cleaned = value.strip().strip('"')
+            if cleaned:
+                return cleaned
+    return None
+
+
+def version_from_path(path: str, path_prefix: str, policy: VersionPolicy) -> str | None:
+    prefix = path_prefix.rstrip("/")
+    rest = path[len(prefix) :] if prefix and path.startswith(prefix) else path
+    segments = [segment for segment in rest.split("/") if segment]
+    if not segments:
+        return None
+    segment = segments[0]
+    return segment if policy.has(segment) or _VERSION_SHAPED.match(segment) else None
+
+
+def _requested(path: str, headers: Mapping[str, str], query: str, policy: VersionPolicy) -> str | None:
+    settings = policy.settings
+    if settings.strategy == "path":
+        return version_from_path(path, settings.path_prefix, policy)
+    if settings.strategy == "header":
+        return header_value(headers, settings.header_name)
+    if settings.strategy == "query":
+        values = parse_qs(query.lstrip("?")).get(settings.query_param, [])
+        return values[0].strip() if values and values[0].strip() else None
+    return version_from_accept(header_value(headers, "accept"))
+
+
+def resolve_version(
+    path: str,
+    headers: Mapping[str, str] | None = None,
+    query: str = "",
+    policy: VersionPolicy | None = None,
+) -> VersionResolution:
+    """Resolves the version to serve, raising UnsupportedApiVersionError when the client
+    named a version this deployment does not have and strict mode is on."""
+    policy = policy or get_policy()
+    settings = policy.settings
+    if not settings.enabled:
+        return VersionResolution(settings.default_version, "default")
+
+    requested = _requested(path, headers or {}, query, policy)
+    if requested is None:
+        return VersionResolution(settings.default_version, "default")
+
+    if not policy.has(requested):
+        if settings.strict:
+            raise UnsupportedApiVersionError(requested, policy.supported)
+        return VersionResolution(settings.default_version, "default", requested)
+
+    return VersionResolution(requested, settings.strategy, requested)

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/settings.py

@@ -0,0 +1,189 @@
+"""The only place an API-versioning default may appear.
+
+A version string, a header name, or a sunset date written at a call site is a bug;
+every other module in this package reads this table.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from datetime import date, datetime, timezone
+from functools import lru_cache
+
+ENV_PREFIX = "{{ apiVersionEnvPrefix }}"
+
+STRATEGIES = ("path", "header", "query", "accept")
+_TRUE = {"1", "true", "yes", "on"}
+_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+class ApiVersionConfigError(ValueError):
+    """Raised at startup for a policy that cannot be honoured."""
+
+
+@dataclass(frozen=True, slots=True)
+class Deprecation:
+    version: str
+    announced: date
+    sunset: date
+
+
+@dataclass(frozen=True, slots=True)
+class ApiVersionSettings:
+    """Typed defaults. Change a value here or in the environment, never at a call site."""
+
+    enabled: bool = True
+    strategy: str = "{{ apiVersionStrategy }}"
+    # Oldest first. Declaration order IS the ordering — no version grammar is parsed.
+    supported: tuple[str, ...] = field(
+        default_factory=lambda: tuple("{{ apiVersionSupported }}".split(","))
+    )
+    # Served when the client states none. Keep it the oldest supported version.
+    default_version: str = "{{ apiVersionDefault }}"
+    strict: bool = True
+    header_name: str = "{{ apiVersionHeaderName }}"
+    query_param: str = "{{ apiVersionQueryParam }}"
+    media_type: str = "{{ apiVersionMediaType }}"
+    path_prefix: str = "{{ apiVersionPathPrefix }}"
+    deprecations: tuple[Deprecation, ...] = ()
+    min_sunset_days: int = {{ apiVersionMinSunsetDays }}
+    policy_url: str = "{{ apiVersionPolicyUrl }}"
+    emit_response_header: bool = True
+    contract_dir: str = "{{ apiVersionContractDir }}"
+
+
+class _Reader:
+    def __init__(self, env: Mapping[str, str]) -> None:
+        self._env = env
+
+    def raw(self, key: str) -> str | None:
+        value = self._env.get(f"{ENV_PREFIX}_{key}")
+        return value.strip() if value and value.strip() else None
+
+    def raw_allow_empty(self, key: str, fallback: str) -> str:
+        """Keys where "" is a real answer — no path prefix, no published policy — not "unset"."""
+        value = self._env.get(f"{ENV_PREFIX}_{key}")
+        return fallback if value is None else value.strip()
+
+    def flag(self, key: str, fallback: bool) -> bool:
+        value = self.raw(key)
+        return fallback if value is None else value.lower() in _TRUE
+
+    def number(self, key: str, fallback: int) -> int:
+        value = self.raw(key)
+        if value is None:
+            return fallback
+        try:
+            parsed = int(value)
+        except ValueError as exc:  # fail at startup, not at the first request
+            raise ApiVersionConfigError(f"{ENV_PREFIX}_{key} must be an integer, got {value!r}") from exc
+        if parsed < 0:
+            raise ApiVersionConfigError(f"{ENV_PREFIX}_{key} must be non-negative, got {parsed}")
+        return parsed
+
+    def csv(self, key: str, fallback: tuple[str, ...]) -> tuple[str, ...]:
+        value = self.raw(key)
+        if value is None:
+            return fallback
+        return tuple(item.strip() for item in value.split(",") if item.strip())
+
+    def strategy(self, key: str, fallback: str) -> str:
+        value = self.raw(key)
+        if value is None:
+            return fallback
+        if value.lower() not in STRATEGIES:
+            raise ApiVersionConfigError(
+                f"{ENV_PREFIX}_{key} must be one of {', '.join(STRATEGIES)}, got {value!r}"
+            )
+        return value.lower()
+
+    def deprecations(self, key: str, fallback: tuple[Deprecation, ...]) -> tuple[Deprecation, ...]:
+        value = self.raw(key)
+        if value is None:
+            return fallback
+        return tuple(_parse_deprecation(key, entry.strip()) for entry in value.split(",") if entry.strip())
+
+
+def _parse_deprecation(key: str, entry: str) -> Deprecation:
+    parts = [part.strip() for part in entry.split(":")]
+    if len(parts) != 3 or not all(parts):
+        raise ApiVersionConfigError(f"{ENV_PREFIX}_{key} entry {entry!r} must be version:announced:sunset")
+    version, announced, sunset = parts
+    return Deprecation(version, _parse_date(key, version, "announcement", announced), _parse_date(key, version, "sunset", sunset))
+
+
+def _parse_date(key: str, version: str, label: str, value: str) -> date:
+    if not _ISO_DATE.match(value):
+        raise ApiVersionConfigError(
+            f"{ENV_PREFIX}_{key}: {version} has an invalid {label} date {value!r}, expected YYYY-MM-DD"
+        )
+    try:
+        return date.fromisoformat(value)
+    except ValueError as exc:
+        raise ApiVersionConfigError(
+            f"{ENV_PREFIX}_{key}: {version} has an invalid {label} date {value!r}"
+        ) from exc
+
+
+def epoch_seconds(day: date) -> int:
+    return int(datetime(day.year, day.month, day.day, tzinfo=timezone.utc).timestamp())
+
+
+def _validate(settings: ApiVersionSettings) -> ApiVersionSettings:
+    """A default outside the supported set, or a sunset inside the notice window, is a
+    promise already broken. Finding it here costs a restart; finding it later costs the client."""
+    if not settings.supported:
+        raise ApiVersionConfigError(f"{ENV_PREFIX}_SUPPORTED must list at least one version")
+    if len(set(settings.supported)) != len(settings.supported):
+        raise ApiVersionConfigError(f"{ENV_PREFIX}_SUPPORTED repeats a version")
+    if settings.default_version not in settings.supported:
+        raise ApiVersionConfigError(
+            f"{ENV_PREFIX}_DEFAULT {settings.default_version!r} is not in "
+            f"{ENV_PREFIX}_SUPPORTED ({', '.join(settings.supported)})"
+        )
+    for deprecation in settings.deprecations:
+        if deprecation.version not in settings.supported:
+            raise ApiVersionConfigError(
+                f"{ENV_PREFIX}_DEPRECATED names {deprecation.version!r}, "
+                f"which is not in {ENV_PREFIX}_SUPPORTED"
+            )
+        notice = (deprecation.sunset - deprecation.announced).days
+        if notice < settings.min_sunset_days:
+            raise ApiVersionConfigError(
+                f"{deprecation.version} gives {notice} days of notice, "
+                f"below {ENV_PREFIX}_MIN_SUNSET_DAYS ({settings.min_sunset_days})"
+            )
+    return settings
+
+
+def load_settings(env: Mapping[str, str] | None = None) -> ApiVersionSettings:
+    reader = _Reader(os.environ if env is None else env)
+    defaults = ApiVersionSettings()
+    return _validate(
+        replace(
+            defaults,
+            enabled=reader.flag("ENABLED", defaults.enabled),
+            strategy=reader.strategy("STRATEGY", defaults.strategy),
+            supported=reader.csv("SUPPORTED", defaults.supported),
+            default_version=reader.raw("DEFAULT") or defaults.default_version,
+            strict=reader.flag("STRICT", defaults.strict),
+            header_name=reader.raw("HEADER_NAME") or defaults.header_name,
+            query_param=reader.raw("QUERY_PARAM") or defaults.query_param,
+            media_type=reader.raw("MEDIA_TYPE") or defaults.media_type,
+            path_prefix=reader.raw_allow_empty("PATH_PREFIX", defaults.path_prefix),
+            deprecations=reader.deprecations("DEPRECATED", defaults.deprecations),
+            min_sunset_days=reader.number("MIN_SUNSET_DAYS", defaults.min_sunset_days),
+            policy_url=reader.raw_allow_empty("POLICY_URL", defaults.policy_url),
+            emit_response_header=reader.flag("EMIT_RESPONSE_HEADER", defaults.emit_response_header),
+            contract_dir=reader.raw("CONTRACT_DIR") or defaults.contract_dir,
+        )
+    )
+
+
+@lru_cache
+def get_settings() -> ApiVersionSettings:
+    """Cached so the environment is read once and every caller shares one instance."""
+    return load_settings()

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/snapshot.py

@@ -0,0 +1,74 @@
+"""Reading and writing committed contract snapshots — the only part that touches disk."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .contract import ContractChange, breaking_changes, diff_contracts, format_changes
+from .settings import ENV_PREFIX, ApiVersionSettings, get_settings
+
+# Set to "1" to accept the current shape as the new baseline. Never set it in CI.
+UPDATE_ENV_KEY = f"{ENV_PREFIX}_UPDATE_CONTRACTS"
+
+
+class ContractBrokenError(AssertionError):
+    def __init__(self, changes: list[ContractChange]) -> None:
+        super().__init__(f"Contract broken for shipped clients:\n{format_changes(changes)}")
+        self.changes = changes
+
+
+@dataclass(frozen=True, slots=True)
+class VerifyResult:
+    changes: list[ContractChange]
+    # True when no baseline existed and one was written.
+    created: bool
+
+
+def snapshot_path(version: str, settings: ApiVersionSettings | None = None) -> Path:
+    settings = settings or get_settings()
+    return Path(settings.contract_dir) / f"{version}.json"
+
+
+def load_snapshot(version: str, settings: ApiVersionSettings | None = None) -> dict[str, Any] | None:
+    path = snapshot_path(version, settings)
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def save_snapshot(snapshot: dict[str, Any], settings: ApiVersionSettings | None = None) -> Path:
+    path = snapshot_path(snapshot["version"], settings)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Sorted keys so a diff shows contract changes, not serialization noise.
+    path.write_text(json.dumps(snapshot, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def verify_contract(
+    current: dict[str, Any],
+    update: bool | None = None,
+    settings: ApiVersionSettings | None = None,
+) -> VerifyResult:
+    """Compares the live contract with what is committed. Raises on a breaking change;
+    additive changes are returned so a test can report them and the author can refresh the
+    baseline in the same commit that introduced them."""
+    settings = settings or get_settings()
+    if update is None:
+        update = os.environ.get(UPDATE_ENV_KEY) == "1"
+
+    baseline = load_snapshot(current["version"], settings)
+    if baseline is None:
+        save_snapshot(current, settings)
+        return VerifyResult([], True)
+
+    changes = diff_contracts(baseline, current)
+    breaking = breaking_changes(changes)
+    if breaking and not update:
+        raise ContractBrokenError(breaking)
+    if update:
+        save_snapshot(current, settings)
+    return VerifyResult(changes, False)

package/templates/layers/api-versioning/files/src/__solutionName.snake__/apiversion/versions.py

@@ -0,0 +1,70 @@
+"""The version policy: what is supported, what order versions are in, what is on the way out.
+
+Ordering is the position in the supported list, so callers never parse a version string
+and ``v10`` never sorts before ``v9``.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+
+from .settings import ApiVersionSettings, Deprecation, get_settings
+
+
+class UnknownVersionError(ValueError):
+    """Raised by policy lookups. Request handling uses UnsupportedApiVersionError instead."""
+
+
+class VersionPolicy:
+    def __init__(self, settings: ApiVersionSettings | None = None) -> None:
+        self.settings = settings or get_settings()
+        self._order = {version: index for index, version in enumerate(self.settings.supported)}
+        self._deprecations = {item.version: item for item in self.settings.deprecations}
+
+    @property
+    def supported(self) -> tuple[str, ...]:
+        return self.settings.supported
+
+    @property
+    def latest(self) -> str:
+        return self.settings.supported[-1]
+
+    @property
+    def oldest(self) -> str:
+        return self.settings.supported[0]
+
+    @property
+    def default_version(self) -> str:
+        return self.settings.default_version
+
+    def has(self, version: str) -> bool:
+        return version in self._order
+
+    def rank(self, version: str) -> int:
+        if version not in self._order:
+            raise UnknownVersionError(
+                f"Unknown API version {version!r}; supported: {', '.join(self.supported)}"
+            )
+        return self._order[version]
+
+    def compare(self, a: str, b: str) -> int:
+        """Negative when ``a`` is older, positive when newer, zero when equal."""
+        return self.rank(a) - self.rank(b)
+
+    def deprecation_for(self, version: str) -> Deprecation | None:
+        return self._deprecations.get(version)
+
+    def overdue(self, today: date | None = None) -> tuple[Deprecation, ...]:
+        """Versions past their sunset date that are still being served."""
+        now = today or date.today()
+        return tuple(item for item in self.settings.deprecations if item.sunset <= now)
+
+
+_policy: VersionPolicy | None = None
+
+
+def get_policy() -> VersionPolicy:
+    global _policy
+    if _policy is None:
+        _policy = VersionPolicy()
+    return _policy

package/templates/layers/api-versioning/files/src/apiversion/client/pinned-fetch.ts

@@ -0,0 +1,89 @@
+/**
+ * Client side of the same contract. A shipped client pins the version it was built
+ * against — an unpinned client inherits whatever the server defaults to, which is exactly
+ * the failure this layer exists to prevent.
+ *
+ * Config is passed in rather than read from the environment, so this module works
+ * unchanged in a browser bundle, in an SDK, and in a server-to-server call.
+ */
+
+export type PinStrategy = 'path' | 'header' | 'query' | 'accept';
+
+export interface PinnedClientOptions {
+  baseUrl: string;
+  version: string;
+  strategy?: PinStrategy;
+  headerName?: string;
+  queryParam?: string;
+  mediaType?: string;
+  pathPrefix?: string;
+  fetch?: typeof globalThis.fetch;
+  /** Called when the server says this version is being retired. */
+  onDeprecated?: (notice: DeprecationNotice) => void;
+}
+
+export interface DeprecationNotice {
+  version: string;
+  /** RFC 8594 Sunset, as sent. Parse with `new Date(...)`. */
+  sunset?: string;
+  policyUrl?: string;
+}
+
+/** Build-time defaults, matching the server's own defaults for this project. */
+const clientDefaults = {
+  strategy: '{{ apiVersionStrategy }}' as PinStrategy,
+  headerName: '{{ apiVersionHeaderName }}',
+  queryParam: '{{ apiVersionQueryParam }}',
+  mediaType: '{{ apiVersionMediaType }}',
+  pathPrefix: '{{ apiVersionPathPrefix }}',
+};
+
+const LINK_URL = /<([^>]+)>/;
+
+function parseDeprecation(response: Response, headerName: string): DeprecationNotice | undefined {
+  if (!response.headers.has('Deprecation')) return undefined;
+  return {
+    version: response.headers.get(headerName) ?? '',
+    sunset: response.headers.get('Sunset') ?? undefined,
+    policyUrl: LINK_URL.exec(response.headers.get('Link') ?? '')?.[1],
+  };
+}
+
+/**
+ * Returns a `fetch` that pins every request to one version. Paths are given relative to
+ * the API root — `/orders/42`, not `/api/v2/orders/42`; the pin is applied here so a call
+ * site can never hardcode a version into a URL.
+ */
+export function createPinnedFetch(options: PinnedClientOptions) {
+  // `??` rather than a spread: an explicitly undefined option must not erase the default.
+  const config = {
+    version: options.version,
+    baseUrl: options.baseUrl,
+    strategy: options.strategy ?? clientDefaults.strategy,
+    headerName: options.headerName ?? clientDefaults.headerName,
+    queryParam: options.queryParam ?? clientDefaults.queryParam,
+    mediaType: options.mediaType ?? clientDefaults.mediaType,
+    pathPrefix: options.pathPrefix ?? clientDefaults.pathPrefix,
+  };
+  const doFetch = options.fetch ?? globalThis.fetch;
+
+  return async (path: string, init: RequestInit = {}): Promise<Response> => {
+    const prefix = config.pathPrefix.replace(/\/+$/, '');
+    const suffix = path.startsWith('/') ? path : `/${path}`;
+    const versionSegment = config.strategy === 'path' ? `/${config.version}` : '';
+    const url = new URL(`${prefix}${versionSegment}${suffix}`, config.baseUrl);
+
+    if (config.strategy === 'query') url.searchParams.set(config.queryParam, config.version);
+
+    const headers = new Headers(init.headers);
+    if (config.strategy === 'header') headers.set(config.headerName, config.version);
+    if (config.strategy === 'accept') {
+      headers.set('Accept', `${config.mediaType}; version=${config.version}`);
+    }
+
+    const response = await doFetch(url, { ...init, headers });
+    const notice = parseDeprecation(response, config.headerName);
+    if (notice && options.onDeprecated) options.onDeprecated(notice);
+    return response;
+  };
+}

package/templates/layers/api-versioning/files/src/apiversion/contract/diff.ts

@@ -0,0 +1,153 @@
+/**
+ * Contract differ. The same edit is safe in one direction and fatal in the other — adding
+ * a field to a response costs nothing, adding a required field to a request breaks every
+ * client already shipped — so direction is part of every comparison.
+ */
+import type { ContractSnapshot, Field, OperationContract, Shape } from './shape.js';
+
+export type Severity = 'breaking' | 'additive' | 'neutral';
+
+export type Direction = 'request' | 'response';
+
+export interface ContractChange {
+  path: string;
+  severity: Severity;
+  message: string;
+}
+
+export function diffShapes(
+  before: Shape,
+  after: Shape,
+  direction: Direction,
+  path = '$',
+): ContractChange[] {
+  // The old contract promised nothing here, so nothing can be broken by narrowing it.
+  if (before.kind === 'unknown') return [];
+
+  if (before.kind !== after.kind) {
+    return [
+      {
+        path,
+        severity: 'breaking',
+        message: `type changed from ${before.kind} to ${after.kind}`,
+      },
+    ];
+  }
+
+  if (before.kind === 'array' && after.kind === 'array') {
+    return diffShapes(before.items, after.items, direction, `${path}[]`);
+  }
+
+  if (before.kind === 'object' && after.kind === 'object') {
+    return diffObjects(before.fields, after.fields, direction, path);
+  }
+
+  return [];
+}
+
+function diffObjects(
+  before: Record<string, Field>,
+  after: Record<string, Field>,
+  direction: Direction,
+  path: string,
+): ContractChange[] {
+  const changes: ContractChange[] = [];
+
+  for (const [name, field] of Object.entries(before)) {
+    const child = `${path}.${name}`;
+    const next = after[name];
+
+    if (!next) {
+      changes.push(
+        direction === 'response'
+          ? { path: child, severity: 'breaking', message: 'response field removed' }
+          : // The server stops reading it; a client still sending it is unaffected.
+            { path: child, severity: 'neutral', message: 'request field no longer read' },
+      );
+      continue;
+    }
+
+    if (field.required && !next.required) {
+      changes.push({
+        path: child,
+        severity: direction === 'response' ? 'breaking' : 'additive',
+        message:
+          direction === 'response'
+            ? 'guaranteed response field is now optional'
+            : 'required request field is now optional',
+      });
+    }
+    if (!field.required && next.required) {
+      changes.push({
+        path: child,
+        severity: direction === 'response' ? 'additive' : 'breaking',
+        message:
+          direction === 'response'
+            ? 'optional response field is now guaranteed'
+            : 'optional request field is now required',
+      });
+    }
+
+    changes.push(...diffShapes(field.shape, next.shape, direction, child));
+  }
+
+  for (const [name, field] of Object.entries(after)) {
+    if (before[name]) continue;
+    const child = `${path}.${name}`;
+    changes.push(
+      direction === 'request' && field.required
+        ? { path: child, severity: 'breaking', message: 'new required request field' }
+        : { path: child, severity: 'additive', message: `new ${direction} field` },
+    );
+  }
+
+  return changes;
+}
+
+export function diffOperations(
+  before: OperationContract,
+  after: OperationContract,
+  path: string,
+): ContractChange[] {
+  const changes: ContractChange[] = [];
+  for (const direction of ['request', 'response'] as const) {
+    const from = before[direction];
+    const to = after[direction];
+    if (!from) continue;
+    if (!to) {
+      changes.push({ path: `${path}.${direction}`, severity: 'breaking', message: `${direction} contract removed` });
+      continue;
+    }
+    changes.push(...diffShapes(from, to, direction, `${path}.${direction}`));
+  }
+  return changes;
+}
+
+export function diffContracts(before: ContractSnapshot, after: ContractSnapshot): ContractChange[] {
+  const changes: ContractChange[] = [];
+
+  for (const [operation, contract] of Object.entries(before.operations)) {
+    const next = after.operations[operation];
+    if (!next) {
+      // Retiring an operation is what a new version is for, never an in-place edit.
+      changes.push({ path: operation, severity: 'breaking', message: 'operation removed' });
+      continue;
+    }
+    changes.push(...diffOperations(contract, next, operation));
+  }
+
+  for (const operation of Object.keys(after.operations)) {
+    if (before.operations[operation]) continue;
+    changes.push({ path: operation, severity: 'additive', message: 'new operation' });
+  }
+
+  return changes;
+}
+
+export function breakingChanges(changes: readonly ContractChange[]): ContractChange[] {
+  return changes.filter((change) => change.severity === 'breaking');
+}
+
+export function formatChanges(changes: readonly ContractChange[]): string {
+  return changes.map((change) => `  [${change.severity}] ${change.path}: ${change.message}`).join('\n');
+}