import json import subprocess import tempfile import unittest from pathlib import Path SCRIPT = Path(__file__).parents[2] / "scripts" / "check-openapi-matrix-compatibility.py" MATRIX_PATH = "crates/crank-import/tests/support-matrix.yaml" MANIFEST_PATH = "crates/crank-import/tests/corpus/manifest.json" DOCS_PATH = "docs/openapi-import.md" BASE_MATRIX = """matrix_version: '1.0.0' constructs: - id: baseline """ BASE_DOC = "Матрица версии `1.0.0`; corpus version — `1.0.0`.\n" def base_manifest() -> dict: return { "corpus_version": "1.0.0", "matrix_version": "1.0.0", "compatibility_impact": "initial contract", "documents": [ { "id": "rep-00", "file": "representative-00.json", "sha256": "a" * 64, "origin": "synthetic:cc0", "license": "CC0-1.0", "specification_version": "OpenAPI 3.0", "classification": "representative", "expected_preview": {}, } ], } class OpenApiMatrixCompatibilityGuardTests(unittest.TestCase): def setUp(self) -> None: self._directory = tempfile.TemporaryDirectory() self.root = Path(self._directory.name) subprocess.run( ["git", "init", "-q"], cwd=self.root, check=True, capture_output=True ) for relative in (MATRIX_PATH, MANIFEST_PATH, DOCS_PATH): target = self.root / relative target.parent.mkdir(parents=True, exist_ok=True) (self.root / MATRIX_PATH).write_text(BASE_MATRIX, encoding="utf-8") (self.root / MANIFEST_PATH).write_text( json.dumps(base_manifest()), encoding="utf-8" ) (self.root / DOCS_PATH).write_text(BASE_DOC, encoding="utf-8") self.commit("base") self.base = self.head() def tearDown(self) -> None: self._directory.cleanup() def self_git(self, *args: str) -> None: subprocess.run( ["git", "-c", "user.email=guard@test", "-c", "user.name=guard", *args], cwd=self.root, check=True, capture_output=True, ) def commit(self, message: str) -> None: self.self_git("add", "-A") self.self_git("commit", "-m", message) def head(self) -> str: result = subprocess.run( ["git", "rev-parse", "HEAD"], cwd=self.root, check=True, capture_output=True, text=True, ) return result.stdout.strip() def run_guard(self) -> subprocess.CompletedProcess[str]: return subprocess.run( ["python3", str(SCRIPT), "--base", self.base], cwd=self.root, text=True, capture_output=True, check=False, ) def test_rejects_docs_only_edit_with_stale_version(self) -> None: # matrix and manifest are untouched relative to the base, but a docs # edit that pins a stale contract version must still be rejected (self.root / DOCS_PATH).write_text( "Матрица версии `0.9.0`; corpus version — `0.9.0`.\n", encoding="utf-8" ) result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn( "must state the current support matrix and corpus versions", result.stderr ) def test_rejects_docs_with_reversed_matrix_and_corpus_versions(self) -> None: (self.root / MATRIX_PATH).write_text( BASE_MATRIX.replace("'1.0.0'", "'1.1.0'") + " - id: addition\n", encoding="utf-8", ) manifest = base_manifest() manifest["matrix_version"] = "1.1.0" manifest["corpus_version"] = "1.0.1" manifest["compatibility_impact"] = "bumped release" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") (self.root / DOCS_PATH).write_text( "Матрица версии `1.0.1`; corpus version — `1.1.0`.\n", encoding="utf-8" ) result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn( "matrix version declaration must state matrix_version 1.1.0", result.stderr ) def test_rejects_contract_change_without_version_bump_on_existing_base(self) -> None: # The base already contains the contract: appending a matrix row must be # rejected even though the versions and impact note stay untouched. (self.root / MATRIX_PATH).write_text( BASE_MATRIX + " - id: addition\n", encoding="utf-8" ) result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("changed without a matrix_version bump", result.stderr) self.assertIn("without updating compatibility_impact", result.stderr) def test_rejects_matrix_version_downgrade(self) -> None: (self.root / MATRIX_PATH).write_text( BASE_MATRIX.replace("'1.0.0'", "'0.9.0'") + " - id: addition\n", encoding="utf-8", ) manifest = base_manifest() manifest["matrix_version"] = "0.9.0" manifest["compatibility_impact"] = "downgraded matrix" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") (self.root / DOCS_PATH).write_text( "Матрица версии `0.9.0`; corpus version — `1.0.0`.\n", encoding="utf-8" ) result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("matrix_version bump (must increase SemVer)", result.stderr) def test_rejects_manifest_change_without_corpus_bump_on_existing_base(self) -> None: manifest = base_manifest() manifest["documents"][0]["file"] = "representative-99.json" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("without a corpus_version bump", result.stderr) self.assertIn("without updating compatibility_impact", result.stderr) def test_rejects_corpus_version_downgrade(self) -> None: manifest = base_manifest() manifest["corpus_version"] = "0.9.0" manifest["compatibility_impact"] = "downgraded corpus" manifest["documents"][0]["file"] = "representative-99.json" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") (self.root / DOCS_PATH).write_text( "Матрица версии `1.0.0`; corpus version — `0.9.0`.\n", encoding="utf-8" ) result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("corpus_version bump (must increase SemVer)", result.stderr) def test_rejects_stale_versions_in_published_docs(self) -> None: matrix = BASE_MATRIX.replace("'1.0.0'", "'1.1.0'") + " - id: addition\n" (self.root / MATRIX_PATH).write_text(matrix, encoding="utf-8") manifest = base_manifest() manifest["matrix_version"] = "1.1.0" manifest["corpus_version"] = "1.0.1" manifest["compatibility_impact"] = "matrix 1.1.0 release" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") # docs still pin the previous `1.0.0` release result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("must state the current support matrix and corpus versions", result.stderr) def test_rejects_docs_citing_versions_missing_from_release(self) -> None: (self.root / MATRIX_PATH).write_text( BASE_MATRIX + " - id: addition\n", encoding="utf-8" ) manifest = base_manifest() manifest["matrix_version"] = "1.1.0" manifest["corpus_version"] = "1.1.0" manifest["compatibility_impact"] = "matrix 1.1.0 release" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") (self.root / DOCS_PATH).write_text( "Матрица версии `1.1.0`; corpus version — `0.9.0`.\n", encoding="utf-8" ) result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("must state the current support matrix and corpus versions", result.stderr) def test_allows_other_semver_in_docs(self) -> None: (self.root / DOCS_PATH).write_text( "Матрица версии `1.0.0`; corpus version — `1.0.0`. OpenAPI `3.1.0`.\n", encoding="utf-8", ) result = self.run_guard() self.assertEqual(result.returncode, 0, result.stderr) def test_rejects_conflicting_second_version_declaration(self) -> None: (self.root / DOCS_PATH).write_text( BASE_DOC + "Матрица версии `0.9.0`; corpus version — `0.9.0`.\n", encoding="utf-8", ) result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("must state the current support matrix and corpus versions", result.stderr) def test_rejects_leading_zero_in_contract_version(self) -> None: (self.root / MATRIX_PATH).write_text( BASE_MATRIX.replace("'1.0.0'", "'01.0.1'") + " - id: addition\n", encoding="utf-8", ) manifest = base_manifest() manifest["matrix_version"] = "01.0.1" manifest["compatibility_impact"] = "invalid version" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") (self.root / DOCS_PATH).write_text( "Матрица версии `01.0.1`; corpus version — `1.0.0`.\n", encoding="utf-8", ) result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("matrix_version bump (must increase SemVer)", result.stderr) def test_rejects_manifest_metadata_change_without_bump(self) -> None: manifest = base_manifest() manifest["canonical_digest_definition"] = "changed contract" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("without a corpus_version bump", result.stderr) def test_rejects_corpus_version_only_downgrade(self) -> None: manifest = base_manifest() manifest["corpus_version"] = "0.9.0" manifest["compatibility_impact"] = "downgrade" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") result = self.run_guard() self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("corpus_version bump (must increase SemVer)", result.stderr) def test_passes_consistent_bumped_release_with_updated_docs(self) -> None: (self.root / MATRIX_PATH).write_text( BASE_MATRIX.replace("'1.0.0'", "'1.1.0'") + " - id: addition\n", encoding="utf-8", ) manifest = base_manifest() manifest["matrix_version"] = "1.1.0" manifest["corpus_version"] = "1.0.1" manifest["compatibility_impact"] = "matrix 1.1.0 release" (self.root / MANIFEST_PATH).write_text(json.dumps(manifest), encoding="utf-8") (self.root / DOCS_PATH).write_text( "Матрица версии `1.1.0`; corpus version — `1.0.1`.\n", encoding="utf-8" ) result = self.run_guard() self.assertEqual(result.returncode, 0, result.stderr) if __name__ == "__main__": unittest.main()