feat: add module support to JustfileFixture

Flattens the nested module tree from just --dump into a flat dict keyed
by recipe namepaths (e.g. module::submodule::recipe). All existing
methods (is_private, dependencies, parameters, etc.) work transparently
with full module paths. Adds all_modules property for module discovery.

Backwards compatible — justfiles without modules work unchanged.

Author: bluefing

src/pytest_just/fixture.py

@@ -42,15 +42,22 @@ def _dump(self) -> dict[str, Any]:
             raise JustJsonFormatError("Unexpected just JSON format: top-level value must be an object.")
         return loaded
 
-    @property
-    def _recipes(self) -> dict[str, dict[str, Any]]:
-        """Return the validated recipe mapping from the parsed just dump."""
-        recipes = self._dump.get("recipes", {})
-        if not isinstance(recipes, dict):
+    @cached_property
+    def _flattened(self) -> dict[str, Any]:
+        """Flatten the dump once, returning recipes and modules."""
+        raw = self._dump.get("recipes", {})
+        if not isinstance(raw, dict):
             raise JustJsonFormatError("Unexpected just JSON format: `recipes` must be a mapping.")
-        if not all(isinstance(value, dict) for value in recipes.values()):
+        if not all(isinstance(value, dict) for value in raw.values()):
             raise JustJsonFormatError("Unexpected just JSON format: each recipe payload must be an object.")
-        return recipes
+        modules: list[str] = []
+        recipes = self._flatten(self._dump, modules)
+        return {"recipes": recipes, "modules": sorted(modules)}
+
+    @property
+    def _recipes(self) -> dict[str, dict[str, Any]]:
+        """Recipes flattened across all modules, keyed by namepath."""
+        return self._flattened["recipes"]
 
     def recipe_names(self, *, include_private: bool = False) -> list[str]:
         """List recipe names, optionally including private recipes."""
@@ -233,6 +240,48 @@ def assert_dry_run_contains(
             f"Output:\n{combined_output}"
         )
 
+    @property
+    def all_modules(self) -> list[str]:
+        """All module paths from the dump, sorted alphabetically.
+
+        Example:
+            ``["module_a", "module_a::submodule_a"]``
+        """
+        return self._flattened["modules"]
+
+    @staticmethod
+    def _flatten(
+        node: dict[str, Any],
+        modules: list[str],
+        _prefix: str = "",
+    ) -> dict[str, dict[str, Any]]:
+        """Recursively flatten nested dump into {namepath: recipe_data}.
+
+        Walks the module tree in the just JSON dump and returns a flat dict
+        keyed by each recipe's ``namepath`` (e.g. ``module::submodule::recipe``).
+        Module paths are appended to ``modules``.
+
+        Args:
+            node: A just JSON dump node (root or module subtree).
+            modules: Module paths are appended to this list.
+            _prefix: Internal — current module path prefix for recursion.
+
+        Returns:
+            Flat dict mapping namepath strings to recipe data dicts.
+        """
+        recipes: dict[str, dict[str, Any]] = {}
+        for name, data in node.get("recipes", {}).items():
+            if not isinstance(data, dict):
+                continue
+            recipes[data.get("namepath", name)] = data
+        for mod_name, mod_data in node.get("modules", {}).items():
+            if not isinstance(mod_data, dict):
+                continue
+            mod_path = f"{_prefix}::{mod_name}" if _prefix else mod_name
+            modules.append(mod_path)
+            recipes.update(JustfileFixture._flatten(mod_data, modules, mod_path))
+        return recipes
+
     def _run(
         self,
         *args: str,

tests/test_module_fixture.py

@@ -0,0 +1,153 @@
+"""Tests for ``JustfileFixture`` module-aware recipe resolution."""
+
+from __future__ import annotations
+
+import shutil
+from textwrap import dedent
+from pathlib import Path
+
+import pytest
+
+from pytest_just import JustfileFixture
+from pytest_just.errors import UnknownRecipeError
+
+
+pytestmark = pytest.mark.skipif(shutil.which("just") is None, reason="just binary is required")
+
+
+@pytest.fixture
+def module_tree(tmp_path: Path) -> JustfileFixture:
+    """Justfile with a module and submodule."""
+    (tmp_path / "justfile").write_text(dedent("""
+        mod infra
+        
+        root:
+            @echo root
+    """), encoding="utf-8")
+    mod = tmp_path / "infra"
+    mod.mkdir()
+    (mod / "mod.just").write_text(dedent("""
+        mod deploy
+        
+        _require-infra:
+            @true
+        
+        status: _require-infra
+            @echo ok
+    """), encoding="utf-8")
+    sub = mod / "deploy"
+    sub.mkdir()
+    (sub / "mod.just").write_text(dedent("""
+        [private]
+        up profile='default': _require-deploy
+            @echo up {{ profile }}
+        
+        _require-deploy:
+            @true
+    """), encoding="utf-8")
+    return JustfileFixture(root=tmp_path)
+
+
+def test_recipes_flattened_by_namepath(module_tree: JustfileFixture) -> None:
+    """Recipes from modules appear keyed by full namepath."""
+    names = module_tree.recipe_names(include_private=True)
+    assert "root" in names
+    assert "infra::status" in names
+    assert "infra::_require-infra" in names
+    assert "infra::deploy::up" in names
+    assert "infra::deploy::_require-deploy" in names
+
+
+def test_is_private_with_namepath(module_tree: JustfileFixture) -> None:
+    """Privacy checks work with full module paths."""
+    assert not module_tree.is_private("root")
+    assert not module_tree.is_private("infra::status")
+    assert module_tree.is_private("infra::_require-infra")
+    assert module_tree.is_private("infra::deploy::up")
+
+
+def test_dependencies_with_namepath(module_tree: JustfileFixture) -> None:
+    """Dependency inspection works with full module paths.
+
+    Note: just stores dependency names as module-local names (not namepaths),
+    so dependencies() returns local names like ``_require-infra``.
+    """
+    assert "_require-infra" in module_tree.dependencies("infra::status")
+    assert "_require-deploy" in module_tree.dependencies("infra::deploy::up")
+
+
+def test_parameters_with_namepath(module_tree: JustfileFixture) -> None:
+    """Parameter inspection works with full module paths."""
+    assert "profile" in module_tree.parameter_names("infra::deploy::up")
+
+
+def test_unknown_namepath_raises(module_tree: JustfileFixture) -> None:
+    """Unknown namepath raises UnknownRecipeError."""
+    with pytest.raises(UnknownRecipeError):
+        module_tree.dependencies("infra::nonexistent")
+
+
+def test_all_modules(module_tree: JustfileFixture) -> None:
+    """all_modules discovers module paths from the dump."""
+    assert "infra" in module_tree.all_modules
+    assert "infra::deploy" in module_tree.all_modules
+
+
+def test_recipe_names_excludes_private_by_default(module_tree: JustfileFixture) -> None:
+    """Public recipe listing excludes private recipes across modules."""
+    public = module_tree.recipe_names()
+    assert "infra::status" in public
+    assert "infra::_require-infra" not in public
+    assert "infra::deploy::up" not in public  # marked [private]
+
+
+def test_flatten_static_method() -> None:
+    """_flatten works as a standalone static method."""
+    dump = {
+        "recipes": {
+            "root": {"namepath": "root", "private": False},
+        },
+        "modules": {
+            "foo": {
+                "recipes": {
+                    "bar": {"namepath": "foo::bar", "private": False},
+                },
+                "modules": {
+                    "baz": {
+                        "recipes": {
+                            "qux": {"namepath": "foo::baz::qux", "private": True},
+                        },
+                        "modules": {},
+                    }
+                },
+            }
+        },
+    }
+
+    modules: list[str] = []
+    flat = JustfileFixture._flatten(dump, modules)
+    assert set(flat.keys()) == {"root", "foo::bar", "foo::baz::qux"}
+    assert flat["foo::baz::qux"]["private"] is True
+    assert sorted(modules) == ["foo", "foo::baz"]
+
+
+def test_flatten_collects_modules() -> None:
+    """_flatten collects module paths when given a list."""
+    dump = {
+        "recipes": {},
+        "modules": {
+            "foo": {
+                "recipes": {},
+                "modules": {
+                    "bar": {
+                        "recipes": {},
+                        "modules": {},
+                    }
+                },
+            }
+        },
+    }
+
+    modules: list[str] = []
+    JustfileFixture._flatten(dump, modules)
+    assert sorted(modules) == ["foo", "foo::bar"]