190 lines
7.1 KiB
Python
Executable File
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())
|