Raise ValueError when a module is assigned to more than one layer (#165)

CHANGELOG.rst

@@ -10,6 +10,9 @@ latest
 * Tweak Just commands for running version-specific Python tests.
 * Remove `typing-extensions` as a dependency.
 * Make package FIPS compatible by marking blake2 hashing with `usedforsecurity=False`.
+* Raise a descriptive `ValueError` instead of an unhelpful panic when the same module is assigned to
+  more than one layer in `find_illegal_dependencies_for_layers`.
+  (https://github.com/python-grimp/grimp/issues/165)
 
 3.14 (2025-12-10)
 -----------------

src/grimp/application/graph.py

@@ -433,9 +433,11 @@ def find_illegal_dependencies_for_layers(
             lower layer (the 'upstream') to the higher layer (the 'downstream').
 
         Raises:
+            ValueError: if the same module is assigned to more than one layer.
             NoSuchContainer: if the container is not a module in the graph.
         """
         layers = _parse_layers(layers)
+        _check_layers_do_not_share_modules(layers)
         try:
             result = self._rustgraph.find_illegal_dependencies_for_layers(
                 layers=tuple(
@@ -518,6 +520,27 @@ def _parse_layers(layers: Sequence[Layer | str | set[str]]) -> tuple[Layer, ...]
     return tuple(out_layers)
 
 
+def _check_layers_do_not_share_modules(layers: tuple[Layer, ...]) -> None:
+    """
+    Raise ValueError if any module is assigned to more than one layer.
+
+    A module cannot sit at two different levels at once. Without this guard a
+    repeated module surfaces as an unhelpful panic from the underlying Rust
+    extension rather than a clear error.
+    """
+    seen: set[str] = set()
+    duplicates: set[str] = set()
+    for layer in layers:
+        for module in layer.module_tails:
+            if module in seen:
+                duplicates.add(module)
+            seen.add(module)
+    if duplicates:
+        formatted = ", ".join(repr(module) for module in sorted(duplicates))
+        msg = f"Modules can only belong to one layer, but the following appear in more than one: {formatted}."
+        raise ValueError(msg)
+
+
 def _dependencies_from_tuple(
     rust_package_dependency_tuple: tuple[_RustPackageDependency, ...],
 ) -> set[PackageDependency]:

tests/unit/application/graph/test_layers.py

@@ -840,6 +840,39 @@ def test_single_missing_container(self, missing_container: str):
             )
 
 
+class TestInvalidLayers:
+    def test_module_in_multiple_layers_raises_value_error(self):
+        graph = ImportGraph()
+        graph.add_module("mypackage")
+        graph.add_module("mypackage.foo")
+        graph.add_module("mypackage.bar")
+
+        with pytest.raises(
+            ValueError,
+            match=re.escape(
+                "Modules can only belong to one layer, but the following appear in "
+                "more than one: 'mypackage.foo'."
+            ),
+        ):
+            graph.find_illegal_dependencies_for_layers(
+                layers=("mypackage.foo", "mypackage.bar", "mypackage.foo"),
+            )
+
+    def test_module_shared_across_sibling_layers_raises_value_error(self):
+        graph = ImportGraph()
+
+        with pytest.raises(
+            ValueError,
+            match=re.escape(
+                "Modules can only belong to one layer, but the following appear in "
+                "more than one: 'shared'."
+            ),
+        ):
+            graph.find_illegal_dependencies_for_layers(
+                layers=(Layer("high", "shared"), Layer("shared", "low")),
+            )
+
+
 # TODO: move test to within Rust.
 @pytest.mark.skip(reason="This only passes if run on its own, due to pyo3_log caching.")
 class TestLogging: