mcp-vector-search 0.12.6__py3-none-any.whl → 1.0.3__py3-none-any.whl

mcp_vector_search/analysis/metrics.py

@@ -0,0 +1,341 @@
+"""Metric dataclasses for structural code analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..config.thresholds import ThresholdConfig
+
+
+@dataclass
+class ChunkMetrics:
+    """Metrics for a single code chunk (function/class/method).
+
+    Tracks complexity metrics, code smells, and computes quality grades
+    for individual code chunks.
+
+    Attributes:
+        cognitive_complexity: Cognitive complexity score (how hard to understand)
+        cyclomatic_complexity: Cyclomatic complexity (number of decision paths)
+        max_nesting_depth: Maximum nesting level (if/for/while/try depth)
+        parameter_count: Number of function parameters
+        lines_of_code: Total lines in the chunk
+        smells: List of detected code smells (e.g., "too_many_parameters")
+        complexity_grade: Computed A-F grade based on cognitive complexity
+    """
+
+    cognitive_complexity: int = 0
+    cyclomatic_complexity: int = 0
+    max_nesting_depth: int = 0
+    parameter_count: int = 0
+    lines_of_code: int = 0
+
+    # Code smells detected
+    smells: list[str] = field(default_factory=list)
+
+    # Computed grades (A-F scale)
+    complexity_grade: str = field(init=False, default="A")
+
+    def __post_init__(self) -> None:
+        """Initialize computed fields after dataclass initialization."""
+        self.complexity_grade = self._compute_grade()
+
+    def _compute_grade(self, thresholds: ThresholdConfig | None = None) -> str:
+        """Compute A-F grade based on cognitive complexity.
+
+        Args:
+            thresholds: Optional custom threshold configuration.
+                       If None, uses default thresholds.
+
+        Grade thresholds (defaults):
+        - A: 0-5 (excellent)
+        - B: 6-10 (good)
+        - C: 11-20 (acceptable)
+        - D: 21-30 (needs improvement)
+        - F: 31+ (refactor recommended)
+
+        Returns:
+            Letter grade from A to F
+        """
+        if thresholds is None:
+            # Use default thresholds
+            if self.cognitive_complexity <= 5:
+                return "A"
+            elif self.cognitive_complexity <= 10:
+                return "B"
+            elif self.cognitive_complexity <= 20:
+                return "C"
+            elif self.cognitive_complexity <= 30:
+                return "D"
+            else:
+                return "F"
+        else:
+            # Use custom thresholds
+            return thresholds.get_grade(self.cognitive_complexity)
+
+    def to_metadata(self) -> dict[str, Any]:
+        """Flatten metrics for ChromaDB metadata storage.
+
+        ChromaDB supports: str, int, float, bool.
+        Lists are converted to JSON strings for compatibility.
+
+        Returns:
+            Dictionary of flattened metrics compatible with ChromaDB
+        """
+        import json
+
+        return {
+            "cognitive_complexity": self.cognitive_complexity,
+            "cyclomatic_complexity": self.cyclomatic_complexity,
+            "max_nesting_depth": self.max_nesting_depth,
+            "parameter_count": self.parameter_count,
+            "lines_of_code": self.lines_of_code,
+            "complexity_grade": self.complexity_grade,
+            "code_smells": json.dumps(self.smells),  # Convert list to JSON string
+            "smell_count": len(self.smells),
+        }
+
+
+@dataclass
+class FileMetrics:
+    """Aggregated metrics for an entire file.
+
+    Tracks file-level statistics and aggregates chunk metrics for all
+    functions/classes within the file.
+
+    Attributes:
+        file_path: Relative or absolute path to the file
+        total_lines: Total lines in file (including blank/comments)
+        code_lines: Lines containing code
+        comment_lines: Lines containing comments
+        blank_lines: Blank lines
+        function_count: Number of top-level functions
+        class_count: Number of classes
+        method_count: Number of methods (functions inside classes)
+        total_complexity: Sum of cognitive complexity across all chunks
+        avg_complexity: Average cognitive complexity per chunk
+        max_complexity: Maximum cognitive complexity in any chunk
+        chunks: List of chunk metrics for each function/class
+    """
+
+    file_path: str
+    total_lines: int = 0
+    code_lines: int = 0
+    comment_lines: int = 0
+    blank_lines: int = 0
+
+    function_count: int = 0
+    class_count: int = 0
+    method_count: int = 0
+
+    # Aggregated complexity
+    total_complexity: int = 0
+    avg_complexity: float = 0.0
+    max_complexity: int = 0
+
+    # Chunk metrics for each function/class
+    chunks: list[ChunkMetrics] = field(default_factory=list)
+
+    def compute_aggregates(self) -> None:
+        """Compute aggregate metrics from chunk metrics.
+
+        Calculates total_complexity, avg_complexity, and max_complexity
+        by aggregating values from all chunks.
+        """
+        if not self.chunks:
+            self.total_complexity = 0
+            self.avg_complexity = 0.0
+            self.max_complexity = 0
+            return
+
+        # Compute complexity aggregates
+        complexities = [chunk.cognitive_complexity for chunk in self.chunks]
+        self.total_complexity = sum(complexities)
+        self.avg_complexity = self.total_complexity / len(self.chunks)
+        self.max_complexity = max(complexities)
+
+    @property
+    def health_score(self) -> float:
+        """Calculate 0.0-1.0 health score based on metrics.
+
+        Health score considers:
+        - Average complexity (lower is better)
+        - Code smells count (fewer is better)
+        - Comment ratio (balanced is better)
+
+        Returns:
+            Health score from 0.0 (poor) to 1.0 (excellent)
+        """
+        score = 1.0
+
+        # Penalty for high average complexity (A=0%, B=-10%, C=-20%, D=-30%, F=-50%)
+        if self.avg_complexity > 30:
+            score -= 0.5
+        elif self.avg_complexity > 20:
+            score -= 0.3
+        elif self.avg_complexity > 10:
+            score -= 0.2
+        elif self.avg_complexity > 5:
+            score -= 0.1
+
+        # Penalty for code smells (up to -30%)
+        total_smells = sum(len(chunk.smells) for chunk in self.chunks)
+        smell_penalty = min(0.3, total_smells * 0.05)  # 5% per smell, max 30%
+        score -= smell_penalty
+
+        # Penalty for poor comment ratio (ideal: 10-30%)
+        if self.total_lines > 0:
+            comment_ratio = self.comment_lines / self.total_lines
+            if comment_ratio < 0.1:  # Too few comments
+                score -= 0.1
+            elif comment_ratio > 0.5:  # Too many comments (suspicious)
+                score -= 0.1
+
+        return max(0.0, score)  # Clamp to 0.0 minimum
+
+
+@dataclass
+class ProjectMetrics:
+    """Project-wide metric aggregates.
+
+    Tracks project-level statistics and identifies complexity hotspots
+    across the entire codebase.
+
+    Attributes:
+        project_root: Root directory of the project
+        analyzed_at: Timestamp when analysis was performed
+        total_files: Total number of analyzed files
+        total_lines: Total lines across all files
+        total_functions: Total number of functions
+        total_classes: Total number of classes
+        files: Dictionary mapping file paths to FileMetrics
+        avg_file_complexity: Average complexity across all files
+        hotspots: List of file paths with highest complexity (top 10)
+    """
+
+    project_root: str
+    analyzed_at: datetime = field(default_factory=datetime.now)
+
+    total_files: int = 0
+    total_lines: int = 0
+    total_functions: int = 0
+    total_classes: int = 0
+
+    # File metrics indexed by path
+    files: dict[str, FileMetrics] = field(default_factory=dict)
+
+    # Project-wide aggregates
+    avg_file_complexity: float = 0.0
+    hotspots: list[str] = field(default_factory=list)  # Top 10 complex files
+
+    def compute_aggregates(self) -> None:
+        """Compute project-wide aggregates from file metrics.
+
+        Calculates:
+        - Total files, lines, functions, classes
+        - Average file complexity
+        - Identifies complexity hotspots
+        """
+        if not self.files:
+            self.total_files = 0
+            self.total_lines = 0
+            self.total_functions = 0
+            self.total_classes = 0
+            self.avg_file_complexity = 0.0
+            self.hotspots = []
+            return
+
+        # Compute totals
+        self.total_files = len(self.files)
+        self.total_lines = sum(f.total_lines for f in self.files.values())
+        self.total_functions = sum(f.function_count for f in self.files.values())
+        self.total_classes = sum(f.class_count for f in self.files.values())
+
+        # Compute average file complexity
+        file_complexities = [f.avg_complexity for f in self.files.values() if f.chunks]
+        if file_complexities:
+            self.avg_file_complexity = sum(file_complexities) / len(file_complexities)
+        else:
+            self.avg_file_complexity = 0.0
+
+        # Identify hotspots (top 10 most complex files)
+        hotspot_files = self.get_hotspots(limit=10)
+        self.hotspots = [f.file_path for f in hotspot_files]
+
+    def get_hotspots(self, limit: int = 10) -> list[FileMetrics]:
+        """Return top N most complex files.
+
+        Complexity is determined by average cognitive complexity per chunk.
+        Files with no chunks are excluded.
+
+        Args:
+            limit: Maximum number of hotspots to return
+
+        Returns:
+            List of FileMetrics sorted by complexity (highest first)
+        """
+        # Filter files with chunks and sort by avg complexity
+        files_with_complexity = [f for f in self.files.values() if f.chunks]
+        sorted_files = sorted(
+            files_with_complexity, key=lambda f: f.avg_complexity, reverse=True
+        )
+        return sorted_files[:limit]
+
+    def to_summary(self) -> dict[str, Any]:
+        """Generate summary dict for reporting.
+
+        Returns:
+            Dictionary containing project summary with key metrics
+        """
+        return {
+            "project_root": self.project_root,
+            "analyzed_at": self.analyzed_at.isoformat(),
+            "total_files": self.total_files,
+            "total_lines": self.total_lines,
+            "total_functions": self.total_functions,
+            "total_classes": self.total_classes,
+            "avg_file_complexity": round(self.avg_file_complexity, 2),
+            "hotspots": self.hotspots,
+            "complexity_distribution": self._compute_grade_distribution(),
+            "health_metrics": {
+                "avg_health_score": self._compute_avg_health_score(),
+                "files_needing_attention": self._count_files_needing_attention(),
+            },
+        }
+
+    def _compute_grade_distribution(self) -> dict[str, int]:
+        """Compute distribution of complexity grades across all chunks.
+
+        Returns:
+            Dictionary mapping grade (A-F) to count of chunks
+        """
+        distribution: dict[str, int] = {"A": 0, "B": 0, "C": 0, "D": 0, "F": 0}
+
+        for file_metrics in self.files.values():
+            for chunk in file_metrics.chunks:
+                distribution[chunk.complexity_grade] += 1
+
+        return distribution
+
+    def _compute_avg_health_score(self) -> float:
+        """Compute average health score across all files.
+
+        Returns:
+            Average health score from 0.0 to 1.0
+        """
+        if not self.files:
+            return 1.0
+
+        health_scores = [f.health_score for f in self.files.values()]
+        return sum(health_scores) / len(health_scores)
+
+    def _count_files_needing_attention(self) -> int:
+        """Count files with health score below 0.7.
+
+        Returns:
+            Number of files that need attention
+        """
+        return sum(1 for f in self.files.values() if f.health_score < 0.7)

mcp_vector_search/analysis/reporters/__init__.py

@@ -0,0 +1,5 @@
+"""Analysis reporters for outputting metrics in various formats."""
+
+from .console import ConsoleReporter
+
+__all__ = ["ConsoleReporter"]

mcp_vector_search/analysis/reporters/console.py

@@ -0,0 +1,222 @@
+"""Console reporter for code analysis results."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.table import Table
+
+if TYPE_CHECKING:
+    from ..metrics import ProjectMetrics
+
+console = Console()
+
+
+class ConsoleReporter:
+    """Console reporter for displaying analysis results in terminal."""
+
+    def print_summary(self, metrics: ProjectMetrics) -> None:
+        """Print high-level project summary.
+
+        Args:
+            metrics: Project metrics to display
+        """
+        console.print("\n[bold blue]📈 Code Complexity Analysis[/bold blue]")
+        console.print("━" * 60)
+        console.print()
+
+        console.print("[bold]Project Summary[/bold]")
+        console.print(f"  Files Analyzed: {metrics.total_files}")
+        console.print(f"  Total Lines: {metrics.total_lines:,}")
+        console.print(f"  Functions: {metrics.total_functions}")
+        console.print(f"  Classes: {metrics.total_classes}")
+        console.print(f"  Avg File Complexity: {metrics.avg_file_complexity:.1f}")
+        console.print()
+
+    def print_distribution(self, metrics: ProjectMetrics) -> None:
+        """Print complexity grade distribution.
+
+        Args:
+            metrics: Project metrics with grade distribution
+        """
+        console.print("[bold]Complexity Distribution[/bold]")
+
+        # Get grade distribution
+        distribution = metrics._compute_grade_distribution()
+        total_chunks = sum(distribution.values())
+
+        if total_chunks == 0:
+            console.print("  No functions/methods analyzed")
+            console.print()
+            return
+
+        # Define grade colors and descriptions
+        grade_info = {
+            "A": ("green", "Excellent (0-5)"),
+            "B": ("blue", "Good (6-10)"),
+            "C": ("yellow", "Acceptable (11-20)"),
+            "D": ("orange1", "Needs Improvement (21-30)"),
+            "F": ("red", "Refactor Required (31+)"),
+        }
+
+        # Print distribution table
+        table = Table(show_header=True, header_style="bold cyan", box=None)
+        table.add_column("Grade", style="bold", width=8)
+        table.add_column("Description", width=25)
+        table.add_column("Count", justify="right", width=8)
+        table.add_column("Percentage", justify="right", width=10)
+        table.add_column("Bar", width=20)
+
+        for grade in ["A", "B", "C", "D", "F"]:
+            count = distribution.get(grade, 0)
+            percentage = (count / total_chunks * 100) if total_chunks > 0 else 0
+            color, description = grade_info[grade]
+
+            # Create visual bar
+            bar_length = int(percentage / 5)  # Scale: 5% = 1 char
+            bar = "█" * bar_length
+
+            table.add_row(
+                f"[{color}]{grade}[/{color}]",
+                description,
+                f"{count}",
+                f"{percentage:.1f}%",
+                f"[{color}]{bar}[/{color}]",
+            )
+
+        console.print(table)
+        console.print()
+
+    def print_hotspots(self, metrics: ProjectMetrics, top: int = 10) -> None:
+        """Print complexity hotspots.
+
+        Args:
+            metrics: Project metrics
+            top: Number of top hotspots to display
+        """
+        hotspot_files = metrics.get_hotspots(limit=top)
+
+        if not hotspot_files:
+            console.print("[bold]🔥 Complexity Hotspots[/bold]")
+            console.print("  No hotspots found")
+            console.print()
+            return
+
+        console.print(
+            f"[bold]🔥 Top {min(top, len(hotspot_files))} Complexity Hotspots[/bold]"
+        )
+
+        table = Table(show_header=True, header_style="bold cyan", box=None)
+        table.add_column("Rank", justify="right", width=6)
+        table.add_column("File", style="cyan", width=50)
+        table.add_column("Avg Complexity", justify="right", width=16)
+        table.add_column("Grade", justify="center", width=8)
+        table.add_column("Functions", justify="right", width=10)
+
+        for rank, file_metrics in enumerate(hotspot_files, 1):
+            # Compute average grade
+            if file_metrics.chunks:
+                grades = [chunk.complexity_grade for chunk in file_metrics.chunks]
+                avg_grade = max(set(grades), key=grades.count)  # Most common grade
+            else:
+                avg_grade = "N/A"
+
+            # Color code grade
+            grade_colors = {
+                "A": "green",
+                "B": "blue",
+                "C": "yellow",
+                "D": "orange1",
+                "F": "red",
+            }
+            grade_color = grade_colors.get(avg_grade, "white")
+
+            # Truncate file path if too long
+            file_path = file_metrics.file_path
+            if len(file_path) > 48:
+                file_path = "..." + file_path[-45:]
+
+            table.add_row(
+                f"{rank}",
+                file_path,
+                f"{file_metrics.avg_complexity:.1f}",
+                f"[{grade_color}]{avg_grade}[/{grade_color}]",
+                f"{len(file_metrics.chunks)}",
+            )
+
+        console.print(table)
+        console.print()
+
+    def print_recommendations(self, metrics: ProjectMetrics) -> None:
+        """Print actionable recommendations.
+
+        Args:
+            metrics: Project metrics
+        """
+        console.print("[bold]💡 Recommendations[/bold]")
+
+        recommendations: list[str] = []
+
+        # Check for files needing attention
+        files_needing_attention = metrics._count_files_needing_attention()
+        if files_needing_attention > 0:
+            recommendations.append(
+                f"[yellow]•[/yellow] {files_needing_attention} files have health score below 0.7 - consider refactoring"
+            )
+
+        # Check for high complexity files
+        hotspots = metrics.get_hotspots(limit=5)
+        high_complexity_files = [f for f in hotspots if f.avg_complexity > 20]
+        if high_complexity_files:
+            recommendations.append(
+                f"[yellow]•[/yellow] {len(high_complexity_files)} files have average complexity > 20 - prioritize these for refactoring"
+            )
+
+        # Check grade distribution
+        distribution = metrics._compute_grade_distribution()
+        total_chunks = sum(distribution.values())
+        if total_chunks > 0:
+            d_f_percentage = (
+                (distribution.get("D", 0) + distribution.get("F", 0))
+                / total_chunks
+                * 100
+            )
+            if d_f_percentage > 20:
+                recommendations.append(
+                    f"[yellow]•[/yellow] {d_f_percentage:.1f}% of functions have D/F grades - aim to reduce this below 10%"
+                )
+
+        # Check overall health
+        avg_health = metrics._compute_avg_health_score()
+        if avg_health < 0.7:
+            recommendations.append(
+                f"[yellow]•[/yellow] Average health score is {avg_health:.2f} - target 0.8+ through refactoring"
+            )
+        elif avg_health >= 0.9:
+            recommendations.append(
+                "[green]✓[/green] Excellent code health! Keep up the good work."
+            )
+
+        if not recommendations:
+            recommendations.append(
+                "[green]✓[/green] Code quality looks good! No critical issues found."
+            )
+
+        for rec in recommendations:
+            console.print(f"  {rec}")
+
+        console.print()
+
+        # Print tips
+        console.print("[dim]💡 Tips:[/dim]")
+        console.print(
+            "[dim]  • Use [cyan]--top N[/cyan] to see more/fewer hotspots[/dim]"
+        )
+        console.print(
+            "[dim]  • Use [cyan]--json[/cyan] to export results for further analysis[/dim]"
+        )
+        console.print(
+            "[dim]  • Focus refactoring efforts on Grade D and F functions first[/dim]"
+        )
+        console.print()