Raise ValueError when a module is assigned to more than one layer

find_illegal_dependencies_for_layers panicked with an opaque
pyo3_runtime.PanicException ("no entry found for key") when the same module
appeared in more than one layer. Add a Python-side guard that raises a
descriptive ValueError naming the repeated module(s) before the call reaches
the Rust extension, and cover it with tests.

Fixes #165.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

CHANGELOG.rst

@@ -13,6 +13,8 @@ latest
 * Raise `ModuleNotPresent` instead of an unclear error when `find_modules_that_directly_import` or
   `find_modules_directly_imported_by` is called with a module that is not in the graph.
   (https://github.com/python-grimp/grimp/issues/113)
+* Raise `ValueError` instead of pyo3_runtime.PanicException when a duplicate layer
+  module is passed to `find_illegal_dependencies_for_layers`.
 
 3.14 (2025-12-10)
 -----------------

src/grimp/application/graph.py

@@ -446,9 +446,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(
@@ -531,6 +533,30 @@ 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()
+    duplicates = set()
+
+    flattened_modules = [module for layer in layers for module in layer.module_tails]
+    for module in flattened_modules:
+        if module in seen:
+            duplicates.add(module)
+        else:
+            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,62 @@ 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")),
+            )
+
+    def test_multiple_duplicate_modules_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: 'blue', 'red', 'yellow'."
+            ),
+        ):
+            graph.find_illegal_dependencies_for_layers(
+                layers=(
+                    Layer("one", "blue"),
+                    Layer("blue", "two", "three", "yellow"),
+                    # Note that green doesn't cause an error as these are stored as a set.
+                    Layer("green", "four", "green"),
+                    Layer("five"),
+                    Layer("red"),
+                    Layer("yellow"),
+                    Layer("red"),
+                ),
+            )
+
+
 # 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: