provide-testkit 0.0.0.dev0__py3-none-any.whl

provide/testkit/quality/__init__.py

@@ -0,0 +1,101 @@
+"""
+Code quality analysis utilities for the provide testkit.
+
+This module provides pytest fixtures and utilities for integrating code quality
+tools into testing workflows. All quality tools are optional and only activated
+when explicitly requested.
+
+Key Features:
+- Coverage tracking and reporting
+- Security scanning with Bandit
+- Complexity analysis with Radon
+- Performance profiling with py-spy
+- Documentation coverage with Interrogate
+
+Usage:
+    # Basic quality fixture
+    def test_with_coverage(quality_coverage):
+        result = quality_coverage.track_coverage()
+
+    # Quality decorator
+    @quality_check(coverage=90, security=True)
+    def test_with_gates():
+        pass
+
+    # CLI usage
+    provide-testkit quality analyze src/
+"""
+
+# Core exports
+from .base import BaseQualityFixture, QualityResult, QualityTool
+from .report import ReportGenerator
+from .runner import QualityRunner
+
+# Lazy imports for performance - only import when used
+__all__ = [
+    "BaseQualityFixture",
+    "QualityResult",
+    "QualityRunner",
+    "QualityTool",
+    "ReportGenerator",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import quality tools to avoid import overhead."""
+    if name == "CoverageFixture":
+        from .coverage import CoverageFixture
+
+        return CoverageFixture
+    elif name == "SecurityFixture":
+        from .security import SecurityFixture
+
+        return SecurityFixture
+    elif name == "ComplexityFixture":
+        from .complexity import ComplexityFixture
+
+        return ComplexityFixture
+    elif name == "ProfilingFixture":
+        from .profiling import ProfilingFixture
+
+        return ProfilingFixture
+    elif name == "DocumentationFixture":
+        from .documentation import DocumentationFixture
+
+        return DocumentationFixture
+
+    # Quality decorators
+    elif name in [
+        "quality_gate",
+        "coverage_gate",
+        "security_gate",
+        "complexity_gate",
+        "documentation_gate",
+        "performance_gate",
+        "quality_check",
+        "coverage_required",
+        "security_required",
+        "complexity_required",
+        "documentation_required",
+        "performance_required",
+        "quality_required",
+    ]:
+        from .decorators import (
+            complexity_gate,
+            complexity_required,
+            coverage_gate,
+            coverage_required,
+            documentation_gate,
+            documentation_required,
+            performance_gate,
+            performance_required,
+            quality_check,
+            quality_gate,
+            quality_required,
+            security_gate,
+            security_required,
+        )
+
+        return locals()[name]
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

provide/testkit/quality/artifacts.py

@@ -0,0 +1,360 @@
+"""Artifact management for quality analysis results."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+import time
+from typing import Any
+
+from provide.foundation.file import ensure_dir
+
+from .base import QualityResult
+
+
+class ArtifactManager:
+    """Manages artifacts generated during quality analysis.
+
+    Provides centralized artifact management with organization, cleanup,
+    and metadata tracking capabilities.
+    """
+
+    def __init__(self, base_dir: Path | str = ".quality-artifacts"):
+        """Initialize artifact manager.
+
+        Args:
+            base_dir: Base directory for all artifacts
+        """
+        self.base_dir = Path(base_dir)
+        self.session_id = str(int(time.time()))
+
+    def create_session_dir(self, tool: str) -> Path:
+        """Create a session-specific directory for a tool.
+
+        Args:
+            tool: Tool name
+
+        Returns:
+            Path to tool's session directory
+        """
+        session_dir = self.base_dir / self.session_id / tool
+        ensure_dir(session_dir)
+        return session_dir
+
+    def create_timestamped_dir(self, tool: str) -> Path:
+        """Create a timestamped directory for a tool.
+
+        Args:
+            tool: Tool name
+
+        Returns:
+            Path to tool's timestamped directory
+        """
+        timestamp = time.strftime("%Y%m%d_%H%M%S")
+        timestamped_dir = self.base_dir / tool / timestamp
+        ensure_dir(timestamped_dir)
+        return timestamped_dir
+
+    def get_latest_dir(self, tool: str) -> Path | None:
+        """Get the latest artifact directory for a tool.
+
+        Args:
+            tool: Tool name
+
+        Returns:
+            Path to latest directory or None if none exist
+        """
+        tool_dir = self.base_dir / tool
+        if not tool_dir.exists():
+            return None
+
+        # Find latest timestamped directory
+        subdirs = [d for d in tool_dir.iterdir() if d.is_dir()]
+        if not subdirs:
+            return None
+
+        return max(subdirs, key=lambda d: d.stat().st_mtime)
+
+    def organize_artifacts(self, result: QualityResult, target_dir: Path) -> None:
+        """Organize artifacts from a quality result.
+
+        Args:
+            result: Quality result with artifacts
+            target_dir: Target directory for organized artifacts
+        """
+        if not result.artifacts:
+            return
+
+        ensure_dir(target_dir)
+
+        # Copy artifacts to organized location
+        for artifact_path in result.artifacts:
+            if not artifact_path.exists():
+                continue
+
+            # Determine target filename
+            target_filename = f"{result.tool}_{artifact_path.name}"
+            target_path = target_dir / target_filename
+
+            # Copy artifact
+            if artifact_path.is_file():
+                shutil.copy2(artifact_path, target_path)
+            elif artifact_path.is_dir():
+                shutil.copytree(artifact_path, target_path, dirs_exist_ok=True)
+
+        # Create metadata file
+        metadata = {
+            "tool": result.tool,
+            "passed": result.passed,
+            "score": result.score,
+            "execution_time": result.execution_time,
+            "timestamp": time.time(),
+            "artifacts": [str(p) for p in result.artifacts],
+        }
+
+        metadata_path = target_dir / f"{result.tool}_metadata.json"
+        with open(metadata_path, "w") as f:
+            import json
+
+            json.dump(metadata, f, indent=2)
+
+    def cleanup_old_artifacts(self, tool: str | None = None, keep_count: int = 5) -> None:
+        """Clean up old artifact directories.
+
+        Args:
+            tool: Specific tool to clean up (None for all tools)
+            keep_count: Number of recent directories to keep
+        """
+        if tool:
+            tool_dirs = [self.base_dir / tool] if (self.base_dir / tool).exists() else []
+        else:
+            tool_dirs = [d for d in self.base_dir.iterdir() if d.is_dir()]
+
+        for tool_dir in tool_dirs:
+            if not tool_dir.is_dir():
+                continue
+
+            # Get all timestamped subdirectories
+            subdirs = [d for d in tool_dir.iterdir() if d.is_dir()]
+            if len(subdirs) <= keep_count:
+                continue
+
+            # Sort by modification time and remove oldest
+            subdirs.sort(key=lambda d: d.stat().st_mtime, reverse=True)
+            for old_dir in subdirs[keep_count:]:
+                shutil.rmtree(old_dir, ignore_errors=True)
+
+    def create_summary_report(self, results: dict[str, QualityResult]) -> Path:
+        """Create a summary report across all tools.
+
+        Args:
+            results: Results from multiple tools
+
+        Returns:
+            Path to summary report
+        """
+        summary_dir = self.base_dir / "summaries"
+        ensure_dir(summary_dir)
+
+        timestamp = time.strftime("%Y%m%d_%H%M%S")
+        summary_path = summary_dir / f"quality_summary_{timestamp}.json"
+
+        # Build summary data
+        summary = {
+            "timestamp": time.time(),
+            "session_id": self.session_id,
+            "overall_passed": all(result.passed for result in results.values()),
+            "tools": {},
+        }
+
+        for tool, result in results.items():
+            summary["tools"][tool] = {
+                "passed": result.passed,
+                "score": result.score,
+                "execution_time": result.execution_time,
+                "artifact_count": len(result.artifacts),
+                "key_metrics": self._extract_key_metrics(result),
+            }
+
+        # Write summary
+        with open(summary_path, "w") as f:
+            import json
+
+            json.dump(summary, f, indent=2)
+
+        return summary_path
+
+    def _extract_key_metrics(self, result: QualityResult) -> dict[str, Any]:
+        """Extract key metrics from a quality result.
+
+        Args:
+            result: Quality result
+
+        Returns:
+            Dictionary of key metrics
+        """
+        details = result.details
+        metrics = {}
+
+        if result.tool == "coverage":
+            metrics.update(
+                {
+                    "coverage_percentage": details.get("coverage_percentage"),
+                    "lines_covered": details.get("lines_covered"),
+                    "lines_missing": details.get("lines_missing"),
+                }
+            )
+        elif result.tool == "security":
+            metrics.update(
+                {
+                    "total_issues": details.get("total_issues"),
+                    "high_severity": details.get("severity_counts", {}).get("HIGH"),
+                    "medium_severity": details.get("severity_counts", {}).get("MEDIUM"),
+                    "low_severity": details.get("severity_counts", {}).get("LOW"),
+                }
+            )
+        elif result.tool == "complexity":
+            metrics.update(
+                {
+                    "average_complexity": details.get("average_complexity"),
+                    "max_complexity": details.get("max_complexity"),
+                    "overall_grade": details.get("overall_grade"),
+                    "total_functions": details.get("total_functions"),
+                }
+            )
+        elif result.tool == "documentation":
+            metrics.update(
+                {
+                    "total_coverage": details.get("total_coverage"),
+                    "covered_count": details.get("covered_count"),
+                    "missing_count": details.get("missing_count"),
+                    "grade": details.get("grade"),
+                }
+            )
+        elif result.tool == "profiling":
+            memory_data = details.get("memory", {})
+            cpu_data = details.get("cpu", {})
+            metrics.update(
+                {
+                    "peak_memory_mb": memory_data.get("peak_memory_mb"),
+                    "execution_time": cpu_data.get("execution_time"),
+                    "memory_score": details.get("scores", {}).get("memory_score"),
+                    "cpu_score": details.get("scores", {}).get("cpu_score"),
+                }
+            )
+
+        # Remove None values
+        return {k: v for k, v in metrics.items() if v is not None}
+
+    def export_artifacts(self, export_path: Path | str, compress: bool = True) -> Path:
+        """Export all artifacts to a specified location.
+
+        Args:
+            export_path: Path to export to
+            compress: Whether to create a compressed archive
+
+        Returns:
+            Path to exported artifacts
+        """
+        export_path = Path(export_path)
+
+        if compress:
+            # Create compressed archive
+            if not export_path.suffix:
+                archive_path = export_path.with_suffix(".tar.gz")
+            else:
+                archive_path = export_path
+
+            shutil.make_archive(str(archive_path.with_suffix("")), "gztar", self.base_dir)
+            return archive_path
+        else:
+            # Copy directory tree
+            if export_path.exists():
+                shutil.rmtree(export_path)
+
+            shutil.copytree(self.base_dir, export_path)
+            return export_path
+
+    def get_disk_usage(self) -> dict[str, int]:
+        """Get disk usage statistics for artifacts.
+
+        Returns:
+            Dictionary with disk usage information
+        """
+        if not self.base_dir.exists():
+            return {"total_bytes": 0, "tool_breakdown": {}}
+
+        total_size = 0
+        tool_breakdown = {}
+
+        for item in self.base_dir.rglob("*"):
+            if item.is_file():
+                size = item.stat().st_size
+                total_size += size
+
+                # Determine which tool this belongs to
+                relative_path = item.relative_to(self.base_dir)
+                tool = relative_path.parts[0] if relative_path.parts else "unknown"
+                tool_breakdown[tool] = tool_breakdown.get(tool, 0) + size
+
+        return {
+            "total_bytes": total_size,
+            "total_mb": total_size / (1024 * 1024),
+            "tool_breakdown": tool_breakdown,
+        }
+
+    def generate_index(self) -> Path:
+        """Generate an index of all artifacts.
+
+        Returns:
+            Path to generated index file
+        """
+        index_path = self.base_dir / "index.json"
+
+        index_data = {
+            "generated_at": time.time(),
+            "session_id": self.session_id,
+            "base_directory": str(self.base_dir),
+            "disk_usage": self.get_disk_usage(),
+            "tools": {},
+        }
+
+        # Scan for tool directories and artifacts
+        for tool_dir in self.base_dir.iterdir():
+            if not tool_dir.is_dir() or tool_dir.name in ["summaries", "exports"]:
+                continue
+
+            tool_info = {"latest_run": None, "total_runs": 0, "artifacts": []}
+
+            # Find all run directories
+            run_dirs = [d for d in tool_dir.iterdir() if d.is_dir()]
+            tool_info["total_runs"] = len(run_dirs)
+
+            if run_dirs:
+                latest_dir = max(run_dirs, key=lambda d: d.stat().st_mtime)
+                tool_info["latest_run"] = {
+                    "timestamp": latest_dir.stat().st_mtime,
+                    "path": str(latest_dir),
+                    "artifacts": [str(f) for f in latest_dir.iterdir() if f.is_file()],
+                }
+
+            # Collect all artifacts
+            for artifact in tool_dir.rglob("*"):
+                if artifact.is_file():
+                    tool_info["artifacts"].append(
+                        {
+                            "path": str(artifact),
+                            "size": artifact.stat().st_size,
+                            "modified": artifact.stat().st_mtime,
+                        }
+                    )
+
+            index_data["tools"][tool_dir.name] = tool_info
+
+        # Write index
+        with open(index_path, "w") as f:
+            import json
+
+            json.dump(index_data, f, indent=2)
+
+        return index_path

provide/testkit/quality/base.py

@@ -0,0 +1,158 @@
+"""Base classes and protocols for quality analysis tools."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class QualityResult:
+    """Result from a quality analysis tool.
+
+    Attributes:
+        tool: Name of the tool that generated this result
+        passed: Whether the quality check passed
+        score: Numeric score (0-100) if applicable
+        details: Tool-specific details and metrics
+        artifacts: List of artifact files created
+        execution_time: Time taken to run the analysis in seconds
+    """
+
+    tool: str
+    passed: bool
+    score: float | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+    artifacts: list[Path] = field(default_factory=list)
+    execution_time: float | None = None
+
+    @property
+    def summary(self) -> str:
+        """Human-readable summary of the result."""
+        status = "✅ PASSED" if self.passed else "❌ FAILED"
+        score_text = f" ({self.score}%)" if self.score is not None else ""
+        return f"{self.tool}: {status}{score_text}"
+
+
+@runtime_checkable
+class QualityTool(Protocol):
+    """Protocol for quality analysis tools."""
+
+    def analyze(self, path: Path, **kwargs: Any) -> QualityResult:
+        """Run analysis on the given path.
+
+        Args:
+            path: Path to analyze (file or directory)
+            **kwargs: Tool-specific options
+
+        Returns:
+            QualityResult containing analysis results
+        """
+        ...
+
+    def report(self, result: QualityResult, format: str = "terminal") -> str:
+        """Generate a report from analysis result.
+
+        Args:
+            result: Result to generate report for
+            format: Output format (terminal, json, html, markdown)
+
+        Returns:
+            Formatted report string
+        """
+        ...
+
+
+class BaseQualityFixture(ABC):
+    """Base class for pytest quality fixtures.
+
+    Provides common functionality for quality analysis fixtures including
+    configuration management, artifact handling, and result tracking.
+    """
+
+    def __init__(self, config: dict[str, Any] | None = None, artifact_dir: Path | None = None):
+        """Initialize the fixture.
+
+        Args:
+            config: Tool-specific configuration
+            artifact_dir: Directory to store artifacts
+        """
+        self.config = config or {}
+        self.artifact_dir = artifact_dir or Path(".quality")
+        self.results: list[QualityResult] = []
+        self._setup_complete = False
+
+    @abstractmethod
+    def setup(self) -> None:
+        """Setup the quality tool."""
+        pass
+
+    @abstractmethod
+    def teardown(self) -> None:
+        """Cleanup after quality check."""
+        pass
+
+    def add_result(self, result: QualityResult) -> None:
+        """Add a result to the tracked results."""
+        self.results.append(result)
+
+    def get_results(self) -> list[QualityResult]:
+        """Get all tracked results."""
+        return self.results.copy()
+
+    def get_results_by_tool(self) -> dict[str, QualityResult]:
+        """Get results indexed by tool name."""
+        return {result.tool: result for result in self.results}
+
+    def ensure_setup(self) -> None:
+        """Ensure setup has been called."""
+        if not self._setup_complete:
+            self.setup()
+            self._setup_complete = True
+
+    def create_artifact_dir(self, subdir: str | None = None) -> Path:
+        """Create and return artifact directory.
+
+        Args:
+            subdir: Optional subdirectory name
+
+        Returns:
+            Path to the artifact directory
+        """
+        if subdir:
+            artifact_path = self.artifact_dir / subdir
+        else:
+            artifact_path = self.artifact_dir
+
+        artifact_path.mkdir(parents=True, exist_ok=True)
+        return artifact_path
+
+
+class QualityError(Exception):
+    """Base exception for quality analysis errors."""
+
+    def __init__(self, message: str, tool: str | None = None, details: dict[str, Any] | None = None):
+        """Initialize quality error.
+
+        Args:
+            message: Error message
+            tool: Name of tool that caused the error
+            details: Additional error details
+        """
+        super().__init__(message)
+        self.tool = tool
+        self.details = details or {}
+
+
+class QualityConfigError(QualityError):
+    """Exception for configuration errors."""
+
+    pass
+
+
+class QualityToolError(QualityError):
+    """Exception for tool execution errors."""
+
+    pass