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,
+    )

tests/test_disk_capacity.py

@@ -0,0 +1,19 @@
+from src.disk_capacity import assess_disk_capacity, read_disk_capacity
+
+
+def test_usage_at_incident_threshold_requires_action():
+    status = assess_disk_capacity(total_bytes=100, available_bytes=15)
+
+    assert status == {
+        "usage_percent": 85.0,
+        "threshold_percent": 85.0,
+        "incident": True,
+    }
+
+
+def test_read_disk_capacity_assesses_a_real_filesystem(tmp_path):
+    status = read_disk_capacity(tmp_path)
+
+    assert 0 <= status["usage_percent"] <= 100
+    assert status["threshold_percent"] == 85.0
+    assert status["incident"] is (status["usage_percent"] >= 85.0)