Files
crank/tests/unit/test_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

272 lines
12 KiB
Python

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()