pycmdcheck 0.1.0__py3-none-any.whl

pycmdcheck/runner.py

@@ -0,0 +1,236 @@
+"""Check runner that orchestrates check execution."""
+
+import logging
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.config import get_check_config, is_check_enabled, load_config
+from pycmdcheck.constants import MAX_WORKERS
+from pycmdcheck.discovery import discover_checks
+from pycmdcheck.results import CheckResult, CheckStatus, Report
+
+logger = logging.getLogger(__name__)
+
+
+def run_checks(
+    package_path: str | Path,
+    checks: list[str] | None = None,
+    skip: list[str] | None = None,
+    config: dict[str, Any] | None = None,
+    parallel: bool = True,
+    fail_fast: bool = False,
+) -> Report:
+    """Run checks on a package.
+
+    This is the core function that orchestrates check discovery and execution.
+    It loads configuration, discovers available checks via entry points,
+    and runs them either in parallel or sequentially.
+
+    Args:
+        package_path: Path to the package directory to check. Can be a string
+            or Path object. Will be resolved to an absolute path.
+        checks: List of specific check names to run. If None, runs all checks
+            that are enabled in the configuration. Available built-in checks:
+            build, dependencies, docs, formatting, imports, license, linting,
+            metadata, py_typed, structure, tests, typing, version.
+        skip: List of check names to skip, even if they would otherwise run.
+        config: Pre-loaded configuration dictionary. If None, configuration
+            is loaded from the package's pyproject.toml file.
+        parallel: Whether to run checks in parallel using threads. Defaults
+            to True. Set to False for deterministic ordering or debugging.
+        fail_fast: Whether to stop after the first ERROR result. Defaults
+            to False.
+
+    Returns:
+        A Report object containing all check results. The report includes
+        the package path and a list of CheckResult objects.
+
+    Examples:
+        Run all enabled checks:
+
+        >>> report = run_checks("/path/to/package")
+        >>> report.passed
+        True
+
+        Run specific checks only:
+
+        >>> report = run_checks(".", checks=["metadata", "tests"])
+        >>> len(report.results)
+        2
+
+        Run sequentially for debugging:
+
+        >>> report = run_checks(".", parallel=False)
+    """
+    package_path = Path(package_path).resolve()
+    skip = skip or []
+
+    # Load configuration
+    if config is None:
+        config = load_config(package_path)
+
+    # Discover available checks
+    available_checks = discover_checks()
+
+    # Determine which checks to run
+    checks_to_run: list[str] = []
+    if checks:
+        # Run only specified checks
+        for name in checks:
+            if name in available_checks:
+                checks_to_run.append(name)
+    else:
+        # Run all enabled checks
+        for name in available_checks:
+            if is_check_enabled(config, name):
+                checks_to_run.append(name)
+
+    # Remove skipped checks
+    checks_to_run = [c for c in checks_to_run if c not in skip]
+
+    # Create report
+    report = Report(package_path=str(package_path))
+
+    if not checks_to_run:
+        return report
+
+    # Run checks
+    if parallel and len(checks_to_run) > 1:
+        results = _run_parallel(
+            package_path, checks_to_run, available_checks, config, fail_fast=fail_fast
+        )
+    else:
+        results = _run_sequential(
+            package_path,
+            checks_to_run,
+            available_checks,
+            config,
+            fail_fast=fail_fast,
+        )
+
+    for result in results:
+        report.add(result)
+
+    return report
+
+
+def _run_sequential(
+    package_path: Path,
+    check_names: list[str],
+    available_checks: dict[str, type],
+    config: dict[str, Any],
+    fail_fast: bool = False,
+) -> list[CheckResult]:
+    """Run checks sequentially."""
+    results: list[CheckResult] = []
+
+    for name in check_names:
+        result = _run_single_check(package_path, name, available_checks, config)
+        results.append(result)
+        if fail_fast and result.status == CheckStatus.ERROR:
+            break
+
+    return results
+
+
+def _run_parallel(
+    package_path: Path,
+    check_names: list[str],
+    available_checks: dict[str, type],
+    config: dict[str, Any],
+    fail_fast: bool = False,
+) -> list[CheckResult]:
+    """Run checks in parallel using threads."""
+    results: list[CheckResult] = []
+
+    with ThreadPoolExecutor(max_workers=min(len(check_names), MAX_WORKERS)) as executor:
+        futures = {
+            executor.submit(
+                _run_single_check, package_path, name, available_checks, config
+            ): name
+            for name in check_names
+        }
+
+        for future in as_completed(futures):
+            try:
+                result = future.result()
+                results.append(result)
+                if fail_fast and result.status == CheckStatus.ERROR:
+                    for f in futures:
+                        f.cancel()
+                    break
+            except Exception as e:
+                name = futures[future]
+                logger.exception("Check %s raised exception in thread", name)
+                results.append(
+                    CheckResult(
+                        name=name,
+                        status=CheckStatus.ERROR,
+                        message=f"Check failed with exception: {e}",
+                    )
+                )
+                if fail_fast:
+                    for f in futures:
+                        f.cancel()
+                    break
+
+    # Sort by original order
+    name_order = {name: i for i, name in enumerate(check_names)}
+    results.sort(key=lambda r: name_order.get(r.name, 999))
+
+    return results
+
+
+def _run_single_check(
+    package_path: Path,
+    name: str,
+    available_checks: dict[str, type],
+    config: dict[str, Any],
+) -> CheckResult:
+    """Run a single check."""
+    check_class = available_checks.get(name)
+    if not check_class:
+        return CheckResult(
+            name=name,
+            status=CheckStatus.ERROR,
+            message=f"Check '{name}' not found",
+        )
+
+    check_config = get_check_config(config, name)
+
+    logger.debug("Starting check: %s", name)
+    start_time = time.time()
+    try:
+        check_instance = check_class()
+        result: CheckResult = check_instance.run(package_path, check_config)
+        if result.name != name:
+            logger.warning(
+                "Check '%s' returned result with name='%s'; correcting",
+                name,
+                result.name,
+            )
+            result = CheckResult(
+                name=name,
+                status=result.status,
+                message=result.message,
+                details=result.details,
+                duration=result.duration,
+            )
+        result.duration = time.time() - start_time
+        logger.debug(
+            "Check %s completed in %.2fs: %s",
+            name,
+            result.duration,
+            result.status.value,
+        )
+        return result
+    except Exception as e:
+        logger.exception("Check %s raised exception", name)
+        return CheckResult(
+            name=name,
+            status=CheckStatus.ERROR,
+            message=f"Check raised exception: {e}",
+            duration=time.time() - start_time,
+        )

pycmdcheck/subprocess_runner.py

@@ -0,0 +1,166 @@
+"""Shared subprocess runner utility for pycmdcheck.
+
+This module provides a unified interface for running external tools
+(pytest, ruff, mypy, pyright, etc.) as subprocesses.  It replaces
+duplicated subprocess-handling code across the check modules with a
+single, well-tested implementation.
+
+Typical usage::
+
+    from pycmdcheck.subprocess_runner import run_tool, tool_available
+
+    if not tool_available("ruff"):
+        ...  # handle missing tool
+
+    result = run_tool(["ruff", "check", "."], cwd=package_path)
+    if result.success:
+        ...
+    else:
+        for line in result.output_lines():
+            ...
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from pycmdcheck.constants import LONG_TIMEOUT
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class SubprocessResult:
+    """Immutable result of a subprocess execution.
+
+    Attributes:
+        returncode: Exit code of the process.  Defaults to ``-1`` when
+            the process was never started.
+        stdout: Captured standard output.
+        stderr: Captured standard error.
+        timed_out: Whether the process exceeded the timeout.
+        error: Human-readable error message when the process could not
+            be started or an unexpected exception occurred.
+    """
+
+    returncode: int = -1
+    stdout: str = ""
+    stderr: str = ""
+    timed_out: bool = False
+    error: str | None = None
+
+    @property
+    def success(self) -> bool:
+        """Return ``True`` when the process exited cleanly with code 0.
+
+        A result is *not* considered successful if the process timed out
+        or an error prevented it from running, even if the return code
+        happens to be 0.
+        """
+        return self.returncode == 0 and not self.timed_out and self.error is None
+
+    @property
+    def output(self) -> str:
+        """Return combined stdout and stderr."""
+        return self.stdout + self.stderr
+
+    def output_lines(self, *, strip_blank: bool = True) -> list[str]:
+        """Split *stdout* into individual lines.
+
+        Parameters:
+            strip_blank: When ``True`` (the default), blank/empty lines
+                are removed from the result.
+
+        Returns:
+            A list of stdout lines.  A trailing newline does not produce
+            a trailing empty string.
+        """
+        if not self.stdout:
+            return []
+
+        # splitlines() already handles the trailing-newline case nicely:
+        # "a\nb\n".splitlines() == ["a", "b"]
+        lines = self.stdout.splitlines()
+
+        if strip_blank:
+            lines = [line for line in lines if line]
+
+        return lines
+
+
+def tool_available(tool_name: str) -> bool:
+    """Check whether an external tool is available on ``$PATH``.
+
+    This is a thin wrapper around :func:`shutil.which`.
+
+    Parameters:
+        tool_name: The command name to look up (e.g. ``"ruff"``).
+
+    Returns:
+        ``True`` if the tool was found, ``False`` otherwise.
+    """
+    return shutil.which(tool_name) is not None
+
+
+def run_tool(
+    cmd: list[str],
+    *,
+    cwd: Path | str | None = None,
+    timeout: int = LONG_TIMEOUT,
+) -> SubprocessResult:
+    """Run an external tool as a subprocess and return a structured result.
+
+    Parameters:
+        cmd: The command and its arguments as a list of strings.
+        cwd: Working directory for the subprocess.
+        timeout: Maximum number of seconds to wait.  Defaults to 300 (5
+            minutes).
+
+    Returns:
+        A :class:`SubprocessResult` with captured stdout, stderr, and
+        metadata about the execution.
+    """
+    try:
+        logger.debug("Running: %s (cwd=%s, timeout=%ds)", cmd, cwd, timeout)
+        proc = subprocess.run(
+            cmd,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        logger.debug("Process exited with code %d", proc.returncode)
+        return SubprocessResult(
+            returncode=proc.returncode,
+            stdout=proc.stdout,
+            stderr=proc.stderr,
+        )
+    except subprocess.TimeoutExpired:
+        logger.warning("Process timed out after %ds: %s", timeout, cmd)
+        return SubprocessResult(timed_out=True)
+    except Exception as exc:
+        logger.error("Failed to run %s: %s", cmd, exc)
+        return SubprocessResult(error=str(exc))
+
+
+def sanitize_args(args: list[str]) -> list[str]:
+    """Validate and return subprocess args from check configuration.
+
+    Ensures all arguments are strings.  Both flags (``--select``) and
+    their values (``"E,F,W"``) are allowed, since ``subprocess.run``
+    is always called with ``shell=False`` which prevents injection.
+
+    Raises:
+        TypeError: If any element is not a string.
+    """
+    for arg in args:
+        if not isinstance(arg, str):
+            raise TypeError(
+                f"Non-string argument in check config args: {arg!r}. "
+                f"All arguments must be strings."
+            )
+    return list(args)