feat(core): define organization hierarchy contracts

tests/test_organization_hierarchy_contract.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import unittest
+
+from govoplan_core.core.organizations import (
+    CAPABILITY_ORGANIZATION_HIERARCHY_DIRECTORY,
+    OrganizationDirectory,
+    OrganizationFunctionTypeRef,
+    OrganizationHierarchyDirectory,
+    OrganizationUnitTypeRef,
+    organization_hierarchy_directory,
+)
+from govoplan_core.core.registry import PlatformRegistry
+from govoplan_core.core.modules import ModuleContext, ModuleManifest
+
+
+class LegacyOrganizationDirectory:
+    def get_organization_unit(self, _organization_unit_id):
+        return None
+
+    def organization_units_for_tenant(self, _tenant_id):
+        return ()
+
+    def get_function(self, _function_id):
+        return None
+
+    def functions_for_organization_unit(
+        self,
+        _organization_unit_id,
+        *,
+        include_subunits=False,
+    ):
+        del include_subunits
+        return ()
+
+
+class HierarchyDirectory:
+    def get_unit_type(self, _tenant_id, _unit_type_id):
+        return None
+
+    def get_function_type(self, _tenant_id, _function_type_id):
+        return None
+
+    def resolve_functions_by_type(
+        self,
+        _tenant_id,
+        _function_type_id,
+        *,
+        organization_unit_ids=(),
+    ):
+        del organization_unit_ids
+        return None
+
+    def resolve_units_by_type(
+        self,
+        _tenant_id,
+        _unit_type_id,
+        **_options,
+    ):
+        return None
+
+    def resolve_hierarchy_relatives(
+        self,
+        _tenant_id,
+        _organization_unit_ids,
+        **_options,
+    ):
+        return ()
+
+    def resolve_hierarchy_paths(
+        self,
+        _tenant_id,
+        _unit_pairs,
+        **_options,
+    ):
+        return ()
+
+
+class OrganizationHierarchyContractTests(unittest.TestCase):
+    def test_legacy_directory_contract_is_not_broadened(self) -> None:
+        self.assertIsInstance(
+            LegacyOrganizationDirectory(),
+            OrganizationDirectory,
+        )
+        self.assertNotIsInstance(
+            LegacyOrganizationDirectory(),
+            OrganizationHierarchyDirectory,
+        )
+
+    def test_hierarchy_capability_resolves_independently(self) -> None:
+        provider = HierarchyDirectory()
+        registry = PlatformRegistry()
+        registry.register(
+            ModuleManifest(
+                id="organization_hierarchy_test",
+                name="Organization hierarchy test",
+                version="0.0.0",
+                capability_factories={
+                    CAPABILITY_ORGANIZATION_HIERARCHY_DIRECTORY: (
+                        lambda _context: provider
+                    ),
+                },
+            )
+        )
+        registry.configure_capability_context(
+            ModuleContext(registry=registry, settings=object())
+        )
+
+        self.assertIsInstance(provider, OrganizationHierarchyDirectory)
+        self.assertIs(
+            provider,
+            organization_hierarchy_directory(registry),
+        )
+
+    def test_type_refs_preserve_tenant_and_status(self) -> None:
+        unit_type = OrganizationUnitTypeRef(
+            id="unit-type-1",
+            tenant_id="tenant-1",
+            slug="department",
+            name="Department",
+            status="inactive",
+        )
+        function_type = OrganizationFunctionTypeRef(
+            id="function-type-1",
+            tenant_id="tenant-1",
+            slug="intake",
+            name="Intake",
+            organization_unit_type_id=unit_type.id,
+        )
+
+        self.assertEqual("inactive", unit_type.status)
+        self.assertEqual(unit_type.id, function_type.organization_unit_type_id)
+
+
+if __name__ == "__main__":
+    unittest.main()