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

mcp_vector_search/analysis/storage/metrics_store.py

@@ -0,0 +1,762 @@
+"""SQLite-based metrics storage for historical tracking and trend analysis.
+
+This module provides the MetricsStore class for persisting code metrics to a
+SQLite database, enabling:
+- Historical tracking of file and project metrics
+- Trend analysis over time
+- Comparison between snapshots
+- Code smell tracking
+
+Design Decisions:
+    Storage Location: ~/.mcp-vector-search/metrics.db by default
+    - Centralized storage for cross-project analysis
+    - User can override with custom path
+    - Same pattern as baseline manager
+
+    Connection Pooling: Single connection with row factory
+    - SQLite doesn't benefit from pooling (single writer)
+    - Row factory enables dict-like access to results
+    - Connection reused across operations
+
+    Transaction Strategy: Auto-commit with explicit transactions for batches
+    - Individual saves use auto-commit for simplicity
+    - Bulk operations use explicit transactions for performance
+
+Performance:
+    - Save file metrics: O(1), ~1-2ms per file
+    - Save project snapshot: O(1), ~5-10ms
+    - Get history: O(n) where n=limit, typically <50ms
+    - Get trends: O(k) where k=snapshots, aggregates in SQL
+
+Error Handling:
+    - IntegrityError: Duplicate entries (file + project + timestamp)
+    - OperationalError: Database locked or corrupted
+    - All errors logged with context, propagated to caller
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from ...utils.version import get_version_string
+from ..metrics import FileMetrics, ProjectMetrics
+from .schema import INIT_SCHEMA_SQL, SCHEMA_VERSION, get_schema_version_query
+
+
+class MetricsStoreError(Exception):
+    """Base exception for metrics store errors."""
+
+    pass
+
+
+class DatabaseLockedError(MetricsStoreError):
+    """Database is locked by another process."""
+
+    pass
+
+
+class DuplicateEntryError(MetricsStoreError):
+    """Duplicate entry violates unique constraint."""
+
+    pass
+
+
+@dataclass
+class GitInfo:
+    """Git repository information for snapshot traceability.
+
+    Attributes:
+        commit: Git commit hash (full SHA-1)
+        branch: Current branch name (None if detached HEAD)
+        remote: Remote repository name (e.g., "origin")
+    """
+
+    commit: str | None = None
+    branch: str | None = None
+    remote: str | None = None
+
+
+@dataclass
+class ProjectSnapshot:
+    """Project-wide metric snapshot at a point in time.
+
+    Attributes:
+        snapshot_id: Unique snapshot identifier (database ID)
+        project_path: Absolute path to project root
+        timestamp: When snapshot was taken
+        total_files: Number of files analyzed
+        total_lines: Total lines across all files
+        total_functions: Total number of functions
+        total_classes: Total number of classes
+        avg_complexity: Average cognitive complexity
+        max_complexity: Maximum cognitive complexity
+        total_complexity: Sum of all cognitive complexity
+        total_smells: Total code smell count
+        avg_health_score: Average health score (0.0-1.0)
+        grade_distribution: Distribution of complexity grades (A-F)
+        git_commit: Git commit hash at time of snapshot
+        git_branch: Git branch at time of snapshot
+        tool_version: Version of mcp-vector-search used
+    """
+
+    snapshot_id: int
+    project_path: str
+    timestamp: datetime
+    total_files: int
+    total_lines: int
+    total_functions: int
+    total_classes: int
+    avg_complexity: float
+    max_complexity: int
+    total_complexity: int
+    total_smells: int
+    avg_health_score: float
+    grade_distribution: dict[str, int]
+    git_commit: str | None = None
+    git_branch: str | None = None
+    tool_version: str | None = None
+
+    @classmethod
+    def from_row(cls, row: sqlite3.Row) -> ProjectSnapshot:
+        """Create ProjectSnapshot from database row.
+
+        Args:
+            row: SQLite row with dict-like access
+
+        Returns:
+            ProjectSnapshot instance
+        """
+        return cls(
+            snapshot_id=row["id"],
+            project_path=row["project_path"],
+            timestamp=datetime.fromisoformat(row["timestamp"]),
+            total_files=row["total_files"],
+            total_lines=row["total_lines"],
+            total_functions=row["total_functions"],
+            total_classes=row["total_classes"],
+            avg_complexity=row["avg_complexity"],
+            max_complexity=row["max_complexity"],
+            total_complexity=row["total_complexity"],
+            total_smells=row["total_smells"],
+            avg_health_score=row["avg_health_score"],
+            grade_distribution=json.loads(row["grade_distribution"]),
+            git_commit=row["git_commit"] if row["git_commit"] else None,
+            git_branch=row["git_branch"] if row["git_branch"] else None,
+            tool_version=row["tool_version"] if row["tool_version"] else None,
+        )
+
+
+@dataclass
+class TrendData:
+    """Trend analysis data over time period.
+
+    Attributes:
+        project_path: Project being analyzed
+        period_days: Number of days in trend period
+        snapshots: List of snapshots in chronological order
+        complexity_trend: List of (timestamp, avg_complexity) tuples
+        smell_trend: List of (timestamp, total_smells) tuples
+        health_trend: List of (timestamp, avg_health_score) tuples
+        change_rate: Average daily change in complexity
+    """
+
+    project_path: str
+    period_days: int
+    snapshots: list[ProjectSnapshot]
+    complexity_trend: list[tuple[datetime, float]]
+    smell_trend: list[tuple[datetime, int]]
+    health_trend: list[tuple[datetime, float]]
+    change_rate: float
+
+    @property
+    def improving(self) -> bool:
+        """Check if trends are improving (complexity decreasing).
+
+        Returns:
+            True if average complexity is trending down
+        """
+        return self.change_rate < 0
+
+
+class MetricsStore:
+    """SQLite-based storage for code metrics history.
+
+    This class provides persistent storage of file and project metrics,
+    enabling historical tracking and trend analysis.
+
+    Storage Strategy:
+        - Default location: ~/.mcp-vector-search/metrics.db
+        - Single SQLite database with normalized schema
+        - Atomic writes with transactions
+        - Foreign key constraints for referential integrity
+
+    Thread Safety:
+        - SQLite uses database-level locking
+        - Safe for single-threaded CLI usage
+        - Not suitable for concurrent writes (would require connection pooling)
+
+    Example:
+        >>> store = MetricsStore()
+        >>> metrics = ProjectMetrics(project_root="/path/to/project")
+        >>> snapshot_id = store.save_project_snapshot(metrics)
+        >>> history = store.get_project_history("/path/to/project", limit=10)
+    """
+
+    def __init__(self, db_path: Path | None = None):
+        """Initialize metrics store with database connection.
+
+        Args:
+            db_path: Optional custom database path.
+                    Defaults to ~/.mcp-vector-search/metrics.db
+
+        Raises:
+            MetricsStoreError: If database initialization fails
+        """
+        if db_path is None:
+            # Default storage location
+            storage_dir = Path.home() / ".mcp-vector-search"
+            storage_dir.mkdir(parents=True, exist_ok=True)
+            db_path = storage_dir / "metrics.db"
+
+        self.db_path = db_path.resolve()
+
+        # Initialize database connection
+        try:
+            self.conn = sqlite3.connect(
+                str(self.db_path),
+                timeout=30.0,  # 30 second timeout for locked database
+                check_same_thread=False,  # Allow usage across threads (with care)
+            )
+
+            # Enable dict-like row access
+            self.conn.row_factory = sqlite3.Row
+
+            # Enable foreign key constraints
+            self.conn.execute("PRAGMA foreign_keys = ON")
+
+            # Initialize schema if needed
+            self._init_schema()
+
+            logger.info(f"Initialized metrics store: {self.db_path}")
+
+        except sqlite3.Error as e:
+            logger.error(f"Failed to initialize metrics store: {e}")
+            raise MetricsStoreError(f"Database initialization failed: {e}") from e
+
+    def _init_schema(self) -> None:
+        """Initialize database schema if not exists.
+
+        Creates all tables and indexes defined in schema.py.
+        Idempotent - safe to call multiple times.
+
+        Raises:
+            MetricsStoreError: If schema creation fails
+        """
+        try:
+            cursor = self.conn.cursor()
+
+            # Execute all schema initialization statements
+            for sql in INIT_SCHEMA_SQL:
+                cursor.execute(sql)
+
+            self.conn.commit()
+
+            # Verify schema version
+            cursor.execute(get_schema_version_query())
+            row = cursor.fetchone()
+            if row:
+                version = row[0]
+                logger.debug(f"Database schema version: {version}")
+
+                if version != SCHEMA_VERSION:
+                    logger.warning(
+                        f"Schema version mismatch: {version} vs {SCHEMA_VERSION}"
+                    )
+
+        except sqlite3.Error as e:
+            logger.error(f"Failed to initialize schema: {e}")
+            raise MetricsStoreError(f"Schema initialization failed: {e}") from e
+
+    def save_project_snapshot(
+        self, metrics: ProjectMetrics, git_info: GitInfo | None = None
+    ) -> int:
+        """Save project-wide metrics snapshot.
+
+        Args:
+            metrics: ProjectMetrics to save
+            git_info: Optional git metadata (auto-detected if None)
+
+        Returns:
+            Snapshot ID (database primary key)
+
+        Raises:
+            DuplicateEntryError: If snapshot with same timestamp exists
+            MetricsStoreError: If database write fails
+
+        Performance: O(1), typically 5-10ms
+        """
+        # Auto-detect git info if not provided
+        if git_info is None:
+            git_info = self._get_git_info(Path(metrics.project_root))
+
+        # Compute grade distribution
+        grade_dist: dict[str, int] = {"A": 0, "B": 0, "C": 0, "D": 0, "F": 0}
+        for file_metrics in metrics.files.values():
+            for chunk in file_metrics.chunks:
+                grade_dist[chunk.complexity_grade] += 1
+
+        # Compute average health score
+        if metrics.files:
+            avg_health = sum(f.health_score for f in metrics.files.values()) / len(
+                metrics.files
+            )
+        else:
+            avg_health = 1.0
+
+        # Compute total smells
+        total_smells = sum(
+            len(chunk.smells)
+            for file_metrics in metrics.files.values()
+            for chunk in file_metrics.chunks
+        )
+
+        try:
+            cursor = self.conn.cursor()
+
+            cursor.execute(
+                """
+                INSERT INTO project_snapshots (
+                    project_path, timestamp, total_files, total_lines,
+                    total_functions, total_classes, avg_complexity,
+                    max_complexity, total_complexity, total_smells,
+                    avg_health_score, grade_distribution, git_commit,
+                    git_branch, git_remote, tool_version
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    metrics.project_root,
+                    metrics.analyzed_at.isoformat(),
+                    metrics.total_files,
+                    metrics.total_lines,
+                    metrics.total_functions,
+                    metrics.total_classes,
+                    metrics.avg_file_complexity,
+                    max(
+                        (f.max_complexity for f in metrics.files.values()),
+                        default=0,
+                    ),
+                    sum(f.total_complexity for f in metrics.files.values()),
+                    total_smells,
+                    avg_health,
+                    json.dumps(grade_dist),
+                    git_info.commit,
+                    git_info.branch,
+                    git_info.remote,
+                    get_version_string(include_build=True),
+                ),
+            )
+
+            snapshot_id = cursor.lastrowid
+            self.conn.commit()
+
+            logger.info(
+                f"Saved project snapshot {snapshot_id} for {metrics.project_root}"
+            )
+
+            return snapshot_id
+
+        except sqlite3.IntegrityError as e:
+            logger.warning(f"Duplicate snapshot for {metrics.project_root}: {e}")
+            raise DuplicateEntryError(
+                f"Snapshot already exists for {metrics.project_root} "
+                f"at {metrics.analyzed_at}"
+            ) from e
+        except sqlite3.OperationalError as e:
+            if "locked" in str(e).lower():
+                raise DatabaseLockedError(f"Database is locked: {self.db_path}") from e
+            raise MetricsStoreError(f"Failed to save project snapshot: {e}") from e
+        except sqlite3.Error as e:
+            logger.error(f"Failed to save project snapshot: {e}")
+            raise MetricsStoreError(f"Database write failed: {e}") from e
+
+    def save_file_metrics(self, file_metrics: FileMetrics, snapshot_id: int) -> int:
+        """Save file-level metrics linked to a project snapshot.
+
+        Args:
+            file_metrics: FileMetrics to save
+            snapshot_id: Project snapshot ID (foreign key)
+
+        Returns:
+            File metrics ID (database primary key)
+
+        Raises:
+            DuplicateEntryError: If metrics for file + snapshot exists
+            MetricsStoreError: If database write fails
+
+        Performance: O(1), typically 1-2ms per file
+        """
+        # Compute aggregates if not already done
+        file_metrics.compute_aggregates()
+
+        # Count smells
+        smell_count = sum(len(chunk.smells) for chunk in file_metrics.chunks)
+
+        # Determine overall grade (worst grade across chunks)
+        if file_metrics.chunks:
+            grades = [chunk.complexity_grade for chunk in file_metrics.chunks]
+            worst_grade = max(grades, key=lambda g: "ABCDF".index(g))
+        else:
+            worst_grade = "A"
+
+        try:
+            cursor = self.conn.cursor()
+
+            cursor.execute(
+                """
+                INSERT INTO file_metrics (
+                    file_path, project_id, total_lines, code_lines,
+                    comment_lines, blank_lines, function_count, class_count,
+                    method_count, cognitive_complexity, cyclomatic_complexity,
+                    total_complexity, avg_complexity, max_complexity,
+                    smell_count, health_score, complexity_grade
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    file_metrics.file_path,
+                    snapshot_id,
+                    file_metrics.total_lines,
+                    file_metrics.code_lines,
+                    file_metrics.comment_lines,
+                    file_metrics.blank_lines,
+                    file_metrics.function_count,
+                    file_metrics.class_count,
+                    file_metrics.method_count,
+                    sum(chunk.cognitive_complexity for chunk in file_metrics.chunks),
+                    sum(chunk.cyclomatic_complexity for chunk in file_metrics.chunks),
+                    file_metrics.total_complexity,
+                    file_metrics.avg_complexity,
+                    file_metrics.max_complexity,
+                    smell_count,
+                    file_metrics.health_score,
+                    worst_grade,
+                ),
+            )
+
+            file_id = cursor.lastrowid
+            self.conn.commit()
+
+            logger.debug(f"Saved file metrics {file_id} for {file_metrics.file_path}")
+
+            return file_id
+
+        except sqlite3.IntegrityError as e:
+            logger.warning(f"Duplicate file metrics for {file_metrics.file_path}: {e}")
+            raise DuplicateEntryError(
+                f"Metrics already exist for {file_metrics.file_path} "
+                f"in snapshot {snapshot_id}"
+            ) from e
+        except sqlite3.OperationalError as e:
+            if "locked" in str(e).lower():
+                raise DatabaseLockedError(f"Database is locked: {self.db_path}") from e
+            raise MetricsStoreError(f"Failed to save file metrics: {e}") from e
+        except sqlite3.Error as e:
+            logger.error(f"Failed to save file metrics: {e}")
+            raise MetricsStoreError(f"Database write failed: {e}") from e
+
+    def save_complete_snapshot(self, metrics: ProjectMetrics) -> int:
+        """Save complete snapshot (project + all files) in single transaction.
+
+        This is the recommended method for saving metrics as it ensures
+        atomicity and better performance through batching.
+
+        Args:
+            metrics: ProjectMetrics with all file metrics
+
+        Returns:
+            Snapshot ID
+
+        Raises:
+            MetricsStoreError: If save fails (rolls back entire transaction)
+
+        Performance: O(n) where n=number of files, typically 50-100ms for 100 files
+        """
+        try:
+            # Begin explicit transaction
+            self.conn.execute("BEGIN")
+
+            # Save project snapshot
+            snapshot_id = self.save_project_snapshot(metrics)
+
+            # Save all file metrics
+            for file_metrics in metrics.files.values():
+                self.save_file_metrics(file_metrics, snapshot_id)
+
+            # Commit transaction
+            self.conn.commit()
+
+            logger.info(
+                f"Saved complete snapshot {snapshot_id} with {len(metrics.files)} files"
+            )
+
+            return snapshot_id
+
+        except Exception as e:
+            # Rollback on any error
+            self.conn.rollback()
+            logger.error(f"Failed to save complete snapshot: {e}")
+            raise MetricsStoreError(f"Failed to save snapshot: {e}") from e
+
+    def get_file_history(self, file_path: str, limit: int = 10) -> list[FileMetrics]:
+        """Get historical metrics for a specific file.
+
+        Args:
+            file_path: Path to file (relative or absolute)
+            limit: Maximum number of history entries to return
+
+        Returns:
+            List of FileMetrics ordered by timestamp (newest first)
+
+        Performance: O(n) where n=limit, typically <50ms
+        """
+        try:
+            cursor = self.conn.cursor()
+
+            cursor.execute(
+                """
+                SELECT * FROM file_metrics
+                WHERE file_path = ?
+                ORDER BY timestamp DESC
+                LIMIT ?
+                """,
+                (file_path, limit),
+            )
+
+            rows = cursor.fetchall()
+
+            # Convert rows to FileMetrics
+            # Note: This is a simplified conversion without chunk details
+            # For full chunk history, need separate chunk storage table
+            history = []
+            for row in rows:
+                fm = FileMetrics(
+                    file_path=row["file_path"],
+                    total_lines=row["total_lines"],
+                    code_lines=row["code_lines"],
+                    comment_lines=row["comment_lines"],
+                    blank_lines=row["blank_lines"],
+                    function_count=row["function_count"],
+                    class_count=row["class_count"],
+                    method_count=row["method_count"],
+                    total_complexity=row["total_complexity"],
+                    avg_complexity=row["avg_complexity"],
+                    max_complexity=row["max_complexity"],
+                    chunks=[],  # Chunk history not stored yet
+                )
+                history.append(fm)
+
+            logger.debug(f"Retrieved {len(history)} history entries for {file_path}")
+
+            return history
+
+        except sqlite3.Error as e:
+            logger.error(f"Failed to get file history: {e}")
+            raise MetricsStoreError(f"Database query failed: {e}") from e
+
+    def get_project_history(
+        self, project_path: str, limit: int = 10
+    ) -> list[ProjectSnapshot]:
+        """Get historical snapshots for a project.
+
+        Args:
+            project_path: Path to project root
+            limit: Maximum number of snapshots to return
+
+        Returns:
+            List of ProjectSnapshot ordered by timestamp (newest first)
+
+        Performance: O(n) where n=limit, typically <50ms
+        """
+        try:
+            cursor = self.conn.cursor()
+
+            cursor.execute(
+                """
+                SELECT * FROM project_snapshots
+                WHERE project_path = ?
+                ORDER BY timestamp DESC
+                LIMIT ?
+                """,
+                (project_path, limit),
+            )
+
+            rows = cursor.fetchall()
+
+            snapshots = [ProjectSnapshot.from_row(row) for row in rows]
+
+            logger.debug(f"Retrieved {len(snapshots)} snapshots for {project_path}")
+
+            return snapshots
+
+        except sqlite3.Error as e:
+            logger.error(f"Failed to get project history: {e}")
+            raise MetricsStoreError(f"Database query failed: {e}") from e
+
+    def get_trends(self, project_path: str, days: int = 30) -> TrendData:
+        """Analyze complexity trends over time period.
+
+        Args:
+            project_path: Path to project root
+            days: Number of days to analyze (from now backwards)
+
+        Returns:
+            TrendData with analyzed trends
+
+        Performance: O(k) where k=snapshots in period, typically <100ms
+
+        Example:
+            >>> trends = store.get_trends("/path/to/project", days=30)
+            >>> if trends.improving:
+            ...     print("Complexity is trending down!")
+        """
+        cutoff_date = datetime.now() - timedelta(days=days)
+
+        try:
+            cursor = self.conn.cursor()
+
+            cursor.execute(
+                """
+                SELECT * FROM project_snapshots
+                WHERE project_path = ?
+                  AND timestamp >= ?
+                ORDER BY timestamp ASC
+                """,
+                (project_path, cutoff_date.isoformat()),
+            )
+
+            rows = cursor.fetchall()
+
+            snapshots = [ProjectSnapshot.from_row(row) for row in rows]
+
+            # Extract trend data
+            complexity_trend = [(s.timestamp, s.avg_complexity) for s in snapshots]
+
+            smell_trend = [(s.timestamp, s.total_smells) for s in snapshots]
+
+            health_trend = [(s.timestamp, s.avg_health_score) for s in snapshots]
+
+            # Compute change rate (complexity per day)
+            if len(snapshots) >= 2:
+                first = snapshots[0]
+                last = snapshots[-1]
+                time_delta = (last.timestamp - first.timestamp).days
+                complexity_delta = last.avg_complexity - first.avg_complexity
+
+                if time_delta > 0:
+                    change_rate = complexity_delta / time_delta
+                else:
+                    change_rate = 0.0
+            else:
+                change_rate = 0.0
+
+            logger.debug(
+                f"Analyzed trends for {project_path}: "
+                f"{len(snapshots)} snapshots, change rate {change_rate:.4f}/day"
+            )
+
+            return TrendData(
+                project_path=project_path,
+                period_days=days,
+                snapshots=snapshots,
+                complexity_trend=complexity_trend,
+                smell_trend=smell_trend,
+                health_trend=health_trend,
+                change_rate=change_rate,
+            )
+
+        except sqlite3.Error as e:
+            logger.error(f"Failed to get trends: {e}")
+            raise MetricsStoreError(f"Database query failed: {e}") from e
+
+    def close(self) -> None:
+        """Close database connection.
+
+        Should be called when done using the store, or use as context manager.
+        """
+        if self.conn:
+            self.conn.close()
+            logger.debug("Closed metrics store connection")
+
+    def __enter__(self) -> MetricsStore:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit - close connection."""
+        self.close()
+
+    def _get_git_info(self, project_root: Path) -> GitInfo:
+        """Extract git information from project repository.
+
+        Args:
+            project_root: Project root directory
+
+        Returns:
+            GitInfo with commit, branch, and remote (if available)
+
+        Note: Does not raise exceptions. Returns GitInfo with None values if git unavailable.
+        """
+        git_info = GitInfo()
+
+        try:
+            # Get commit hash
+            result = subprocess.run(
+                ["git", "rev-parse", "HEAD"],
+                cwd=project_root,
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=5,
+            )
+            git_info.commit = result.stdout.strip()
+
+            # Get branch name
+            result = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                cwd=project_root,
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=5,
+            )
+            branch = result.stdout.strip()
+            git_info.branch = branch if branch != "HEAD" else None
+
+            # Get remote name (if exists)
+            result = subprocess.run(
+                ["git", "remote"],
+                cwd=project_root,
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=5,
+            )
+            remotes = result.stdout.strip().split("\n")
+            git_info.remote = remotes[0] if remotes and remotes[0] else None
+
+        except (
+            subprocess.CalledProcessError,
+            FileNotFoundError,
+            subprocess.TimeoutExpired,
+        ):
+            # Git not available or not a git repo
+            logger.debug("Git information unavailable")
+
+        return git_info