124 lines
4.1 KiB
Python
124 lines
4.1 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
check_sentinel_contract_parity.py
|
|
|
|
Ensures Sentinel v1 contracts (docs) and verifier implementation stay aligned:
|
|
- Every FailureCode is referenced by the verifier implementation.
|
|
- Every FailureCode is referenced by the contract matrix.
|
|
- The contract matrix does not reference unknown E_/W_ codes.
|
|
|
|
Usage:
|
|
python3 tools/check_sentinel_contract_parity.py
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
from sentinel_failure_codes import FailureCode, WarningCode
|
|
|
|
REPO_ROOT = Path(__file__).resolve().parents[1]
|
|
VERIFIER_PATH = REPO_ROOT / "tools" / "vm_verify_sentinel_bundle.py"
|
|
CONTRACT_MATRIX_PATH = REPO_ROOT / "spec" / "SENTINEL_V1_CONTRACT_MATRIX.md"
|
|
SEMANTICS_PATH = REPO_ROOT / "spec" / "SENTINEL_FAILURE_CODE_SEMANTICS.md"
|
|
|
|
|
|
def _read_text(path: Path) -> str:
|
|
return path.read_text(encoding="utf-8")
|
|
|
|
|
|
def main() -> int:
|
|
errors: list[str] = []
|
|
|
|
verifier = _read_text(VERIFIER_PATH)
|
|
matrix = _read_text(CONTRACT_MATRIX_PATH)
|
|
semantics = _read_text(SEMANTICS_PATH)
|
|
|
|
known_failure_values = {c.value for c in FailureCode}
|
|
known_warning_values = {c.value for c in WarningCode}
|
|
|
|
# 1) Every FailureCode is referenced by the verifier code.
|
|
for code in FailureCode:
|
|
needle = f"FailureCode.{code.name}"
|
|
if needle not in verifier:
|
|
errors.append(f"Verifier does not reference {needle} ({code.value})")
|
|
|
|
# 1b) Every WarningCode is referenced by the verifier code.
|
|
for code in WarningCode:
|
|
needle = f"WarningCode.{code.name}"
|
|
if needle not in verifier:
|
|
errors.append(f"Verifier does not reference {needle} ({code.value})")
|
|
|
|
# 2) Every FailureCode value appears in the contract matrix.
|
|
for code in FailureCode:
|
|
if code.value not in matrix:
|
|
errors.append(
|
|
f"Contract matrix does not reference failure code {code.value}"
|
|
)
|
|
|
|
# 2b) Every WarningCode value appears in the contract matrix.
|
|
for code in WarningCode:
|
|
if code.value not in matrix:
|
|
errors.append(
|
|
f"Contract matrix does not reference warning code {code.value}"
|
|
)
|
|
|
|
# 3) Contract matrix does not contain unknown E_/W_ codes.
|
|
referenced_failures = set(re.findall(r"\bE_[A-Z_]+\b", matrix))
|
|
referenced_warnings = set(re.findall(r"\bW_[A-Z_]+\b", matrix))
|
|
|
|
unknown_failures = sorted(referenced_failures - known_failure_values)
|
|
unknown_warnings = sorted(referenced_warnings - known_warning_values)
|
|
|
|
if unknown_failures:
|
|
errors.append(
|
|
"Contract matrix references unknown failure codes: "
|
|
+ ", ".join(unknown_failures)
|
|
)
|
|
if unknown_warnings:
|
|
errors.append(
|
|
"Contract matrix references unknown warning codes: "
|
|
+ ", ".join(unknown_warnings)
|
|
)
|
|
|
|
# 4) Semantics doc must cover all codes.
|
|
for code in FailureCode:
|
|
if code.value not in semantics:
|
|
errors.append(f"Failure code semantics doc does not reference {code.value}")
|
|
|
|
for code in WarningCode:
|
|
if code.value not in semantics:
|
|
errors.append(f"Warning code semantics doc does not reference {code.value}")
|
|
|
|
# 5) Semantics doc does not contain unknown E_/W_ codes.
|
|
referenced_failures = set(re.findall(r"\bE_[A-Z_]+\b", semantics))
|
|
referenced_warnings = set(re.findall(r"\bW_[A-Z_]+\b", semantics))
|
|
|
|
unknown_failures = sorted(referenced_failures - known_failure_values)
|
|
unknown_warnings = sorted(referenced_warnings - known_warning_values)
|
|
|
|
if unknown_failures:
|
|
errors.append(
|
|
"Failure code semantics doc references unknown failure codes: "
|
|
+ ", ".join(unknown_failures)
|
|
)
|
|
if unknown_warnings:
|
|
errors.append(
|
|
"Failure code semantics doc references unknown warning codes: "
|
|
+ ", ".join(unknown_warnings)
|
|
)
|
|
|
|
if errors:
|
|
for e in errors:
|
|
print(f"[FAIL] {e}", file=sys.stderr)
|
|
return 1
|
|
|
|
print("[OK] Sentinel contract parity verified")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|