Add find_shortest_cycle to python graph

Author: Peter554

src/grimp/adaptors/graph.py

@@ -126,6 +126,15 @@ def find_shortest_chains(
     def chain_exists(self, importer: str, imported: str, as_packages: bool = False) -> bool:
         return self._rustgraph.chain_exists(importer, imported, as_packages)
 
+    def find_shortest_cycle(
+        self, module: str, as_package: bool = False
+    ) -> Optional[Tuple[str, ...]]:
+        if not self._rustgraph.contains_module(module):
+            raise ValueError(f"Module {module} is not present in the graph.")
+
+        cycle = self._rustgraph.find_shortest_cycle(module, as_package)
+        return tuple(cycle) if cycle else None
+
     def find_illegal_dependencies_for_layers(
         self,
         layers: Sequence[Layer | str | set[str]],

src/grimp/application/ports/graph.py

@@ -282,6 +282,22 @@ def chain_exists(self, importer: str, imported: str, as_packages: bool = False)
         """
         raise NotImplementedError
 
+    # Cycles
+    # ------
+
+    @abc.abstractmethod
+    def find_shortest_cycle(
+        self, module: str, as_package: bool = False
+    ) -> Optional[Tuple[str, ...]]:
+        """
+        Returns the shortest import cycle from `module` to itself, or `None` if no cycle exist.
+
+        Optional args:
+            as_package:    Whether or not to treat the supplied module as an individual module,
+                           or as an entire subpackage (including any descendants).
+        """
+        raise NotImplementedError
+
     # High level analysis
     # -------------------
 

tests/unit/adaptors/graph/test_cycles.py

@@ -0,0 +1,55 @@
+import pytest
+
+from grimp.adaptors.graph import ImportGraph
+
+
+class TestFindShortestCycle:
+    @pytest.mark.parametrize(
+        "expected_cycle",
+        [
+            ("foo", "bar", "foo"),
+            ("foo", "bar", "baz", "foo"),
+        ],
+    )
+    def test_finds_shortest_cycle_when_exists(self, expected_cycle):
+        graph = ImportGraph()
+        # Shortest cycle
+        for importer, imported in zip(expected_cycle[:-1], expected_cycle[1:]):
+            graph.add_import(importer=importer, imported=imported)
+        # Longer cycle
+        graph.add_import(importer="foo", imported="x")
+        graph.add_import(importer="x", imported="y")
+        graph.add_import(importer="y", imported="z")
+        graph.add_import(importer="z", imported="foo")
+
+        assert graph.find_shortest_cycle("foo") == expected_cycle
+
+        graph.remove_import(importer=expected_cycle[-2], imported=expected_cycle[-1])
+
+        assert graph.find_shortest_cycle("foo") == ("foo", "x", "y", "z", "foo")
+
+    def test_returns_none_if_no_cycle_exists(self):
+        graph = ImportGraph()
+        graph.add_import(importer="foo", imported="bar")
+        graph.add_import(importer="bar", imported="baz")
+        # graph.add_import(importer="baz", imported="foo")  # This import is missing -> No cycle.
+
+        assert graph.find_shortest_cycle("foo") is None
+
+    def test_ignores_internal_imports_when_as_package_is_true(self):
+        graph = ImportGraph()
+        graph.add_module("colors")
+        graph.add_import(importer="colors.red", imported="colors.blue")
+        graph.add_import(importer="colors.blue", imported="colors.red")
+        graph.add_import(importer="colors.red", imported="x")
+        graph.add_import(importer="x", imported="y")
+        graph.add_import(importer="y", imported="z")
+        graph.add_import(importer="z", imported="colors.blue")
+
+        assert graph.find_shortest_cycle("colors", as_package=True) == (
+            "colors.red",
+            "x",
+            "y",
+            "z",
+            "colors.blue",
+        )