Files
crank/scripts/check-openapi-matrix-compatibility.py
bsodfather e93de7015a
CI / Rust Checks (pull_request) Failing after 1s
CI / UI Checks (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Deploy (pull_request) Skipped
feat(import): complete OpenAPI onboarding and verify delivery
2026-10-09 17:50:38 +03:00

190 lines
7.1 KiB
Python
Executable File

#!/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>'} -> {new_matrix_version}; "
f"corpus {old_manifest.get('corpus_version') if old_manifest else '<new>'} -> {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())