Run Python coverage tooling in a venv

.github/actions/generate-coverage/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v1.3.14 (2026-04-28)
+
+- Run Python coverage tooling in an isolated, job-local virtual environment
+  (`.venv-coverage`) instead of using `uv run --with`. The venv is created
+  once per process, reused across calls within the same job, and repaired
+  automatically when the Python executable is missing.
+- Project dependencies are synced into the venv via `uv sync --inexact
+  --python`; `slipcover`, `pytest`, and `coverage` are installed via
+  `uv pip install --python` without `--system`.
+- Broken-venv recovery: if `.venv-coverage` exists but its Python executable
+  is absent or a non-directory placeholder occupies its path, the directory is
+  removed and recreated before proceeding.
+
 ## v1.3.13 (2026-04-16)
 
 - Override Cranelift coverage builds via

.github/actions/generate-coverage/README.md

@@ -7,8 +7,10 @@ projects. The action uses `cargo llvm-cov` (with `cargo nextest` by default)
 when a `Cargo.toml` is present and `slipcover` with `pytest` when a
 `pyproject.toml` is present. If the repository root does not contain a Cargo
 manifest, set `cargo-manifest` to point to a nested `Cargo.toml`. It installs
-`slipcover` and `pytest` automatically via `uv` before running the tests,
-leveraging ``uv run --with`` so no system-level Python installs are required.
+the project dependencies plus `slipcover`, `pytest`, and `coverage`
+automatically via `uv` into an isolated throwaway virtual environment
+(`.venv-coverage`) before running the tests, so no system-level Python installs
+are required.
 When Rust coverage is required, `cargo-llvm-cov` and `cargo-nextest` are
 installed automatically. If both configuration files are present, coverage is
 run for each language and the Cobertura reports are merged using
@@ -45,6 +47,7 @@ codegen-backend-related variables first, and then merges
 `get_cargo_coverage_env(manifest_path)` on top so workflow-level Cranelift
 exports are not treated as the default coverage behaviour.
 
+<!-- markdownlint-disable MD013 -->
 ```mermaid
 sequenceDiagram
     actor GitHubActions
@@ -78,6 +81,7 @@ sequenceDiagram
         _run_cargo-->>run_rust_py: stdout
     end
 ```
+<!-- markdownlint-enable MD013 -->
 
 ## Cranelift codegen backend support
 
@@ -123,6 +127,7 @@ Known limitations:
 
 ## Inputs
 
+<!-- markdownlint-disable MD013 -->
 | Name | Description | Required | Default |
 | --- | --- | --- | --- |
 | features | Enable Cargo (Rust) features; space- or comma-separated. | no | |
@@ -134,11 +139,11 @@ Known limitations:
 | with-ratchet | Fail if coverage drops below baseline | no | `false` |
 | artefact-name-suffix | Additional suffix appended to the uploaded coverage artefact | no | |
 | baseline-rust-file | Rust baseline path | no | `.coverage-baseline.rust` |
-<!-- markdownlint-disable-next-line MD013 -->
 | baseline-python-file | Python baseline path | no | `.coverage-baseline.python` |
 | with-cucumber-rs | Run cucumber-rs scenarios under coverage | no | `false` |
 | cucumber-rs-features | Path to cucumber feature files | no | |
 | cucumber-rs-args | Extra arguments for cucumber | no | |
+<!-- markdownlint-enable MD013 -->
 
 \* `lcov` is only supported for Rust projects, while `coveragepy` is only
 supported for Python projects. Mixed projects must use `cobertura`.

.github/actions/generate-coverage/scripts/run_python.py

@@ -9,12 +9,16 @@
 
 import collections.abc as cabc  # noqa: TC003 - used at runtime
 import contextlib
+import os
+import shutil
 import typing as typ
+from functools import lru_cache
 from pathlib import Path
 
 import typer
 from cmd_utils_loader import run_cmd
 from coverage_parsers import get_line_coverage_percent_from_cobertura
+from plumbum import local
 from plumbum.cmd import uv
 from plumbum.commands.processes import ProcessExecutionError
 from shared_utils import read_previous_coverage
@@ -27,6 +31,9 @@
 FMT_OPT = typer.Option(..., envvar="DETECTED_FMT")
 GITHUB_OUTPUT_OPT = typer.Option(..., envvar="GITHUB_OUTPUT")
 BASELINE_OPT = typer.Option(None, envvar="BASELINE_PYTHON_FILE")
+COVERAGE_VENV = Path(".venv-coverage")
+TOOLING_PACKAGES: tuple[str, ...] = ("slipcover", "pytest", "coverage")
+PROJECT_SYNC_ARGS: tuple[str, ...] = ("sync", "--inexact", "--python")
 
 SLIPCOVER_ARGS: tuple[str, ...] = (
     "-m",
@@ -40,18 +47,95 @@
 )
 
 
-def _uv_python_cmd() -> BoundCommand:
-    """Return ``uv run`` configured with the required coverage tools."""
-    return uv[
-        "run",
-        "--with",
-        "slipcover",
-        "--with",
-        "pytest",
-        "--with",
-        "coverage",
-        "python",
-    ]
+def _find_coverage_python() -> Path | None:
+    """Return the coverage venv Python executable path when it exists."""
+    if COVERAGE_VENV.is_symlink() or not COVERAGE_VENV.is_dir():
+        return None
+    candidates = (
+        COVERAGE_VENV / "bin" / "python",
+        COVERAGE_VENV / "Scripts" / "python.exe",
+        COVERAGE_VENV / "Scripts" / "python",
+    )
+    return next((c for c in candidates if c.is_file()), None)
+
+
+def _remove_coverage_venv() -> None:
+    """Remove the coverage venv directory or non-directory placeholder.
+
+    Uses ``shutil.rmtree`` for directories and ``Path.unlink`` for any
+    other filesystem object (e.g. a symlink or a stale file).
+    """
+    if COVERAGE_VENV.is_dir() and not COVERAGE_VENV.is_symlink():
+        shutil.rmtree(COVERAGE_VENV)
+    else:
+        COVERAGE_VENV.unlink(missing_ok=True)
+
+
+def _recreate_coverage_venv() -> Path:
+    """Remove any existing broken venv, create a fresh one, and return its Python.
+
+    Returns
+    -------
+    Path
+        Absolute path to the Python executable inside the newly created venv.
+
+    Raises
+    ------
+    RuntimeError
+        If the Python executable cannot be located after creation.
+    """
+    if COVERAGE_VENV.exists() or COVERAGE_VENV.is_symlink():
+        typer.echo(
+            f"Coverage venv at {COVERAGE_VENV} is missing its Python "
+            "executable; recreating.",
+            err=True,
+        )
+        _remove_coverage_venv()
+    else:
+        typer.echo(f"Creating coverage venv at {COVERAGE_VENV}")
+    run_cmd(uv["venv", str(COVERAGE_VENV)])
+    python = _find_coverage_python()
+    if python is None:
+        msg = f"Coverage venv Python executable not found in {COVERAGE_VENV}"
+        raise RuntimeError(msg)
+    return python
+
+
+def _ensure_coverage_venv() -> str:
+    """Create or repair the coverage venv and install project/test tooling.
+
+    Returns the Python executable path inside the isolated coverage venv.
+    """
+    python = _find_coverage_python()
+    if python is None:
+        python = _recreate_coverage_venv()
+    typer.echo(f"Installing project dependencies into {COVERAGE_VENV}")
+    os.environ["UV_PROJECT_ENVIRONMENT"] = str(COVERAGE_VENV.resolve())
+    try:
+        run_cmd(uv[*PROJECT_SYNC_ARGS, str(python)])
+    except ProcessExecutionError as exc:
+        typer.echo(
+            f"uv sync failed with code {exc.retcode}: {exc.stderr}",
+            err=True,
+        )
+        raise
+    typer.echo(f"Installing coverage tooling {TOOLING_PACKAGES} into {COVERAGE_VENV}")
+    try:
+        run_cmd(uv["pip", "install", "--python", str(python), *TOOLING_PACKAGES])
+    except ProcessExecutionError as exc:
+        typer.echo(
+            f"uv pip install failed with code {exc.retcode}: {exc.stderr}",
+            err=True,
+        )
+        raise
+    return str(python)
+
+
+@lru_cache(maxsize=1)
+def _coverage_python_cmd() -> BoundCommand:
+    """Return the coverage venv Python command, creating it on first use."""
+    python = _ensure_coverage_venv()
+    return local[python]
 
 
 def _coverage_args(fmt: str, out: Path) -> list[str]:
@@ -65,17 +149,55 @@ def _coverage_args(fmt: str, out: Path) -> list[str]:
 
 
 def coverage_cmd_for_fmt(fmt: str, out: Path) -> BoundCommand:
-    """Return the slipcover command for the requested format."""
-    python_cmd = _uv_python_cmd()
+    """Return the slipcover command for the requested coverage format.
+
+    Parameters
+    ----------
+    fmt : str
+        Coverage format identifier. ``"cobertura"`` adds slipcover's
+        ``--xml`` and ``--out`` flags; all other values produce a bare
+        slipcover/pytest invocation.
+    out : Path
+        Destination path for the coverage output file; passed to slipcover's
+        ``--out`` argument when ``fmt == "cobertura"``.
+
+    Returns
+    -------
+    plumbum.commands.base.BoundCommand
+        A plumbum command that runs slipcover via the coverage venv Python.
+    """
+    python_cmd = _coverage_python_cmd()
     return python_cmd[_coverage_args(fmt, out)]
 
 
 @contextlib.contextmanager
 def tmp_coveragepy_xml(out: Path) -> cabc.Generator[Path]:
-    """Generate a cobertura XML from coverage.py and clean up afterwards."""
+    """Generate a Cobertura XML from coverage.py and clean it up afterwards.
+
+    Invokes ``python -m coverage xml -o <xml_tmp>`` using the coverage venv
+    Python, yields the temporary XML path for the caller to consume, and
+    removes the file on exit - whether the body raised or returned normally.
+
+    Parameters
+    ----------
+    out : Path
+        Path to the ``.dat`` (coverage.py data) file.  The temporary XML is
+        written to ``out.with_suffix(".xml")``.
+
+    Yields
+    ------
+    Path
+        Absolute path to the freshly generated temporary Cobertura XML file.
+
+    Raises
+    ------
+    typer.Exit
+        If ``coverage xml`` exits with a non-zero return code.
+    """
     xml_tmp = out.with_suffix(".xml")
+    python_cmd = _coverage_python_cmd()
     try:
-        cmd = _uv_python_cmd()["-m", "coverage", "xml", "-o", str(xml_tmp)]
+        cmd = python_cmd["-m", "coverage", "xml", "-o", str(xml_tmp)]
         run_cmd(cmd)
     except ProcessExecutionError as exc:
         typer.echo(
@@ -89,17 +211,54 @@ def tmp_coveragepy_xml(out: Path) -> cabc.Generator[Path]:
         xml_tmp.unlink(missing_ok=True)
 
 
+def _resolve_output_path(output_path: Path, lang: str) -> Path:
+    """Return the effective output path, accounting for mixed-language projects.
+
+    Parameters
+    ----------
+    output_path : Path
+        Base output path supplied by the caller.
+    lang : str
+        Detected project language.  When ``"mixed"``, a ``.python`` infix
+        is inserted between the stem and the suffix.
+
+    Returns
+    -------
+    Path
+        Adjusted output path.
+    """
+    if lang == "mixed":
+        return output_path.with_name(f"{output_path.stem}.python{output_path.suffix}")
+    return output_path
+
+
 def main(
     output_path: Path = OUTPUT_PATH_OPT,
     lang: str = LANG_OPT,
     fmt: str = FMT_OPT,
     github_output: Path = GITHUB_OUTPUT_OPT,
     baseline_file: Path | None = BASELINE_OPT,
 ) -> None:
-    """Run slipcover coverage and write the output path to ``GITHUB_OUTPUT``."""
-    out = output_path
-    if lang == "mixed":
-        out = output_path.with_name(f"{output_path.stem}.python{output_path.suffix}")
+    """Run slipcover coverage and write the result to ``GITHUB_OUTPUT``.
+
+    Parameters
+    ----------
+    output_path : Path
+        Destination path for the coverage output file.
+    lang : str
+        Detected project language (``"rust"``, ``"python"``, or
+        ``"mixed"``).  When ``"mixed"``, the output file is renamed to
+        include a ``.python`` infix.
+    fmt : str
+        Coverage format identifier passed to :func:`coverage_cmd_for_fmt`.
+    github_output : Path
+        Path to the ``GITHUB_OUTPUT`` append file where ``file=`` and
+        ``percent=`` are written.
+    baseline_file : Path or None
+        Optional path to a previous coverage baseline file.  When present,
+        the previous percentage is echoed to the log.
+    """
+    out = _resolve_output_path(output_path, lang)
     out.parent.mkdir(parents=True, exist_ok=True)
 
     cmd = coverage_cmd_for_fmt(fmt, out)