ops: add disk capacity incident assessment

src/disk_capacity.py

@@ -0,0 +1,35 @@
+"""Disk-capacity incident assessment shared by operations checks."""
+
+from __future__ import annotations
+
+import shutil
+from os import PathLike
+
+
+def assess_disk_capacity(
+    *,
+    total_bytes: int,
+    available_bytes: int,
+    threshold_percent: float = 85.0,
+) -> dict[str, float | bool]:
+    """Return the capacity status using the runbook's inclusive threshold."""
+    usage_percent = round((total_bytes - available_bytes) / total_bytes * 100, 1)
+    return {
+        "usage_percent": usage_percent,
+        "threshold_percent": threshold_percent,
+        "incident": usage_percent >= threshold_percent,
+    }
+
+
+def read_disk_capacity(
+    path: str | PathLike[str] = "/",
+    *,
+    threshold_percent: float = 85.0,
+) -> dict[str, float | bool]:
+    """Assess capacity for a real filesystem path."""
+    usage = shutil.disk_usage(path)
+    return assess_disk_capacity(
+        total_bytes=usage.total,
+        available_bytes=usage.free,
+        threshold_percent=threshold_percent,
+    )