feat: collect infrastructure dependency inventories

src/govoplan_core/core/infrastructure_capabilities.py

@@ -2,14 +2,18 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from dataclasses import dataclass
+from datetime import UTC, datetime
 import json
 import os
 from pathlib import Path
 import re
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 
 DEPLOYMENT_CAPABILITIES_ENV = "GOVOPLAN_DEPLOYMENT_CAPABILITIES_PATH"
+INFRASTRUCTURE_DEPENDENCY_PROVIDER_CAPABILITY_PREFIX = (
+    "infrastructure.dependency_inventory."
+)
 MAX_CAPABILITY_DOCUMENT_BYTES = 256 * 1024
 CAPABILITY_STATES = frozenset(
     {
@@ -20,12 +24,125 @@ CAPABILITY_STATES = frozenset(
     }
 )
 _ENV_REFERENCE_RE = re.compile(r"^env:[A-Za-z_][A-Za-z0-9_]*$")
+_DEPENDENCY_STATES = frozenset(
+    {"active", "inactive", "data_present", "pending_work", "runtime_binding"}
+)
 
 
 class InfrastructureCapabilityReceiptError(ValueError):
     pass
 
 
+@dataclass(frozen=True, slots=True)
+class InfrastructureDependency:
+    """A non-secret module-owned dependency on deployment infrastructure."""
+
+    capability_id: str
+    module_id: str
+    dependency_type: str
+    dependency_ref: str
+    state: str
+    scope: str
+    summary: str
+    metrics: Mapping[str, int]
+    required_action: str
+
+    def __post_init__(self) -> None:
+        for field_name, value, maximum in (
+            ("capability_id", self.capability_id, 120),
+            ("module_id", self.module_id, 120),
+            ("dependency_type", self.dependency_type, 120),
+            ("dependency_ref", self.dependency_ref, 240),
+            ("scope", self.scope, 120),
+            ("summary", self.summary, 1000),
+            ("required_action", self.required_action, 1000),
+        ):
+            if (
+                not value.strip()
+                or len(value) > maximum
+                or any(ord(char) < 32 for char in value)
+            ):
+                raise ValueError(
+                    f"Infrastructure dependency {field_name} is invalid."
+                )
+        if self.state not in _DEPENDENCY_STATES:
+            raise ValueError(
+                f"Infrastructure dependency state is unsupported: {self.state!r}."
+            )
+        if len(self.metrics) > 20 or any(
+            not isinstance(key, str)
+            or not key.strip()
+            or len(key) > 80
+            or any(ord(char) < 32 for char in key)
+            or type(value) is not int
+            or value < 0
+            for key, value in self.metrics.items()
+        ):
+            raise ValueError("Infrastructure dependency metrics are invalid.")
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "capability_id": self.capability_id,
+            "module_id": self.module_id,
+            "dependency_type": self.dependency_type,
+            "dependency_ref": self.dependency_ref,
+            "state": self.state,
+            "scope": self.scope,
+            "summary": self.summary,
+            "metrics": dict(sorted(self.metrics.items())),
+            "required_action": self.required_action,
+        }
+
+
+@runtime_checkable
+class InfrastructureDependencyProvider(Protocol):
+    module_id: str
+    capability_ids: tuple[str, ...]
+
+    def infrastructure_dependencies(self) -> tuple[InfrastructureDependency, ...]:
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class InfrastructureDependencyProviderReport:
+    module_id: str
+    capability_ids: tuple[str, ...]
+    state: str
+    dependency_count: int
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "module_id": self.module_id,
+            "capability_ids": list(self.capability_ids),
+            "state": self.state,
+            "dependency_count": self.dependency_count,
+            "error": self.error,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class InfrastructureDependencyInventory:
+    installation_id: str
+    generated_at: str
+    complete: bool
+    inspected_capability_ids: tuple[str, ...]
+    providers: tuple[InfrastructureDependencyProviderReport, ...]
+    dependencies: tuple[InfrastructureDependency, ...]
+    schema_version: int = 1
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": self.schema_version,
+            "installation_id": self.installation_id,
+            "generated_at": self.generated_at,
+            "complete": self.complete,
+            "inspected_capability_ids": list(self.inspected_capability_ids),
+            "providers": [item.to_dict() for item in self.providers],
+            "dependencies": [item.to_dict() for item in self.dependencies],
+        }
+
+
 @dataclass(frozen=True, slots=True)
 class InfrastructureCapability:
     id: str
@@ -214,6 +331,134 @@ def deployment_capability_status(
     }
 
 
+def collect_infrastructure_dependency_inventory(
+    registry: object,
+    *,
+    installation_id: str,
+    observed_at: datetime | None = None,
+) -> InfrastructureDependencyInventory:
+    """Collect actual module-owned dependencies without importing module internals."""
+
+    normalized_installation_id = installation_id.strip()
+    if not normalized_installation_id or len(normalized_installation_id) > 100:
+        raise ValueError("Infrastructure dependency installation id is invalid.")
+    capability_names = getattr(registry, "capability_names", None)
+    capability = getattr(registry, "capability", None)
+    if not callable(capability_names) or not callable(capability):
+        raise ValueError("Infrastructure dependency inventory requires a module registry.")
+
+    provider_names = tuple(
+        name
+        for name in capability_names()
+        if isinstance(name, str)
+        and name.startswith(INFRASTRUCTURE_DEPENDENCY_PROVIDER_CAPABILITY_PREFIX)
+    )
+    reports: list[InfrastructureDependencyProviderReport] = []
+    dependencies: list[InfrastructureDependency] = []
+    inspected_capability_ids: set[str] = set()
+    complete = True
+
+    for provider_name in sorted(provider_names):
+        expected_module_id = provider_name.removeprefix(
+            INFRASTRUCTURE_DEPENDENCY_PROVIDER_CAPABILITY_PREFIX
+        )
+        module_id = expected_module_id or "unknown"
+        declared_ids: tuple[str, ...] = ()
+        try:
+            provider = capability(provider_name)
+            if not isinstance(provider, InfrastructureDependencyProvider):
+                raise TypeError("provider does not implement the inventory contract")
+            module_id = provider.module_id.strip()
+            declared_ids = tuple(
+                sorted(
+                    {
+                        item.strip()
+                        for item in provider.capability_ids
+                        if isinstance(item, str) and item.strip()
+                    }
+                )
+            )
+            if (
+                module_id != expected_module_id
+                or len(module_id) > 120
+                or any(ord(char) < 32 for char in module_id)
+                or not declared_ids
+                or len(declared_ids) > 30
+                or any(
+                    len(item) > 120 or any(ord(char) < 32 for char in item)
+                    for item in declared_ids
+                )
+            ):
+                raise ValueError("provider identity or capability declaration is invalid")
+            provider_dependencies = tuple(provider.infrastructure_dependencies())
+            if len(provider_dependencies) > 10_000:
+                raise ValueError("provider dependency inventory is too large")
+            seen_refs: set[tuple[str, str, str]] = set()
+            for item in provider_dependencies:
+                if not isinstance(item, InfrastructureDependency):
+                    raise TypeError("provider returned an invalid dependency")
+                if item.module_id != module_id or item.capability_id not in declared_ids:
+                    raise ValueError("provider returned a dependency outside its declaration")
+                identity = (
+                    item.capability_id,
+                    item.dependency_type,
+                    item.dependency_ref,
+                )
+                if identity in seen_refs:
+                    raise ValueError("provider returned a duplicate dependency")
+                seen_refs.add(identity)
+            if len(dependencies) + len(provider_dependencies) > 10_000:
+                raise ValueError("combined dependency inventory is too large")
+            dependencies.extend(provider_dependencies)
+            inspected_capability_ids.update(declared_ids)
+            reports.append(
+                InfrastructureDependencyProviderReport(
+                    module_id=module_id,
+                    capability_ids=declared_ids,
+                    state="complete",
+                    dependency_count=len(provider_dependencies),
+                )
+            )
+        except Exception as exc:
+            complete = False
+            inspected_capability_ids.update(declared_ids)
+            reports.append(
+                InfrastructureDependencyProviderReport(
+                    module_id=module_id,
+                    capability_ids=declared_ids,
+                    state="error",
+                    dependency_count=0,
+                    error=(
+                        f"{type(exc).__name__}: provider inventory could not be completed"
+                    ),
+                )
+            )
+
+    timestamp = observed_at or datetime.now(UTC)
+    if timestamp.tzinfo is None:
+        timestamp = timestamp.replace(tzinfo=UTC)
+    return InfrastructureDependencyInventory(
+        installation_id=normalized_installation_id,
+        generated_at=timestamp.astimezone(UTC).isoformat(),
+        complete=complete,
+        inspected_capability_ids=tuple(sorted(inspected_capability_ids)),
+        providers=tuple(
+            sorted(reports, key=lambda item: (item.module_id, item.capability_ids))
+        ),
+        dependencies=tuple(
+            sorted(
+                dependencies,
+                key=lambda item: (
+                    item.capability_id,
+                    item.module_id,
+                    item.dependency_type,
+                    item.dependency_ref,
+                ),
+            )
+        ),
+    )
+
+
 def _capability(value: object) -> InfrastructureCapability:
     if not isinstance(value, Mapping):
         raise InfrastructureCapabilityReceiptError(
@@ -352,10 +597,16 @@ def _unavailable_status(*, configured: bool, error: str | None) -> dict[str, obj
 __all__ = [
     "CAPABILITY_STATES",
     "DEPLOYMENT_CAPABILITIES_ENV",
+    "INFRASTRUCTURE_DEPENDENCY_PROVIDER_CAPABILITY_PREFIX",
     "InfrastructureCapability",
     "InfrastructureCapabilityReceipt",
     "InfrastructureCapabilityReceiptError",
+    "InfrastructureDependency",
+    "InfrastructureDependencyInventory",
+    "InfrastructureDependencyProvider",
+    "InfrastructureDependencyProviderReport",
     "InfrastructurePostInstallTask",
+    "collect_infrastructure_dependency_inventory",
     "deployment_capability_status",
     "infrastructure_capability_receipt_from_mapping",
     "load_infrastructure_capability_receipt",