#!/usr/bin/env python3 """Require versioned, explained compatibility changes to OpenAPI contracts.""" from __future__ import annotations import argparse import json import re import subprocess import sys from typing import Any MATRIX_PATH = "crates/crank-import/tests/support-matrix.yaml" MANIFEST_PATH = "crates/crank-import/tests/corpus/manifest.json" DOCS_PATH = "docs/openapi-import.md" def git_show(revision: str, path: str) -> str | None: result = subprocess.run( ["git", "show", f"{revision}:{path}"], check=False, capture_output=True, text=True, ) return result.stdout if result.returncode == 0 else None def matrix_version(contents: str | None) -> str | None: if contents is None: return None match = re.search(r"(?m)^matrix_version:\s*['\"]?([^\s'\"]+)", contents) return match.group(1) if match else None def parse_manifest(contents: str | None, label: str) -> dict[str, Any] | None: if contents is None: return None try: value = json.loads(contents) except json.JSONDecodeError as error: raise ValueError(f"{label} is not valid JSON: {error}") from error if not isinstance(value, dict): raise ValueError(f"{label} must be a JSON object") return value def require(condition: bool, message: str, errors: list[str]) -> None: if not condition: errors.append(message) def valid_version(value: Any) -> bool: return isinstance(value, str) and re.fullmatch( r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)", value ) is not None def version_increases(old: Any, new: Any) -> bool: """Compare the numeric contract versions used by the matrix and corpus.""" if not valid_version(old) or not valid_version(new): return False return tuple(map(int, new.split("."))) > tuple(map(int, old.split("."))) def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--base", required=True, help="base commit or ref to compare against") args = parser.parse_args() try: subprocess.run( ["git", "rev-parse", "--verify", f"{args.base}^{{commit}}"], check=True, capture_output=True, text=True, ) except subprocess.CalledProcessError: print(f"OpenAPI compatibility guard: base revision {args.base!r} is unavailable", file=sys.stderr) return 2 try: old_matrix_text = git_show(args.base, MATRIX_PATH) old_manifest_text = git_show(args.base, MANIFEST_PATH) with open(MATRIX_PATH, encoding="utf-8") as matrix_file: new_matrix_text = matrix_file.read() with open(MANIFEST_PATH, encoding="utf-8") as manifest_file: new_manifest_text = manifest_file.read() with open(DOCS_PATH, encoding="utf-8") as docs_file: new_docs_text = docs_file.read() old_manifest = parse_manifest(old_manifest_text, "base manifest") new_manifest = parse_manifest(new_manifest_text, "working manifest") except (OSError, ValueError) as error: print(f"OpenAPI compatibility guard: {error}", file=sys.stderr) return 2 matrix_changed = old_matrix_text != new_matrix_text manifest_changed = old_manifest_text != new_manifest_text errors: list[str] = [] old_matrix_version = matrix_version(old_matrix_text) new_matrix_version = matrix_version(new_matrix_text) new_corpus_version = new_manifest.get("corpus_version") new_impact = new_manifest.get("compatibility_impact") require(bool(new_matrix_version), "support matrix must declare matrix_version", errors) require(bool(new_corpus_version), "corpus manifest must declare corpus_version", errors) require(valid_version(new_matrix_version), "matrix_version must be numeric SemVer", errors) require(valid_version(new_corpus_version), "corpus_version must be numeric SemVer", errors) require( new_manifest.get("matrix_version") == new_matrix_version, "manifest matrix_version must match support matrix", errors, ) require( isinstance(new_impact, str) and bool(new_impact.strip()), "corpus manifest must include a non-empty compatibility_impact note", errors, ) if matrix_changed and old_matrix_text is not None: require( version_increases(old_matrix_version, new_matrix_version), "support-matrix.yaml changed without a matrix_version bump (must increase SemVer)", errors, ) old_matrix_was_present = old_matrix_text is not None if matrix_changed and old_matrix_was_present: old_impact = old_manifest.get("compatibility_impact") if old_manifest else None require( new_impact != old_impact, "support matrix changed without updating compatibility_impact", errors, ) # The published documentation states concrete matrix/corpus versions; # a stale or mixed version in docs must not outlive the machine source. matrix_decls = re.findall( r"матриц[аы] версии `([0-9]+\.[0-9]+\.[0-9]+)`", new_docs_text, re.IGNORECASE ) corpus_decls = re.findall( r"corpus version — `([0-9]+\.[0-9]+\.[0-9]+)`", new_docs_text, re.IGNORECASE ) require( bool(matrix_decls) and all(version == new_matrix_version for version in matrix_decls), f"{DOCS_PATH} matrix version declaration must state matrix_version {new_matrix_version}", errors, ) require( bool(corpus_decls) and all(version == new_corpus_version for version in corpus_decls), f"{DOCS_PATH} corpus version declaration must state corpus_version {new_corpus_version}", errors, ) require( bool(matrix_decls) and bool(corpus_decls) and all(version == new_matrix_version for version in matrix_decls) and all(version == new_corpus_version for version in corpus_decls), f"{DOCS_PATH} must state the current support matrix and corpus versions", errors, ) if old_manifest is not None: if old_manifest != new_manifest: require( version_increases(old_manifest.get("corpus_version"), new_corpus_version), "corpus manifest changed without a corpus_version bump (must increase SemVer)", errors, ) require( new_impact != old_manifest.get("compatibility_impact"), "corpus manifest changed without updating compatibility_impact", errors, ) if errors: print("OpenAPI compatibility guard failed:", file=sys.stderr) for error in errors: print(f"- {error}", file=sys.stderr) return 1 print( "OpenAPI compatibility guard passed: " f"matrix {old_matrix_version or ''} -> {new_matrix_version}; " f"corpus {old_manifest.get('corpus_version') if old_manifest else ''} -> {new_corpus_version}" ) if not matrix_changed and not manifest_changed: print("OpenAPI compatibility guard: matrix and corpus manifest are unchanged") return 0 if __name__ == "__main__": raise SystemExit(main())