feat: define governed report provider contract

tests/test_module_system.py

@@ -232,7 +232,15 @@ class ModuleSystemTests(unittest.TestCase):
         self.assertTrue(manifests["campaigns"].required_capabilities)
         self.assertEqual(
             manifests["campaigns"].optional_dependencies,
-            ("files", "mail", "notifications", "addresses", "postbox", "approvals"),
+            (
+                "files",
+                "mail",
+                "notifications",
+                "addresses",
+                "postbox",
+                "approvals",
+                "reporting",
+            ),
         )
         self.assertEqual(manifests["dashboard"].dependencies, ())
         self.assertTrue(manifests["dashboard"].required_capabilities)
@@ -3436,7 +3444,15 @@ finally:
             "version_max_exclusive": "0.3.0",
         }, modules["campaigns"]["requires_interfaces"])
         self.assertEqual(
-            ["files", "mail", "notifications", "addresses", "postbox", "approvals"],
+            [
+                "files",
+                "mail",
+                "notifications",
+                "addresses",
+                "postbox",
+                "approvals",
+                "reporting",
+            ],
             modules["campaigns"]["optional_dependencies"],
         )
         self.assertEqual("requires_review", modules["files"]["migration_safety"])

tests/test_reporting_contract.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from govoplan_core.core.modules import ModuleContext, ModuleManifest
+from govoplan_core.core.registry import PlatformRegistry
+from govoplan_core.core.reporting import (
+    REPORT_PROVIDER_CAPABILITY_PREFIX,
+    REPORT_PROVIDER_CONTRACT_VERSION,
+    ReportProviderRequest,
+    report_providers,
+)
+
+
+class _Provider:
+    provider_id = "example"
+    contract_version = REPORT_PROVIDER_CONTRACT_VERSION
+
+    def list_reports(self, session, principal):
+        return ()
+
+    def parameter_options(self, session, principal, **kwargs):
+        return ()
+
+    def execute_report(self, session, principal, *, request: ReportProviderRequest):
+        raise NotImplementedError
+
+    def authorize_result(self, session, principal, **kwargs):
+        return True
+
+
+def test_report_provider_discovery_is_prefix_based_and_optional() -> None:
+    registry = PlatformRegistry()
+    registry.register(
+        ModuleManifest(
+            id="example",
+            name="Example",
+            version="1.0",
+            capability_factories={
+                REPORT_PROVIDER_CAPABILITY_PREFIX + "example": lambda _context: (
+                    _Provider()
+                )
+            },
+        )
+    )
+    registry.configure_capability_context(
+        ModuleContext(registry=registry, settings=object())
+    )
+
+    providers = report_providers(registry)
+
+    assert len(providers) == 1
+    assert providers[0][0] == "example"
+
+
+def test_report_provider_id_must_match_capability_name() -> None:
+    registry = PlatformRegistry()
+    registry.register(
+        ModuleManifest(
+            id="example",
+            name="Example",
+            version="1.0",
+            capability_factories={
+                REPORT_PROVIDER_CAPABILITY_PREFIX + "other": lambda _context: (
+                    _Provider()
+                )
+            },
+        )
+    )
+    registry.configure_capability_context(
+        ModuleContext(registry=registry, settings=object())
+    )
+
+    try:
+        report_providers(registry)
+    except ValueError as exc:
+        assert "does not match" in str(exc)
+    else:
+        raise AssertionError("mismatched provider id was accepted")