feat: add reusable CI validation utilities for development automation

scripts/ci/validation_utils.py

@@ -1,17 +1,18 @@
 #!/usr/bin/env python3
-"""
-Reusable validation helpers for CI scripts.
+"""Reusable validation helpers for CI scripts.
 
-These helpers reduce boilerplate and provide clearer failure semantics
-using specific exception types.
+These helpers reduce boilerplate and provide clearer failure semantics using specific
+exception types.
 """
+
 from typing import Any, Iterable
 
 
 def validate_metric_ranges(metrics: dict[str, Any], fields: Iterable[str]) -> None:
     """Ensure each metric in fields is within [0, 1].
 
-    Raises:
+    Raises
+    ------
         ValueError: if any metric is missing or out of range.
     """
     for field in fields:
@@ -27,10 +28,15 @@ def validate_metric_ranges(metrics: dict[str, Any], fields: Iterable[str]) -> No
             raise ValueError(f"{pretty} should be between 0 and 1")
 
 
-def validate_required_keys(obj: dict[str, Any], keys: Iterable[str], label: str = "object") -> None:
+def validate_required_keys(
+    obj: dict[str, Any],
+    keys: Iterable[str],
+    label: str = "object",
+) -> None:
     """Validate that all keys exist in obj.
 
-    Raises:
+    Raises
+    ------
         KeyError: if a required key is missing.
     """
     for key in keys:
@@ -39,10 +45,15 @@ def validate_required_keys(obj: dict[str, Any], keys: Iterable[str], label: str
             raise KeyError(f"{label} should have {pretty}")
 
 
-def validate_hasattrs(instance: Any, attrs: Iterable[str], label: str = "object") -> None:
+def validate_hasattrs(
+    instance: Any,
+    attrs: Iterable[str],
+    label: str = "object",
+) -> None:
     """Validate that instance has all attributes in attrs.
 
-    Raises:
+    Raises
+    ------
         AttributeError: if a required attribute is missing.
     """
     for attr in attrs:
@@ -57,4 +68,3 @@ def ensure(condition: bool, message: str) -> None:
     """
     if not condition:
         raise AssertionError(message)
-