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

mcp_vector_search/analysis/metrics.py

@@ -33,6 +33,12 @@ class ChunkMetrics:
     parameter_count: int = 0
     lines_of_code: int = 0
 
+    # Halstead metrics (Phase 4)
+    halstead_volume: float | None = None
+    halstead_difficulty: float | None = None
+    halstead_effort: float | None = None
+    halstead_bugs: float | None = None
+
     # Code smells detected
     smells: list[str] = field(default_factory=list)
 
@@ -87,7 +93,7 @@ class ChunkMetrics:
         """
         import json
 
-        return {
+        metadata = {
             "cognitive_complexity": self.cognitive_complexity,
             "cyclomatic_complexity": self.cyclomatic_complexity,
             "max_nesting_depth": self.max_nesting_depth,
@@ -98,6 +104,61 @@ class ChunkMetrics:
             "smell_count": len(self.smells),
         }
 
+        # Add Halstead metrics if available
+        if self.halstead_volume is not None:
+            metadata["halstead_volume"] = self.halstead_volume
+        if self.halstead_difficulty is not None:
+            metadata["halstead_difficulty"] = self.halstead_difficulty
+        if self.halstead_effort is not None:
+            metadata["halstead_effort"] = self.halstead_effort
+        if self.halstead_bugs is not None:
+            metadata["halstead_bugs"] = self.halstead_bugs
+
+        return metadata
+
+
+@dataclass
+class CouplingMetrics:
+    """Coupling metrics for a file.
+
+    Tracks dependencies between files to measure coupling.
+
+    Attributes:
+        efferent_coupling: Number of files this file depends on (outgoing dependencies)
+        afferent_coupling: Number of files that depend on this file (incoming dependencies)
+        imports: List of all imported modules
+        internal_imports: Imports from same project
+        external_imports: Third-party and standard library imports
+        dependents: List of files that import this file
+        instability: Ratio Ce / (Ce + Ca), measures resistance to change (0-1)
+    """
+
+    efferent_coupling: int = 0  # Ce - outgoing dependencies
+    afferent_coupling: int = 0  # Ca - incoming dependencies
+    imports: list[str] = field(default_factory=list)
+    internal_imports: list[str] = field(default_factory=list)
+    external_imports: list[str] = field(default_factory=list)
+    dependents: list[str] = field(default_factory=list)
+
+    @property
+    def instability(self) -> float:
+        """Calculate instability metric (0-1).
+
+        Instability = Ce / (Ce + Ca)
+
+        Interpretation:
+        - 0.0: Maximally stable (many incoming, few outgoing)
+        - 0.5: Balanced (equal incoming and outgoing)
+        - 1.0: Maximally unstable (many outgoing, few incoming)
+
+        Returns:
+            Instability ratio from 0.0 to 1.0
+        """
+        total = self.efferent_coupling + self.afferent_coupling
+        if total == 0:
+            return 0.0
+        return self.efferent_coupling / total
+
 
 @dataclass
 class FileMetrics:
@@ -119,6 +180,7 @@ class FileMetrics:
         avg_complexity: Average cognitive complexity per chunk
         max_complexity: Maximum cognitive complexity in any chunk
         chunks: List of chunk metrics for each function/class
+        coupling: Coupling metrics for this file
     """
 
     file_path: str
@@ -136,9 +198,20 @@ class FileMetrics:
     avg_complexity: float = 0.0
     max_complexity: int = 0
 
+    # Coupling metrics (Phase 3)
+    efferent_coupling: int = 0  # Outgoing dependencies
+    imports: list[str] = field(default_factory=list)  # All imported modules
+    internal_imports: list[str] = field(default_factory=list)  # Same-project imports
+    external_imports: list[str] = field(
+        default_factory=list
+    )  # Third-party/stdlib imports
+
     # Chunk metrics for each function/class
     chunks: list[ChunkMetrics] = field(default_factory=list)
 
+    # Coupling metrics
+    coupling: CouplingMetrics = field(default_factory=CouplingMetrics)
+
     def compute_aggregates(self) -> None:
         """Compute aggregate metrics from chunk metrics.
 

mcp_vector_search/analysis/reporters/__init__.py

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

mcp_vector_search/analysis/reporters/console.py

@@ -148,6 +148,213 @@ class ConsoleReporter:
         console.print(table)
         console.print()
 
+    def print_smells(self, smells: list, top: int = 10) -> None:
+        """Print detected code smells.
+
+        Args:
+            smells: List of CodeSmell objects
+            top: Maximum number of smells to display
+        """
+        from ..collectors.smells import SmellSeverity
+
+        if not smells:
+            console.print("[bold]🔍 Code Smells[/bold]")
+            console.print("  No code smells detected!")
+            console.print()
+            return
+
+        console.print(
+            f"[bold]🔍 Code Smells Detected[/bold] - Found {len(smells)} issues"
+        )
+
+        # Group smells by severity
+        error_smells = [s for s in smells if s.severity == SmellSeverity.ERROR]
+        warning_smells = [s for s in smells if s.severity == SmellSeverity.WARNING]
+        info_smells = [s for s in smells if s.severity == SmellSeverity.INFO]
+
+        # Summary
+        console.print(
+            f"  [red]Errors: {len(error_smells)}[/red]  "
+            f"[yellow]Warnings: {len(warning_smells)}[/yellow]  "
+            f"[blue]Info: {len(info_smells)}[/blue]"
+        )
+        console.print()
+
+        # Show top smells (prioritize errors first)
+        smells_to_display = error_smells + warning_smells + info_smells
+        smells_to_display = smells_to_display[:top]
+
+        # Create table
+        table = Table(show_header=True, header_style="bold cyan", box=None)
+        table.add_column("Severity", width=10)
+        table.add_column("Smell Type", width=20)
+        table.add_column("Location", width=40)
+        table.add_column("Details", width=30)
+
+        for smell in smells_to_display:
+            # Color code by severity
+            if smell.severity == SmellSeverity.ERROR:
+                severity_str = "[red]ERROR[/red]"
+            elif smell.severity == SmellSeverity.WARNING:
+                severity_str = "[yellow]WARNING[/yellow]"
+            else:
+                severity_str = "[blue]INFO[/blue]"
+
+            # Truncate location if too long
+            location = smell.location
+            if len(location) > 38:
+                location = "..." + location[-35:]
+
+            # Format details (metric value vs threshold)
+            details = f"{smell.metric_value} > {smell.threshold}"
+
+            table.add_row(severity_str, smell.name, location, details)
+
+        console.print(table)
+        console.print()
+
+        # Show suggestions for top smells
+        if smells_to_display:
+            console.print("[bold]💡 Top Suggestions[/bold]")
+            shown_suggestions = set()
+            suggestion_count = 0
+
+            for smell in smells_to_display:
+                if smell.suggestion and smell.suggestion not in shown_suggestions:
+                    console.print(f"  • [dim]{smell.suggestion}[/dim]")
+                    shown_suggestions.add(smell.suggestion)
+                    suggestion_count += 1
+
+                    # Limit to 5 unique suggestions
+                    if suggestion_count >= 5:
+                        break
+
+        console.print()
+
+    def print_instability(self, metrics: ProjectMetrics, top: int = 10) -> None:
+        """Print instability metrics.
+
+        Args:
+            metrics: Project metrics
+            top: Number of top files to display
+        """
+        console.print("[bold]🔗 Instability Metrics[/bold]")
+
+        # Collect instability data from files with coupling metrics
+        files_with_coupling = [
+            (f.file_path, f.coupling)
+            for f in metrics.files.values()
+            if f.coupling.efferent_coupling + f.coupling.afferent_coupling > 0
+        ]
+
+        if not files_with_coupling:
+            console.print("  No coupling data available")
+            console.print()
+            return
+
+        # Compute instability distribution
+        stable_count = sum(1 for _, c in files_with_coupling if c.instability <= 0.3)
+        balanced_count = sum(
+            1 for _, c in files_with_coupling if 0.3 < c.instability <= 0.7
+        )
+        unstable_count = sum(1 for _, c in files_with_coupling if c.instability > 0.7)
+        total_files = len(files_with_coupling)
+
+        console.print(f"  Total Files: {total_files}")
+        console.print(
+            f"  [green]Stable (I ≤ 0.3):[/green] {stable_count} "
+            f"({stable_count / total_files * 100:.1f}%)"
+        )
+        console.print(
+            f"  [yellow]Balanced (0.3 < I ≤ 0.7):[/yellow] {balanced_count} "
+            f"({balanced_count / total_files * 100:.1f}%)"
+        )
+        console.print(
+            f"  [red]Unstable (I > 0.7):[/red] {unstable_count} "
+            f"({unstable_count / total_files * 100:.1f}%)"
+        )
+        console.print()
+
+        # Show most stable files
+        most_stable = sorted(files_with_coupling, key=lambda x: x[1].instability)[:top]
+        if most_stable:
+            console.print(
+                f"[bold green]✓ Most Stable Files (Top {len(most_stable)})[/bold green]"
+            )
+
+            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=45)
+            table.add_column("Instability", justify="right", width=12)
+            table.add_column("Category", justify="center", width=12)
+            table.add_column("Ce/Ca", justify="right", width=10)
+
+            for rank, (file_path, coupling) in enumerate(most_stable, 1):
+                # Truncate file path if too long
+                display_path = file_path
+                if len(display_path) > 43:
+                    display_path = "..." + display_path[-40:]
+
+                # Determine category color
+                if coupling.instability <= 0.3:
+                    category = "[green]Stable[/green]"
+                elif coupling.instability <= 0.7:
+                    category = "[yellow]Balanced[/yellow]"
+                else:
+                    category = "[red]Unstable[/red]"
+
+                table.add_row(
+                    f"{rank}",
+                    display_path,
+                    f"{coupling.instability:.3f}",
+                    category,
+                    f"{coupling.efferent_coupling}/{coupling.afferent_coupling}",
+                )
+
+            console.print(table)
+            console.print()
+
+        # Show most unstable files
+        most_unstable = sorted(
+            files_with_coupling, key=lambda x: x[1].instability, reverse=True
+        )[:top]
+        if most_unstable:
+            console.print(
+                f"[bold red]⚠️  Most Unstable Files (Top {len(most_unstable)})[/bold red]"
+            )
+
+            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=45)
+            table.add_column("Instability", justify="right", width=12)
+            table.add_column("Category", justify="center", width=12)
+            table.add_column("Ce/Ca", justify="right", width=10)
+
+            for rank, (file_path, coupling) in enumerate(most_unstable, 1):
+                # Truncate file path if too long
+                display_path = file_path
+                if len(display_path) > 43:
+                    display_path = "..." + display_path[-40:]
+
+                # Determine category color
+                if coupling.instability <= 0.3:
+                    category = "[green]Stable[/green]"
+                elif coupling.instability <= 0.7:
+                    category = "[yellow]Balanced[/yellow]"
+                else:
+                    category = "[red]Unstable[/red]"
+
+                table.add_row(
+                    f"{rank}",
+                    display_path,
+                    f"{coupling.instability:.3f}",
+                    category,
+                    f"{coupling.efferent_coupling}/{coupling.afferent_coupling}",
+                )
+
+            console.print(table)
+            console.print()
+
     def print_recommendations(self, metrics: ProjectMetrics) -> None:
         """Print actionable recommendations.
 
@@ -187,6 +394,18 @@ class ConsoleReporter:
                     f"[yellow]•[/yellow] {d_f_percentage:.1f}% of functions have D/F grades - aim to reduce this below 10%"
                 )
 
+        # Check for highly unstable files (instability > 0.8)
+        highly_unstable = [
+            f
+            for f in metrics.files.values()
+            if f.coupling.instability > 0.8
+            and (f.coupling.efferent_coupling + f.coupling.afferent_coupling) > 0
+        ]
+        if highly_unstable:
+            recommendations.append(
+                f"[yellow]•[/yellow] {len(highly_unstable)} files have instability > 0.8 - consider reducing dependencies"
+            )
+
         # Check overall health
         avg_health = metrics._compute_avg_health_score()
         if avg_health < 0.7:
@@ -219,4 +438,209 @@ class ConsoleReporter:
         console.print(
             "[dim]  • Focus refactoring efforts on Grade D and F functions first[/dim]"
         )
+        console.print(
+            "[dim]  • Stable files (I ≤ 0.3) should contain abstractions and core logic[/dim]"
+        )
+        console.print(
+            "[dim]  • Unstable files (I > 0.7) should contain concrete implementations[/dim]"
+        )
+        console.print()
+
+    def print_baseline_comparison(self, comparison_result) -> None:
+        """Print baseline comparison results.
+
+        Args:
+            comparison_result: ComparisonResult from BaselineComparator
+        """
+        console.print(
+            f"\n[bold blue]📊 Baseline Comparison[/bold blue] - vs {comparison_result.baseline_name}"
+        )
+        console.print("━" * 80)
+        console.print()
+
+        # Summary statistics
+        console.print("[bold]Summary[/bold]")
+        summary = comparison_result.summary
+        console.print(
+            f"  Total Files Compared: {comparison_result.total_files_compared}"
+        )
+        console.print(
+            f"  Files - Current: {summary.get('total_files_current', 0)} | "
+            f"Baseline: {summary.get('total_files_baseline', 0)}"
+        )
+        console.print(
+            f"  Functions - Current: {summary.get('total_functions_current', 0)} | "
+            f"Baseline: {summary.get('total_functions_baseline', 0)}"
+        )
+        console.print()
+
+        # Change summary
+        console.print("[bold]Changes[/bold]")
+        console.print(
+            f"  [red]Regressions:[/red] {len(comparison_result.regressions)} files"
+        )
+        console.print(
+            f"  [green]Improvements:[/green] {len(comparison_result.improvements)} files"
+        )
+        console.print(
+            f"  [dim]Unchanged:[/dim] {len(comparison_result.unchanged)} files"
+        )
+        console.print(
+            f"  [blue]New Files:[/blue] {len(comparison_result.new_files)} files"
+        )
+        console.print(
+            f"  [yellow]Deleted Files:[/yellow] {len(comparison_result.deleted_files)} files"
+        )
         console.print()
+
+        # Complexity metrics comparison
+        avg_cc_current = summary.get("avg_complexity_current", 0.0)
+        avg_cc_baseline = summary.get("avg_complexity_baseline", 0.0)
+        avg_cc_delta = avg_cc_current - avg_cc_baseline
+        avg_cc_pct = (
+            (avg_cc_delta / avg_cc_baseline * 100) if avg_cc_baseline > 0 else 0.0
+        )
+
+        max_cc_current = summary.get("max_complexity_current", 0)
+        max_cc_baseline = summary.get("max_complexity_baseline", 0)
+        max_cc_delta = max_cc_current - max_cc_baseline
+
+        console.print("[bold]Complexity Metrics[/bold]")
+
+        # Average complexity with color coding
+        delta_color = (
+            "red" if avg_cc_delta > 0 else "green" if avg_cc_delta < 0 else "dim"
+        )
+        delta_sign = "+" if avg_cc_delta > 0 else ""
+        console.print(
+            f"  Avg Complexity: {avg_cc_current:.2f} "
+            f"(baseline: {avg_cc_baseline:.2f}, "
+            f"[{delta_color}]{delta_sign}{avg_cc_delta:.2f} / {delta_sign}{avg_cc_pct:.1f}%[/{delta_color}])"
+        )
+
+        # Max complexity with color coding
+        max_delta_color = (
+            "red" if max_cc_delta > 0 else "green" if max_cc_delta < 0 else "dim"
+        )
+        max_delta_sign = "+" if max_cc_delta > 0 else ""
+        console.print(
+            f"  Max Complexity: {max_cc_current} "
+            f"(baseline: {max_cc_baseline}, "
+            f"[{max_delta_color}]{max_delta_sign}{max_cc_delta}[/{max_delta_color}])"
+        )
+        console.print()
+
+        # Show regressions
+        if comparison_result.regressions:
+            console.print(
+                f"[bold red]⚠️  Regressions ({len(comparison_result.regressions)} files)[/bold red]"
+            )
+
+            # Show top 10 regressions
+            top_regressions = comparison_result.regressions[:10]
+
+            table = Table(show_header=True, header_style="bold cyan", box=None)
+            table.add_column("File", style="cyan", width=45)
+            table.add_column("Metric", width=20)
+            table.add_column("Change", justify="right", width=15)
+
+            for file_comp in top_regressions:
+                # Truncate file path
+                file_path = file_comp.file_path
+                if len(file_path) > 43:
+                    file_path = "..." + file_path[-40:]
+
+                # Show worst regression metric for this file
+                regression_changes = [
+                    c for c in file_comp.metric_changes if c.is_regression
+                ]
+                if regression_changes:
+                    worst_change = max(
+                        regression_changes, key=lambda c: abs(c.percentage_delta)
+                    )
+                    table.add_row(
+                        file_path,
+                        worst_change.metric_name.replace("_", " ").title(),
+                        f"+{worst_change.percentage_delta:.1f}%",
+                    )
+
+            console.print(table)
+
+            if len(comparison_result.regressions) > 10:
+                console.print(
+                    f"  [dim]... and {len(comparison_result.regressions) - 10} more[/dim]"
+                )
+            console.print()
+
+        # Show improvements
+        if comparison_result.improvements:
+            console.print(
+                f"[bold green]✓ Improvements ({len(comparison_result.improvements)} files)[/bold green]"
+            )
+
+            # Show top 10 improvements
+            top_improvements = comparison_result.improvements[:10]
+
+            table = Table(show_header=True, header_style="bold cyan", box=None)
+            table.add_column("File", style="cyan", width=45)
+            table.add_column("Metric", width=20)
+            table.add_column("Change", justify="right", width=15)
+
+            for file_comp in top_improvements:
+                # Truncate file path
+                file_path = file_comp.file_path
+                if len(file_path) > 43:
+                    file_path = "..." + file_path[-40:]
+
+                # Show best improvement metric for this file
+                improvement_changes = [
+                    c for c in file_comp.metric_changes if c.is_improvement
+                ]
+                if improvement_changes:
+                    best_change = max(
+                        improvement_changes, key=lambda c: abs(c.percentage_delta)
+                    )
+                    table.add_row(
+                        file_path,
+                        best_change.metric_name.replace("_", " ").title(),
+                        f"{best_change.percentage_delta:.1f}%",
+                    )
+
+            console.print(table)
+
+            if len(comparison_result.improvements) > 10:
+                console.print(
+                    f"  [dim]... and {len(comparison_result.improvements) - 10} more[/dim]"
+                )
+            console.print()
+
+        # Show new/deleted files summary
+        if comparison_result.new_files:
+            console.print(
+                f"[bold blue]📄 New Files ({len(comparison_result.new_files)})[/bold blue]"
+            )
+            for file_comp in comparison_result.new_files[:5]:
+                file_path = file_comp.file_path
+                if len(file_path) > 70:
+                    file_path = "..." + file_path[-67:]
+                console.print(f"  • {file_path}")
+            if len(comparison_result.new_files) > 5:
+                console.print(
+                    f"  [dim]... and {len(comparison_result.new_files) - 5} more[/dim]"
+                )
+            console.print()
+
+        if comparison_result.deleted_files:
+            console.print(
+                f"[bold yellow]🗑  Deleted Files ({len(comparison_result.deleted_files)})[/bold yellow]"
+            )
+            for file_comp in comparison_result.deleted_files[:5]:
+                file_path = file_comp.file_path
+                if len(file_path) > 70:
+                    file_path = "..." + file_path[-67:]
+                console.print(f"  • {file_path}")
+            if len(comparison_result.deleted_files) > 5:
+                console.print(
+                    f"  [dim]... and {len(comparison_result.deleted_files) - 5} more[/dim]"
+                )
+            console.print()