pytest-rhiza 0.2.1__py3-none-any.whl

pytest_rhiza/__init__.py

@@ -0,0 +1,18 @@
+"""The rhiza repository checks, packaged as a pytest plugin.
+
+Two halves, because pytest treats them differently:
+
+* :mod:`pytest_rhiza.plugin` is the ``pytest11`` entry point. It contributes the
+  ``root``, ``logger`` and ``latest_tag`` fixtures to every session, which is what
+  removes ``.rhiza/tests/conftest.py`` from consumer repositories.
+* :mod:`pytest_rhiza.checks` holds the check modules themselves. An entry point cannot
+  contribute *tests*, so these are collected explicitly with ``--pyargs``.
+
+See ``README.md`` for the make wiring that replaces the synced folder.
+"""
+
+__all__ = ["__version__"]
+
+# Kept in step with [project].version by bump-my-version; no [[files]] entry is needed
+# for pyproject.toml itself, only for this one.
+__version__ = "0.1.0"

pytest_rhiza/_fences.py

@@ -0,0 +1,96 @@
+"""Markdown fence parsing shared by the two README checks.
+
+**Why this module exists.** Upstream, ``SKIP_FLAG`` and ``_should_skip`` are duplicated
+between ``core``'s ``test_readme.py`` and the ``tests`` bundle's
+``test_readme_validation.py``, and both files say why::
+
+    Bundles are copied independently — a Rust project receives this file and not the
+    other — so a shared helper would need a third home that both bundles ship, which is
+    a worse trade for four lines.
+
+One distribution *is* that third home, so the trade reverses. The duplication also had a
+second cost that is easy to miss: the ``TestSkipFlag`` classes exercising these helpers
+shipped into every consumer repository, where they tested template code against itself.
+They now live in this package's own suite instead.
+
+The regexes and the flag keep their upstream names so the ported checks read as a move.
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+import subprocess  # nosec B404
+
+# Bash code blocks — captures optional flags (e.g. "+RHIZA_SKIP") and the code body.
+BASH_BLOCK = re.compile(r"```bash([^\n]*)\n(.*?)```", re.DOTALL)
+
+# Python code blocks, same shape.
+CODE_BLOCK = re.compile(r"```python([^\n]*)\n(.*?)```", re.DOTALL)
+
+# The ```result fences a python fence's stdout is diffed against.
+RESULT = re.compile(r"```result\n(.*?)```", re.DOTALL)
+
+# Bash executable used for syntax checking; `bash -n` parses without executing.
+BASH = "bash"
+
+# A snippet that is unambiguously valid bash: `:` is the no-op builtin. Used to probe
+# the toolchain rather than the README.
+_PROBE = ":\n"
+
+# Flag marking a fence as intentionally excluded. Usage: add it after the language
+# identifier on the opening fence line, e.g. ```bash +RHIZA_SKIP
+SKIP_FLAG = "+RHIZA_SKIP"
+
+# Box-drawing characters mean the fence is a directory tree, not runnable shell.
+TREE_MARKERS = ("├──", "└──", "│")
+
+
+def should_skip(flags: str) -> bool:
+    """Return True if the fence flags string contains the +RHIZA_SKIP marker.
+
+    Args:
+        flags: Text following the language identifier on the opening fence line.
+
+    Returns:
+        True when the block is intentionally excluded.
+
+    Examples:
+        >>> should_skip(" +RHIZA_SKIP")
+        True
+        >>> should_skip("other-flag")
+        False
+    """
+    return SKIP_FLAG in flags
+
+
+@functools.cache
+def bash_usable() -> bool:
+    r"""Return True when ``bash -n`` actually parses a trivially valid snippet.
+
+    **Why probe instead of just running the check.** ``bash -n`` reports a syntax error
+    by exiting non-zero, so anything else that exits non-zero is indistinguishable from
+    one. On Windows that is not hypothetical: ``bash`` can resolve to
+    ``C:\Windows\System32\bash.exe``, the WSL launcher, which exits non-zero having
+    written nothing to stderr when no distribution is installed. The README checks then
+    fail on ``make install`` and print an empty error, which is worse than not running:
+    it accuses the project of a defect the tool invented.
+
+    Probing with :data:`_PROBE` separates "this fence is broken" from "there is no usable
+    bash here", so the checks can skip honestly in the second case. The result is cached
+    because it cannot change within a session and every fence would otherwise re-pay it.
+
+    Returns:
+        True when a working bash was found, False otherwise.
+    """
+    try:
+        result = subprocess.run(  # noqa: S603 - fixed argument list, no shell  # nosec B603
+            [BASH, "-n"],
+            input=_PROBE,
+            capture_output=True,
+            text=True,
+        )
+    except OSError:
+        # bash is absent entirely, or not executable.
+        return False
+    return result.returncode == 0

pytest_rhiza/checks/__init__.py

@@ -0,0 +1,24 @@
+"""The check modules, collected with ``--pyargs`` rather than by entry point.
+
+A ``pytest11`` plugin can contribute fixtures, hooks and options; it cannot contribute
+tests. So the checks are named explicitly on the command line:
+
+.. code-block:: bash
+
+    pytest --pyargs pytest_rhiza.checks.test_readme pytest_rhiza.checks.test_pyproject
+
+**One module per file the template used to sync**, names unchanged. That is deliberate:
+selection stays where it already is — with the make fragment the owning bundle ships, one
+``RHIZA_CHECKS +=`` line each — so a Python project never names the Cargo checks and
+nothing has to sniff for manifests at runtime to decide what applies.
+
+| module | bundle that names it | replaces |
+| --- | --- | --- |
+| ``test_readme`` | ``core`` | ``.rhiza/tests/test_readme.py`` |
+| ``test_release_tags`` | ``core`` | ``.rhiza/tests/test_release_tags.py`` |
+| ``test_pyproject`` | ``python-core`` | ``.rhiza/tests/test_pyproject.py`` |
+| ``test_docstrings`` | ``python-core`` | ``.rhiza/tests/test_docstrings.py`` |
+| ``test_readme_validation`` | ``tests`` | ``.rhiza/tests/test_readme_validation.py`` |
+| ``test_cargo_toml`` | ``rust-core`` | ``.rhiza/tests/test_cargo_toml.py`` |
+| ``test_go_module`` | ``go-core`` | ``.rhiza/tests/test_go_module.py`` |
+"""

pytest_rhiza/checks/test_cargo_toml.py

@@ -0,0 +1,296 @@
+"""Tests for Cargo.toml structure and the release config that rewrites it.
+
+Ported from ``jebel-quant/rhiza`` at 89f9298, where bundle ``rust-core`` synced it
+to ``.rhiza/tests/test_cargo_toml.py``. It now arrives installed, and is collected by name:
+``pytest --pyargs pytest_rhiza.checks.test_cargo_toml``.
+
+The Rust counterpart of ``test_pyproject.py``. Written in Python and run through uv by
+``make rhiza-test`` rather than as a ``#[test]``, for the same reason the rest of the
+suite is: it validates *configuration*, and the release flow that reads it is Python
+tooling. ``uv`` lives in ``core`` precisely so it is available whatever the project's
+language.
+
+Validates that Cargo.toml:
+- is syntactically valid TOML
+- contains the [package] fields cargo publish requires
+- declares a semver version
+- carries a license or license-file, which deny.toml's allow-list checks against
+- version matches the latest git tag (vX.Y.Z → X.Y.Z)
+
+…and that the shipped .bumpversion.toml can still write the version back:
+- it is the config bump-my-version discovers, and nothing shadows it
+- it points at Cargo.toml's [package] table, anchored
+- it leaves the commit and the tag to /rhiza:release
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from pathlib import Path
+
+import pytest
+
+_SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+")
+
+# cargo tolerates more than this, but a crate that cannot be published is a crate whose
+# release flow breaks at the last step rather than the first.
+_REQUIRED_PACKAGE_FIELDS = ("name", "version", "edition", "description")
+
+# The only filenames bump-my-version auto-discovers (#1453). A Rust project owns none of
+# them natively, which is why rust-core ships the first one.
+_DISCOVERABLE_CONFIGS = (".bumpversion.toml", ".bumpversion.cfg", "setup.cfg", "pyproject.toml")
+
+
+def _has_bumpversion_section(path: Path) -> bool:
+    """Report whether a config file carries a bumpversion section at all.
+
+    Args:
+        path: Candidate config file; a missing or malformed file counts as absent.
+
+    Returns:
+        True when the file declares ``[tool.bumpversion]`` (TOML) or ``[bumpversion]``
+        (INI).
+    """
+    if not path.is_file():
+        return False
+    if path.suffix == ".cfg":
+        return "[bumpversion]" in path.read_text(encoding="utf-8")
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except tomllib.TOMLDecodeError:
+        return False
+    return isinstance(data.get("tool", {}).get("bumpversion"), dict)
+
+
+@pytest.fixture(scope="module")
+def cargo_toml(root: Path) -> dict:
+    """Load and return Cargo.toml as a parsed dict."""
+    path = root / "Cargo.toml"
+    if not path.exists():
+        pytest.skip("Cargo.toml not found")
+    with path.open("rb") as handle:
+        return tomllib.load(handle)
+
+
+@pytest.fixture(scope="module")
+def package(cargo_toml: dict) -> dict:
+    """Return the [package] table, skipping on a virtual workspace manifest.
+
+    A workspace root legitimately has no ``[package]`` — it carries only
+    ``[workspace]`` — and its members hold the versions. Nothing here applies.
+    """
+    table = cargo_toml.get("package")
+    if not isinstance(table, dict):
+        if "workspace" in cargo_toml:
+            pytest.skip("virtual workspace manifest — the members carry the versions")
+        pytest.fail("Cargo.toml is missing a [package] table")
+    return table
+
+
+@pytest.fixture(scope="module")
+def bumpversion(root: Path) -> dict:
+    """Return the [tool.bumpversion] table from .bumpversion.toml."""
+    path = root / ".bumpversion.toml"
+    if not path.is_file():
+        pytest.skip(".bumpversion.toml not found — reported by TestBumpversionConfig")
+    with path.open("rb") as handle:
+        return tomllib.load(handle).get("tool", {}).get("bumpversion", {})
+
+
+class TestCargoToml:
+    """Tests for basic Cargo.toml existence and validity."""
+
+    def test_cargo_toml_exists(self, root: Path) -> None:
+        """Cargo.toml must exist at the project root."""
+        assert (root / "Cargo.toml").is_file(), "Cargo.toml not found at project root"
+
+    def test_cargo_toml_is_valid_toml(self, root: Path) -> None:
+        """Cargo.toml must be syntactically valid TOML."""
+        with (root / "Cargo.toml").open("rb") as handle:
+            data = tomllib.load(handle)
+        assert isinstance(data, dict), "Parsed Cargo.toml must be a TOML table"
+
+
+class TestPackageFields:
+    """Tests for required fields within the [package] table."""
+
+    @pytest.mark.parametrize("field", _REQUIRED_PACKAGE_FIELDS)
+    def test_required_field_present(self, package: dict, field: str) -> None:
+        """Each required [package] field must be present."""
+        assert field in package, f"[package] is missing required field '{field}'"
+
+    def test_name_is_non_empty_string(self, package: dict) -> None:
+        """[package].name must be a non-empty string."""
+        name = package.get("name", "")
+        assert isinstance(name, str), "[package].name must be a string"
+        assert name.strip(), "[package].name must be a non-empty string"
+
+    def test_version_follows_semver(self, package: dict) -> None:
+        """[package].version must follow semver (MAJOR.MINOR.PATCH).
+
+        Not merely a convention here: ``.bumpversion.toml``'s ``parse`` regex and its
+        ``tag_name = "v{new_version}"`` both assume this shape, and a version cargo
+        accepts but that regex does not would fail the release rather than the build.
+        """
+        version = package.get("version", "")
+        if isinstance(version, dict):
+            pytest.skip("[package].version is inherited from the workspace")
+        assert _SEMVER_RE.match(str(version)), (
+            f"[package].version {version!r} does not follow semver (expected MAJOR.MINOR.PATCH)"
+        )
+
+    def test_description_is_non_empty_string(self, package: dict) -> None:
+        """[package].description must be a non-empty string."""
+        desc = package.get("description", "")
+        if isinstance(desc, dict):
+            pytest.skip("[package].description is inherited from the workspace")
+        assert isinstance(desc, str), "[package].description must be a string"
+        assert desc.strip(), "[package].description must be a non-empty string"
+
+    def test_a_license_is_declared(self, package: dict) -> None:
+        """[package] must declare `license` or `license-file`.
+
+        ``make license`` is ``cargo deny check licenses`` and deny.toml is an
+        allow-list, so a crate with no licence of its own fails that gate on itself
+        rather than on a dependency.
+        """
+        declared = [key for key in ("license", "license-file") if package.get(key)]
+        assert declared, (
+            "[package] declares neither 'license' nor 'license-file'; `make license` runs "
+            "cargo-deny against an allow-list and fails a crate that does not state its own"
+        )
+
+
+class TestBumpversionConfig:
+    """The release flow must find a version config, not silently invent one (#1453).
+
+    bump-my-version searches four filenames and stops. Finding none it does **not**
+    fail — it falls back to ``git describe`` and reports the last reachable tag as the
+    current version, so a release can be cut at a version that already exists. A Rust
+    project owns none of those four filenames natively, so ``rust-core`` ships a root
+    ``.bumpversion.toml``; these tests assert it is still the file that wins and still
+    points where the version actually lives.
+    """
+
+    def test_a_discoverable_config_exists(self, root: Path) -> None:
+        """A bumpversion section must live in a file bump-my-version actually reads."""
+        found = [name for name in _DISCOVERABLE_CONFIGS if _has_bumpversion_section(root / name)]
+        hint = ""
+        if (root / ".rhiza" / ".cfg.toml").is_file():
+            hint = (
+                " A leftover .rhiza/.cfg.toml is present: that path is never auto-discovered "
+                "(it predates the fix for issue #1453) and can be deleted."
+            )
+        assert found, (
+            f"No bumpversion config was found in any file bump-my-version searches "
+            f"({', '.join(_DISCOVERABLE_CONFIGS)}). It will silently fall back to "
+            f"`git describe`, so a release can be cut at a version that already exists. "
+            f"Restore the .bumpversion.toml the rust-core bundle ships.{hint}"
+        )
+
+    def test_no_pyproject_shadows_the_rust_config(self, root: Path) -> None:
+        """A stray ``[tool.bumpversion]`` in pyproject.toml must not take over.
+
+        ``.bumpversion.toml`` is searched first, so this is about the reverse mistake:
+        a Rust repo that also carries a Python manifest (a helper package, a docs
+        toolchain) and declares the table there too now has two configs, only one of
+        which knows about Cargo.toml.
+        """
+        if not _has_bumpversion_section(root / ".bumpversion.toml"):
+            pytest.skip("no .bumpversion.toml — reported by test_a_discoverable_config_exists")
+        duplicates = [
+            name
+            for name in _DISCOVERABLE_CONFIGS
+            if name != ".bumpversion.toml" and _has_bumpversion_section(root / name)
+        ]
+        assert not duplicates, (
+            f"{duplicates} also declares a bumpversion section. .bumpversion.toml is searched "
+            f"first and wins, so the other config is inert — and being inert, it drifts."
+        )
+
+    def test_the_config_does_not_pin_a_current_version(self, bumpversion: dict) -> None:
+        """``current_version`` must stay absent from a synced config.
+
+        The file is owned by rhiza, so a value only the consuming repo can maintain
+        would be reset by the next ``/rhiza:update``. Omitting it makes bump-my-version
+        derive the version from the newest tag matching ``tag_name``, which is what
+        Cargo.toml carries in any repo whose crate version and tags agree.
+        """
+        assert "current_version" not in bumpversion, (
+            "[tool.bumpversion].current_version is set in a file rhiza syncs; the next "
+            "/rhiza:update would overwrite it. Omit the key and let the newest tag supply it."
+        )
+
+    def test_the_config_targets_cargo_toml(self, bumpversion: dict) -> None:
+        """A ``[[files]]`` entry must point at Cargo.toml, or nothing gets rewritten.
+
+        With no entry for it the bump still "succeeds": it rewrites ``current_version``
+        in its own config, tags nothing, and leaves ``[package].version`` untouched.
+        """
+        targets = [entry.get("filename") for entry in bumpversion.get("files", [])]
+        assert "Cargo.toml" in targets, (
+            f"no [[tool.bumpversion.files]] entry targets Cargo.toml (found {targets}); "
+            f"a bump would leave [package].version untouched"
+        )
+
+    def test_the_cargo_toml_pattern_is_anchored_to_the_package_table(self, bumpversion: dict) -> None:
+        """The search must be anchored, or it rewrites a same-numbered dependency.
+
+        ``search``/``replace`` are applied to *every* occurrence in the file, so a bare
+        ``version = "{current_version}"`` also rewrites a ``[dependencies]`` entry that
+        happens to share the crate's number.
+        """
+        entries = [entry for entry in bumpversion.get("files", []) if entry.get("filename") == "Cargo.toml"]
+        if not entries:
+            pytest.skip("no Cargo.toml entry — reported by test_the_config_targets_cargo_toml")
+        for entry in entries:
+            search = str(entry.get("search", ""))
+            assert entry.get("regex") is True, (
+                f"the Cargo.toml entry's search {search!r} is not a regex, so it cannot be "
+                f"anchored to the [package] table and would also rewrite a [dependencies] pin "
+                f"sharing the crate's version"
+            )
+            # Backslashes stripped before matching: the anchored form is a regex, so the
+            # table header is escaped there as `\[package\]`.
+            assert "[package]" in search.replace("\\", ""), (
+                f"the Cargo.toml entry's search {search!r} does not mention the [package] table; "
+                f"an unanchored version pattern also rewrites a [dependencies] entry that happens "
+                f"to share the crate's number"
+            )
+
+    def test_the_release_flow_owns_the_commit_and_the_tag(self, bumpversion: dict) -> None:
+        """``/rhiza:release`` folds the changelog into the bump commit and tags it itself."""
+        for key in ("commit", "tag"):
+            assert bumpversion.get(key, False) is False, (
+                f"[tool.bumpversion].{key} must be false: the release flow commits and tags "
+                f"itself so the changelog lands in the bump commit, and a bare "
+                f"`bump-my-version bump` would otherwise add a second commit and a duplicate tag"
+            )
+
+
+class TestGitTagVersion:
+    """Harmony between the latest git tag and the crate version.
+
+    Reachability of that tag is asserted by ``test_release_tags.py``, which ``core``
+    ships for every language layer.
+    """
+
+    def test_latest_tag_matches_cargo_version(self, latest_tag: str, package: dict) -> None:
+        """The latest git tag (vX.Y.Z) must match [package].version.
+
+        This is the invariant ``.bumpversion.toml`` relies on rather than a style
+        preference. With no ``current_version`` key, bump-my-version reads the current
+        version from the newest tag and then searches Cargo.toml for it; if the two
+        disagree the next release fails with "did not find current version" — loudly,
+        but only at release time, which is the worst moment to find out.
+        """
+        version = package.get("version")
+        if isinstance(version, dict):
+            pytest.skip("[package].version is inherited from the workspace")
+        assert latest_tag.lstrip("v") == str(version), (
+            f"Latest git tag {latest_tag!r} does not match [package].version {version!r}. "
+            f"bump-my-version derives the current version from the tag and then looks for it "
+            f"in Cargo.toml, so the next release would fail to find it."
+        )

pytest_rhiza/checks/test_docstrings.py

@@ -0,0 +1,213 @@
+"""Tests for module docstrings using doctest.
+
+Ported from ``jebel-quant/rhiza`` at 89f9298, where bundle ``python-core`` synced it
+to ``.rhiza/tests/test_docstrings.py``. It now arrives installed, and is collected by name:
+``pytest --pyargs pytest_rhiza.checks.test_docstrings``.
+
+Automatically discovers all packages and runs doctests for each.
+
+**Scope.** The folders searched come from ``RHIZA_DOCTEST_FOLDERS``, which ``quality.mk``
+sets from python-core's ``DOCSTRING_FOLDERS`` accumulator — the same list ``make
+docs-coverage`` uses. With the variable unset (running pytest by hand, say) it falls back
+to ``SOURCE_FOLDER`` from ``.rhiza/.env``, defaulting to ``src``.
+
+That indirection exists because this gate used to resolve ``src`` and nothing else, so a
+project keeping Python outside its source root had its docstring examples silently
+skipped — the mother repo being the extreme case, with no ``src/`` at all and 23 unchecked
+examples in ``utils/`` (#1517). It is the same hole #1505 closed for the Makefile gates
+and #1516 for coverage, in the shipped suite rather than in make.
+
+**Two layouts, deliberately.** A folder may hold packages (``src/mypkg/__init__.py``) or
+loose scripts (``utils/link_dogfood.py``); both carry docstrings worth checking, so both
+are discovered. A module that cannot be imported is reported as a warning and skipped, not
+failed: a loose script may execute at import, and "we could not measure this" is a
+different statement from "this example is wrong".
+"""
+
+from __future__ import annotations
+
+import doctest
+import importlib
+import importlib.util
+import os
+import warnings
+from pathlib import Path
+
+import pytest
+from dotenv import dotenv_values
+
+# Read .rhiza/.env at collection time (no environment side-effects).
+RHIZA_ENV_PATH = Path(".rhiza/.env")
+
+# Set by `make rhiza-test` from DOCSTRING_FOLDERS; whitespace-separated.
+DOCTEST_FOLDERS_ENV = "RHIZA_DOCTEST_FOLDERS"
+
+
+def _iter_modules_from_path(logger, package_path: Path, src_path: Path):
+    """Recursively find all Python modules in a directory."""
+    for path in package_path.rglob("*.py"):
+        if path.name == "__init__.py":
+            module_path = path.parent.relative_to(src_path)
+        else:
+            module_path = path.relative_to(src_path).with_suffix("")
+
+        # Convert path to module name in an OS-independent way
+        module_name = ".".join(module_path.parts)
+
+        try:
+            yield importlib.import_module(module_name)
+        except ImportError as e:
+            warnings.warn(f"Could not import {module_name}: {e}", stacklevel=2)
+            logger.warning("Could not import module %s: %s", module_name, e)
+            continue
+
+
+def _find_packages(src_path: Path):
+    """Find all packages in the source path, including those nested under namespace packages."""
+    for init_file in src_path.rglob("__init__.py"):
+        package_dir = init_file.parent
+        # Only yield top-level packages (those whose parent doesn't have __init__.py or is src_path)
+        parent = package_dir.parent
+        if parent == src_path or not (parent / "__init__.py").exists():
+            yield package_dir
+
+
+def _doctest_folders(root: Path, values: dict) -> list[Path]:
+    """Return the existing folders whose docstrings should be doctested.
+
+    Args:
+        root: The repository root.
+        values: The parsed ``.rhiza/.env`` mapping.
+
+    Returns:
+        Each configured folder that exists, in order, without duplicates.
+    """
+    configured = os.environ.get(DOCTEST_FOLDERS_ENV, "").split()
+    if not configured:
+        configured = [values.get("SOURCE_FOLDER") or "src"]
+
+    folders: list[Path] = []
+    for name in configured:
+        path = root / name
+        if path.is_dir() and path not in folders:
+            folders.append(path)
+    return folders
+
+
+def _iter_loose_modules(logger, folder: Path):
+    """Import the top-level ``*.py`` files in ``folder`` that are not part of a package.
+
+    A folder of standalone scripts (``utils/``, ``scripts/``, ``tools/``) has no
+    ``__init__.py``, so :func:`_find_packages` never reaches it even though its docstrings
+    may carry examples. Each file is loaded from its path rather than by module name, so
+    no ``sys.path`` manipulation is needed and two folders may hold same-named scripts.
+
+    Args:
+        logger: The test logger.
+        folder: The directory to scan (not recursed — a package below it is the other
+            discovery path's job).
+
+    Yields:
+        Each imported module. A module that raises on import is warned about and skipped:
+        a loose script may run code at import time, and being unable to measure an example
+        is not the same as the example being wrong.
+    """
+    if (folder / "__init__.py").exists():
+        return  # a package; _find_packages handles it
+
+    for path in sorted(folder.glob("*.py")):
+        spec = importlib.util.spec_from_file_location(path.stem, path)
+        if spec is None or spec.loader is None:  # pragma: no cover - defensive
+            continue
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+        except BaseException as e:  # noqa: BLE001 - a script may raise or SystemExit on import
+            warnings.warn(f"Could not import {path}: {e}", stacklevel=2)
+            logger.warning("Could not import loose module %s: %s", path, e)
+            continue
+        yield module
+
+
+def test_doctests(logger, root, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]):
+    """Run doctests for every module in the configured folders."""
+    values = dotenv_values(root / RHIZA_ENV_PATH) if (root / RHIZA_ENV_PATH).exists() else {}
+    folders = _doctest_folders(root, values)
+
+    logger.info("Starting doctest discovery in: %s", [str(f) for f in folders] or "(nothing configured)")
+    if not folders:
+        configured = os.environ.get(DOCTEST_FOLDERS_ENV) or values.get("SOURCE_FOLDER") or "src"
+        logger.info("No doctest folder exists (looked for: %s) — skipping doctests", configured)
+        pytest.skip(f"No doctest folder found (looked for: {configured})")
+
+    total_tests = 0
+    total_failures = 0
+    failed_modules = []
+
+    def _run(module) -> None:
+        """Run one module's doctests and fold the result into the running totals."""
+        nonlocal total_tests, total_failures
+        logger.debug("Running doctests for module: %s", module.__name__)
+        # Disable pytest's stdout capture during doctest to avoid interference
+        with capsys.disabled():
+            results = doctest.testmod(
+                module,
+                verbose=False,
+                optionflags=(doctest.ELLIPSIS | doctest.NORMALIZE_WHITESPACE),
+            )
+        total_tests += results.attempted
+
+        if results.failed:
+            logger.warning(
+                "Doctests failed for %s: %d/%d failed",
+                module.__name__,
+                results.failed,
+                results.attempted,
+            )
+            total_failures += results.failed
+            failed_modules.append((module.__name__, results.failed, results.attempted))
+        else:
+            logger.debug("Doctests passed for %s (%d test(s))", module.__name__, results.attempted)
+
+    for src_path in folders:
+        # Add the folder to sys.path with automatic cleanup
+        monkeypatch.syspath_prepend(str(src_path))
+        logger.debug("Prepended to sys.path: %s", src_path)
+
+        # Find all packages in the folder (supports namespace packages)
+        for package_dir in _find_packages(src_path):
+            if package_dir.is_dir() and (package_dir / "__init__.py").exists():
+                # Import the package
+                package_name = package_dir.name
+                logger.info("Discovered package: %s", package_name)
+                try:
+                    modules = list(_iter_modules_from_path(logger, package_dir, src_path))
+                    logger.debug("%d module(s) found in package %s", len(modules), package_name)
+
+                    for module in modules:
+                        _run(module)
+
+                except ImportError as e:
+                    warnings.warn(f"Could not import package {package_name}: {e}", stacklevel=2)
+                    logger.warning("Could not import package %s: %s", package_name, e)
+                    continue
+
+        # And the loose scripts, which no package walk reaches
+        for module in _iter_loose_modules(logger, src_path):
+            _run(module)
+
+    if failed_modules:
+        formatted = "\n".join(f"  {name}: {failed}/{attempted} failed" for name, failed, attempted in failed_modules)
+        msg = (
+            f"Doctest summary: {total_tests} tests across {len(failed_modules)} module(s)\n"
+            f"Failures: {total_failures}\n"
+            f"Failed modules:\n{formatted}"
+        )
+        logger.error("%s", msg)
+        assert total_failures == 0, msg
+    else:
+        logger.info("Doctest summary: %d tests, 0 failures", total_tests)
+
+    if total_tests == 0:
+        logger.info("No doctests were found in any module — skipping")
+        pytest.skip("No doctests were found in any module")