ctrlcode 0.1.0__py3-none-any.whl

ctrlcode/metrics/tech_debt.py

@@ -0,0 +1,663 @@
+"""Technical debt metrics tracking and dashboard generation."""
+
+import json
+import sqlite3
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+from dataclasses import dataclass
+
+
+@dataclass
+class TechDebtSnapshot:
+    """Snapshot of technical debt at a point in time."""
+
+    timestamp: str
+    total_violations: int
+    violations_by_type: dict[str, int]
+    violations_by_file: dict[str, int]
+    stale_docs_count: int
+    code_smells: dict[str, int]
+    cleanup_prs: dict[str, int]  # created, merged, rejected
+
+
+class TechDebtMetrics:
+    """Track and analyze technical debt over time."""
+
+    def __init__(self, storage_path: Path | str, project_path: Path | str | None = None):
+        """
+        Initialize tech debt metrics tracker.
+
+        Args:
+            storage_path: Path to SQLite database or JSON storage directory
+            project_path: Base directory of the project being tracked (defaults to cwd)
+        """
+        self.storage_path = Path(storage_path)
+        self.storage_path.mkdir(parents=True, exist_ok=True)
+
+        # Store project path for filtering
+        self.project_path = str(Path(project_path).resolve()) if project_path else str(Path.cwd().resolve())
+
+        # Use SQLite for efficient querying
+        self.db_path = self.storage_path / "tech_debt.db"
+        self._init_database()
+
+    def _get_schema_version(self, cursor) -> int:
+        """Get current schema version."""
+        try:
+            cursor.execute("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1")
+            row = cursor.fetchone()
+            return row[0] if row else 0
+        except sqlite3.OperationalError:
+            # schema_version table doesn't exist yet
+            return 0
+
+    def _set_schema_version(self, cursor, version: int):
+        """Set schema version."""
+        cursor.execute("INSERT INTO schema_version (version) VALUES (?)", (version,))
+
+    def _run_migrations(self, conn, cursor):
+        """Run database migrations to bring schema up to date."""
+        current_version = self._get_schema_version(cursor)
+
+        # Migration 1: Initial schema
+        if current_version < 1:
+            # Schema version table
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS schema_version (
+                    version INTEGER PRIMARY KEY,
+                    applied_at TEXT DEFAULT CURRENT_TIMESTAMP
+                )
+            """)
+
+            # Snapshots table (without project_path - old schema)
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS snapshots (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    timestamp TEXT NOT NULL,
+                    total_violations INTEGER NOT NULL,
+                    stale_docs_count INTEGER NOT NULL,
+                    created_at TEXT DEFAULT CURRENT_TIMESTAMP
+                )
+            """)
+
+            # Violations table (without project_path - old schema)
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS violations (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    snapshot_id INTEGER NOT NULL,
+                    violation_type TEXT NOT NULL,
+                    file_path TEXT NOT NULL,
+                    line_number INTEGER,
+                    message TEXT,
+                    severity TEXT,
+                    FOREIGN KEY (snapshot_id) REFERENCES snapshots (id)
+                )
+            """)
+
+            # Code smells table (without project_path - old schema)
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS code_smells (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    snapshot_id INTEGER NOT NULL,
+                    smell_type TEXT NOT NULL,
+                    count INTEGER NOT NULL,
+                    FOREIGN KEY (snapshot_id) REFERENCES snapshots (id)
+                )
+            """)
+
+            # Cleanup PRs table (without project_path - old schema)
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS cleanup_prs (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    pr_number INTEGER,
+                    created_at TEXT,
+                    merged_at TEXT,
+                    status TEXT NOT NULL,
+                    files_changed INTEGER,
+                    violations_fixed INTEGER
+                )
+            """)
+
+            self._set_schema_version(cursor, 1)
+            conn.commit()
+
+        # Migration 2: Add project_path columns
+        if current_version < 2:
+            # Add project_path to all tables
+            for table in ["snapshots", "violations", "code_smells", "cleanup_prs"]:
+                cursor.execute(f"PRAGMA table_info({table})")
+                columns = {row[1] for row in cursor.fetchall()}
+                if "project_path" not in columns:
+                    cursor.execute(f"ALTER TABLE {table} ADD COLUMN project_path TEXT NOT NULL DEFAULT ''")
+
+            # Create indexes
+            cursor.execute("""
+                CREATE INDEX IF NOT EXISTS idx_snapshots_project
+                ON snapshots(project_path)
+            """)
+            cursor.execute("""
+                CREATE INDEX IF NOT EXISTS idx_violations_project
+                ON violations(project_path)
+            """)
+            cursor.execute("""
+                CREATE INDEX IF NOT EXISTS idx_code_smells_project
+                ON code_smells(project_path)
+            """)
+            cursor.execute("""
+                CREATE INDEX IF NOT EXISTS idx_cleanup_prs_project
+                ON cleanup_prs(project_path)
+            """)
+
+            self._set_schema_version(cursor, 2)
+            conn.commit()
+
+    def _init_database(self):
+        """Initialize SQLite database schema with migrations."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        try:
+            self._run_migrations(conn, cursor)
+        finally:
+            conn.close()
+
+    def record_snapshot(self, snapshot: TechDebtSnapshot) -> int:
+        """
+        Record a tech debt snapshot.
+
+        Args:
+            snapshot: TechDebtSnapshot to record
+
+        Returns:
+            Snapshot ID
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Insert snapshot
+        cursor.execute("""
+            INSERT INTO snapshots (project_path, timestamp, total_violations, stale_docs_count)
+            VALUES (?, ?, ?, ?)
+        """, (self.project_path, snapshot.timestamp, snapshot.total_violations, snapshot.stale_docs_count))
+
+        snapshot_id = cursor.lastrowid
+
+        # Insert violations by type and file
+        for violation_type, count in snapshot.violations_by_type.items():
+            # Store aggregated by type
+            cursor.execute("""
+                INSERT INTO violations (snapshot_id, project_path, violation_type, file_path, message)
+                VALUES (?, ?, ?, ?, ?)
+            """, (snapshot_id, self.project_path, violation_type, "aggregated", f"{count} violations"))
+
+        # Insert code smells
+        for smell_type, count in snapshot.code_smells.items():
+            cursor.execute("""
+                INSERT INTO code_smells (snapshot_id, project_path, smell_type, count)
+                VALUES (?, ?, ?, ?)
+            """, (snapshot_id, self.project_path, smell_type, count))
+
+        conn.commit()
+        conn.close()
+
+        return snapshot_id
+
+    def record_cleanup_pr(
+        self,
+        pr_number: int,
+        status: str,
+        files_changed: int,
+        violations_fixed: int,
+        created_at: str | None = None,
+        merged_at: str | None = None,
+    ):
+        """
+        Record a cleanup PR.
+
+        Args:
+            pr_number: PR number
+            status: PR status (open, merged, closed)
+            files_changed: Number of files changed
+            violations_fixed: Number of violations fixed
+            created_at: When PR was created (ISO format)
+            merged_at: When PR was merged (ISO format)
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute("""
+            INSERT INTO cleanup_prs
+            (project_path, pr_number, created_at, merged_at, status, files_changed, violations_fixed)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """, (self.project_path, pr_number, created_at, merged_at, status, files_changed, violations_fixed))
+
+        conn.commit()
+        conn.close()
+
+    def get_current_state(self) -> dict[str, Any]:
+        """
+        Get current tech debt state for this project.
+
+        Returns:
+            Dict with current metrics
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Get latest snapshot for this project
+        cursor.execute("""
+            SELECT timestamp, total_violations, stale_docs_count
+            FROM snapshots
+            WHERE project_path = ?
+            ORDER BY id DESC
+            LIMIT 1
+        """, (self.project_path,))
+
+        latest = cursor.fetchone()
+
+        if not latest:
+            conn.close()
+            return {
+                "total_violations": 0,
+                "stale_docs_count": 0,
+                "timestamp": None,
+            }
+
+        timestamp, total_violations, stale_docs = latest
+
+        # Get snapshot ID
+        cursor.execute("""
+            SELECT id FROM snapshots
+            WHERE project_path = ? AND timestamp = ?
+        """, (self.project_path, timestamp))
+        snapshot_id = cursor.fetchone()[0]
+
+        # Get violations by type
+        cursor.execute("""
+            SELECT violation_type, COUNT(*)
+            FROM violations
+            WHERE snapshot_id = ? AND project_path = ?
+            GROUP BY violation_type
+        """, (snapshot_id, self.project_path))
+
+        violations_by_type = dict(cursor.fetchall())
+
+        # Get code smells
+        cursor.execute("""
+            SELECT smell_type, SUM(count)
+            FROM code_smells
+            WHERE snapshot_id = ? AND project_path = ?
+            GROUP BY smell_type
+        """, (snapshot_id, self.project_path))
+
+        code_smells = dict(cursor.fetchall())
+
+        conn.close()
+
+        return {
+            "timestamp": timestamp,
+            "total_violations": total_violations,
+            "stale_docs_count": stale_docs,
+            "violations_by_type": violations_by_type,
+            "code_smells": code_smells,
+        }
+
+    def get_trend(self, days: int = 30) -> list[dict[str, Any]]:
+        """
+        Get tech debt trend over time for this project.
+
+        Args:
+            days: Number of days to look back
+
+        Returns:
+            List of snapshots ordered by time
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cutoff = (datetime.now() - timedelta(days=days)).isoformat()
+
+        cursor.execute("""
+            SELECT timestamp, total_violations, stale_docs_count
+            FROM snapshots
+            WHERE project_path = ? AND timestamp > ?
+            ORDER BY timestamp ASC
+        """, (self.project_path, cutoff))
+
+        snapshots = []
+        for row in cursor.fetchall():
+            snapshots.append({
+                "timestamp": row[0],
+                "total_violations": row[1],
+                "stale_docs_count": row[2],
+            })
+
+        conn.close()
+        return snapshots
+
+    def get_cleanup_velocity(self, days: int = 30) -> dict[str, Any]:
+        """
+        Get cleanup PR velocity metrics for this project.
+
+        Args:
+            days: Number of days to look back
+
+        Returns:
+            Dict with velocity metrics
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cutoff = (datetime.now() - timedelta(days=days)).isoformat()
+
+        # Count PRs by status for this project
+        cursor.execute("""
+            SELECT status, COUNT(*), SUM(violations_fixed)
+            FROM cleanup_prs
+            WHERE project_path = ? AND created_at > ?
+            GROUP BY status
+        """, (self.project_path, cutoff))
+
+        velocity = {
+            "created": 0,
+            "merged": 0,
+            "closed": 0,
+            "violations_fixed": 0,
+        }
+
+        for row in cursor.fetchall():
+            status, count, fixed = row
+            if status == "merged":
+                velocity["merged"] = count
+                velocity["violations_fixed"] = fixed or 0
+            elif status == "open":
+                velocity["created"] = count
+            elif status == "closed":
+                velocity["closed"] = count
+
+        conn.close()
+        return velocity
+
+    def get_hot_spots(self, limit: int = 10) -> list[dict[str, Any]]:
+        """
+        Get files with most violations (hot spots) for this project.
+
+        Args:
+            limit: Maximum number of hot spots to return
+
+        Returns:
+            List of files with violation counts
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Get latest snapshot for this project
+        cursor.execute("""
+            SELECT id FROM snapshots
+            WHERE project_path = ?
+            ORDER BY id DESC
+            LIMIT 1
+        """, (self.project_path,))
+
+        snapshot_result = cursor.fetchone()
+        if not snapshot_result:
+            conn.close()
+            return []
+
+        snapshot_id = snapshot_result[0]
+
+        cursor.execute("""
+            SELECT file_path, COUNT(*) as count
+            FROM violations
+            WHERE snapshot_id = ? AND project_path = ? AND file_path != 'aggregated'
+            GROUP BY file_path
+            ORDER BY count DESC
+            LIMIT ?
+        """, (snapshot_id, self.project_path, limit))
+
+        hot_spots = []
+        for row in cursor.fetchall():
+            hot_spots.append({
+                "file": row[0],
+                "violations": row[1],
+            })
+
+        conn.close()
+        return hot_spots
+
+    def generate_dashboard_html(self) -> str:
+        """
+        Generate HTML dashboard for tech debt metrics.
+
+        Returns:
+            HTML string
+        """
+        current = self.get_current_state()
+        trend = self.get_trend(days=30)
+        velocity = self.get_cleanup_velocity(days=30)
+        hot_spots = self.get_hot_spots(limit=10)
+
+        # Generate trend chart data
+        trend_labels = [t["timestamp"][:10] for t in trend]  # Date only
+        trend_values = [t["total_violations"] for t in trend]
+
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <title>Tech Debt Dashboard - ctrl+code</title>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <style>
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            margin: 0;
+            padding: 20px;
+            background: #1e1e1e;
+            color: #d4d4d4;
+        }}
+        .container {{
+            max-width: 1200px;
+            margin: 0 auto;
+        }}
+        h1 {{
+            color: #fff;
+            margin-bottom: 10px;
+        }}
+        .subtitle {{
+            color: #888;
+            margin-bottom: 30px;
+        }}
+        .grid {{
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 20px;
+            margin-bottom: 30px;
+        }}
+        .card {{
+            background: #252526;
+            border: 1px solid #3e3e42;
+            border-radius: 8px;
+            padding: 20px;
+        }}
+        .card h2 {{
+            margin-top: 0;
+            font-size: 18px;
+            color: #fff;
+        }}
+        .metric {{
+            font-size: 36px;
+            font-weight: bold;
+            color: #4ec9b0;
+            margin: 10px 0;
+        }}
+        .metric.warning {{
+            color: #ce9178;
+        }}
+        .metric.error {{
+            color: #f48771;
+        }}
+        .chart-container {{
+            position: relative;
+            height: 300px;
+            margin-top: 20px;
+        }}
+        .list {{
+            list-style: none;
+            padding: 0;
+            margin: 0;
+        }}
+        .list li {{
+            padding: 10px;
+            border-bottom: 1px solid #3e3e42;
+            display: flex;
+            justify-content: space-between;
+        }}
+        .list li:last-child {{
+            border-bottom: none;
+        }}
+        .badge {{
+            background: #3e3e42;
+            padding: 4px 8px;
+            border-radius: 4px;
+            font-size: 12px;
+        }}
+        .timestamp {{
+            color: #888;
+            font-size: 14px;
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>📊 Tech Debt Dashboard</h1>
+        <p class="subtitle">Last updated: {current.get('timestamp', 'Never')}</p>
+
+        <div class="grid">
+            <div class="card">
+                <h2>Total Violations</h2>
+                <div class="metric {'warning' if current['total_violations'] > 50 else 'error' if current['total_violations'] > 100 else ''}">
+                    {current['total_violations']}
+                </div>
+                <p class="timestamp">Golden principle violations</p>
+            </div>
+
+            <div class="card">
+                <h2>Stale Documentation</h2>
+                <div class="metric {'warning' if current['stale_docs_count'] > 5 else ''}">
+                    {current['stale_docs_count']}
+                </div>
+                <p class="timestamp">Docs needing updates</p>
+            </div>
+
+            <div class="card">
+                <h2>Cleanup Velocity</h2>
+                <div class="metric">
+                    {velocity['merged']}
+                </div>
+                <p class="timestamp">PRs merged (30 days)</p>
+            </div>
+
+            <div class="card">
+                <h2>Violations Fixed</h2>
+                <div class="metric">
+                    {velocity['violations_fixed']}
+                </div>
+                <p class="timestamp">Via cleanup PRs (30 days)</p>
+            </div>
+        </div>
+
+        <div class="card">
+            <h2>Violation Trend (30 Days)</h2>
+            <div class="chart-container">
+                <canvas id="trendChart"></canvas>
+            </div>
+        </div>
+
+        <div class="grid" style="margin-top: 20px;">
+            <div class="card">
+                <h2>Violations by Type</h2>
+                <ul class="list">
+                    {''.join(f'<li><span>{vtype}</span><span class="badge">{count}</span></li>'
+                            for vtype, count in current.get('violations_by_type', {}).items())}
+                    {'' if current.get('violations_by_type') else '<li><span>No violations</span></li>'}
+                </ul>
+            </div>
+
+            <div class="card">
+                <h2>Hot Spots (Top Files)</h2>
+                <ul class="list">
+                    {''.join(f'<li><span>{h["file"]}</span><span class="badge">{h["violations"]}</span></li>'
+                            for h in hot_spots)}
+                    {'' if hot_spots else '<li><span>No hot spots</span></li>'}
+                </ul>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        const ctx = document.getElementById('trendChart').getContext('2d');
+        new Chart(ctx, {{
+            type: 'line',
+            data: {{
+                labels: {json.dumps(trend_labels)},
+                datasets: [{{
+                    label: 'Total Violations',
+                    data: {json.dumps(trend_values)},
+                    borderColor: '#4ec9b0',
+                    backgroundColor: 'rgba(78, 201, 176, 0.1)',
+                    tension: 0.4
+                }}]
+            }},
+            options: {{
+                responsive: true,
+                maintainAspectRatio: false,
+                plugins: {{
+                    legend: {{
+                        labels: {{
+                            color: '#d4d4d4'
+                        }}
+                    }}
+                }},
+                scales: {{
+                    y: {{
+                        beginAtZero: true,
+                        ticks: {{
+                            color: '#d4d4d4'
+                        }},
+                        grid: {{
+                            color: '#3e3e42'
+                        }}
+                    }},
+                    x: {{
+                        ticks: {{
+                            color: '#d4d4d4'
+                        }},
+                        grid: {{
+                            color: '#3e3e42'
+                        }}
+                    }}
+                }}
+            }}
+        }});
+    </script>
+</body>
+</html>
+"""
+        return html
+
+    def save_dashboard(self, output_path: Path | str | None = None):
+        """
+        Save dashboard HTML to file.
+
+        Args:
+            output_path: Where to save dashboard (defaults to storage_path/dashboard.html)
+        """
+        if output_path is None:
+            output_path = self.storage_path / "dashboard.html"
+        else:
+            output_path = Path(output_path)
+
+        html = self.generate_dashboard_html()
+        output_path.write_text(html)
+
+        return output_path