Add '--hide-acyclic' option to hide vertices not part of a cycle

CHANGELOG.rst

@@ -1,6 +1,10 @@
 Changelog
 =========
 
+latest
+----------------
+* Add --hide-acyclic flag.
+
 2.2 (2025-12-12)
 ----------------
 

README.rst

@@ -64,6 +64,7 @@ There is currently only one command.
       --show-cycle-breakers  Identify a set of dependencies that, if removed,
                              would make the graph acyclic, and display them as
                              dashed lines.
+      --hide-acyclic         Hide submodules that are not part of a cycle.
       --help                 Show this message and exit.
 
 Draw a graph of the dependencies within any installed Python package or subpackage.
@@ -119,4 +120,18 @@ within ``django.db.utils``.
 
 Here you can see that two of the dependencies are shown as a dashed line. If these dependencies were to be
 removed, the graph would be acyclic. To decide on the cycle breakers, Impulse uses the
-`nominate_cycle_breakers method provided by Grimp <https://grimp.readthedocs.io/en/stable/usage.html#ImportGraph.nominate_cycle_breakers>`_.
+`nominate_cycle_breakers method provided by Grimp <https://grimp.readthedocs.io/en/stable/usage.html#ImportGraph.nominate_cycle_breakers>`_.
+
+**Example with hide acyclic**
+
+.. code-block:: text
+
+    impulse drawgraph django.db --hide-acyclic
+
+.. image:: https://raw.githubusercontent.com/seddonym/impulse/master/docs/_static/images/django.db.hide-acyclic.png
+  :align: center
+  :alt: Graph of django.db package with acyclic submodules hidden.
+
+This hides all submodules that do not form part of any cycle, making it easier to focus on circular
+dependencies in larger packages. Combine this with ``--show-cycle-breakers`` for a condensed view
+of cycles and how they can be broken.

justfile

@@ -14,6 +14,7 @@ test:
     @uv run --with=google-cloud-audit-log impulse drawgraph google.cloud.audit
     @uv run impulse drawgraph grimp --show-import-totals
     @uv run --with=django impulse drawgraph django.db --show-cycle-breakers
+    @uv run --with=django impulse drawgraph django.db --hide-acyclic
 
 
 # Run tests under all supported Python versions.

src/impulse/application/use_cases.py

@@ -1,14 +1,15 @@
 from collections.abc import Set
 from collections.abc import Callable
-import itertools
+
 import grimp
-from impulse import ports, dotfile
+from impulse import ports, dotfile, graph
 
 
 def draw_graph(
     module_name: str,
     show_import_totals: bool,
     show_cycle_breakers: bool,
+    hide_acyclic: bool,
     sys_path: list[str],
     current_directory: str,
     get_top_level_package: Callable[[str], str],
@@ -21,6 +22,7 @@ def draw_graph(
         module_name: the package or subpackage name of any importable Python package.
         show_import_totals: whether to label the arrows with the total number of imports they represent.
         show_cycle_breakers: marks a set of dependencies that, if removed, would make the graph acyclic.
+        hide_acyclic: whether to hide submodules that are not part of a cycle.
         sys_path: the sys.path list (or a test double).
         current_directory: the current working directory.
         get_top_level_package: the function to retrieve the top level package name. This will usually be the first part
@@ -35,23 +37,46 @@ def draw_graph(
     top_level_package = get_top_level_package(module_name)
     grimp_graph = build_graph(top_level_package)
 
-    dot = _build_dot(grimp_graph, module_name, show_import_totals, show_cycle_breakers)
+    dot = _build_dot(
+        grimp_graph,
+        module_name,
+        show_import_totals,
+        show_cycle_breakers,
+        hide_acyclic,
+    )
 
     viewer.view(dot)
 
 
 class _DotGraphBuildStrategy:
-    def build(self, module_name: str, grimp_graph: grimp.ImportGraph) -> dotfile.DotGraph:
+    def build(
+        self,
+        module_name: str,
+        grimp_graph: grimp.ImportGraph,
+        hide_acyclic: bool,
+    ) -> dotfile.DotGraph:
         children = grimp_graph.find_children(module_name)
 
         self.prepare_graph(grimp_graph, children)
 
+        presentation_graph = graph.DirectedGraphWithoutLoops.from_adjacency_condition(
+            vertices=children,
+            is_adjacent=lambda upstream, downstream: self.has_edge(
+                grimp_graph, upstream, downstream
+            ),
+        )
+
+        if hide_acyclic:
+            presentation_graph = presentation_graph.remove_acyclic_vertices()
+
         dot = dotfile.DotGraph(title=module_name, concentrate=self.should_concentrate())
-        for child in children:
-            dot.add_node(child)
-        for upstream, downstream in itertools.permutations(children, r=2):
-            if edge := self.build_edge(grimp_graph, upstream, downstream):
-                dot.add_edge(edge)
+
+        for vertex in presentation_graph.vertices:
+            dot.add_node(vertex)
+
+        for upstream, downstream in presentation_graph.iter_edges():
+            dot_edge = self.build_edge(grimp_graph, upstream, downstream)
+            dot.add_edge(dot_edge)
 
         return dot
 
@@ -61,9 +86,12 @@ def should_concentrate(self) -> bool:
     def prepare_graph(self, grimp_graph: grimp.ImportGraph, children: Set[str]) -> None:
         pass
 
+    def has_edge(self, grimp_graph: grimp.ImportGraph, upstream: str, downstream: str) -> bool:
+        raise NotImplementedError
+
     def build_edge(
         self, grimp_graph: grimp.ImportGraph, upstream: str, downstream: str
-    ) -> dotfile.Edge | None:
+    ) -> dotfile.Edge:
         raise NotImplementedError
 
 
@@ -74,12 +102,13 @@ def prepare_graph(self, grimp_graph: grimp.ImportGraph, children: Set[str]) -> N
         for child in children:
             grimp_graph.squash_module(child)
 
+    def has_edge(self, grimp_graph: grimp.ImportGraph, upstream: str, downstream: str) -> bool:
+        return grimp_graph.direct_import_exists(importer=downstream, imported=upstream)
+
     def build_edge(
         self, grimp_graph: grimp.ImportGraph, upstream: str, downstream: str
-    ) -> dotfile.Edge | None:
-        if grimp_graph.direct_import_exists(importer=downstream, imported=upstream):
-            return dotfile.Edge(source=downstream, destination=upstream)
-        return None
+    ) -> dotfile.Edge:
+        return dotfile.Edge(source=downstream, destination=upstream)
 
 
 class _ImportExpressionBuildStrategy(_DotGraphBuildStrategy):
@@ -128,31 +157,32 @@ def _get_self_or_ancestor(candidate: str, ancestors: Set[str]) -> str | None:
                 return ancestor
         return None
 
+    def has_edge(self, grimp_graph: grimp.ImportGraph, upstream: str, downstream: str) -> bool:
+        return grimp_graph.direct_import_exists(
+            importer=downstream, imported=upstream, as_packages=True
+        )
+
     def build_edge(
         self, grimp_graph: grimp.ImportGraph, upstream: str, downstream: str
-    ) -> dotfile.Edge | None:
-        if grimp_graph.direct_import_exists(
-            importer=downstream, imported=upstream, as_packages=True
-        ):
-            if self.show_import_totals:
-                number_of_imports = self._count_imports_between_packages(
-                    grimp_graph, importer=downstream, imported=upstream
-                )
-                label = str(number_of_imports)
-            else:
-                label = ""
-
-            if self.show_cycle_breakers:
-                assert self.cycle_breakers is not None
-                is_cycle_breaker = (downstream, upstream) in self.cycle_breakers
-                emphasized = is_cycle_breaker
-            else:
-                emphasized = False
-
-            return dotfile.Edge(
-                source=downstream, destination=upstream, label=label, emphasized=emphasized
+    ) -> dotfile.Edge:
+        if self.show_import_totals:
+            number_of_imports = self._count_imports_between_packages(
+                grimp_graph, importer=downstream, imported=upstream
             )
-        return None
+            label = str(number_of_imports)
+        else:
+            label = ""
+
+        if self.show_cycle_breakers:
+            assert self.cycle_breakers is not None
+            is_cycle_breaker = (downstream, upstream) in self.cycle_breakers
+            emphasized = is_cycle_breaker
+        else:
+            emphasized = False
+
+        return dotfile.Edge(
+            source=downstream, destination=upstream, label=label, emphasized=emphasized
+        )
 
     @staticmethod
     def _count_imports_between_packages(
@@ -183,6 +213,7 @@ def _build_dot(
     module_name: str,
     show_import_totals: bool,
     show_cycle_breakers: bool,
+    hide_acyclic: bool,
 ) -> dotfile.DotGraph:
     strategy: _DotGraphBuildStrategy
     if show_import_totals or show_cycle_breakers:
@@ -194,4 +225,4 @@ def _build_dot(
     else:
         strategy = _ModuleSquashingBuildStrategy()
 
-    return strategy.build(module_name, grimp_graph)
+    return strategy.build(module_name, grimp_graph, hide_acyclic)

src/impulse/cli.py

@@ -27,12 +27,23 @@ def main():
         "and display them as dashed lines."
     ),
 )
+@click.option(
+    "--hide-acyclic",
+    is_flag=True,
+    help="Hide submodules that are not part of a cycle.",
+)
 @click.argument("module_name", type=str)
-def drawgraph(module_name: str, show_import_totals: bool, show_cycle_breakers: bool) -> None:
+def drawgraph(
+    module_name: str,
+    show_import_totals: bool,
+    show_cycle_breakers: bool,
+    hide_acyclic: bool,
+) -> None:
     use_cases.draw_graph(
         module_name=module_name,
         show_import_totals=show_import_totals,
         show_cycle_breakers=show_cycle_breakers,
+        hide_acyclic=hide_acyclic,
         sys_path=sys.path,
         current_directory=os.getcwd(),
         get_top_level_package=adapters.get_top_level_package,

src/impulse/graph.py

@@ -0,0 +1,104 @@
+import dataclasses
+import itertools
+from typing import Callable, Generic, Iterator, Mapping, TypeVar
+
+V = TypeVar("V")  # type for graph vertices
+
+
+@dataclasses.dataclass(frozen=True)
+class DirectedGraphWithoutLoops(Generic[V]):
+    vertices: frozenset[V]
+    _adjacency_map: Mapping[V, set[V]]
+
+    @classmethod
+    def from_adjacency_condition(cls, vertices: set[V], is_adjacent: Callable[[V, V], bool]):
+        adjacency_map = {
+            from_vertex: {
+                to_vertex
+                for to_vertex in vertices
+                if from_vertex != to_vertex and is_adjacent(from_vertex, to_vertex)
+            }
+            for from_vertex in vertices
+        }
+        return cls(vertices=frozenset(vertices), _adjacency_map=adjacency_map)
+
+    def iter_edges(self) -> Iterator[tuple[V, V]]:
+        for from_vertex in self._adjacency_map:
+            for to_vertex in self._adjacency_map[from_vertex]:
+                yield from_vertex, to_vertex
+
+    def remove_vertices(self, vertices_to_remove: set[V]) -> "DirectedGraphWithoutLoops[V]":
+        new_vertices = frozenset(self.vertices - vertices_to_remove)
+        return self.__class__(
+            vertices=new_vertices,
+            _adjacency_map={
+                from_vertex: self._adjacency_map[from_vertex] - vertices_to_remove
+                for from_vertex in new_vertices
+            },
+        )
+
+    def find_acyclic_vertices(self) -> set[V]:
+        """
+        Find all vertices that are not part of any cycle.
+
+        This function uses Tarjan's strongly connected components algorithm. The
+        algorithm performs a single depth first search of the graph and groups
+        vertices into strongly connected components (SCCs), where each vertex in
+        an SCC is reachable from every other vertex in the same SCC.
+
+        Under the assumption that the graph contains no self loops, a vertex is
+        not part of a cycle if and only if the SCC it is part of contains no
+        other vertices.
+
+        Returns:
+            A set of vertices that are not part of any cycle.
+        """
+        # Vertices are assigned indices in the order they are encountered
+        index_generator: Iterator[int] = itertools.count()
+        index_map: dict[V, int] = {}
+        lowest_reachable_index: dict[V, int] = {}
+
+        active_stack: list[V] = []
+        # Mirror of active_stack for O(1) membership checks
+        active_stack_set: set[V] = set()
+
+        acyclic_vertices: set[V] = set()
+
+        def visit(v: V) -> None:
+            index = next(index_generator)
+
+            index_map[v] = index
+            lowest_reachable_index[v] = index
+
+            active_stack.append(v)
+            active_stack_set.add(v)
+
+            for w in self._adjacency_map.get(v, {}):
+                if w not in index_map:
+                    visit(w)
+                    lowest_reachable_index[v] = min(
+                        lowest_reachable_index[v], lowest_reachable_index[w]
+                    )
+                elif w in active_stack_set:
+                    lowest_reachable_index[v] = min(lowest_reachable_index[v], index_map[w])
+
+            if lowest_reachable_index[v] == index_map[v]:
+                scc: list[V] = []
+                while True:
+                    w = active_stack.pop()
+                    active_stack_set.remove(w)
+                    scc.append(w)
+                    if w == v:
+                        break
+
+                if len(scc) == 1:
+                    acyclic_vertices.update(scc)
+
+        for vertex in self.vertices:
+            if vertex not in index_map:
+                visit(vertex)
+
+        return acyclic_vertices
+
+    def remove_acyclic_vertices(self) -> "DirectedGraphWithoutLoops[V]":
+        return self.remove_vertices(self.find_acyclic_vertices())